sg_rem_rest_elem: new utility for removing or restoring elements; bug fixes

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

6 files changed, 140 insertions, 16 deletions

diff --git a/doc/README b/doc/README
index d20d510f..6664a32b 100644
--- a/doc/README
+++ b/doc/README
@@ -23,6 +23,8 @@ https://sg.danny.cz/sg/sg_io.html
 https://sg.danny.cz/sg/tools.html
     - overview of around 25 storage and SCSI tools
 
+Many of those pages are also found at: https://doug-gilbert.github.io/
+
 
 There are two versions of sg_scan: one for Linux and the other for Windows.
 They have different man pages: sg_scan.8.linux and sg_scan.8.win32 with
@@ -31,4 +33,4 @@ sg_scan.8 . sg_scan is not supported for other ports.
 
 
 Douglas Gilbert
-16th April 2021
+10th June 2022
diff --git a/doc/sg3_utils.8 b/doc/sg3_utils.8
index fc0b70a0..5f4c8456 100644
--- a/doc/sg3_utils.8
+++ b/doc/sg3_utils.8
@@ -739,10 +739,10 @@ be given as "0x100" or "100h".
 .SH FORMAT OF FILES CONTAINING ASCII HEX
 Such a file is assumed to contain a sequence of one or two digit ASCII
 hexadecimal values separated by whitespace. "Whitespace consists of either
-spaces, tabs, blank lines, or any combination thereof". Each one or two digit
-ASCII hex pair is decoded into a byte (i.e. 8 bits). The following will be
-decoded to valid (ascending valued)
-bytes: '0', '01', '3', 'c', 'F', '4a', 'cC', 'ff'.
+spaces, tabs, blank lines, or any combination thereof". Hyphens (e.g. '\-')
+are also allowed as separators. Each one or two digit ASCII hex pair is
+decoded into a byte (i.e. 8 bits). The following will be decoded to
+valid (ascending valued) bytes: '0', '01', '3', 'c', 'F', '4a', 'cC', 'ff'.
 Lines containing only whitespace are ignored. The contents of any line
 containing a hash mark ('#') is ignored from that point until the end of that
 line. Users are encouraged to use hash marks to introduce comments in hex
diff --git a/doc/sg_decode_sense.8 b/doc/sg_decode_sense.8
index 7c952ed0..5680a075 100644
--- a/doc/sg_decode_sense.8
+++ b/doc/sg_decode_sense.8
@@ -65,10 +65,10 @@ feed. All other command line options and arguments are ignored.
 \fB\-f\fR, \fB\-\-file\fR=\fIHFN\fR
 the sense data is read in ASCII hexadecimal from a file called \fIHFN\fR.
 The sense data should appear as a sequence of bytes separated by space,
-comma, tab or newline. Everything from and including a hash symbol to the
-end of that line is ignored. If \fI\-\-nospace\fR is set then no separator
-is required between the ASCII hexadecimal digits in \fIHFN\fR with bytes
-decoded from pairs of ASCII hexadecimal digits.
+comma, tab, hyphen or newline. Everything from and including a hash symbol
+to the end of that line is ignored. If \fI\-\-nospace\fR is set then no
+separator is required between the ASCII hexadecimal digits in \fIHFN\fR
+with bytes decoded from pairs of ASCII hexadecimal digits.
 .TP
 \fB\-h\fR, \fB\-\-help\fR
 output the usage message then exit.
@@ -82,6 +82,11 @@ starting with "0x3b,0x07,0x00,0xff").
 In other cases (i.e. when \fI\-\-write=WFN\fR is not given, or this option
 is given more than once) then the output is as described in the sg3_utils(8)
 manpage.
+.br
+The combination of \fI\-\-inhex=HFN\fR and this option used three times
+can be useful to converting hexadecimal bytes (e.g. hyphen separated) into
+a more regular form. The short option form is more convenient for invoking
+this option three times (e.g. '\-HHH').
 .TP
 \fB\-i\fR, \fB\-\-inhex\fR=\fIHFN\fR
 same action as \fI\-\-file=HFN\fR. This option was added for compatibility
diff --git a/doc/sg_get_lba_status.8 b/doc/sg_get_lba_status.8
index 282b3fed..b9fe7c18 100644
--- a/doc/sg_get_lba_status.8
+++ b/doc/sg_get_lba_status.8
@@ -1,10 +1,11 @@
-.TH SG_GET_LBA_STATUS "8" "August 2019" "sg3_utils\-1.45" SG3_UTILS
+.TH SG_GET_LBA_STATUS "8" "June 2022" "sg3_utils\-1.48" SG3_UTILS
 .SH NAME
 sg_get_lba_status \- send SCSI GET LBA STATUS(16 or 32) command
 .SH SYNOPSIS
 .B sg_get_lba_status
-[\fI\-\-16\fR] [\fI\-\-32\fR] [\fI\-\-brief\fR] [\fI\-\-element-id=EI\fR]
-[\fI\-\-help\fR] [\fI\-\-hex\fR]  [\fI\-\-inhex=FN\fR] [\fI\-\-lba=LBA\fR]
+[\fI\-\-16\fR] [\fI\-\-32\fR] [\fI\-\-blockhex\fR] [\fI\-\-brief\fR]
+[\fI\-\-element-id=EI\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR]
+[\fI\-\-inhex=FN\fR] [\fI\-\-json[=JO\fR]] [\fI\-\-lba=LBA\fR]
 [\fI\-\-maxlen=LEN\fR] [\fI\-\-raw\fR] [\fI\-\-readonly\fR]
 [\fI\-\-report\-type=RT\fR] [\fI\-\-scan-len=SL\fR] [\fI\-\-verbose\fR]
 [\fI\-\-version\fR] \fIDEVICE\fR
@@ -56,6 +57,13 @@ option is not given) is output to stdout. A check is made that the given
 it should according to SBC\-3 revision 20) and warnings are sent to stderr
 if it doesn't.
 .TP
+\fB\-B\fR, \fB\-\-blockhex\fR
+the number of blocks in each LBA status descriptor is usually displayed in
+decimal. An exception is when the \fI\-\-brief\fR option is given in which
+case it is shown in hexadecimal. When the option is given once, both cases
+are output in hexadecimal. When the option is given twice, both cases are
+output in decimal.
+.TP
 \fB\-e\fR, \fB\-\-element\-id\fR=\fIEI\fR
 where \fIEI\fR is the element identifier of the physical element for which
 the LBAs shall be reported based on the value in the report type field (i.e.
@@ -78,6 +86,10 @@ in the sg3_utils manpage for more information. If \fIDEVICE\fR is also
 given then it is ignored. If the \fI\-\-raw\fR option is also given then
 the contents of \fIFN\fR are treated as binary.
 .TP
+\fB\-j\fR, \fB\-\-json[\fR=\fIJO\fR]
+output is in JSON format instead of human readable form. This is an
+EXPERIMENTAL feature; more information to follow.
+.TP
 \fB\-l\fR, \fB\-\-lba\fR=\fILBA\fR
 where \fILBA\fR is the starting Logical Block Address (LBA) to check the
 provisioning status for. Note that the \fIDEVICE\fR chooses how many
@@ -141,7 +153,7 @@ 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\-2022 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_rem_rest_elem.8 b/doc/sg_rem_rest_elem.8
new file mode 100644
index 00000000..6300eef7
--- /dev/null
+++ b/doc/sg_rem_rest_elem.8
@@ -0,0 +1,94 @@
+.TH SG_REM_REST_ELEM "8" "June 2022" "sg3_utils\-1.48" SG3_UTILS
+.SH NAME
+sg_rem_rest_elem \- send SCSI remove or restore element command
+.SH SYNOPSIS
+.B sg_rem_rest_elem
+[\fI\-\-capacity=RC\fR] [\fI\-\-element=EID\fR] [\fI\-\-help\fR]
+[\fI\-\-quick\fR] [\fI\-\-remove\fR] [\fI\-\-restore\fR] [\fI\-\-verbose\fR]
+[\fI\-\-version\fR] \fIDEVICE\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Sends a SCSI REMOVE ELEMENT AND TRUNCATE [RMEAT] or RESTORE ELEMENTS AND
+REBUILD [RSEAB] command to the \fIDEVICE\fR. Since both these commands have
+a potentially huge impact on the \fIDEVICE\fR (similar to the FORMAT UNIT
+command: destroying data and taking a long time to complete fully),
+neither is executed by default.
+.PP
+Unlike the FORMAT UNIT command, these commands seem designed to work in
+the background. So they will return quickly (although sbc5r01.pdf does not
+state that) and the disk will be placed in a reduced functionality state
+where only a specified number of commands will be executed (e.g. INQUIRY and
+REPORT LUNS) until the operation is complete. Other commands will receive
+sense data with a sense key of NOT READY and an additional sense code
+of 'Depopulation in progress' (for RMEAT) or 'Depopulation restoration in
+progress' (for RSEAB).
+.PP
+The REMOVE ELEMENT AND TRUNCATE has a close relative in ZBC\-2 called the
+REMOVE ELEMENT AND MODIFY ZONES [RMEMZ] command. See the sg_zone utility
+for an implementation of the latter command.
+.br
+The difference between RMEAT and RMEMZ is that the former "changes the
+association between LBAs and physical blocks" and the latter does not
+change that association. Zones affected by the RMEMZ command are placed
+into the zone condition: "Offline".
+.SH OPTIONS
+Arguments to long options are mandatory for short options as well.
+.TP
+\fB\-c\fR, \fB\-\-capacity\fR=\fIRC\fR
+RC stands for Requested Capacity and is the number of logical blocks the
+\fIDEVICE\fR should have after the element is removed with the RMEAT
+command. The default value is 0 which allows the \fIDEVICE\fR to decide
+what the reduced capacity will be after the element removal. The RSEAB
+command ignores this value.
+.TP
+\fB\-e\fR, \fB\-\-element\fR=\fIEID\fR
+where \fIEID\fR is an element identifier which is a 32 bit unsigned integer
+starting at one. This field is used by the RMEAT command and ignored
+otherwise. The default value is zero (which is invalid). So the user needs
+to supply a valid element identifier when \fI\-\-remove\fR is used.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+output the usage message then exit.
+.TP
+\fB\-q\fR, \fB\-\-quick\fR
+the default action (i.e. when this option is not given) is to give the user
+15 seconds to reconsider doing a remove or restore element operation on the
+\fIDEVICE\fR.  When this option is given that step (i.e. the 15 second
+warning period) is bypassed.
+.TP
+\fB\-r\fR, \fB\-\-remove\fR
+causes the REMOVE ELEMENT AND TRUNCATE command to be sent to the
+\fIDEVICE\fR. In practice, \fI\-\-element=EID\fR needs to be also given.
+.TP
+\fB\-R\fR, \fB\-\-restore\fR
+causes the RESTORE ELEMENTS AND REBUILD command to be sent to the
+\fIDEVICE\fR.
+.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 NOTES
+Once an element is removed successfully it is termed as "depopulated".
+Depopulated elements that have the 'Restoration Allowed' (RALWD) bit
+set (see sg_get_elem_status) are candidates for future restoration.
+.PP
+A (storage) element of a rotating hard disk is once side of a platter
+typically associated with one head. Such hard disks typically have multiple
+platters with two heads per platter (i.e. one head each side of the platter).
+.SH EXIT STATUS
+The exit status of sg_rem_rest_elem 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 2022 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_get_elem_status,sg_zone(sg3_utils)
diff --git a/doc/sg_zone.8 b/doc/sg_zone.8
index 53cf7cfe..6c39dea2 100644
--- a/doc/sg_zone.8
+++ b/doc/sg_zone.8
@@ -1,4 +1,4 @@
-.TH SG_ZONE "8" "December 2021" "sg3_utils\-1.48" SG3_UTILS
+.TH SG_ZONE "8" "June 2022" "sg3_utils\-1.48" SG3_UTILS
 .SH NAME
 sg_zone \- send a SCSI ZONE modifying command
 .SH SYNOPSIS
@@ -70,6 +70,17 @@ where \fIID\fR is placed in the cdb's ZONE ID field. A zone id is a zone
 start logical block address (LBA). The default value is 0. \fIID\fR is
 assumed to be in decimal unless prefixed with '0x' or has a trailing 'h'
 which indicate hexadecimal.
+.SH NOTES
+After a REMOVE ELEMENT AND MODIFY ZONES command has completed, the element
+in question is said to be depopulated and any affected zones are placed in
+the 'offline' zone condition.
+.PP
+SBC\-4 has a similar command to REMOVE ELEMENT AND MODIFY ZONES called REMOVE
+ELEMENT AND TRUNCATE. The difference is that the latter "changes the
+association between LBAs and physical blocks" and the former does not change
+that association. In both cases, depopulated elements that have
+the 'Restoration Allowed' (RALWD) bit set (see sg_get_elem_status) may be
+restored with the RESTORE ELEMENTS AND REBUILD command (see sg_rem_rest_elem).
 .SH EXIT STATUS
 The exit status of sg_zone is 0 when it is successful. Otherwise see
 the sg3_utils(8) man page.
@@ -78,9 +89,9 @@ Written by Douglas Gilbert.
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
-Copyright \(co 2014\-2021 Douglas Gilbert
+Copyright \(co 2014\-2022 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_rep_zones,sg_reset_wp,sg_z_act_query(sg3_utils)
+.B sg_rem_rest_elem,sg_rep_zones,sg_reset_wp,sg_z_act_query(sg3_utils)