Read a SATA General Purpose Log Through SAT

You will finish with a repeatable way to read an ATA General Purpose log through a SCSI to ATA Translation (SAT) layer, save the hexadecimal response, and tell a bad device path from an unsupported transport. The command does not decode the log for you. It prints the returned bytes, normally grouped as ATA-style little-endian 16-bit words.

Allow about fifteen minutes for a first inspection. You need the sg3-utils package, a SATA disk or SSD that exposes SAT through the chosen SCSI device, and permission to open that device. Reading a log is not a filesystem repair operation, but it does send an ATA command to real hardware. Confirm the target before running it, and use a maintenance window if the disk belongs to a busy service.

This guide was checked with Ubuntu package sg3-utils 1.46-3ubuntu4. The installed binary reports version: 1.20 20180628, while the local manpage identifies its reference text as sg3_utils-1.41. Use the installed command's help as the final word if those documents differ.

1. Confirm the installed command

Start with read-only inspection of the binary and its interface. These commands do not touch a disk:

$ command -v sg_sat_read_gplog
/usr/bin/sg_sat_read_gplog
$ sg_sat_read_gplog --version
version: 1.20 20180628
$ dpkg-query -W -f='${Package} ${Version}\n' sg3-utils
sg3-utils 1.46-3ubuntu4

The version discrepancy is useful evidence, not a reason to guess. It can occur when the package metadata and the utility's own version string come from different release conventions. Record both when reporting a problem.

Checkpoint: confirm that the program is present and note the version string you will include in any support report.

2. Identify the SAT device

The final argument is a SCSI device path, not a mount point and not automatically a partition. Common examples are /dev/sg2 or another generic SCSI device node. The number is host-specific, so do not copy it from this guide. Map the disk to its SCSI generic device with the tools already used on your host, then verify the identity before reading it.

For example, list the available generic SCSI nodes and inspect the one you intend to use:

$ ls -l /dev/sg*
$ sg_inq /dev/sgX
$ readlink -f /dev/sgX

Replace sgX with an actual node. sg_inq is a separate sg3-utils utility and is used here only to identify the path. If the node does not describe the SATA device you expect, stop. A successful command against the wrong disk is still the wrong result.

Device access commonly requires elevated privileges. Try the identification command as your ordinary account first. If the operating system denies access, use sudo for that one command or arrange the appropriate group permission according to your system policy. Do not make a broad permission change just to avoid one access error.

3. Read the log directory first

With the target confirmed, read log address zero and page zero. The manpage describes log address zero as the directory of available logs. The installed command defaults to both values, but writing them explicitly makes a script and its audit trail easier to understand:

$ sudo sg_sat_read_gplog --readonly --log=0 --page=0 /dev/sgX

The command normally exits silently apart from the hexadecimal response when it succeeds. Its exit status is the first check:

$ printf 'exit status: %s\n' "$?"
exit status: 0

Do not treat a block of hexadecimal as decoded meaning. This utility currently does not interpret individual log pages. Keep the raw response, the exact command line, and the device identity together. A page directory can tell you which addresses exist, but interpreting a particular page requires the relevant ATA specification or the disk vendor's documentation.

Checkpoint: you have a response from the intended device and an exit status of zero. If the command failed, stay with the diagnosis in step 6 instead of changing several options at once.

4. Capture a known log and preserve the raw bytes

Once you know the log address and page number you need, pass them with --log and --page. For a safe capture, redirect standard output to a new file rather than overwriting an existing record:

$ sudo sg_sat_read_gplog --readonly --log=LOG_ADDRESS --page=PAGE_NUMBER /dev/sgX > sat-log.txt
$ status=$?
$ printf 'exit status: %s\n' "$status"
exit status: 0
$ test -s sat-log.txt && echo 'capture is non-empty'
capture is non-empty

Replace LOG_ADDRESS and PAGE_NUMBER with decimal values that you have verified. The documented ranges are 0 through 255 for the log address and 0 through 65535 for the page number. The command reads --count 512-byte blocks; the installed help reports a default count of one. Set it explicitly when the page format requires more than one block:

$ sudo sg_sat_read_gplog --readonly --count=2 --log=LOG_ADDRESS --page=PAGE_NUMBER /dev/sgX > sat-log-2-blocks.txt

Shell redirection creates or truncates its destination before the utility runs. Choose a fresh filename or use a temporary name and rename it only after a successful exit:

$ sudo sg_sat_read_gplog --readonly --log=LOG_ADDRESS --page=PAGE_NUMBER /dev/sgX > sat-log.txt.new
$ status=$?
$ if [ "$status" -eq 0 ] && [ -s sat-log.txt.new ]; then mv sat-log.txt.new sat-log.txt; else rm -f sat-log.txt.new; fi
$ exit "$status"

The final line returns the utility's status to the calling shell. If you already had a useful sat-log.txt, a failed read leaves it in place. Removing the temporary file is safe; do not remove the old capture until the replacement has been checked.

5. Select the output form deliberately

By default, the response is shown as hexadecimal grouped into 16-bit words using ATA little-endian conventions. That is convenient for reading ATA documentation, but it is not the byte order used to write the SCSI command itself. The distinction matters when comparing output with a SCSI trace.

Use one --hex for hexadecimal bytes, two for the default-style word grouping, and three for word-grouped output without offsets or trailing ASCII. The third form is intended to be accepted by hdparm --Istdin:

$ sudo sg_sat_read_gplog --readonly --hex --log=0 --page=0 /dev/sgX
$ sudo sg_sat_read_gplog --readonly -HHH --log=0 --page=0 /dev/sgX

Use the form that matches the next tool or the evidence format you are documenting. Do not call --hex repeatedly by accident in a script: -H, -HH and -HHH are different output modes.

6. Diagnose transport and device failures

A non-zero exit status means the operation was not successful. Add --verbose to expose more detail, while keeping the same device and log values:

$ sudo sg_sat_read_gplog --readonly --verbose --log=0 --page=0 /dev/sgX
$ printf 'exit status: %s\n' "$?"

First re-check the path with sg_inq. Then check whether the enclosure, HBA or operating-system driver actually provides SAT. This utility sends ATA READ LOG EXT through an ATA PASS-THROUGH SCSI command; it cannot make a non-SAT path understand that command. Some transports also cannot convey the default 16-byte CDB. If the transport is limited to 12-byte commands, try the documented alternative:

$ sudo sg_sat_read_gplog --readonly --len=12 --log=0 --page=0 /dev/sgX

Use that option because the transport requires it, not as a general retry. If a device needs the DMA form to return valid data, use --dma:

$ sudo sg_sat_read_gplog --readonly --dma --log=0 --page=0 /dev/sgX

The ordinary command uses ATA READ LOG EXT. The DMA variant is a compatibility choice for devices that require it, not a guarantee that every bridge supports it.

7. Keep the safety boundaries clear

--readonly opens the device with the Unix read-only flag. It is the sensible default for an inspection workflow because the program otherwise opens the device read-write. The utility still sends a command to the drive, and read-only opening does not fix a broken bridge or prevent every device-side effect. Do not use this command as evidence that a disk is healthy under load.

--ck_cond requests an ATA Result descriptor in the SCSI sense buffer whether the ATA command succeeds or fails. It is useful when you need lower-level result information, but it makes output and diagnosis more transport-dependent:

$ sudo sg_sat_read_gplog --readonly --ck_cond --verbose --log=0 --page=0 /dev/sgX

Use it when collecting evidence for a SAT problem, not as a routine spell to make a failed read work. Older USB mass-storage paths can truncate sense data, producing misleading results. Capture the command, utility version and bridge details before escalating.