From 62c85c807d9d57f6bcf9a731d0126feaab661d93 Mon Sep 17 00:00:00 2001 From: Douglas Gilbert Date: Fri, 5 Jun 2020 16:19:48 +0000 Subject: 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 --- doc/Makefile.am | 12 +++++------ doc/Makefile.in | 17 ++++++++-------- doc/sg3_utils.8 | 2 +- doc/sg_rep_pip.8 | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/sg_rep_zones.8 | 8 ++++---- doc/sg_write_same.8 | 36 ++++++++++++++++++++++++++++----- doc/sg_write_x.8 | 8 ++++++-- 7 files changed, 115 insertions(+), 26 deletions(-) create mode 100644 doc/sg_rep_pip.8 (limited to 'doc') 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 . +.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 . .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 -- cgit v1.2.3