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

19 files changed, 106 insertions, 42 deletions

diff --git a/doc/README b/doc/README
index 48d3e308..89205622 100644
--- a/doc/README
+++ b/doc/README
@@ -12,6 +12,11 @@ http://sg.danny.cz/sg/sg_dd.html
     - discussion and examples of the sg_dd utility which is a dd variant
       (also discusses the sgm_dd, sgp_dd and sg_read utilities)
 
+http://sg.danny.cz/sg/sg_ses.html
+    - discussion and examples of the sg_ses utility. SCSI Enclosure
+      Services (SES) devices may contain a lot of information,
+      structured in a non-trivial way.
+
 http://sg.danny.cz/sg/sg_io.html
     - discussion of Linux SG_IO ioctl (SCSI pass-through)
 
@@ -25,5 +30,5 @@ the Makefile logic (rule in Makefile.am) copying the appropriate one to
 sg_scan.8 . sg_scan is not supported for other ports.
 
 
-Doug Gilbert
-4th November 2010
+Douglas Gilbert
+10th February 2010
diff --git a/doc/sg_dd.8 b/doc/sg_dd.8
index d9fff628..641e6973 100644
--- a/doc/sg_dd.8
+++ b/doc/sg_dd.8
@@ -457,7 +457,7 @@ to exit.
 An additional exit status of 90 is generated if the flock flag is given
 and some other process holds the advisory exclusive lock.
 .SH AUTHORS
-Written by Doug Gilbert and Peter Allworth.
+Written by Douglas Gilbert and Peter Allworth.
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
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
diff --git a/doc/sg_inq.8 b/doc/sg_inq.8
index e37e5822..8a80530f 100644
--- a/doc/sg_inq.8
+++ b/doc/sg_inq.8
@@ -350,7 +350,7 @@ can also be used to show the contents of VPD pages.
 Further examples of sg_inq together with some typical output can be found
 on http://sg.danny.cz/sg/sg3_utils.html web page.
 .SH AUTHOR
-Written by Doug Gilbert
+Written by Douglas Gilbert
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
diff --git a/doc/sg_logs.8 b/doc/sg_logs.8
index 551acf30..16f26d5c 100644
--- a/doc/sg_logs.8
+++ b/doc/sg_logs.8
@@ -334,7 +334,7 @@ print out version string then exit.
 \fB\-?\fR
 output usage message then exit.
 .SH AUTHOR
-Written by Doug Gilbert
+Written by Douglas Gilbert
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
diff --git a/doc/sg_map.8 b/doc/sg_map.8
index c3aad5ec..1501228a 100644
--- a/doc/sg_map.8
+++ b/doc/sg_map.8
@@ -155,7 +155,7 @@ By process of elimination /dev/sg3 must be the scanner.
 The exit status of sg_map is 0 when it is successful. Otherwise see
 the sg3_utils(8) man page.
 .SH AUTHOR
-Written by Doug Gilbert
+Written by Douglas Gilbert
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
diff --git a/doc/sg_modes.8 b/doc/sg_modes.8
index 8343a808..0d8862c4 100644
--- a/doc/sg_modes.8
+++ b/doc/sg_modes.8
@@ -262,7 +262,7 @@ print out version string then exit.
 \fB\-?\fR
 output usage message then exit. Ignore all other parameters.
 .SH AUTHOR
-Written by Doug Gilbert
+Written by Douglas Gilbert
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
diff --git a/doc/sg_opcodes.8 b/doc/sg_opcodes.8
index 191650d7..cbb515bd 100644
--- a/doc/sg_opcodes.8
+++ b/doc/sg_opcodes.8
@@ -223,7 +223,7 @@ Task Management Functions supported by device:
     Query task
 .br
 .SH AUTHOR
-Written by Doug Gilbert
+Written by Douglas Gilbert
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
diff --git a/doc/sg_persist.8 b/doc/sg_persist.8
index fc2be7a6..68dc87f1 100644
--- a/doc/sg_persist.8
+++ b/doc/sg_persist.8
@@ -388,7 +388,7 @@ The above sequence of commands was tested successfully on a Seagate Savvio
 The exit status of sg_persist is 0 when it is successful. Otherwise see
 the sg3_utils(8) man page.
 .SH AUTHOR
-Written by Doug Gilbert
+Written by Douglas Gilbert
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
diff --git a/doc/sg_rbuf.8 b/doc/sg_rbuf.8
index fef5de79..2c2b7720 100644
--- a/doc/sg_rbuf.8
+++ b/doc/sg_rbuf.8
@@ -166,7 +166,7 @@ increase level of verbosity. Can be used multiple times.
 \fB\-V\fR
 print out version string then exit.
 .SH AUTHOR
-Written by Doug Gilbert
+Written by Douglas Gilbert
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
diff --git a/doc/sg_read.8 b/doc/sg_read.8
index 527827bc..f6b17d09 100644
--- a/doc/sg_read.8
+++ b/doc/sg_read.8
@@ -167,7 +167,7 @@ output of third command will look like this:
 The exit status of sg_read is 0 when it is successful. Otherwise see
 the sg3_utils(8) man page.
 .SH AUTHORS
-Written by Doug Gilbert.
+Written by Douglas Gilbert.
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
diff --git a/doc/sg_sat_identify.8 b/doc/sg_sat_identify.8
index db1eff21..c1037388 100644
--- a/doc/sg_sat_identify.8
+++ b/doc/sg_sat_identify.8
@@ -104,7 +104,7 @@ USB mass storage limited sense data to 18 bytes which made the
 The exit status of sg_sat_identify is 0 when it is successful. Otherwise
 see the sg3_utils(8) man page.
 .SH AUTHOR
-Written by Doug Gilbert
+Written by Douglas Gilbert
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
diff --git a/doc/sg_sat_phy_event.8 b/doc/sg_sat_phy_event.8
index 98f02a1c..7cd15090 100644
--- a/doc/sg_sat_phy_event.8
+++ b/doc/sg_sat_phy_event.8
@@ -96,7 +96,7 @@ USB mass storage limited sense data to 18 bytes which made the
 The exit status of sg_sat_identify is 0 when it is successful. Otherwise
 see the sg3_utils(8) man page.
 .SH AUTHOR
-Written by Doug Gilbert
+Written by Douglas Gilbert
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
diff --git a/doc/sg_sat_set_features.8 b/doc/sg_sat_set_features.8
index 4d3208e1..b4d12a3e 100644
--- a/doc/sg_sat_set_features.8
+++ b/doc/sg_sat_set_features.8
@@ -84,7 +84,7 @@ USB mass storage limited sense data to 18 bytes which made the
 The exit status of sg_sat_set_features is 0 when it is successful. Otherwise
 see the sg3_utils(8) man page.
 .SH AUTHOR
-Written by Doug Gilbert
+Written by Douglas Gilbert
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
diff --git a/doc/sg_senddiag.8 b/doc/sg_senddiag.8
index e81dd5c6..90e8aaaf 100644
--- a/doc/sg_senddiag.8
+++ b/doc/sg_senddiag.8
@@ -247,7 +247,7 @@ or with the STOP phy pattern function:
 .PP
   sg_senddiag \-\-pf \-\-raw=\- /dev/sg2 < sdiag_sas_p1_stop.txt
 .SH AUTHOR
-Written by Doug Gilbert
+Written by Douglas Gilbert
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
diff --git a/doc/sg_vpd.8 b/doc/sg_vpd.8
index 94dad610..1a0fa519 100644
--- a/doc/sg_vpd.8
+++ b/doc/sg_vpd.8
@@ -1,4 +1,4 @@
-.TH SG_VPD "8" "October 2011" "sg3_utils\-1.33" SG3_UTILS
+.TH SG_VPD "8" "February 2012" "sg3_utils\-1.34" SG3_UTILS
 .SH NAME
 sg_vpd \- fetches Vital Product Data (VPD) pages using a SCSI INQUIRY command
 .SH SYNOPSIS
@@ -168,14 +168,29 @@ extended INQUIRY data VPD page:
 .br
   POA_SUP=0 HRA_SUP=0 VSA_SUP=0
 .PP
+To check if any protection types are supported by a disk use the '\-\-long'
+option on the Extended inquiry data VPD page:
+.PP
+   # sg_vpd \-\-page=ei \-\-long /dev/sdb
+.br
+   extended INQUIRY data VPD page:
+.br
+     ACTIVATE_MICROCODE=0
+.br
+     SPT=1 [protection types 1 and 2 supported]
+.br
+     GRD_CHK=1
+.br
+     ....
+.PP
 Further examples can be found on the http://sg.danny.cz/sg/sg3_utils.html
 web page.
 .SH AUTHOR
-Written by Doug Gilbert
+Written by Douglas Gilbert
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
-Copyright \(co 2006\-2011 Douglas Gilbert
+Copyright \(co 2006\-2012 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.
diff --git a/doc/sg_wr_mode.8 b/doc/sg_wr_mode.8
index c53d0759..36a6f998 100644
--- a/doc/sg_wr_mode.8
+++ b/doc/sg_wr_mode.8
@@ -1,4 +1,4 @@
-.TH SG_WR_MODE "8" "April 2009" "sg3_utils\-1.27" SG3_UTILS
+.TH SG_WR_MODE "8" "February 2012" "sg3_utils\-1.34" SG3_UTILS
 .SH NAME
 sg_wr_mode \- write mode page
 .SH SYNOPSIS
@@ -171,7 +171,7 @@ after the next power cycle. The output from sg_modes is abridged.
 .PP
  $ sg_modes \-\-page=1a /dev/hdc
 .br
->> Power condition (mmc), page_control: current
+ >> Power condition (mmc), page_control: current
 .br
  00     1a 0a 00 03 00 00 00 28  00 00 01 2c
 .PP
@@ -179,7 +179,7 @@ after the next power cycle. The output from sg_modes is abridged.
 .PP
  $ sg_modes \-p 1a /dev/hdc
 .br
->> Power condition (mmc), page_control: current
+ >> Power condition (mmc), page_control: current
 .br
  00     1a 0a 00 03 00 00 00 37  00 00 01 2c
 .SH EXIT STATUS
@@ -190,7 +190,7 @@ Written by Douglas Gilbert.
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
-Copyright \(co 2004\-2009 Douglas Gilbert
+Copyright \(co 2004\-2012 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.
diff --git a/doc/sgm_dd.8 b/doc/sgm_dd.8
index e54d9d6f..86eb286e 100644
--- a/doc/sgm_dd.8
+++ b/doc/sgm_dd.8
@@ -262,7 +262,7 @@ than individual commands, and there are 'coe' and 'retries' flags,
 individual SCSI command failures do not necessary cause the process
 to exit.
 .SH AUTHORS
-Written by Doug Gilbert and Peter Allworth.
+Written by Douglas Gilbert and Peter Allworth.
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
diff --git a/doc/sgp_dd.8 b/doc/sgp_dd.8
index 00c4ef57..012ac9b8 100644
--- a/doc/sgp_dd.8
+++ b/doc/sgp_dd.8
@@ -298,7 +298,7 @@ than individual commands, and there are 'coe' and 'retries' flags,
 individual SCSI command failures do not necessary cause the process
 to exit.
 .SH AUTHORS
-Written by Doug Gilbert and Peter Allworth.
+Written by Douglas Gilbert and Peter Allworth.
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT