more spc4r18 sync, start sbc3r18 sync (sg_format and sg_readcap); change interface of sg_ll_format_unit() removing rto_req argument

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

1 files changed, 77 insertions, 69 deletions

diff --git a/doc/sg_format.8 b/doc/sg_format.8
index da0077ae..009cecc4 100644
--- a/doc/sg_format.8
+++ b/doc/sg_format.8
@@ -4,56 +4,56 @@ 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\-\-format\fR] [\fI\-\-help\fR] [\fI\-\-long\fR]
-[\fI\-\-pfu=PFU\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\-\-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
-Not all SCSI direct access devices need to be formatted and some have
-vendor specific formatting procedures. SCSI disks with rotating media are
-probably 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.
+Not all SCSI direct access devices need to be formatted and some have vendor
+specific formatting procedures. SCSI disks with rotating media are probably
+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.
 .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
+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
 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 name)
-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).
+When this utility is used without options (apart from a device name) 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).
 .PP
 Recent SBC\-3 drafts add several "protection types" to the "protection
 information" introduced in the SBC\-2 standard. See the "protection
 information" section (section 4.17 in draft SBC\-3 rev 11). 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" and "RTO_REQ" bits in the FORMAT command cdb plus
-the "Protection Field Usage" in the parameter header are associated with
-protection information and can be set by this utility.
+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.
 .SH OPTIONS
 Arguments to long options are mandatory for short options as well.
 The options are arranged in alphabetical order based on the long
 option name.
 .TP
 \fB\-C\fR, \fB\-\-cmplst\fR=0 | 1
-sets the CMPLST ("complete list") bit in the FORMAT cdb to 0 or 1.
+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
@@ -102,12 +102,12 @@ blocks (for the block size) then the disk reports an error.
 See NOTES section below.
 .TP
 \fB\-D\fR, \fB\-\-dcrt\fR
-this option sets the DCRT bit in the FORMAT command's parameter list header.
-It will "disable certification". Certification verifies that blocks are usable
-during the format process. Using this option may speed the format. The default
-action of this utility (i.e. when this option is not given) is 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.
+this option sets the DCRT bit in the FORMAT UNIT command's parameter list
+header. It will "disable certification". Certification verifies that blocks
+are usable during the format process. Using this option may speed the format.
+The default action of this utility (i.e. when this option is not given) is
+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
@@ -118,8 +118,17 @@ 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.
 .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.
+.TP
 \fB\-F\fR, \fB\-\-format\fR
-issue a SCSI FORMAT command.
+issue a SCSI FORMAT UNIT command.
 .B This will destroy all the data held on the media.
 This option is required to change the block size of a disk. The user is given
 a 10 second count down to ponder the wisdom of doing this, during which time
@@ -141,16 +150,20 @@ supports "protection information" then this option may also be useful.
 .TP
 \fB\-P\fR, \fB\-\-pfu\fR=\fIPFU\fR
 sets the "Protection Field Usage" field in the parameter block associated
-with a FORMAT command to \fIPFU\fR. The default value is 0, the only other
-defined value currently is 1. Used together with \fI\-\-pinfo\fR and
-\fI\-\-rto_req\fR to specify the "protection type" to format the disk
-to (see SBC\-3).
+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).
 .TP
 \fB\-p\fR, \fB\-\-pinfo\fR
-instructs a format operation to add an extra 8 bytes of protection
-information by setting the FMTPINFO bit in the FORMAT command cdb. Default
-action is not to format with protection information. Has no action
-unless \fI\-\-format\fR is given.
+The option is deprecated, use the \fI\-\-fmtpinfo=FPI\fR option instead.
+If used, then a 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 revison 18. Has no action unless
+\fI\-\-format\fR is given.
 .TP
 \fB\-r\fR, \fB\-\-resize\fR
 rather than format the disk, it can be resized. This means changing the
@@ -163,14 +176,12 @@ or a \fI\-\-size=SIZE\fR whose argument is different to the existing block
 size.
 .TP
 \fB\-R\fR, \fB\-\-rto_req\fR
-instructs a format to enable application client ownership of
-the "logical block reference tag" field (i.e. the RTO_REQ bit in the
-FORMAT cdb). The default action is to disable application client
-ownership of that field. Has no action unless both \fI\-\-format\fR
-and \fI\-\-pinfo\fR are given.
+The option is deprecated, use the \fI\-\-fmtpinfo=FPI\fR option instead.
+If used, then a 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 command's
+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)
@@ -189,7 +200,7 @@ 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
 this option is different from the current value then a MODE SELECT command
-is used to change it prior to the FORMAT command being started (as
+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
@@ -318,28 +329,25 @@ are made:
 .PP
    sg_format /dev/sdm
 .PP
-Now a simple format, leaving the block count and size as they
-were previously. The FORMAT command is executed in IMMED mode
-and the device is polled every 30 seconds to print out a progress
-indication:
+Now a simple format, leaving the block count and size as they were previously.
+The FORMAT UNIT command is executed in IMMED mode and the device is polled
+every 30 seconds to print out a progress indication:
 .PP
    sg_format \-\-format /dev/sdm
 .PP
-Now the same format, but waiting (passively) until the format
-operation is complete:
+Now the same format, but waiting (passively) until the format operation is
+complete:
 .PP
    sg_format \-\-format \-\-wait /dev/sdm
 .PP
-Next is a format in which the block size is changed to 520 bytes
-and the block count is set to the manufacturer's maximum
-value (for that block size). Note, not all disks support changing
-the block size:
+Next is a format in which the block size is changed to 520 bytes and the block
+count is set to the manufacturer's maximum value (for that block size). Note,
+not all disks support changing the block size:
 .PP
    sg_format \-\-format \-\-size=520 /dev/sdm
 .PP
-Now a resize operation so that only the first 0x10000 (65536)
-blocks on a disk are accessible. The remaining blocks remain
-unaltered.
+Now a resize operation so that only the first 0x10000 (65536) blocks on a disk
+are accessible. The remaining blocks remain unaltered.
 .PP
    sg_format \-\-resize \-\-count=0x10000 /dev/sdm
 .PP
@@ -362,6 +370,6 @@ Copyright \(co 2005\-2009 Grant Grundler, James Bottomley and Douglas Gilbert
 This software is distributed under the GPL version 2. There is NO
 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 .SH "SEE ALSO"
-.B sg_turs(8), sg_requests(8), sg_inq(8), sg_modes(8), sg_vpd(8)
-.B sg_reassign(8) [all in sg3_utils], sdparm(8), scsiformat (old)
-.B hdparm(8)
+.B sg_turs(8), sg_requests(8), sg_inq(8), sg_modes(8), sg_vpd(8),
+.B sg_reassign(8), sg_readcap(8) [all in sg3_utils], sdparm(8),
+.B scsiformat (old), hdparm(8)