diff options
author | Douglas Gilbert <dgilbert@interlog.com> | 2022-06-25 04:05:14 +0000 |
---|---|---|
committer | Douglas Gilbert <dgilbert@interlog.com> | 2022-06-25 04:05:14 +0000 |
commit | 2e225c87784735360e9619766efe06782179a86a (patch) | |
tree | 1df2832c733c55207261b829ec7f0146287afe82 /doc | |
parent | a3eb530bb4b93949287f19a2b6fb418901f1f699 (diff) | |
download | sg3_utils-2e225c87784735360e9619766efe06782179a86a.tar.gz |
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
Diffstat (limited to 'doc')
-rw-r--r-- | doc/README | 4 | ||||
-rw-r--r-- | doc/sg3_utils.8 | 8 | ||||
-rw-r--r-- | doc/sg_decode_sense.8 | 13 | ||||
-rw-r--r-- | doc/sg_get_lba_status.8 | 20 | ||||
-rw-r--r-- | doc/sg_rem_rest_elem.8 | 94 | ||||
-rw-r--r-- | doc/sg_zone.8 | 17 |
6 files changed, 140 insertions, 16 deletions
@@ -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) |