diff options
Diffstat (limited to 'doc/sg_sat_identify.8')
| -rw-r--r-- | doc/sg_sat_identify.8 | 167 |
1 files changed, 167 insertions, 0 deletions
diff --git a/doc/sg_sat_identify.8 b/doc/sg_sat_identify.8 new file mode 100644 index 00000000..595321c9 --- /dev/null +++ b/doc/sg_sat_identify.8 @@ -0,0 +1,167 @@ +.TH SG_SAT_IDENTIFY "8" "January 2020" "sg3_utils\-1.45" SG3_UTILS +.SH NAME +sg_sat_identify \- send ATA IDENTIFY DEVICE command via SCSI to ATA +Translation (SAT) layer +.SH SYNOPSIS +.B sg_sat_identify +[\fI\-\-ck_cond\fR] [\fI\-\-extend\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR] +[\fI\-\-ident\fR] [\fI\-\-len=CLEN\fR] [\fI\-\-packet\fR] [\fI\-\-raw\fR] +[\fI\-\-readonly\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR] \fIDEVICE\fR +.SH DESCRIPTION +.\" Add any additional description here +.PP +This utility sends either an ATA IDENTIFY DEVICE command or an ATA IDENTIFY +PACKET DEVICE command to \fIDEVICE\fR and outputs the response. The devices +that respond to these commands are ATA disks and ATAPI devices respectively. +Rather than send these commands directly to the device they are 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 firmware or in some external enclosure. +.PP +The SAT standard (SAT ANSI INCITS 431\-2007, prior draft: sat\-r09.pdf at +www.t10.org) defines two SCSI "ATA PASS\-THROUGH" commands: one using a 16 +byte "cdb" and the other with a 12 byte cdb. This utility defaults to using +the 16 byte cdb variant. SAT\-4 revision 5 added a SCSI "ATA +PASS\-THROUGH(32)" command. SAT\-2 and SAT\-3 are now also standards: SAT\-2 +ANSI INCITS 465\-2010 and SAT\-3 ANSI INCITS 517-2015 . The SAT\-4 project +is near standardization and the most recent draft is sat4r06.pdf . +.SH OPTIONS +Arguments to long options are mandatory for short options as well. +.TP +\fB\-c\fR, \fB\-\-ck_cond\fR +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 command succeeded or failed. When clear the SATL should only yield +a sense buffer containing a ATA Result descriptor if the command failed. +.TP +\fB\-e\fR, \fB\-\-extend\fR +sets the EXTEND bit in the ATA PASS\-THROUGH SCSI cdb. The +default setting is clear (i.e. 0). When set a 48 bit LBA command is sent +to the device. This option has no effect when \fI\-\-len=12\fR. +.TP +\fB\-h\fR, \fB\-\-help\fR +outputs the usage message summarizing command line options +then exits. Ignores \fIDEVICE\fR if given. +.TP +\fB\-H\fR, \fB\-\-hex\fR +outputs the ATA IDENTIFY (PACKET) DEVICE response in hex. The default +action (i.e. without any '\-H' options) is to output the response in +hex, grouped in 16 bit words (i.e. the ATA standard's preference). +When given once, the response is output in ASCII hex bytes (i.e. the +SCSI standard's preference). When given twice (i.e. '\-HH') the output +is in hex, grouped in 16 bit words, the same as the default but without +a header. When given thrice (i.e. '\-HHH') the output is in hex, grouped in +16 bit words, in a format that is acceptable for 'hdparm \-\-Istdin' to +process. '\-HHHH' simply outputs hex data bytes, space separated, 16 per +line. +.TP +\fB\-i\fR, \fB\-\-ident\fR +outputs the World Wide Name (WWN) of the device. This should be a NAA\-5 +64 bit number. It is output in hex prefixed with "0x". If not available +then "0x0000000000000000" is output. The equivalent for a SCSI disk (i.e. its +logical unit name) can be found with "sg_vpd \-ii". +.TP +\fB\-l\fR, \fB\-\-len\fR=CLEN +CLEN this is the length of the SCSI cdb used for the ATA PASS\-THROUGH +command. CLEN can either be 12, 16 or 32. The default is 16. The larger +cdb sizes are needed for 48 bit LBA addressing of ATA devices. The ATA +Auxiliary and ICC registers are only conveyed with the 32 byte cdb variant. +.TP +\fB\-p\fR, \fB\-\-packet\fR +send an ATA IDENTIFY PACKET DEVICE command (via the SATL). The default +action is to send an ATA IDENTIFY DEVICE command. Note that the ATAPI +specification by T13 (i.e. the PACKET interface) is now obsolete. +.TP +\fB\-r\fR, \fB\-\-raw\fR +output the ATA IDENTIFY (PACKET) DEVICE response in binary. The output +should be piped to a file or another utility when this option is used. +The binary is sent to stdout, and errors are sent to stderr. +.TP +\fB\-R\fR, \fB\-\-readonly\fR +open the \fIDEVICE\fR read\-only (e.g. in Unix with the O_RDONLY flag). +The default is to open it read\-write. +.TP +\fB\-v\fR, \fB\-\-verbose\fR +increases the level or verbosity. +.TP +\fB\-V\fR, \fB\-\-version\fR +print out version string +.SH NOTES +Since the response to the IDENTIFY (PACKET) DEVICE command is very +important for the correct use of an ATA(PI) device (and is typically the +first command sent), a SATL should provide an ATA Information VPD page +which contains the similar information. +.PP +The SCSI ATA PASS\-THROUGH (12) command's opcode is 0xa1 and it clashes with +the MMC set's BLANK command used by cd/dvd writers. So a SATL in front +of an ATAPI device that uses MMC (i.e. has peripheral device type 5) +probably should treat opcode 0xa1 as a BLANK command and send it through +to the cd/dvd drive. The ATA PASS\-THROUGH (16) command's opcode (0x85) +does not clash with anything so it is a better choice. +.PP +Prior to Linux kernel 2.6.29 USB mass storage limited sense data to 18 bytes +which made the \fB\-\-ck_cond\fR option yield strange (truncated) results. +.SH EXAMPLES +These examples use Linux device names and a Linux utility called hdparm. For +suitable device names in other supported Operating Systems see the +sg3_utils(8) man page. +.PP +In this example /dev/sdb is a SATA 2.5" disk connected via a USB (type C +connector) dongle that implements the UAS (USB attached SCSI) protocol (also +known as UASP). UAS is a vast improvement over the USB mass storage class. +.PP + # sg_sat_identify /dev/sdb +.br +Response for IDENTIFY DEVICE ATA command: +.br + 00 0c5a 3fff c837 0010 0000 0000 003f 0000 .Z ?. .7 .. .. .. .? .. +.br + .... +.PP +The hexadecimal ASCII (with plain ASCII to the right) output is abridged +to a single line (i.e. the first 16 bytes (or 8 words)). Now to decode +some of that ATA Identify response. First sg_inq can decode a few strings: +.PP + # sg_sat_identify \-HHHH /dev/sdb | sg_inq \-\-ata \-I \- +.br +ATA device: model, serial number and firmware revision: +.br + ST9500420AS 5VJCE6R7 0002SDM1 +.PP +For a lot more details, the hdparm utility is a good choice: +.PP + # sg_sat_identify \-HHH /dev/sdb | hdparm \-\-Istdin +.br +ATA device, with non\-removable media +.br + Model Number: ST9500420AS +.br + Serial Number: 5VJCE6R7 +.br + Firmware Revision: 0002SDM1 +.br + Transport: Serial +.br +Standards: +.br + .... +.PP +There are about 80 more lines of details decoded by hdparm in this case. +Notice the difference in the number of "H" options: three give an unadorned +hex output arranged in (little endian) words (i.e. 16 bits each) while +four "H" options give an unadorned hex output in bytes (i.e. 8 bits each). +.SH EXIT STATUS +The exit status of sg_sat_identify is 0 when it is successful. Otherwise +see the sg3_utils(8) man page. +.SH AUTHOR +Written by Douglas Gilbert +.SH "REPORTING BUGS" +Report bugs to <dgilbert at interlog dot com>. +.SH COPYRIGHT +Copyright \(co 2006\-2020 Douglas Gilbert +.br +This software is distributed under a BSD\-2\-Clause license. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +.SH "SEE ALSO" +.B sg_vpd(sg3_utils), sg_inq(sg3_utils), sdparm(sdparm), hdparm(hdparm) |