SG_SAT_READ_GPLOG(8)

💖 SG_SAT_READ_GPLOG(8) · SG3_UTILS 💖

✨ NAME ✨

okay so this is the sg_sat_read_gplog tool, and it's giving "use ATA READ LOG EXT or SMART READ LOG command via a SCSI to ATA Translation (SAT) layer" 🧚 bestie, that's the whole vibe.

🎀 SYNOPSIS 🎀

sg_sat_read_gplog [--address=LA_L] [--ck_cond] [--count=CO] [--dma]
[--help] [--hex] [--len=CMD_LEN] [--log=LA_L] [--page=PN] [--ppt=PPT]
[--readonly] [--smart] [--verbose] [--version] DEVICE

🦋 DESCRIPTION 🦋

okay so this utility sends an ATA READ LOG EXT, an ATA READ LOG DMA EXT, or an ATA SMART READ LOG command to the DEVICE 💅 By default it sends one of the first two, and the goal is to read "general purpose log" page(s). Only (S)ATA devices (think disks) support general purpose log pages, not ATAPI devices (think DVD readers) 💀 Also, it doesn't talk to the device directly. The command goes through a SCSI transport that's assumed to have a SCSI to ATA Translation (SAT) Layer (SATL) in it. That SATL could live in an operating system driver, in host bus adapter (HBA) firmware, or in some external enclosure 🔥

this tool does not decode the response from the ATA disk yet 🙈 Instead it dumps the response as ASCII hexadecimal, grouped into 8 bit bytes or 16 bit words. Following ATA conventions, those words are decoded little endian (SCSI commands use big endian, so watch out 👀). Log address 0, page number 0 is the directory log page, and it gets decoded if no --hex option is given. Maybe in the future this tool will decode other log pages too. Until then, another ATA utility might be able to decode them if you feed it the hex output from here 🌸

fetching all the log pages sounds easy: read the directory log page, then grab every log address that has more than zero page numbers attached. but honestly? it is not that simple 😭 some log addresses need extra stuff first. for example, 0xe1 ("SCT Data transfer") needs an SCT command run before you fetch its log page. other addresses might be problematic too, like the "Device vendor specific logs" 0xa0:0xdf, so those might be best avoided. that's exactly why the --address=LA_L and --log=LA_L options take a list of ranges 🧚

the SAT-4 standard (SAT ANSI INCITS 491-201r7 prior draft: sat4r06.pdf at www.t10.org) defines three SCSI "ATA PASS-THROUGH" commands. One uses a 12 byte "cdb", another uses a 16 byte cdb, and the last one uses a 32 byte cdb. This utility defaults to the 16 byte cdb variant ✨

🌈 OPTIONS 🌈

okay bestie, arguments to long options are mandatory for short options as well. so no skipping them 🫶

• -a, --address=LA_L — LA_L can be a single "log address", a range of log addresses, or a list of (ranges of) log addresses 🦋 A log address is a number between 0 and 255 (0xff), and log address 0, page number 0, is the directory. A range looks like "lo:hi", and "hi" has to be greater than or equal to "lo". A log address list is just a comma separated list of log addresses or ranges. Each log address can hold up to 256 (SMART log) or 65536 (General purpose log) page numbers, starting at page number 0. How many page numbers each log address actually has is listed in the log directory page 💅 Quick syntax summary: lo:hi,lo2:hi2,lo3:hi3 ...
• -C, --ck_cond — this one sets the CK_COND bit in the ATA PASS-THROUGH SCSI cdb 💖 The default is clear (i.e. 0). When it's set, the SATL should give you a sense buffer with an ATA Result descriptor no matter if the ATA command worked or failed. When it's clear, the SATL only gives you that sense buffer with an ATA Result descriptor if the ATA command failed.
• -c, --count=CO — the number CO goes into the "count" field of the ATA READ LOG EXT command 🍓 It tells the device how many 512-byte log pages to read from the given log address, starting at the given page number. The last page number read will be (PN + CO - 1), assuming it exists. The max for CO is 0xffff (65,535) for general purpose log pages and 0xff (255) for SMART log pages. If --page=PN (default 0) plus CO goes past the number shown in the log directory (log address 0) for that log address, you'll typically get an error 🙈 Also, CO only applies to the current log address. There's no wrap around into the next log address, so don't expect that 💀
• -d, --dma — uses the ATA READ LOG DMA EXT command instead of the ATA READ LOG EXT command. Some devices need this to return valid log data, so if you're getting nonsense, try this one 🔥
• -h, --help — outputs the usage message, which summarizes the command line options, then exits 🌸 If you give it a DEVICE, that gets ignored.
• -H, --hex — this one has levels, bestie 🎀
  • given once, the response comes out as ASCII hexadecimal bytes
  • given twice, the response is grouped into 16 bit words using ATA conventions (i.e. little endian). This is the default output, so you get it if you don't pass this option at all ✨
  • given thrice (i.e. -HHH), the output is hex grouped in 16 bit words, with no leading offset and no trailing ASCII on each line. The format is acceptable for hdparm --Istdin to process 🧚

If you invoke this option four times (e.g. -HHHH), log pages come out as hex bytes with no leading address at the start of each line. That makes the hex easier for computers to decode, though humans will have a harder time reading it 🤖

If you invoke it five times, a comment line starting with a # character is output before each 512 byte log page. That comment describes the log page that follows 💜

✨ COPYRIGHT ✨

okay so the legal stuff, but make it cute 🎀 Copyright © 2014-2023 Hannes Reinecke, SUSE Linux GmbH. This software is distributed under a BSD-2-Clause license. There is NO warranty, not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE 🙈

✨ SEE ALSO ✨

bestie, go check these out too 🫶 they're the lowkey best siblings of this one:

• sg_sat_identify(sg3_utils) 🧚
• sg_inq(sg3_utils) 💜
• sdparm(sdparm) ⭐
• hdparm(hdparm) 🌸
• smartctl(smartmontools) 🦋

and that's a wrap on sg_sat_read_gplog 💅✨ this page came from sg3_utils 1.48, January 2023, and honestly it's giving main character energy 👑 periodt 🌈