1 files changed, 109 insertions, 0 deletions
diff --git a/doc/sg_sat_phy_event.8 b/doc/sg_sat_phy_event.8
new file mode 100644
index 00000000..8b842a3f
--- /dev/null
+++ b/doc/sg_sat_phy_event.8
@@ -0,0 +1,109 @@
+.TH SG_SAT_PHY_EVENT "8" "July 2020" "sg3_utils\-1.46" SG3_UTILS
+.SH NAME
+sg_sat_phy_event \- use ATA READ LOG EXT via a SAT pass\-through to fetch
+SATA phy event counters
+.SH SYNOPSIS
+.B sg_sat_phy_event
+[\fI\-\-ck_cond\fR] [\fI\-\-extend\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR]
+[\fI\-\-ignore\fR] [\fI\-\-len=\fR{16|12}] [\fI\-\-raw\fR] [\fI\-\-reset\fR]
+[\fI\-\-verbose\fR] [\fI\-\-version\fR] \fIDEVICE\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+This utility sends an ATA READ LOG EXT with the log page ("address") set to
+11h to \fIDEVICE\fR and outputs the response. Log page 11h is defined in
+the SATA 2.5 standard and contains phy event counters. Rather than send this
+command directly to the \fIDEVICE\fR, 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\-2 is also a standard: SAT\-2 ANSI INCITS
+465\-2010 and the draft prior to that is sat2r09.pdf . The SAT-3 project has
+started and the most recent draft is sat3r01.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 READ LOG EXT 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.
+.TP
+\fB\-i\fR, \fB\-\-ignore\fR
+usually the phy counter identifier names are decoded. When this option is
+given, the numeric value of the identifier is output, the vendor flag, the
+data length (in bytes) and the corresponding value.
+.TP
+\fB\-l\fR, \fB\-\-len\fR={16|12}
+this is the length of the SCSI cdb used for the ATA PASS\-THROUGH commands.
+The argument can either be 16 or 12. The default is 16. The larger cdb
+size is needed for 48 bit LBA addressing of ATA devices. On the other
+hand some SCSI transports cannot convey SCSI commands longer than 12 bytes.
+.TP
+\fB\-r\fR, \fB\-\-raw\fR
+output the ATA READ LOG EXT 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\-\-reset\fR
+reset the counters after the current values are returned, decoded and
+displayed.
+.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
+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
+In the 2.4 series of Linux kernels the \fIDEVICE\fR must be
+a SCSI generic (sg) device. In the 2.6 series block devices (e.g. disks
+and ATAPI DVDs) can also be specified. For example "sg_inq /dev/sda"
+will work in the 2.6 series kernels. From lk 2.6.6 other SCSI "char"
+device names may be used as well (e.g. "/dev/st0m"). Prior to lk 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 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_sat_identify,sg_sat_read_gplog(sg3_utils),
+.B smp_rep_phy_err_log(smp_utils),sdparm(sdparm),hdparm(hdparm)