sg_format: add --poll=PT; > 2 TB additions; DIF stuff

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

1 files changed, 138 insertions, 112 deletions

diff --git a/doc/sg_format.8 b/doc/sg_format.8
index c42ddaed..dd5ba73b 100644
--- a/doc/sg_format.8
+++ b/doc/sg_format.8
@@ -1,14 +1,14 @@
-.TH SG_FORMAT "8" "August 2011" "sg3_utils\-1.33" SG3_UTILS
+.TH SG_FORMAT "8" "November 2011" "sg3_utils\-1.33" SG3_UTILS
 .SH NAME
 sg_format \- format or resize a SCSI disk (perhaps change its block size)
 .SH SYNOPSIS
 .B sg_format
 [\fI\-\-cmplst=\fR0|1] [\fI\-\-count=COUNT\fR] [\fI\-\-dcrt\fR]
-[\fI\-\-early\fR] [\fI\-\-fmtpinfo=FPI\fR] [\fI\-\-format\fR] [\fI\-\-help\fR]
-[\fI\-\-long\fR] [\fI\-\-pfu=PFU\fR] [\fI\-\-pie=PIE\fR] [\fI\-\-pinfo\fR]
-[\fI\-\-resize\fR] [\fI\-\-rto_req\fR] [\fI\-\-security\fR] [\fI\-\-six\fR]
-[\fI\-\-size=SIZE\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR] [\fI\-\-wait\fR]
-\fIDEVICE\fR
+[\fI\-\-early\fR] [\fI\-\-fmtpinfo=FPI\fR] [\fI\-\-format\fR]
+[\fI\-\-help\fR] [\fI\-\-long\fR] [\fI\-\-pfu=PFU\fR] [\fI\-\-pie=PIE\fR]
+[\fI\-\-pinfo\fR] [\fI\-\-poll=PT\fR] [\fI\-\-resize\fR] [\fI\-\-rto_req\fR]
+[\fI\-\-security\fR] [\fI\-\-six\fR] [\fI\-\-size=SIZE\fR]
+[\fI\-\-verbose\fR] [\fI\-\-version\fR] [\fI\-\-wait\fR] \fIDEVICE\fR
 .SH DESCRIPTION
 .\" Add any additional description here
 .PP
@@ -18,42 +18,36 @@ the largest group that do support a 'standard' format operation. They are
 typically factory formatted to a block size of 512 bytes with the largest
 number of blocks that the manufacturer recommends. The manufacturer's
 recommendation typically leaves aside a certain number of tracks, spread
-across the media, for reassignment of logical block addresses during the life
-of the disk.
+across the media, for reassignment of blocks to logical block addresses
+during the life of the disk.
 .PP
 This utility can format modern SCSI disks and potentially change their block
 size (if permitted) and the block count (i.e. number of accessible blocks on
 the media also known as "resizing"). Resizing a disk to less than the
 manufacturer's recommended block count is sometimes called "short
-stroking" (see NOTES section). Resizing the block count while not changing the
-block size may not require a format operation. The SBC\-2 standard (see
+stroking" (see NOTES section). Resizing the block count while not changing
+the block size may not require a format operation. The SBC\-2 standard (see
 www.t10.org) has obsoleted the "format device" mode page. Many of the low
 level details found in that mode page are now left up to the discretion of
 the manufacturer.
 .PP
-When this utility is used without options (apart from a DEVICE) it prints
-out the existing block size and block count derived from two sources. These
-two sources are a block descriptor in the response to a MODE SENSE command and
-the response to a READ CAPACITY command. The reason for this double check is
-to detect a "format corrupt" state (see NOTES section). This usage will not
-modify the disk.
+When this utility is used without options (i.e. it is only given a DEVICE
+argument) it prints out the existing block size and block count derived from
+two sources. These two sources are a block descriptor in the response to a
+MODE SENSE command and the response to a READ CAPACITY command. The reason
+for this double check is to detect a "format corrupt" state (see NOTES
+section). This usage will not modify the disk.
 .PP
-When this utility is used with the "\-\-format" (or "\-F") option it will attempt
-to format the given DEVICE. There is a 10 second pause during which 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.
+When this utility is used with the "\-\-format" (or "\-F") option it will
+attempt to format the given DEVICE. There is a 10 second pause during which
+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
-SBC\-3 drafts have added several "protection types" to the "protection
-information" introduced in the SBC\-2 standard. See the "protection
-information" section (section 4.18 in draft SBC\-3 rev 18). 8 bytes of
-protection information are added to each block (a 2 byte "logical block
-guard" (CRC), a 2 byte "logical block application guard", and a 4 byte "logical
-block reference tag"). A device that supports protection information sets
-the "PROTECT" bit in its standard INQUIRY response. The "FMTPINFO" field in
-in the FORMAT UNIT command cdb plus the "Protection Field Usage" in the
-parameter header are associated with protection information and can be set by
-this utility.
+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 TYPES 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
@@ -63,10 +57,8 @@ option name.
 sets the CMPLST ("complete list") bit in the FORMAT UNIT cdb to 0 or 1.
 The default is 1 in which case the existing GLIST (grown list) is ignored.
 If the value is 0 then the existing GLIST is taken into account. See the
-LISTS section below. Active when the \fI\-\-format\fR option is given. In
-most cases this bit should be left set; some MO disk drives need this bit
-cleared. The SCSI to ATA Translation (SAT) standard (prior draft: sat\-r09)
-requires this bit to be cleared.
+LISTS section below. In most cases this bit should be left set; some MO
+disk drives need this bit cleared.
 .TP
 \fB\-c\fR, \fB\-\-count\fR=\fICOUNT\fR
 where \fICOUNT\fR is the number of blocks to be formatted or media to be
@@ -117,22 +109,23 @@ to clear the DCRT bit thereby requesting "media certification". When the DCRT
 bit is set, the FOV bit must also be set hence sg_format does that.
 .TP
 \fB\-e\fR, \fB\-\-early\fR
-this option is active when \fI\-\-format\fR is given. The default action of
-this utility is to poll the disk every 60 seconds to determine the progress
-of the format operation until it is finished. When this option is given this
-utility will exit "early" as soon as the format has commenced. Then the
-user can monitor the progress of the ongoing format operation with other
-utilities (e.g. sg_turs(8) or sg_requests(8)). This option and
-\fI\-\-wait\fR cannot both be given.
+during a format operation, The default action of this utility is to poll the
+disk every 60 seconds to determine the progress of the format operation until
+it is finished. When this option is given this utility will exit "early",
+that is as soon as the format operation has commenced. Then the user can
+monitor the progress of the ongoing format operation with other
+utilities (e.g. sg_turs(8) or sg_requests(8)). This option and \fI\-\-wait\fR
+are mutually exclusive.
 .TP
 \fB\-f\fR, \fB\-\-fmtpinfo\fR=\fIFPI\fR
 sets the FMTPINFO field in the FORMAT UNIT cdb to a value between 0 and 3.
 The default value is 0. The FMTPINFO field from SBC\-3 revision 16 is a 2
 bit field (bits 7 and 6 of byte 1 in the cdb). Prior to that it was a single
 bit field (bit 7 of byte 1 in the cdb) and there was an accompanying bit
-called RTO_REQ (bit 6 of byte 1 in the cdb). The deprecated options "\-\-pinfo"
-and "\-\-rto\-req" represent the older usage. This option should be used in
-their place. This option has no action unless \fI\-\-format\fR is given.
+called RTO_REQ (bit 6 of byte 1 in the cdb). The deprecated
+options "\-\-pinfo" and "\-\-rto\-req" represent the older usage. This
+option should be used in their place. See the PROTECTION TYPES section below
+for more information.
 .TP
 \fB\-F\fR, \fB\-\-format\fR
 issue a SCSI FORMAT UNIT command.
@@ -147,31 +140,38 @@ EXAMPLES section for typical use.
 print out the usage information then exit.
 .TP
 \fB\-l\fR, \fB\-\-long\fR
-the default action of this utility is to assume 32 bit logical block addresses.
-With 512 byte block size this permits almost 2 terabytes (almost 2 ** 41
-bytes) on a single disk. This option selects commands and parameters that
-allow for 64 bit logical block addresses.  Specifically this option sets
-the "longlba" flag in the MODE SENSE (10) command and uses READ CAPACITY (16)
-rather than READ CAPACITY (10). This option does not set the LONGLIST bit
-in the FORMAT UNIT command. The LONGLIST bit is set as required depending
-other parameters (e.g. when '\-\-pie=PIE' is greater than zero).
+the default action of this utility is to assume 32 bit logical block
+addresses. With 512 byte block size this permits more than 2
+terabytes (almost 2 ** 41 bytes) on a single disk. This option selects
+commands and parameters that allow for 64 bit logical block addresses.
+Specifically this option sets the "longlba" flag in the MODE SENSE (10)
+command and uses READ CAPACITY (16) rather than READ CAPACITY (10). If this
+option is not given and READ CAPACITY (10) or MODE SELECT detects a disk
+the needs more than 32 bits to represent its logical blocks then it is
+set internally. This option does not set the LONGLIST bit in the FORMAT UNIT
+command. The LONGLIST bit is set as required depending other
+parameters (e.g. when '\-\-pie=PIE' is greater than zero).
 .TP
 \fB\-P\fR, \fB\-\-pfu\fR=\fIPFU\fR
 sets the "Protection Field Usage" field in the parameter block associated
 with a FORMAT UNIT command to \fIPFU\fR. The default value is 0, the only
-other defined value currently is 1. Used together with \fI\-\-fmtpinfo=FPI\fR
-to specify the "protection type" to format the disk to (see SBC\-3).
+other defined value currently is 1. See the PROTECTION TYPES section below 
+for more information.
 .TP
 \fB\-p\fR, \fB\-\-pinfo\fR
 The option is deprecated, use the \fI\-\-fmtpinfo=FPI\fR option instead.
 If used, then it sets bit 7 of byte 1 in the FORMAT UNIT cdb.
-Has no action unless \fI\-\-format\fR is given.
 .TP
 \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.
-This field first appeared in SBC\-3 revision 18. Has no action unless
-\fI\-\-format\fR is given.
+This field first appeared in SBC\-3 revision 18.
+.TP
+\fB\-x\fR, \fB\-\-poll\fR=\fIPT\fR
+where \fIPT\fR is the type of poll used. If \fIPT\fR is 0 then a TEST UNIT
+READY command is used, otherwise a REQUEST SENSE command is used. The
+default is currently 0 but this will change to 1 in the near future. See
+the NOTES sections below.
 .TP
 \fB\-r\fR, \fB\-\-resize\fR
 rather than format the disk, it can be resized. This means changing the
@@ -186,16 +186,13 @@ size.
 \fB\-R\fR, \fB\-\-rto_req\fR
 The option is deprecated, use the \fI\-\-fmtpinfo=FPI\fR option instead.
 If used, then it sets bit 6 of byte 1 in the FORMAT UNIT cdb.
-Has no action unless \fI\-\-format\fR is given.
 .TP
 \fB\-S\fR, \fB\-\-security\fR
 sets the "Security Initialization" (SI) bit in the FORMAT UNIT command's
 initialization pattern descriptor within the parameter list. According
 to SBC\-3 the default initialization pattern "shall be written using a
-security erasure write technique". The SI bit is found in SBC (1998)
-and SBC\-2 (2005) so vendors should support it. SATA and parallel ATA
-disks have a separate command called SECURITY ERASE UNIT to perform this
-action. Recent versions of the hdparm utility can execute that ATA command.
+security erasure write technique". See the NOTES section on the SCSI
+SANITIZE command.
 .TP
 \fB\-6\fR, \fB\-\-six\fR
 Use 6 byte variants of MODE SENSE and MODE SELECT. The default action
@@ -204,35 +201,33 @@ when doing a format.
 .TP
 \fB\-s\fR, \fB\-\-size\fR=\fISIZE\fR
 where \fISIZE\fR is the block size (i.e. number of bytes in each block) to
-format the device to.  The default value is whatever is currently reported
-by the block descriptor in a MODE SENSE command. This option is only active
-when the \fI\-\-format\fR option is also given. If the block size given by
+format the device to. The default value is whatever is currently reported
+by the block descriptor in a MODE SENSE command. If the block size given by
 this option is different from the current value then a MODE SELECT command
 is used to change it prior to the FORMAT UNIT command being started (as
-recommended in the draft standard). Recent SCSI disks usually have 512 byte
-sectors by default and allow up to 16 bytes extra in a sector (i.e. 528 byte
-sectors).  If the given size in unacceptable to the disk, most likely
+recommended in the draft standard). Many SCSI disks have 512 byte sectors
+by default and allow up to 16 bytes extra in a sector (i.e. 528 byte
+sectors).  If the given size in unacceptable with the disk, most likely
 an "Invalid field in parameter list" message will appear in sense
 data (requires the use of '\-v' to decode sense data).
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
 increase the level of verbosity, (i.e. debug output). "\-vvv" gives
-the maximum debug output.
+a lot more debug output.
 .TP
 \fB\-V\fR, \fB\-\-version\fR
 print the version string and then exit.
 .TP
 \fB\-w\fR, \fB\-\-wait\fR
-this option only has an effect when used together with the \fI\-\-format\fR
-option. The default format action is to set the "IMMED" bit in the FORMAT
-UNIT 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
+the default format action is to set the "IMMED" bit in the FORMAT UNIT
+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 several hours on large disks. This
-utility sets a four hour timeout on such a FORMAT UNIT command.
+returning its response. This can be many hours on large disks. This
+utility sets a 15 hour timeout on such a FORMAT UNIT command!
 .SH LISTS
-The SBC\-3 draft (revision 18) defines PLIST, CLIST, DLIST and GLIST in
-section 4.10 on "Medium defects". Briefly, the PLIST is the "primary"
+The SBC\-3 draft (revision 29) defines PLIST, CLIST, DLIST and GLIST in
+section 4.13 on "Medium defects". Briefly, the PLIST is the "primary"
 list of manufacturer detected defects, the CLIST ("certification" list)
 contains those detected during the format operation, the DLIST is a list of
 defects that can be given to the format operation. The GLIST is the grown
@@ -249,33 +244,60 @@ the CLIST is generated and used during the format process.
 .PP
 The sg_format utility does not permit a user to provide a defect
 list (i.e. DLIST).
+.SH PROTECTION TYPES
+SBC\-3 drafts have added several "protection types" to the "protection
+information" introduced in the SBC\-2 standard. See the "protection
+information" section (section 4.21 in draft SBC\-3 rev 29). 8 bytes of
+protection information are added to each logical block (a 2 byte "logical
+block guard" (CRC), a 2 byte "logical block application guard", and a 4
+byte "logical block reference tag"). SBC\-3 defines 4 protection
+types (types 0 to 4) with protection type 0 meaning no protection information
+is maintained.
+.PP
+A device that supports protection information (i.e. supports one or more
+protection types of 1 or higher) sets the "PROTECT" bit in its standard
+INQUIRY response. It also sets the SPT field in the EXTENDED INQUIRY VPD page
+response to indicate which protection types it supports. The current
+protection type of a disk can be found in the "P_TYPE" and "PROT_EN"
+fields in the response of a READ CAPACITY (16) command (e.g. with
+the 'sg_readcap \-\-long' utility).
+.PP
+Given that a device supports a particular protection type, a user can then
+then choose to format that disk with that protection type by setting
+the "FMTPINFO" and "Protection Field Usage" fields in the FORMAT UNIT
+command. Those fields correspond to the \fI\-\-fmtpinfo=FPI\fR and the
+\fI\-\-pfu=PFU\fR options in this utility. If \fIFPI\fR and \fIPFU\fR are
+both 0 (their default values) then protection type 0 is chosen. If \fIFPI\fR
+is 2 and \fIPFU\fR is 0 then protection type 1 is chosen. If \fIFPI\fR is 3
+and \fIPFU\fR is 0 then protection type 2 is chosen. If \fIFPI\fR is 3 and
+\fIPFU\fR is 1 then protection type 3 is chosen.
 .SH NOTES
 The SBC\-2 standard states that the REQUEST SENSE command should be used
-for obtaining a progress indication when the format command is underway.
-However, tests on a selection of recent disks shows that TEST UNIT READY
+for obtaining progress indication when the format command is underway.
+However, tests on a selection of disks shows that TEST UNIT READY
 commands yield progress indications (but not REQUEST SENSE commands). So
-the current version of this utility uses TEST UNIT READY commands to
-poll the disk to find out the progress of the format. A new option may be
-required to handle this when disks catch up.
+the current version of this utility defaults to using TEST UNIT READY
+commands to poll the disk to find out the progress of the format. The
+\fI\-\-poll=PT\fR option has been added to control this.
 .PP
 When the \fI\-\-format\fR option is given without the \fI\-\-wait\fR option
 then the SCSI FORMAT UNIT command is issued with the IMMED bit set which
 causes the SCSI command to return after it has started the format operation.
 The \fI\-\-early\fR option will cause sg_format to exit at that point.
 Otherwise the \fIDEVICE\fR is polled every 60 seconds with TEST UNIT READY
-commands until it reports an "all clear" (i.e. the format operation has
-completed). Normally these polling commands will result in a progress
-indicator (expressed as a percentage) being output to the screen. If the user
-gets bored watching the progress report then sg_format process can be
-terminated (e.g. with control\-C) without affecting the format operation
-which continues. However a bus or device reset (or a power cycle) will
-probably cause the device to become "format corrupt".
+or REQUEST SENSE commands until it reports an "all clear" (i.e. the format
+operation has completed). Normally these polling commands will result in a
+progress indicator (expressed as a percentage) being output to the screen.
+If the user gets bored watching the progress report then sg_format process
+can be terminated (e.g. with control\-C) without affecting the format
+operation which continues. However a target or device reset (or a power
+cycle) will probably cause the device to become "format corrupt".
 .PP
 When the \fI\-\-format\fR and \fI\-\-wait\fR options are both given then
 this utility may take a long time to return. In this case care should be
 taken not to send any other SCSI commands to the disk as it may not respond
 leaving those commands queued behind the active format command. This may
-cause a timeout in the OS driver (in a lot shorter period than 4 hours
+cause a timeout in the OS driver (in a lot shorter period than 15 hours
 applicable to some format operations). This may result in the OS resetting
 the disk leaving the format operation incomplete. This may leave the
 disk in a "format corrupt" state requiring another format to remedy
@@ -293,40 +315,40 @@ potentially requiring a format. The solution to this situation is to
 do a format again (and this time the new block size does not have to
 be given) or change the block size back to the original size.
 .PP
-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 the manufacturer's maximum recommended value. To see
-exactly which SCSI commands are being executed and parameters passed
-add "\-vvv" to the sg_format command line.
-.PP
-Short stroking is a technique to trade off capacity for performance.
-Disk performance is usually highest on the outer tracks (i.e. lower
-logical block addresses) so by resizing or reformatting a disk to
-a smaller capacity, average performance will usually be increased.
+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
+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.
+.PP
+Short stroking is a technique to trade off capacity for performance. Rotating
+disk performance is usually highest on the outer tracks (i.e. lower logical
+block addresses) so by resizing or reformatting a disk to a smaller capacity,
+average performance will usually be increased.
 .PP
 Other utilities may be useful in finding information associated with
 formatting. These include sg_inq(8) to fetch standard INQUIRY
-information (e.g. the PROTECT bit) and to fetch the extended INQUIRY
+information (e.g. the PROTECT bit) and to fetch the EXTENDED INQUIRY
 VPD page (e.g. RTO and GRD_CHK bits). The sdparm(8) utility can be
 used to access and potentially change the now obsolete format mode page.
 .PP
 scsiformat is another utility available for formatting SCSI disks
-with linux. It dates from 1997 (most recent update) and may be useful for
+with Linux. It dates from 1997 (most recent update) and may be useful for
 disks whose firmware is of that vintage.
 .PP
 The \fICOUNT\fR numeric argument may include a multiplicative suffix or be
 given in hexadecimal. See the "NUMERIC ARGUMENTS" section in the
 sg3_utils(8) man page.
 .PP
-The SCSI SANITIZE command was introduced in SBC\-3 revision 27. It is
-closely related to the ATA SANITIZE command and can be used to remove
-all existing data from a disk. This is more likely to be implemented
-than FORMAT UNIT's security initialization feature (see the
-\fI\-\-security\fR option) and in some cases much faster.
+The SCSI SANITIZE command was introduced in SBC\-3 revision 27. It is closely
+related to the ATA sanitize disk feature set and can be used to remove all
+existing data from a disk. Sanitize is more likely to be implemented on
+modern disks (including SSDs) than FORMAT UNIT's security initialization
+feature (see the \fI\-\-security\fR option) and in some cases much faster.
 .SH EXAMPLES
 These examples use Linux device names. For suitable device names in
 other supported Operating Systems see the sg3_utils(8) man page.
@@ -366,6 +388,10 @@ Now resize the disk back to its normal (maximum) block count:
 .PP
 Format with type 1 protection:
 .PP
+   sg_format \-\-format \-\-fmtpinfo=2 /dev/sdm
+.PP
+Format with type 3 protection:
+.PP
    sg_format \-\-format \-\-fmtpinfo=3 \-\-pfu /dev/sdm
 .PP
 .SH EXIT STATUS