sg_opcodes: add --mask option; sg_rbuf: add --echo option; sg_lib: fix output truncation error

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

4 files changed, 44 insertions, 24 deletions

diff --git a/doc/sg_format.8 b/doc/sg_format.8
index 816424c9..903ab0f6 100644
--- a/doc/sg_format.8
+++ b/doc/sg_format.8
@@ -1,6 +1,6 @@
 .TH SG_FORMAT "8" "April 2014" "sg3_utils\-1.39" SG3_UTILS
 .SH NAME
-sg_format \- format or resize a SCSI disk (perhaps change its block size)
+sg_format \- format, resize or modify protection information of a SCSI disk
 .SH SYNOPSIS
 .B sg_format
 [\fI\-\-cmplst=\fR{0|1}] [\fI\-\-count=COUNT\fR] [\fI\-\-dcrt\fR]
@@ -45,10 +45,10 @@ time the user is invited twice (5 seconds apart) to abort sg_format. This
 occurs just prior the SCSI FORMAT UNIT command being issued. See the NOTES
 section for more information.
 .PP
-Protection information is optional and is made up of 8 additional bytes
-associated with each logical block. Four protection types are defined
-with protection type 0 being no additional protection bytes. See the
-PROTECTION INFORMATION section below for more information.
+Protection information is optional and is made up of one or more protection
+intervals, each made up of 8 bytes associated with each logical block. Four
+protection types are defined with protection type 0 being no protection
+intervals. See the PROTECTION INFORMATION section below for more information.
 .SH OPTIONS
 Arguments to long options are mandatory for short options as well.
 The options are arranged in alphabetical order based on the long
@@ -169,10 +169,11 @@ below for more information.
 \fB\-q\fR, \fB\-\-pie\fR=\fIPIE\fR
 sets the "Protection Interval Exponent" field in the parameter block
 associated with a FORMAT UNIT command to \fIPIE\fR. The default value is 0.
-The value of 0 is typical for 512 byte blocks, often with 4096 byte blocks
-a value of 3 might be appropriate (i.e. 8 protection intervals interleaved
-with 4096 bytes of user data). This field first appeared in SBC\-3 revision
-18.
+\fIPIE\fR can only be non-zero with protection types 2 and 3.
+The value of 0 is typical for 512 byte blocks; with 4096 byte blocks a value
+of 3 may be appropriate (i.e. 8 protection intervals interleaved with 4096
+bytes of user data). A device may not support any non-zero values. This
+field first appeared in SBC\-3 revision 18.
 .TP
 \fB\-p\fR, \fB\-\-pinfo\fR
 this option is deprecated, use the \fI\-\-fmtpinfo=FPI\fR option instead.
@@ -239,7 +240,9 @@ command's (short) parameter header. If this option (i.e. \fI\-\-wait\fR) is
 given then the "IMMED" bit is not set. If \fI\-\-wait\fR is given the
 FORMAT UNIT command waits until the format operation completes before
 returning its response. This can be many hours on large disks. This
-utility sets a 15 hour timeout on such a FORMAT UNIT command!
+utility sets a 15 hour timeout on such a FORMAT UNIT command! Some recent
+SSDs go to the other extreme of completing a format operation in 1.5
+seconds hence waiting is not an issue.
 .SH LISTS
 The SBC\-3 draft (revision 36) defines PLIST, CLIST, DLIST and GLIST in
 section 4.13 on "Medium defects". Briefly, the PLIST is the "primary"
diff --git a/doc/sg_scan.8.linux b/doc/sg_scan.8.linux
index b42761a0..06980004 100644
--- a/doc/sg_scan.8.linux
+++ b/doc/sg_scan.8.linux
@@ -50,7 +50,7 @@ do numeric scan (i.e. sg0, sg1...) [default]
 use a read/write flag when opening sg device (default is read\-only)
 .TP
 \fB\-x\fR
-extra information output about queuing
+extra information output about queueing
 .SH NOTES
 This utility was written at a time when hotplugging of SCSI devices
 was not supported in Linux. It used a simple algorithm to scan sg
diff --git a/doc/sg_unmap.8 b/doc/sg_unmap.8
index 7eb0588c..5e8e5817 100644
--- a/doc/sg_unmap.8
+++ b/doc/sg_unmap.8
@@ -1,4 +1,4 @@
-.TH SG_UNMAP "8" "January 2014" "sg3_utils\-1.38" SG3_UTILS
+.TH SG_UNMAP "8" "April 2014" "sg3_utils\-1.39" SG3_UTILS
 .SH NAME
 sg_unmap \- send SCSI UNMAP command (known as 'trim' in ATA specs)
 .SH SYNOPSIS
@@ -22,7 +22,8 @@ and the corresponding number(s) to unmap to the '\-\-num=' option. The
 other way is by putting start LBA and number to unmap pairs in a file whose
 name is given to the '\-\-in=' option. All values are assumed to be decimal
 unless prefixed by "0x" (or "0X") or have a trailing "h" (or "H") in which
-case they are interpreted as hexadecimal.
+case they are interpreted as hexadecimal. Suffix multipliers are permitted
+on decimal values (e.g. '\-\-num=1m').
 .PP
 When the '\-\-lba=' option is given then the '\-\-num=' option must also be
 given. If one has a comma separated list as its argument then the other must
@@ -105,6 +106,12 @@ In SBC\-3 revision 25 the LBPU and ANC_SUP bits where added to the
 Logical Block Provisioning VPD page. When LBPU is set it indicates that
 the device supports the UNMAP command. When the ANC_SUP bit is set it
 indicates the device supports anchored LBAs.
+.PP
+The SCSI UNMAP command does the "right thing" with respect to command
+queueing. However its ATA counterpart: the DATA SET MANAGEMENT command with
+the "Trim" bit set does not interact well with SATA queueing known as NCQ.
+To address this problem T13 have introduced a new command called SFQ DATA SET
+MANAGEMENT which also has a Trim bit.
 .SH EXAMPLES
 In the examples directory of the sg3_utils package there is a
 sg_unmap_example.txt file that shows the format that the '\-\-in='
diff --git a/doc/sg_write_same.8 b/doc/sg_write_same.8
index fe4dabc3..2663bda2 100644
--- a/doc/sg_write_same.8
+++ b/doc/sg_write_same.8
@@ -1,4 +1,4 @@
-.TH SG_WRITE_SAME "8" "May 2013" "sg3_utils\-1.36" SG3_UTILS
+.TH SG_WRITE_SAME "8" "April 2014" "sg3_utils\-1.39" SG3_UTILS
 .SH NAME
 sg_write_same \- send SCSI WRITE SAME command
 .SH SYNOPSIS
@@ -157,14 +157,16 @@ greater. If both this option and the \fIIF\fR option are given and
 \fILEN\fR exceeds the length of the \fIIF\fR file then \fILEN\fR is the
 data out buffer length with zeros used as pad bytes.
 .SH UNMAP
-Logical block provisioning is a new term introduced in SBC\-3 revision
-25 for the ability to mark blocks as unused. It is closely related to the
-ATA DATA SET MANAGEMENT command with the "Trim" bit set. For large
-storage arrays, it is a way to provision less physical storage than the
-READ CAPACITY command reports is available, potentially allocating more
-physical storage when WRITE commands require it. For flash memory it is
-a way of potentially saving power (and perhaps access time) when it is
-known large sections (or almost all) of the flash memory is not in use.
+Logical block provisioning is a new term introduced in SBC\-3 revision 25
+for the ability to mark blocks as unused. For large storage arrays, it is a
+way to provision less physical storage than the READ CAPACITY command reports
+is available, potentially allocating more physical storage when WRITE
+commands require it. For flash memory (e.g. SSD drives) it is a way of
+potentially saving power (and perhaps access time) when it is known large
+sections (or almost all) of the flash memory is not in use. SSDs need wear
+levelling algorithms to have acceptable endurance and typically over
+provision to simplify those algorithms; hence they typically contain more
+physical flash storage than their logical size would dictate.
 .PP
 Support for logical block provisioning is indicated by the LBPME bit being
 set in the READ CAPACITY(16) command response (see the sg_readcap utility).
@@ -191,10 +193,18 @@ set then the UNMAP bit is ignored and the data out buffer is written to the
 \fIDEVICE\fR as if the UNMAP bit was zero. In the absence of the
 \fI\-\-in=IF\fR option, this utility will attempt build a data out buffer
 that meets the requirements for the UNMAP bit in the cdb to be acted on by
-the \fIDEVICE\fR. 
+the \fIDEVICE\fR.
 .PP
 Logical blocks may also be unmapped by the SCSI UNMAP and FORMAT UNIT
 commands (see the sg_unmap and sg_format utilities).
+.PP
+The unmap capability in SCSI is closely related to the ATA DATA SET
+MANAGEMENT command with the "Trim" bit set. That ATA trim capability does
+not interact well with SATA command queueing known as NCQ. T13 have
+introduced a new command called the SFQ DATA SET MANAGEMENT command also
+with a the "Trim" bit to address that problem. The SCSI WRITE SAME with
+the UNMAP bit set and the UNMAP commands do not have any problems with
+SCSI queueing.
 .SH NOTES
 Various numeric arguments (e.g. \fILBA\fR) may include multiplicative
 suffixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section
@@ -296,7 +306,7 @@ Written by Douglas Gilbert.
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
-Copyright \(co 2009\-2013 Douglas Gilbert
+Copyright \(co 2009\-2014 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.