sg_rep_pip: new utility; testing/sg_tst_ioctl.c work

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

7 files changed, 115 insertions, 26 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index fc8e85d3..e0dd2e64 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -7,12 +7,12 @@ man_MANS = \
 	sg_logs.8 sg_luns.8 sg_modes.8 sg_opcodes.8 sg_persist.8 \
 	sg_prevent.8 sg_raw.8 sg_rdac.8 sg_read_attr.8 \
 	sg_read_block_limits.8 sg_read_buffer.8 sg_read_long.8 sg_readcap.8 \
-	sg_reassign.8 sg_referrals.8 sg_rep_zones.8 sg_requests.8 \
-	sg_reset_wp.8 sg_rmsn.8 sg_rtpg.8 sg_safte.8 sg_sanitize.8 \
-	sg_sat_identify.8 sg_sat_phy_event.8 sg_sat_read_gplog.8 \
-	sg_sat_set_features.8 sg_seek.8 sg_senddiag.8 sg_ses.8 \
-	sg_ses_microcode.8 sg_start.8 sg_stpg.8 sg_stream_ctl.8 sg_sync.8 \
-	sg_timestamp.8 sg_turs.8 sg_unmap.8 sg_verify.8 sg_vpd.8 \
+	sg_reassign.8 sg_referrals.8 sg_rep_pip.8 sg_rep_zones.8 \
+	sg_requests.8 sg_reset_wp.8 sg_rmsn.8 sg_rtpg.8 sg_safte.8 \
+	sg_sanitize.8 sg_sat_identify.8 sg_sat_phy_event.8
+	sg_sat_read_gplog.8 sg_sat_set_features.8 sg_seek.8 sg_senddiag.8 \
+	sg_ses.8 sg_ses_microcode.8 sg_start.8 sg_stpg.8 sg_stream_ctl.8 \
+	sg_sync.8 sg_timestamp.8 sg_turs.8 sg_unmap.8 sg_verify.8 sg_vpd.8 \
 	sg_wr_mode.8 sg_write_buffer.8 sg_write_long.8 sg_write_same.8 \
 	sg_write_verify.8 sg_write_x.8 sg_zone.8
 CLEANFILES =
diff --git a/doc/Makefile.in b/doc/Makefile.in
index 6a37b4f8..448bf3eb 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -288,14 +288,10 @@ man_MANS = scsi_mandat.8 scsi_readcap.8 scsi_ready.8 scsi_satl.8 \
 	sg_modes.8 sg_opcodes.8 sg_persist.8 sg_prevent.8 sg_raw.8 \
 	sg_rdac.8 sg_read_attr.8 sg_read_block_limits.8 \
 	sg_read_buffer.8 sg_read_long.8 sg_readcap.8 sg_reassign.8 \
-	sg_referrals.8 sg_rep_zones.8 sg_requests.8 sg_reset_wp.8 \
-	sg_rmsn.8 sg_rtpg.8 sg_safte.8 sg_sanitize.8 sg_sat_identify.8 \
-	sg_sat_phy_event.8 sg_sat_read_gplog.8 sg_sat_set_features.8 \
-	sg_seek.8 sg_senddiag.8 sg_ses.8 sg_ses_microcode.8 sg_start.8 \
-	sg_stpg.8 sg_stream_ctl.8 sg_sync.8 sg_timestamp.8 sg_turs.8 \
-	sg_unmap.8 sg_verify.8 sg_vpd.8 sg_wr_mode.8 sg_write_buffer.8 \
-	sg_write_long.8 sg_write_same.8 sg_write_verify.8 sg_write_x.8 \
-	sg_zone.8 $(am__append_1) $(am__append_3) $(am__append_5)
+	sg_referrals.8 sg_rep_pip.8 sg_rep_zones.8 sg_requests.8 \
+	sg_reset_wp.8 sg_rmsn.8 sg_rtpg.8 sg_safte.8 sg_sanitize.8 \
+	sg_sat_identify.8 sg_sat_phy_event.8 $(am__append_1) \
+	$(am__append_3) $(am__append_5)
 CLEANFILES = $(am__append_2) $(am__append_4) $(am__append_6)
 all: all-am
 
@@ -541,6 +537,11 @@ uninstall-man: uninstall-man8
 
 .PRECIOUS: Makefile
 
+	sg_sat_read_gplog.8 sg_sat_set_features.8 sg_seek.8 sg_senddiag.8 \
+	sg_ses.8 sg_ses_microcode.8 sg_start.8 sg_stpg.8 sg_stream_ctl.8 \
+	sg_sync.8 sg_timestamp.8 sg_turs.8 sg_unmap.8 sg_verify.8 sg_vpd.8 \
+	sg_wr_mode.8 sg_write_buffer.8 sg_write_long.8 sg_write_same.8 \
+	sg_write_verify.8 sg_write_x.8 sg_zone.8
 @OS_LINUX_TRUE@sg_scan.8: sg_scan.8.linux
 @OS_LINUX_TRUE@	cp -p $< $@
 @OS_WIN32_MINGW_TRUE@sg_scan.8: sg_scan.8.win32
diff --git a/doc/sg3_utils.8 b/doc/sg3_utils.8
index de3106b3..fd0f7991 100644
--- a/doc/sg3_utils.8
+++ b/doc/sg3_utils.8
@@ -1,4 +1,4 @@
-.TH SG3_UTILS "8" "May 2020" "sg3_utils\-1.46" SG3_UTILS
+.TH SG3_UTILS "8" "June 2020" "sg3_utils\-1.46" SG3_UTILS
 .SH NAME
 sg3_utils \- a package of utilities for sending SCSI commands
 .SH SYNOPSIS
diff --git a/doc/sg_rep_pip.8 b/doc/sg_rep_pip.8
new file mode 100644
index 00000000..81dd060d
--- /dev/null
+++ b/doc/sg_rep_pip.8
@@ -0,0 +1,58 @@
+.TH SG_REP_PIP "8" "June 2020" "sg3_utils\-1.46" SG3_UTILS
+.SH NAME
+sg_rep_pip \- send SCSI REPORT PROVISIONING INITIALIZATION PATTERN command
+.SH SYNOPSIS
+.B sg_rep_pip
+[\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-maxlen=LEN\fR] [\fI\-\-raw\fR]
+[\fI\-\-readonly\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR]
+\fIDEVICE\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Sends a SCSI REPORT PROVISIONING INITIALIZATION PATTERN command to
+\fIDEVICE\fR and outputs the data returned. This command is found in the
+SBC\-4 draft standard, revision 21 (sbc\4r21.pdf).
+.SH OPTIONS
+Arguments to long options are mandatory for short options as well.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+output the usage message then exit.
+.TP
+\fB\-H\fR, \fB\-\-hex\fR
+output the response in hexadecimal to stdout. When used once the whole
+response is output in ASCII hexadecimal with a leading address (starting at
+0) on each line. When used twice the whole response is output in hexadecimal
+with no leading address (on each line). The default action is the same as
+giving the \fI\-\-hex\fR option once.
+.TP
+\fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR
+where \fILEN\fR is the (maximum) response length in bytes. It is placed in
+the cdb's "allocation length" field. If not given (or \fILEN\fR is zero)
+then 8192 is used. The maximum allowed value of \fILEN\fR is 1048576.
+.TP
+\fB\-r\fR, \fB\-\-raw\fR
+output the SCSI response (i.e. the data\-out buffer) in binary (to stdout).
+.TP
+\fB\-R\fR, \fB\-\-readonly\fR
+open the \fIDEVICE\fR read\-only (e.g. in Unix with the O_RDONLY flag).
+The default is to open it read\-write.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+increase the level of verbosity, (i.e. debug output).
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print the version string and then exit.
+.SH EXIT STATUS
+The exit status of sg_rep_pip is 0 when it is successful. Otherwise see
+the sg3_utils(8) man page.
+.SH AUTHORS
+Written by Douglas Gilbert.
+.SH "REPORTING BUGS"
+Report bugs to <dgilbert at interlog dot com>.
+.SH COPYRIGHT
+Copyright \(co 2020 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.
+.SH "SEE ALSO"
+.B sg3_utils(sg3_utils)
diff --git a/doc/sg_rep_zones.8 b/doc/sg_rep_zones.8
index 29fecd19..cf810799 100644
--- a/doc/sg_rep_zones.8
+++ b/doc/sg_rep_zones.8
@@ -1,4 +1,4 @@
-.TH SG_REP_ZONES "8" "February 2020" "sg3_utils\-1.45" SG3_UTILS
+.TH SG_REP_ZONES "8" "June 2020" "sg3_utils\-1.45" SG3_UTILS
 .SH NAME
 sg_rep_zones \- send SCSI REPORT ZONES command
 .SH SYNOPSIS
@@ -68,12 +68,12 @@ prefixed with '0x' or has a trailing 'h' which indicate hexadecimal.
 increase the level of verbosity, (i.e. debug output).
 .TP
 \fB\-V\fR, \fB\-\-version\fR
+print the version string and then exit.
+.TP
+\fB\-w\fR, \fB\-\-wp\fR
 print the write pointer (in hex) only. In the absence of errors, then a hex
 LBA will be printed on each line, one line for each zone. Can be usefully
 combined with the \fI\-\-num=NUM\fR and \fI\-\-start=LBA\fR options.
-.TP
-\fB\-w\fR, \fB\-\-wp\fR
-print the version string and then exit.
 .SH EXIT STATUS
 The exit status of sg_rep_zones is 0 when it is successful. Otherwise see
 the sg3_utils(8) man page.
diff --git a/doc/sg_write_same.8 b/doc/sg_write_same.8
index 55dcfec9..1a9d4fff 100644
--- a/doc/sg_write_same.8
+++ b/doc/sg_write_same.8
@@ -1,4 +1,4 @@
-.TH SG_WRITE_SAME "8" "December 2019" "sg3_utils\-1.45" SG3_UTILS
+.TH SG_WRITE_SAME "8" "June 2020" "sg3_utils\-1.45" SG3_UTILS
 .SH NAME
 sg_write_same \- send SCSI WRITE SAME command
 .SH SYNOPSIS
@@ -124,6 +124,10 @@ sets the NDOB bit in the WRITE SAME (16 and 32 byte) commands. NDOB stands
 for No Data\-Out Buffer. Default is to clear this bit. When this option
 is given then \fI\-\-in=IF\fR is not allowed and \fI\-\-xferlen=LEN\fR can
 only be given if \fILEN\fR is 0 .
+.br
+By default zeros are written in each block, but it is possible that
+the "provisioning initialization pattern" is written depending on other
+settings.
 .TP
 \fB\-n\fR, \fB\-\-num\fR=\fINUM\fR
 where \fINUM\fR is the number of blocks, starting at \fILBA\fR, to write the
@@ -235,7 +239,11 @@ introduction in lk 2.6.28 .
 The exit status of sg_write_same is 0 when it is successful. Otherwise see
 the sg3_utils(8) man page.
 .SH EXAMPLES
-One simple usage is to write blocks of zero from (and including) a given LBA:
+BEWARE: all these examples will overwrite the data on one or more blocks,
+potentially CLEARING the WHOLE DISK.
+.PP
+One simple usage is to write blocks of zero from (and including) a given LBA
+for 63 blocks:
 .PP
   sg_write_same \-\-lba=0x1234 \-\-num=63 /dev/sdc
 .PP
@@ -246,7 +254,24 @@ of bytes in a logical block.  Let us assume that is 512 bytes. Since
 of zeros (each block containing 512 bytes) will be written from (and
 including) LBA 0x1234 . Note that only one block of zeros is passed
 to the SCSI WRITE SAME command in the data\-out buffer (as required by
-SBC\-3).
+SBC\-3). Using the WRITE SAME SCSI command to write one or more blocks
+blocks of zeros is equivalent to the NVMe command: Write Zeroes.
+.br
+Now we will write zero blocks to the WHOLE disk. [Note sanitize type
+commands will also clear blocks and metdata that are not directly
+visible]:
+.PP
+  sg_write_same \-\-lba=0x0 \-\-num=0 /dev/sdc
+.PP
+Yes, in this context \-\-num=0 means the rest of the disk. The above
+invocation may give an error due to the WSNZ bit in the Block Limits VPD
+page being set. To get around that try:
+.PP
+  sg_write_same \-\-lba=0x0 \-\-ndob /dev/sdc
+.PP
+this invocation, if supported, has the added benefit of not sending a data
+out buffer of zeros. Notes that it is possible that the "provisioning
+initialization pattern" is written to each block instead of zeros.
 .PP
 A similar example follows but in this case the blocks
 are "unmapped" ("trimmed" in ATA speak) rather than zeroed:
@@ -322,9 +347,10 @@ Written by Douglas Gilbert.
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
-Copyright \(co 2009\-2019 Douglas Gilbert
+Copyright \(co 2009\-2020 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.
 .SH "SEE ALSO"
-.B sg_format,sg_get_lba_status,sg_readcap,sg_vpd,sg_unmap(sg3_utils)
+.B sg_format,sg_get_lba_status,sg_readcap,sg_vpd,sg_unmap,
+.B sg_write_x(sg3_utils)
diff --git a/doc/sg_write_x.8 b/doc/sg_write_x.8
index de9f10da..95352aae 100644
--- a/doc/sg_write_x.8
+++ b/doc/sg_write_x.8
@@ -1,4 +1,4 @@
-.TH SG_WRITE_X "8" "January 2020" "sg3_utils\-1.45" SG3_UTILS
+.TH SG_WRITE_X "8" "June 2020" "sg3_utils\-1.45" SG3_UTILS
 .SH NAME
 sg_write_x \- SCSI WRITE normal/ATOMIC/SAME/SCATTERED/STREAM, ORWRITE commands
 .SH SYNOPSIS
@@ -137,7 +137,7 @@ The current reference for these commands is draft SBC\-4 (T10/BSR INCITS
 506) revision 15 dated 9 November 2017. All six SCSI commands are described
 in that document. WRITE ATOMIC was added in SBC\-4 revision 3; WRITE STREAM
 was added in SBC\-4 revision 7; WRITE SCATTERED was added in SBC\-4
-revision 11 while the others are in the SBC\-3 standard. 
+revision 11 while the others are in the SBC\-3 standard.
 .SH OPTIONS
 Arguments to long options are mandatory for short options as well.
 The options are arranged in alphabetical order based on the long
@@ -536,6 +536,10 @@ would be 520 bytes. To send the 32 byte variant add \-\-32 as in:
   sg_write_x \-\-atomic=0 \-\-32 \-\-bs=512 \-\-in=/dev/zero \-\-lba=0x1234
 \-\-num=4 /dev/sdc
 .PP
+For examples using 'sg_write_x \-\-same=NDOB' see the manpage for
+sg_write_same(8). The syntax is a little different but the semantics are the
+same.
+.PP
 To send a WRITE STREAM(32) with a STR_ID of 1 use the following:
 .PP
   sg_write_x \-\-stream=1 \-\-32 \-\-bs=512 \-\-in=/dev/zero \-\-lba=0x1234