Ubuntu Manpage: sg_sat_read_gplog - use ATA READ LOG EXT or SMART READ LOG command via a SCSI to ATA Translation (SAT)

Provided by: sg3-utils_1.48-2ubuntu1_amd64

NAME

       sg_sat_read_gplog  -  use  ATA READ LOG EXT or SMART READ LOG command via a SCSI to ATA Translation (SAT)
       layer

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

This utility sends an ATA READ LOG EXT, an ATA READ LOG DMA EXT, or an ATA SMART READ LOG command to the
DEVICE. The default is to send one of the first two commands to read "general purpose log" page(s). Only
(S)ATA devices (e.g. disks) but not ATAPI devices (e.g. DVD readers) support the general purpose log
pages. Rather than send the READ LOG (DMA) EXT command directly to the device it is sent via a SCSI
transport which is assumed to contain a SCSI to ATA Translation (SAT) Layer (SATL). The SATL may be in an
operating system driver, in host bus adapter (HBA) firmware or in some external enclosure.

This utility does not currently attempt to decode the response from the ATA disk, rather it outputs the
response in ASCII hexadecimal grouped in 8 bit bytes or 16 bit words. Following ATA conventions those
words are decoded little endian (note that SCSI commands use a big endian representation). Log address 0,
page number 0 is the 'directory' log page and it is decoded if no --hex option is given. In the future
this utility may attempt to decode other log pages. Perhaps other ATA utility will be able to decode
these log pages given hex output from this utility.

Fetching all log pages seems as simple as reading the directory log page then accessing those log
addresses that have more than zero associated page numbers. Unfortunately it is not that simple. Some log
addresses (looking specifically at 0xe1 ("SCT Data transfer")) need a SCT command executed prior to
fetching the log page at that log address. Other log addresses might be problematic (e.g. it has been
suggested that the "Device vendor specific logs" 0xa0:0xdf) so maybe they also should be avoided. That is
the reason the --address=LA_L and --log=LA_L options are designed to 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 using a 12 byte "cdb", another using a 16 bytes cdb, and the third a 32
byte cdb. This utility defaults to using the 16 byte cdb variant.

OPTIONS

Arguments to long options are mandatory for short options as well.

-a, --address=LA_L
where LA_L is as 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) where log address 0, page number 0,
is a directory. A range of log addresses has the form "lo:hi" where log address "hi" must be
greater than or equal to "lo". A log address list is a comma separated list of log addresses or
log address ranges.
Each log address contain up to 256 (SMART log) or 65536 (General purpose log) page numbers,
starting at page number 0. The number of page numbers available for each log address is enumerated
in the log directory page.
Summary of LA_L syntax: lo:hi,lo2:hi2,lo3:hi3 ...

-C, --ck_cond
sets the CK_COND bit in the ATA PASS-THROUGH SCSI cdb. The default setting is clear (i.e. 0). When
set the SATL should yield a sense buffer containing a ATA Result descriptor irrespective of
whether the ATA command succeeded or failed. When clear the SATL should only yield a sense buffer
containing an ATA Result descriptor if the ATA command failed.

-c, --count=CO
the number CO is placed in the "count" field in the ATA READ LOG EXT command. This specified the
number of 512-byte log pages of data to be read from the specified log address. The given page
address starting at the given page number is read. The last page number read will be (PN + CO - 1)
if it exists.
The maximum value of CO is 0xffff (65,535) for general purpose log pages and 0xff (255) for SMART
log pages.
An error is typically reported if the given --page=PN (default 0) plus CO exceeds the number shown
in the log directory (log address 0) for the given log address.
Note that the CO only applies to the current log address; in other words there is no wrap around
to the beginning of the next log address.

-d, --dma
use the ATA READ LOG DMA EXT command instead of ATA READ LOG EXT command. Some devices require
this to return valid log data.

-h, --help
outputs the usage message summarizing command line options then exits. Ignores DEVICE if given.

-H, --hex
when given once, the response is output in ASCII hexadecimal bytes. When given twice, then the
response is grouped into 16 bit words using ATA conventions (i.e. little endian); this is the
default output (i.e. when this option is not given). When given thrice (i.e. '-HHH') the output is
in hex, grouped in 16 bit words (without a leading offset and trailing ASCII on each line), in a
format that is acceptable for 'hdparm --Istdin' to process.

If this option is invoked four times (e.g. '-HHHH') log pages are output as hex bytes, with no leading
address at the start of each line. That makes the hex easier for computers to decode (but not humans). If
this option is invoked five times then a comment line, starting with a '#' character is output before
each 512 byte log page. The comment describes the following log page.

-l, --len=CMD_LEN
where CMD_LEN is the command (cdb) length of the SCSI ATA PASS-THROUGH command that is used to
tunnel ATA commands. Three values are permitted: 12, 16 and 32 (bytes long). The 12 byte variant
has the most restrictions (e.g. its 'count' field is a single byte) but older systems may not
permit 16 or 32 byte commands.

-L, --log=LA_L
see the --address=LA_L option.

-p, --page=PN
the number PN is the page number (within the log address) and is placed in bits 32:16 of the "lba"
field of the ATA READ LOG (DMA) EXT command. The default value placed in the "lba" field is 0.
The maximum value of PN is 0xffff (65,535) for general purpose log pages and 0xff (255) for SMART
log pages. In the latter case PN must be 0 and CO is 255.

When multiple log addresses are specified (via the LA_L argument) then this option is treated
differently. With multiple log addresses and if PN is greater than 0 then it acts as an upper limit of
the number of page numbers that will be output for each log address. The actual number of 512 byte log
pages output will also depend on the number of page numbers shown in the directory log page for the
current log address.

-P, --ppt=PPT
where PPT is the number of pages to transfer from the DEVICE per ATA READ LOG EXT or an ATA READ
LOG DMA EX command invocation. The default value is 128 (or 64 kibiBytes) which is chosen because
most OSes have an upper limit on the size of transfers to and from a device with a single command.
When the number of log pages given with the --count=CO option is large , it can exceed what an OS
will allow in a single command invocation. Hence the need for this option.

-l, --len={32|16|12}
this is the length of the SCSI cdb used for the ATA PASS-THROUGH commands. The argument can
either be 32, 16 or 12. The default is 16. Some SCSI transports cannot convey SCSI commands longer
than 12 bytes.

-r, --readonly
causes the DEVICE to be opened with the read-only flag (O_RDONLY in Unix). The default action is
to open DEVICE with the read-write flag (O_RDWR in Unix). In some cases sending power management
commands to ATA disks are defeated by OS actions on the close() if the DEVICE was opened with the
read-write flag (e.g. the OS might think it needs to flush something to disk).

-s, --smart
in the ATA SMART feature set, "SMART" log pages have been present for a long time and pre-date the
later addition of the "general purpose" log pages. So this utility can be easily be extended to
read "SMART" log pages instead of the general purpose log pages. That is exactly what this option
does.
The ATA SMART READ LOG command has no page number field, all fetches start from page number 0.
Also the number of page numbers (in it log address) is limited to a single byte (so 255). The
general purpose log directory page and the SMART log directory page have the same format (given
the single byte restriction on the number of page numbers in each SMART log address).

-v, --verbose
increases the level or verbosity.

-V, --version
print out version string

NOTES

       Prior to Linux kernel 2.6.29 USB mass storage limited sense data to 18 bytes  which  made  the  --ck_cond
       option yield strange (truncated) results.

       There  are  slight  differences in handling when a single log address is being fetched, and when multiple
       log pages are being fetched. In the single log address case the log address,  the  page  number  and  the
       count  going  into  the corresponding fields in the ATA READ LOG EXT or ATA SMART READ LOG command.  When
       multiple log addresses are given, the  'directory'  log  page  (log_address=0,  page_number=0)  is  first
       loaded.  Then  only log addresses which the directory indicates have more than zero log page numbers, are
       fetched. The count of log page numbers accessed may be further restricted by the --page=PN option  if  PN
       is greater than zero.

EXAMPLES

       First here is an example avoiding the problematic log addresses noted in the DESCRIPTION section above.

         sg_sat_read_gplog -a 0:0xb,0xd:0x9f,0xe0,0xe2:255 /dev/sdc

       The above is using the short form of the --address=LA_L option with a list that avoids log addresses 0xc,
       0xa0  to 0xdf and 0xe1 . The output will include all log addresses, apart from those exclusions, that the
       directory indicates have more than 0 page numbers.
       The following invocation uses the SMART READ LOG command instead of the READ LOG EXT command:

         sg_sat_read_gplog --smart -a 0:0xb,0xd:0x9f,0xe0,0xe2:255 /dev/sdc

EXIT STATUS

       The exit status of sg_sat_read_gplog is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

AUTHOR

       Written by Hannes Reinecke and Douglas Gilbert

REPORTING BUGS

       Report bugs to <dgilbert at interlog dot com>.

COPYRIGHT

       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.