sg_ses_microcode: add --dry-run and --ealsd; sg_write_buffer: add --dry-run

git-svn-id: https://svn.bingwo.ca/repos/sg3_utils/trunk@744 6180dd3e-e324-4e3e-922d-17de1ae2f315

1 files changed, 52 insertions, 3 deletions

diff --git a/doc/sg_sat_identify.8 b/doc/sg_sat_identify.8
index db05d0f2..aee34674 100644
--- a/doc/sg_sat_identify.8
+++ b/doc/sg_sat_identify.8
@@ -1,4 +1,4 @@
-.TH SG_SAT_IDENTIFY "8" "October 2017" "sg3_utils\-1.43" SG3_UTILS
+.TH SG_SAT_IDENTIFY "8" "January 2018" "sg3_utils\-1.43" SG3_UTILS
 .SH NAME
 sg_sat_identify \- send ATA IDENTIFY DEVICE command via SCSI to ATA
 Translation (SAT) layer
@@ -24,7 +24,7 @@ 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 ongiong and the most recent draft is sat4r05c.pdf .
+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
@@ -102,6 +102,55 @@ 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.
@@ -110,7 +159,7 @@ Written by Douglas Gilbert
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
-Copyright \(co 2006\-2017 Douglas Gilbert
+Copyright \(co 2006\-2018 Douglas Gilbert
 .br
 This software is distributed under a FreeBSD license. There is NO
 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.