doco: improve sg_format.8 examples; other cleanups

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

1 files changed, 62 insertions, 18 deletions

diff --git a/doc/sg_format.8 b/doc/sg_format.8
index 390762c5..3e3fc8fd 100644
--- a/doc/sg_format.8
+++ b/doc/sg_format.8
@@ -1,4 +1,4 @@
-.TH SG_FORMAT "8" "January 2012" "sg3_utils\-1.33" SG3_UTILS
+.TH SG_FORMAT "8" "February 2012" "sg3_utils\-1.33" SG3_UTILS
 .SH NAME
 sg_format \- format or resize a SCSI disk (perhaps change its block size)
 .SH SYNOPSIS
@@ -164,8 +164,11 @@ associated with a FORMAT UNIT command to \fIPIE\fR. The default value is 0.
 This field first appeared in SBC\-3 revision 18.
 .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.
+this 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 and that
+is equivalent to setting \fI\-\-fmtpinfo=2\fR. [So if \fI\-\-pinfo\fR is
+used (plus \fI\-\-fmtpinfo=FPI\fR and \fI\-\-pfu=PFU\fR are not given or
+their arguments are 0) then protection type 1 is selected.]
 .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
@@ -251,7 +254,7 @@ 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
+types (types 0 to 3) with protection type 0 meaning no protection information
 is maintained.
 .PP
 A device that supports protection information (i.e. supports one or more
@@ -266,11 +269,22 @@ 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.
+\fI\-\-pfu=PFU\fR options in this utility. The list below shows the four
+protection types followed by the options of this utility needed to select
+them:
+.br
+  \fB0\fR : \-\-fmtpinfo=0 \-\-pfu=0
+.br
+  \fB1\fR : \-\-fmtpinfo=2 \-\-pfu=0
+.br
+  \fB2\fR : \-\-fmtpinfo=3 \-\-pfu=0
+.br
+  \fB3\fR : \-\-fmtpinfo=3 \-\-pfu=1
+.br
+The default value of \fIFPI\fR (in \fI\-\-fmtpinfo=FPI\fR) is 0 and the
+default value of \fIPFU\fR (in \fI\-\-pfu=PFU\fR) is 0. So if neither
+\fI\-\-fmtpinfo=FPI\fR nor \fI\-\-pfu=PFU\fR are given then protection
+type 0 (i.e. no protection information) is chosen.
 .SH NOTES
 The SBC\-2 standard states that the REQUEST SENSE command should be used
 for obtaining progress indication when the format command is underway.
@@ -358,42 +372,72 @@ size derived from two sources: a block descriptor in a MODE SELECT command
 response and from the response of a READ CAPACITY commands. No changes
 are made:
 .PP
-   sg_format /dev/sdm
+   # sg_format /dev/sdm
 .PP
 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 60 seconds to print out a progress indication:
 .PP
-   sg_format \-\-format /dev/sdm
+   # sg_format \-\-format /dev/sdm
 .PP
 Now the same format, but waiting (passively) until the format operation is
 complete:
 .PP
-   sg_format \-\-format \-\-wait /dev/sdm
+   # 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:
 .PP
-   sg_format \-\-format \-\-size=520 /dev/sdm
+   # 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.
 .PP
-   sg_format \-\-resize \-\-count=0x10000 /dev/sdm
+   # sg_format \-\-resize \-\-count=0x10000 /dev/sdm
 .PP
 Now resize the disk back to its normal (maximum) block count:
 .PP
-   sg_format \-\-resize \-\-count=\-1 /dev/sdm
+   # sg_format \-\-resize \-\-count=\-1 /dev/sdm
+.PP
+One reason to format a SCSI disk is to add protection information. First
+check which protection types are supported by a disk (by checking the SPT
+field in the Extended inquiry VPD page together with the Protect bit in the
+standard inquiry response):
+.PP
+   # sg_vpd -p ei -l /dev/sdb
+.br
+   extended INQUIRY data VPD page:
+.br
+     ACTIVATE_MICROCODE=0
+.br
+     SPT=1 [protection types 1 and 2 supported]
+.br
+     ....
 .PP
 Format with type 1 protection:
 .PP
-   sg_format \-\-format \-\-fmtpinfo=2 /dev/sdm
+   # sg_format \-\-format \-\-fmtpinfo=2 /dev/sdm
+.PP
+After a successful format with type 1 protection, READ CAPACITY(16)
+should show something like this:
+.PP
+   # sg_readcap -l /dev/sdm
+.br
+   Read Capacity results:
+.br
+      Protection: prot_en=1, p_type=0, p_i_exponent=0 [type 1 protection]
+.br
+      Logical block provisioning: lbpme=0, lbprz=0
+.br
+      ....
 .PP
-Format with type 3 protection:
+To format with type 3 protection:
 .PP
-   sg_format \-\-format \-\-fmtpinfo=3 \-\-pfu /dev/sdm
+   # sg_format \-\-format \-\-fmtpinfo=3 \-\-pfu=1 /dev/sdm
 .PP
+For the disk shown above this will probably fail because the Extended inquiry
+VPD page showed only types 1 and 2 protection are supported.
 .SH EXIT STATUS
 The exit status of sg_format is 0 when it is successful. Otherwise see
 the sg3_utils(8) man page. Unless the \fI\-\-wait\fR option is given, the