doco: improve sg_format.8 examples; other cleanups

git-svn-id: svn://localhost/trunk@438 6180dd3e-e324-4e3e-922d-17de1ae2f315

Author: doug-gilbert

COPYING

@@ -27,5 +27,5 @@ The author's intention is that the (Free-) BSD licensed code can be used
 freely by others. On Debian systems, the complete text of the BSD License
 can be found in `/usr/share/common-licenses/BSD'.
 
-Doug Gilbert
+Douglas Gilbert
 4th January 2009

COVERAGE

@@ -95,5 +95,5 @@ SMART READ DATA     examples/sg_sat_smart_rd_data
 (3) this command was known as SET DEVICE IDENTIFIER prior to spc4r07
 
 
-Doug Gilbert
+Douglas Gilbert
 21st June 2011

CREDITS

@@ -104,5 +104,5 @@ Trent Piepho <xyzzy at speakeasy dot org> print out some "sense key specific"
         data and "-6" switch for sg_modes
 
 
-Doug Gilbert
+Douglas Gilbert
 18th May 2011

ChangeLog

@@ -2,7 +2,7 @@ Each utility has its own version number, date of last change and
 some description at the top of its ".c" file. All utilities in the main
 directory have their own "man" pages. There is also a sg3_utils man page.
 
-Changelog for sg3_utils-1.34 [20120125] [svn: r437]
+Changelog for sg3_utils-1.34 [20120210] [svn: r438]
   - sg_pt_linux: expand DID_ (host_byte) codes
 
 Changelog for sg3_utils-1.33 [20120118] [svn: r435]

README

@@ -369,5 +369,5 @@ Other SCSI and storage tools
 See http://sg.danny.cz/sg/tools.html
 
 
-Doug Gilbert
+Douglas Gilbert
 19th January 2012

README.freebsd

@@ -133,5 +133,5 @@ utilities.
 
 
 
-Doug Gilbert
+Douglas Gilbert
 17th January 2012

README.sg_start

@@ -34,4 +34,5 @@ Postscript
 sg_start has been reworked to allow a block device (e.g. /dev/sda) in
 addition to the sg device name (e.g. /dev/sg0) in the lk 2.6 series.
 sg_start now has more command line options, see its man page.
-	Doug Gilbert <dgilbert at interlog dot com> 2004/5/8
+
+	Douglas Gilbert <dgilbert at interlog dot com> 2004/5/8

README.solaris

@@ -135,5 +135,5 @@ present (perhaps externally or within a HBA) then that would allow SATA
 disks to accept SCSI commands including the SCSI ATA PASS THROUGH commands.
 
 
-Doug Gilbert
+Douglas Gilbert
 21st June 2011

README.tru64

@@ -92,5 +92,5 @@ function "getopt_long()" has been placed in the "getopt_long"
 subdirectory. Currently only the Tru64 port uses it.
 
 
-Doug Gilbert
+Douglas Gilbert
 21st June 2011

README.win32

@@ -9,6 +9,11 @@ Linux idiosyncrasies to be easily ported. A new package called 'ddpt'
 contains a utility with similar functionality to sg_dd and is available
 for Windows.
 
+The Windows port uses the Microsoft SCSI Pass Through (SPT) interface.
+It has two variants: "SPT" where data is double buffered; and "SPTD"
+where data pointers to the user space are passed to the OS. Only Windows
+2000 and later (i.e. not 95, 98 or ME) support SPT.
+
 Two build environments are catered for: cygwin (see www.cygwin.com) and
 MinGW ("Minimalist GNU for Windows", see www.mingw.org). Both are based in
 the gcc compiler (although other C compilers should have little problem with
@@ -209,5 +214,5 @@ problem by changing what it knows to be binary output files to "binary
 mode" with the setmode() Windows command.
 
 
-Doug Gilbert
-21st June 2011
+Douglas Gilbert
+4th February 2012

debian/changelog

@@ -2,43 +2,43 @@ sg3-utils (1.34-0.1) unstable; urgency=low
 
   * New upstream version
 
- -- Doug Gilbert <[email protected]>  Thu, 19 Jan 2012 18:00:00 -0500
+ -- Douglas Gilbert <[email protected]>  Thu, 19 Jan 2012 18:00:00 -0500
 
 sg3-utils (1.33-0.1) unstable; urgency=low
 
   * New upstream version
 
- -- Doug Gilbert <[email protected]>  Wed, 18 Jan 2012 14:00:00 -0500
+ -- Douglas Gilbert <[email protected]>  Wed, 18 Jan 2012 14:00:00 -0500
 
 sg3-utils (1.32-0.1) unstable; urgency=low
 
   * New upstream version
 
- -- Doug Gilbert <[email protected]>  Wed, 22 Jun 2011 16:00:00 -0400
+ -- Douglas Gilbert <[email protected]>  Wed, 22 Jun 2011 16:00:00 -0400
 
 sg3-utils (1.31-0.1) unstable; urgency=low
 
   * New upstream version
 
- -- Doug Gilbert <[email protected]>  Wed, 16 Feb 2011 16:00:00 -0500
+ -- Douglas Gilbert <[email protected]>  Wed, 16 Feb 2011 16:00:00 -0500
 
 sg3-utils (1.30-0.1) unstable; urgency=low
 
   * New upstream version
 
- -- Doug Gilbert <[email protected]>  Fri, 05 Nov 2010 10:30:00 -0400
+ -- Douglas Gilbert <[email protected]>  Fri, 05 Nov 2010 10:30:00 -0400
 
 sg3-utils (1.29-0.1) unstable; urgency=low
 
   * New upstream version
 
- -- Doug Gilbert <[email protected]>  Wed, 31 Mar 2010 23:00:00 -0400
+ -- Douglas Gilbert <[email protected]>  Wed, 31 Mar 2010 23:00:00 -0400
 
 sg3-utils (1.28-0.1) unstable; urgency=low
 
   * New upstream version
 
- -- Doug Gilbert <[email protected]>  Fri, 02 Oct 2009 00:20:00 -0400
+ -- Douglas Gilbert <[email protected]>  Fri, 02 Oct 2009 00:20:00 -0400
 
 sg3-utils (1.27-0.1) unstable; urgency=low
 

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

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

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

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

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

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

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

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

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

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

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

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

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