sg_ses: further NVMe support work; decode array status dpage (obsolete); build: add SG_LIB_ANDROID

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

5 files changed, 97 insertions, 25 deletions

diff --git a/doc/sg_format.8 b/doc/sg_format.8
index 8733f797..449fa605 100644
--- a/doc/sg_format.8
+++ b/doc/sg_format.8
@@ -428,8 +428,8 @@ The SBC\-2 standard states that the block count can be set back to the
 manufacturer's maximum recommended value in a format or resize operation.
 This can be done by placing an address of 0xffffffff (or the 64 bit
 equivalent) in the appropriate block descriptor field to a MODE SELECT
-command. In signed (two's complement) arithmetic that value corresponds to
-'\-1'. So a \fI\-\-count=\fR\-1 causes the block count to be set back to
+command. In signed (two's complement) arithmetic that value corresponds
+to '\-1'. So a \-\-count=\-1 causes the block count to be set back to
 the manufacturer's maximum recommended value. To see exactly which SCSI
 commands are being executed and parameters passed add the "\-vvv" option to
 the sg_format command line.
diff --git a/doc/sg_inq.8 b/doc/sg_inq.8
index 8a4c84bd..ef8b77f1 100644
--- a/doc/sg_inq.8
+++ b/doc/sg_inq.8
@@ -1,4 +1,4 @@
-.TH SG_INQ "8" "September 2017" "sg3_utils\-1.43" SG3_UTILS
+.TH SG_INQ "8" "December 2017" "sg3_utils\-1.43" SG3_UTILS
 .SH NAME
 sg_inq \- issue SCSI INQUIRY command and/or decode its response
 .SH SYNOPSIS
@@ -6,15 +6,15 @@ sg_inq \- issue SCSI INQUIRY command and/or decode its response
 [\fI\-\-ata\fR] [\fI\-\-block=0|1\fR] [\fI\-\-cmddt\fR]
 [\fI\-\-descriptors\fR] [\fI\-\-export\fR] [\fI\-\-extended\fR]
 [\fI\-\-force\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-id\fR]
-[\fI\-\-inhex=FN\fR] [\fI\-\-len=LEN\fR] [\fI\-\-maxlen=LEN\fR]
-[\fI\-\-page=PG\fR] [\fI\-\-raw\fR] [\fI\-\-vendor\fR] [\fI\-\-verbose\fR]
-[\fI\-\-version\fR] [\fI\-\-vpd\fR] \fIDEVICE\fR
+[\fI\-\-inhex=FN\fR] [\fI\-\-len=LEN\fR]  [\fI\-\-long\fR]
+[\fI\-\-maxlen=LEN\fR] [\fI\-\-page=PG\fR] [\fI\-\-raw\fR] [\fI\-\-vendor\fR]
+[\fI\-\-verbose\fR] [\fI\-\-version\fR] [\fI\-\-vpd\fR] \fIDEVICE\fR
 .PP
 .B sg_inq
 [\fI\-36\fR] [\fI\-a\fR] [\fI\-A\fR] [\fI\-b\fR] [\fI\-\-B=0|1\fR]
 [\fI\-c\fR] [\fI\-cl\fR] [\fI\-d\fR] [\fI\-e\fR] [\fI\-f\fR]
 [\fI\-h\fR] [\fI\-H\fR] [\fI\-i\fR] [\fI\-I=FN\fR] [\fI\-l=LEN\fR]
-[\fI\-m\fR] [\fI\-M\fR] [\fI\-o=OPCODE_PG\fR] [\fI\-p=VPD_PG\fR]
+[\fI\-L\fR] [\fI\-m\fR] [\fI\-M\fR] [\fI\-o=OPCODE_PG\fR] [\fI\-p=VPD_PG\fR]
 [\fI\-P\fR] [\fI\-r\fR] [\fI\-s\fR] [\fI\-u\fR] [\fI\-v\fR]
 [\fI\-V\fR] [\fI\-x\fR] [\fI\-36\fR] [\fI\-?\fR] \fIDEVICE\fR
 .SH DESCRIPTION
@@ -48,6 +48,13 @@ tried. If it succeeds then device identification strings are output. The
 If the \fI\-\-ata\fR option is given then the SCSI INQUIRY is not performed
 and the \fIDEVICE\fR is assumed to be ATA (or ATAPI).
 .PP
+In some operating systems a NVMe device (e.g. SSD) may be given as the
+\fIDEVICE\fR. An Identify command is sent to the controller followed
+by an namespace if \fIDEVICE\fR is associated with a namespace. If not,
+for example if \fIDEVICE\fR corresponds to a controller, then an Identify
+is sent to the controller and then an Identify coomand is sent to all
+attached namespaces.
+.PP
 The reference document used for interpreting an INQUIRY is T10/BSR INCITS
 502 Revision 07 which is draft SPC\-5 revision 07, 26 November 2015). It can
 be found at http://www.t10.org . Obsolete and reserved items in the standard
@@ -164,6 +171,10 @@ length" field in the response indicates that more than 36 bytes is available.
 If \fILEN\fR is greater than 0 then only one INQUIRY command is performed.
 See paragraph below about "36 byte INQUIRYs".
 .TP
+\fB\-L\fR, \fB\-\-long\fR
+this option causes more information to be decoded from the Identify command
+sent to a NVMe \fIDEVICE\fR.
+.TP
 \fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR
 this option has the same action as the \fI\-\-len=LEN\fR option. It has
 been added for compatibility with the sg_vpd, sg_modes and sg_logs
@@ -352,6 +363,12 @@ response in hex use '\-p=83 \-h'.
 \fB\-I\fR=\fIFN\fR
 equivalent to \fI\-\-inhex=FN\fR in the OPTIONS section.
 .TP
+\fB\-l\fR=\fILEN\fR
+equivalent to \fI\-\-len=LEN\fR in the OPTIONS section.
+.TP
+\fB\-L\fR
+equivalent to \fI\-\-long\fR in the OPTIONS section.
+.TP
 \fB\-m\fR
 decodes the Management network addresses VPD page [0x85]. Equivalent
 to '\-\-page=mna' in the OPTIONS section.
diff --git a/doc/sg_ses.8 b/doc/sg_ses.8
index 4d015c8c..8042b059 100644
--- a/doc/sg_ses.8
+++ b/doc/sg_ses.8
@@ -1,4 +1,4 @@
-.TH SG_SES "8" "November 2017" "sg3_utils\-1.43" SG3_UTILS
+.TH SG_SES "8" "December 2017" "sg3_utils\-1.43" SG3_UTILS
 .SH NAME
 sg_ses \- access a SCSI Enclosure Services (SES) device
 .SH SYNOPSIS
@@ -142,7 +142,7 @@ index field is 1 (in other words a heuristic to guess whether the EIIOE field
 should be set to 1 or 0).
 .br
 If the enclosure sets the actual EIIOE field to 1 or more then this option has
-no effect. It is recommended that HP JBOD users set --eiioe=auto .
+no effect. It is recommended that HP JBOD users set \-\-eiioe=auto .
 .TP
 \fB\-e\fR, \fB\-\-enumerate\fR
 enumerate all known page names and SES elements when this option is given
@@ -347,6 +347,10 @@ Enclosure Status page has only one "overall" element corresponding to that
 type header. The Element Descriptor page and the Threshold (In and Out)
 pages follow the same pattern as the Enclosure Status page.
 .PP
+The numeric index corresponding to the overall element is "\-1". If the
+Configuration page indicates a particular element type has "n" elements
+and n is greater than 0 then its indexes range from 0 to n-\1 . 
+.PP
 The Additional Element Status page is a bit more complicated. It has
 entries for "Number of possible elements" of certain Element types. It
 does not have entries corresponding to the "overall" elements. To make
@@ -377,7 +381,7 @@ individual index then the option is equivalent to \fI\-\-index=0,II\fR. When
 .PP
 Wherever an individual index is applicable, it can be replaced by an
 individual index range. It has the form: <first_ii>-<last_ii>. For
-example: '3-5' will select individial indexes 3, 4 and 5 .
+example: '3\-5' will select individial indexes 3, 4 and 5 .
 .PP
 To cope with vendor specific Element types (which should be in the range 128
 to 255) the Element type can be given as a number with a leading underscore.
diff --git a/doc/sg_write_x.8 b/doc/sg_write_x.8
index 73fd8c30..294096d4 100644
--- a/doc/sg_write_x.8
+++ b/doc/sg_write_x.8
@@ -231,12 +231,22 @@ commands supported by thus utility except WRITE SAME.
 \fB\-x\fR, \fB\-\-dry\-run\fR
 this option exits (with a status of 0) just before it would otherwise send
 the selected SCSI write command. It may still send a SCSI READ CAPACITY
-command (16 byte variant and perhaps 10 byte variant as well) and read
-the data in and process it if the \fI\-\-in=IF\fR and/or the
-\fI\-\-scat\-file=SF\fR options are given. All command line processing
-and sanity checks (e.g. if the \fI\-\-strict\fR option is given) will be
-performed and if there is an error then there will be a non zero exit
-status value.
+command (16 byte variant and perhaps 10 byte variant as well) so the
+\fIDEVICE\fR is still required. It reads the data in and processes it if the
+\fI\-\-in=IF\fR and/or the \fI\-\-scat\-file=SF\fR options are given. All
+command line processing and sanity checks (e.g. if the \fI\-\-strict\fR
+option is given) will be performed and if there is an error then there will
+be a non zero exit status value.
+.br
+If this option is given twice (e.g. \-xx) then instead of performing the
+selected write SCSI command, the data\-out buffer is written to a file
+called sg_write_x.bin . If it doesn't exist then that file is created in
+the current directory and is truncated if it previously did exist with
+longer contents. The data\-out buffer is written in binary with some
+information about it written to stdout. For writes other than scattered
+the filename and its length in bytes is output to stdout. For write
+scattered additionally its number of LBA range descriptors and its
+logical block data offset written to stdout.
 .TP
 \fB\-f\fR, \fB\-\-fua\fR
 if this option is given then the FUA (force unit access) bit field in the
@@ -491,7 +501,9 @@ The exit status of sg_write_x is 0 when it is successful. Otherwise see
 the sg3_utils(8) man page.
 .SH EXAMPLES
 One simple usage is to write 4 blocks of zeros from (and including) a given
-LBA:
+LBA according to the rules of WRITE ATOMIC with an atomic boundary of 0.
+Since no cdb size option is given, the 16 byte cdb will be assumed (i.e.
+WRITE ATOMIC(16)):
 .PP
   sg_write_x \-\-atomic=0 \-\-in=/dev/zero \-\-lba=0x1234 \-\-num=4 /dev/sdc
 .PP
@@ -507,8 +519,10 @@ LBA 0x1234 . Now to bypass the need for the READ CAPACITY command(s) the
   sg_write_x \-\-atomic=0 \-\-bs=512 \-\-in=/dev/zero \-\-lba=0x1234 \-\-num=4
 /dev/sdc
 .PP
-Both of the examples above issue a SCSI WRITE ATOMIC(16) command. To send the
-32 byte variant add \-\-32 as in:
+Since \-\-bs= is given and its value (512) is a power of 2, then the actual
+block size is also 512. If instead 520 was given then the logical block size
+would be 512 (the highest power of 2 less than 520) and the actual block size
+would be 520 bytes. To send the 32 byte variant add \-\-32 as in:
 .PP
   sg_write_x \-\-atomic=0 \-\-32 \-\-bs=512 \-\-in=/dev/zero \-\-lba=0x1234
 \-\-num=4 /dev/sdc
@@ -518,11 +532,47 @@ To send a WRITE STREAM(32) with a STR_ID of 1 use the following:
   sg_write_x \-\-stream=1 \-\-32 \-\-bs=512 \-\-in=/dev/zero \-\-lba=0x1234
 \-\-num=4 /dev/sdc
 .PP
+Next is a WRITE SCATTERED(16) command with the scatter list, split between
+the \-\-lba= and \-\-num= options, on the command line:
+.PP
+  sg_write_x  \-\-scattered=2 \-\-lba=2,0x33 \-\-num=4,1 -i /dev/zero /dev/sg1
+.PP
+Example of a WRITE SCATTERED(16) command with a degenerate LBA range
+descriptor (first element to \-\-lba= and \-\-num=):
+.PP
+  sg_write_x  \-\-scattered=2 \-\-lba=0,0x33 \-\-num=0,1 -i /dev/zero /dev/sg1
+.PP
 Example of a WRITE SCATTERED(16) command with the scatter list in
 scat_file.txt
-  sg_write_x  \-\-scattered=3 \-q scat_file.txt \-i /dev/zero /dev/sg
 .PP
-xxxxxx More examples ...
+  sg_write_x  \-\-scattered=3 \-q scat_file.txt \-i /dev/zero /dev/sg1
+.PP
+Next a WRITE SCATTERED(16) command with its scatter list and data in a
+single file. Note that the argument to \-\-scattered= is 0 so the number of
+LBA range descriptors is calculated by analyzing the first two blocks of
+scat_data.bin (because the argument to \-\-combined= is 2) :
+.PP
+  sg_write_x  \-\-scattered=0 \-\-combined=2 \-i scat_data.bin /dev/sg1
+.PP
+When the \-xx option is used, a WRITE SCATTERED command is not executed
+but instead the contents of the data\-out buffer are written to a file
+called sg_write_x.bin . In the case of WRITE SCATTERED that binary file
+is suitable for supplying to a later invocation to do the actual write
+to media. For example:
+.PP
+  sg_write_x  \-\-scattered=3 \-q scat_file.txt \-xx \-i /dev/zero /dev/sg1
+.br
+Wrote 8192 bytes to sg_write_x.bin, LB data offset: 1
+.br
+Number of LBA range descriptors: 3
+.br
+  sg_write_x  \-\-scattered=0 \-\-combined=1 \-i sg_write_x.bin /dev/sg1
+.PP
+Notice when the sg_write_x.bin is written (and nothing is written to the
+media), a summary of what has happened is sent to stdout. The value shown
+for "LB data offset:" (1) should be given to the \-\-combined= option
+when the write to media actually occurs (i.e. the second invocation shown
+directly above).
 .SH AUTHORS
 Written by Douglas Gilbert.
 .SH "REPORTING BUGS"
diff --git a/doc/sgp_dd.8 b/doc/sgp_dd.8
index 6d148f52..9a0ead5c 100644
--- a/doc/sgp_dd.8
+++ b/doc/sgp_dd.8
@@ -1,4 +1,4 @@
-.TH SGP_DD "8" "November 2012" "sg3_utils\-1.35" SG3_UTILS
+.TH SGP_DD "8" "December 2017" "sg3_utils\-1.43" SG3_UTILS
 .SH NAME
 sgp_dd \- copy data to and from files and devices, especially SCSI
 devices
@@ -17,8 +17,9 @@ devices
 Copy data to and from any files. Specialised for "files" that are
 Linux SCSI generic (sg) and raw devices. Similar syntax and semantics to
 .B dd(1)
-but does not perform any conversions. Uses POSIX threads to increase
-the amount of parallelism. This improves speed in some cases.
+but does not perform any conversions. Uses POSIX threads (often
+called "pthreads") to increase the amount of parallelism. This improves
+speed in some cases.
 .PP
 The first group in the synopsis above are "standard" Unix
 .B dd(1)
@@ -302,7 +303,7 @@ Written by Douglas Gilbert and Peter Allworth.
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
-Copyright \(co 2000\-2012 Douglas Gilbert
+Copyright \(co 2000\-2017 Douglas Gilbert
 .br
 This software is distributed under the GPL version 2. There is NO
 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.