diff options
author | Douglas Gilbert <dgilbert@interlog.com> | 2022-08-18 19:46:38 +0000 |
---|---|---|
committer | Douglas Gilbert <dgilbert@interlog.com> | 2022-08-18 19:46:38 +0000 |
commit | 7e7308a2dbdec4c900b0805ad94324d3a288a163 (patch) | |
tree | c6c84399abcab97cc9bb0657f0734e0aa56a917d /doc | |
parent | 98b99ad2ab348bbba1676b95a8895f12ee48fd31 (diff) | |
download | sg3_utils-7e7308a2dbdec4c900b0805ad94324d3a288a163.tar.gz |
sg_inq+sg_vpd: more updates but not finished
The sg_inq+sg_inq work is mainly JSON additions.
sg_vpd has a new --sinq_inraw=RFN option.
Update and place names for the 64 TapeAlert flags
in the library. This improves TapeAlert reporting
for sg_inq, sg_vpd and sg_logs.
Refine the description of the VPD page merge of
processing for sg_inq and sg_vpd to only include _T10_
defined pages, so the vendor specific VPD page
processings of those utilities are still separate.
git-svn-id: https://svn.bingwo.ca/repos/sg3_utils/trunk@969 6180dd3e-e324-4e3e-922d-17de1ae2f315
Diffstat (limited to 'doc')
-rw-r--r-- | doc/sg3_utils_json.8 | 25 | ||||
-rw-r--r-- | doc/sg_decode_sense.8 | 14 | ||||
-rw-r--r-- | doc/sg_get_elem_status.8 | 6 | ||||
-rw-r--r-- | doc/sg_get_lba_status.8 | 6 | ||||
-rw-r--r-- | doc/sg_inq.8 | 13 | ||||
-rw-r--r-- | doc/sg_opcodes.8 | 6 | ||||
-rw-r--r-- | doc/sg_rep_zones.8 | 6 | ||||
-rw-r--r-- | doc/sg_vpd.8 | 54 |
8 files changed, 84 insertions, 46 deletions
diff --git a/doc/sg3_utils_json.8 b/doc/sg3_utils_json.8 index d24ebb06..e8cdb62f 100644 --- a/doc/sg3_utils_json.8 +++ b/doc/sg3_utils_json.8 @@ -14,9 +14,10 @@ returned by SCSI commands (e.g. sg_vpd) can optionally provide JSON output, rather than simple, human-readable output. The default remains human-readable output. .PP -JSON is an open standard file format that can be used for data exchange -between systems. See https://en.wikipedia.org/wiki/JSON . JSON comes in many -flavours and this one uses the json-builder C implementation found at +JavaScript Object Notation (JSON) is an open standard file format that can be +used for data exchange between programs including across a network. See +https://en.wikipedia.org/wiki/JSON . JSON comes in many flavours and this one +uses the json-builder C implementation found at https://github.com/json-parser/json-builder which implements four simple JSON data types: string, integer, boolean and null. Its other data types are JSON object and JSON array. @@ -210,11 +211,17 @@ human readable form. Errors are reported to stderr and may cause the early termination of a utility (e.g. command line option syntax error). .PP When the \fI\-\-json\fR option is given and no errors are detected, then -only JSON is sent to stdout. If the 'o' control character is in the \fIJO\fR -argument to the \fI\-\-json\fR option, then the former "human readable" -output is placed in a JSON array named "output" within a JSON object -named "utility_invoked". Each line of the former "human readable" output -is placed in its own element of the JSON array named "output". +only JSON is normally sent to stdout. As the SCSI response is parsed, a JSON +representation is built as a tree in memory. After all other actions (perhaps +apart from the final exit status report) that JSON tree is "dumped" to +stdout. This means if there is any non-JSON output sent to stdout that +it will appear _before_ the JSON output. +.PP +If the 'o' control character is in the \fIJO\fR argument to the +\fI\-\-json\fR option, then the former "human readable" output is placed in +a JSON array named "output" within a JSON object named "utility_invoked". +Each line of the former "human readable" output is placed in its own +element of the JSON array named "output". .PP A JSON tree is built in memory as the utility parses the data returned from the SCSI device (e.g. sg_vpd parsing a VPD page returned from a @@ -236,7 +243,7 @@ reason then no JSON output will appear. With the normal, human readable output processing, some output may appear before the utility aborts in such bad situations. .SH ERRORS -No attempts has been made to translate errors into JSON form, apart from the +No attempts have been made to translate errors into JSON form, apart from the final "exit_status" JSON object where a value of 0 means "no errors". Exit status values indicating a problem range from 1 to 255. .PP diff --git a/doc/sg_decode_sense.8 b/doc/sg_decode_sense.8 index ea68eb16..e91d6892 100644 --- a/doc/sg_decode_sense.8 +++ b/doc/sg_decode_sense.8 @@ -1,13 +1,13 @@ -.TH SG_DECODE_SENSE "8" "July 2022" "sg3_utils\-1.48" SG3_UTILS +.TH SG_DECODE_SENSE "8" "August 2022" "sg3_utils\-1.48" SG3_UTILS .SH NAME sg_decode_sense \- decode SCSI sense and related data .SH SYNOPSIS .B sg_decode_sense [\fI\-\-binary=BFN\fR] [\fI\-\-cdb\fR] [\fI\-\-err=ES\fR] [\fI\-\-file=HFN\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-inhex=HFN\fR] -[\fI\-\-ignore\-first\fR] [\fI\-\-nodecode\fR] [\fI\-\-nospace\fR] -[\fI\-\-status=SS\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR] -[\fI\-\-write=WFN\fR] [H1 H2 H3 ...] +[\fI\-\-ignore\-first\fR] [\fI\-\-json[=JO]\fR] [\fI\-\-nodecode\fR] +[\fI\-\-nospace\fR] [\fI\-\-status=SS\fR] [\fI\-\-verbose\fR] +[\fI\-\-version\fR] [\fI\-\-write=WFN\fR] [H1 H2 H3 ...] .SH DESCRIPTION .\" Add any additional description here This utility takes SCSI sense data in binary or as a sequence of ASCII @@ -106,6 +106,12 @@ first hexadecimal value on each line. This option has no effect if character from and after "#" on a line are ignored. Useful with the \fI\-\-file=HFN\fR and \fI\-\-nodecode\fR options. .TP +\fB\-j\fR, \fB\-\-json[\fR=\fIJO\fR] +output is in JSON format instead of human readable form. See sg3_utils_json +manpage or use '?' for \fIJO\fR for a summary. +.br +This option is designed to parse sense data into JSON output. +.TP \fB\-N\fR, \fB\-\-nodecode\fR Do not decode the given data as sense or a cdb. Useful when arbitrary data is given (e.g. when converting hex to binary or vice versa). diff --git a/doc/sg_get_elem_status.8 b/doc/sg_get_elem_status.8 index 8baad4fc..e6ec8448 100644 --- a/doc/sg_get_elem_status.8 +++ b/doc/sg_get_elem_status.8 @@ -1,4 +1,4 @@ -.TH SG_GET_ELEM_STATUS "8" "July 2022" "sg3_utils\-1.48" SG3_UTILS +.TH SG_GET_ELEM_STATUS "8" "August 2022" "sg3_utils\-1.48" SG3_UTILS .SH NAME sg_get_elem_status \- send SCSI GET PHYSICAL ELEMENT STATUS command .SH SYNOPSIS @@ -72,8 +72,8 @@ sg3_utils manpage for more information. 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; see the sg3_utils_json manpage. +output is in JSON format instead of human readable form. See sg3_utils_json +manpage or use '?' for \fIJO\fR for a summary. .TP \fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR where \fILEN\fR is the (maximum) response length in bytes. It is placed in diff --git a/doc/sg_get_lba_status.8 b/doc/sg_get_lba_status.8 index 3f887aa3..0ccc70e4 100644 --- a/doc/sg_get_lba_status.8 +++ b/doc/sg_get_lba_status.8 @@ -1,4 +1,4 @@ -.TH SG_GET_LBA_STATUS "8" "July 2022" "sg3_utils\-1.48" SG3_UTILS +.TH SG_GET_LBA_STATUS "8" "August 2022" "sg3_utils\-1.48" SG3_UTILS .SH NAME sg_get_lba_status \- send SCSI GET LBA STATUS(16 or 32) command .SH SYNOPSIS @@ -87,8 +87,8 @@ 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; see sg3_utils_json manpage. +output is in JSON format instead of human readable form. See sg3_utils_json +manpage or use '?' for \fIJO\fR for a summary. .TP \fB\-l\fR, \fB\-\-lba\fR=\fILBA\fR where \fILBA\fR is the starting Logical Block Address (LBA) to check the diff --git a/doc/sg_inq.8 b/doc/sg_inq.8 index 76a5d97f..d01d35c7 100644 --- a/doc/sg_inq.8 +++ b/doc/sg_inq.8 @@ -1,4 +1,4 @@ -.TH SG_INQ "8" "July 2022" "sg3_utils\-1.48" SG3_UTILS +.TH SG_INQ "8" "August 2022" "sg3_utils\-1.48" SG3_UTILS .SH NAME sg_inq \- issue SCSI INQUIRY command and/or decode its response .SH SYNOPSIS @@ -13,8 +13,8 @@ sg_inq \- issue SCSI INQUIRY command and/or decode its response .PP .B sg_inq [\fI\-36\fR] [\fI\-a\fR] [\fI\-A\fR] [\fI\-b\fR] [\fI\-\-B=0|1\fR] -[\fI\-c\fR] [\fI\-cl\fR] [\fI\-d\fR] [\fI\-e\fR] [\fI\-f\fR] -[\fI\-h\fR] [\fI\-H\fR] [\fI\-i\fR] [\fI\-I=FN\fR] [\fI\-l=LEN\fR] +[\fI\-c\fR] [\fI\-cl\fR] [\fI\-d\fR] [\fI\-e\fR] [\fI\-f\fR] [\fI\-h\fR] +[\fI\-H\fR] [\fI\-i\fR] [\fI\-I=FN\fR] [\fI\-j[=LEN]\fR] [\fI\-l=LEN\fR] [\fI\-L\fR] [\fI\-m\fR] [\fI\-M\fR] [\fI\-o\fR] [\fI\-p=VPD_PG\fR] [\fI\-P\fR] [\fI\-r\fR] [\fI\-s\fR] [\fI\-u\fR] [\fI\-v\fR] [\fI\-V\fR] [\fI\-x\fR] [\fI\-36\fR] [\fI\-?\fR] \fIDEVICE\fR @@ -166,8 +166,8 @@ including a hash mark to the end of a line is ignored. If the \fI\-\-raw\fR option is also given then \fIFN\fR is 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; see sg3_utils_json manpage. +output is in JSON format instead of human readable form. See sg3_utils_json +manpage or use '?' for \fIJO\fR for a summary. .TP \fB\-l\fR, \fB\-\-len\fR=\fILEN\fR the number \fILEN\fR is the "allocation length" field in the INQUIRY cdb. @@ -433,6 +433,9 @@ response in hex use '\-p=83 \-h'. \fB\-I\fR=\fIFN\fR equivalent to \fI\-\-inhex=FN\fR in the OPTIONS section. .TP +\fB\-j[\fR=\fIJO]\fR +equivalent to \fI\-\-json[=JO]\fR in the OPTIONS section. +.TP \fB\-l\fR=\fILEN\fR equivalent to \fI\-\-len=LEN\fR in the OPTIONS section. .TP diff --git a/doc/sg_opcodes.8 b/doc/sg_opcodes.8 index f4ea0cbf..26cfd1fb 100644 --- a/doc/sg_opcodes.8 +++ b/doc/sg_opcodes.8 @@ -1,4 +1,4 @@ -.TH SG_OPCODES "8" "April 2022" "sg3_utils\-1.48" SG3_UTILS +.TH SG_OPCODES "8" "August 2022" "sg3_utils\-1.48" SG3_UTILS .SH NAME sg_opcodes \- report supported SCSI commands or task management functions .SH SYNOPSIS @@ -94,8 +94,8 @@ sg3_utils manpage for more information. 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; see the sg3_utils_json manpage. +output is in JSON format instead of human readable form. See sg3_utils_json +manpage or use '?' for \fIJO\fR for a summary. .TP \fB\-m\fR, \fB\-\-mask\fR additionally prints out the cdb mask in hex. So a 12 byte cdb will have diff --git a/doc/sg_rep_zones.8 b/doc/sg_rep_zones.8 index 8ab9feb5..49ee070a 100644 --- a/doc/sg_rep_zones.8 +++ b/doc/sg_rep_zones.8 @@ -1,4 +1,4 @@ -.TH SG_REP_ZONES "8" "July 2022" "sg3_utils\-1.48" SG3_UTILS +.TH SG_REP_ZONES "8" "AUGUST 2022" "sg3_utils\-1.48" SG3_UTILS .SH NAME sg_rep_zones \- send SCSI REPORT ZONES, REALMS or ZONE DOMAINS command .SH SYNOPSIS @@ -103,8 +103,8 @@ from a REPORT ZONES command. Use the \fI\-\-domain\fR or \fI\-\-realm\fR option for decoding the other two commands. .TP \fB\-j\fR, \fB\-\-json[\fR=\fIJO\fR] -output is in JSON format instead of human readable form. This is an -EXPERIMENTAL feature; see the sg3_utils_json manpage. +output is in JSON format instead of human readable form. See sg3_utils_json +manpage or use '?' for \fIJO\fR for a summary. .TP \fB\-l\fR, \fB\-\-locator\fR=\fILBA\fR where \fILBA\fR plays a similar role as it does in \fI\-\-start=LBA\fR. diff --git a/doc/sg_vpd.8 b/doc/sg_vpd.8 index 45f496c3..8bb88eef 100644 --- a/doc/sg_vpd.8 +++ b/doc/sg_vpd.8 @@ -6,8 +6,9 @@ sg_vpd \- fetch SCSI VPD page and/or decode its response [\fI\-\-all\fR] [\fI\-\-enumerate\fR] [\fI\-\-examine\fR] [\fI\-\-force\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-ident\fR] [\fI\-\-inhex=FN\fR] [\fI\-\-json[=JO]\fR] [\fI\-\-long\fR] [\fI\-\-maxlen=LEN\fR] -[\fI\-\-page=PG\fR] [\fI\-\-quiet\fR] [\fI\-\-raw\fR] [\fI\-\-vendor=VP\fR] -[\fI\-\-verbose\fR] [\fI\-\-version\fR] [\fIDEVICE\fR] +[\fI\-\-page=PG\fR] [\fI\-\-quiet\fR] [\fI\-\-raw\fR] +[\fI\-\-sinq_inraw=RFN\fR] [\fI\-\-vendor=VP\fR] [\fI\-\-verbose\fR] +[\fI\-\-version\fR] [\fIDEVICE\fR] .SH DESCRIPTION .\" Add any additional description here .PP @@ -62,20 +63,24 @@ with \fI\-\-vendor=VP\fR to restrict output to known vendor specific pages for vendor/product \fIVP\fR. .TP \fB\-E\fR, \fB\-\-examine\fR -scan part of all of the VPD space (from 0x0 to 0xff) and output any pages -found. This option ignores the contents of VPD page 0x0 which should contain -a list of all supported VPD pages. However some vendors either forget to -list some standard pages or perhaps purposely don't list vendor specific -pages which are in the range 0xc0 to 0xff. -.br -If the \fI\-\-page=PG\fR option is not given and this option is given once -then the scan is from VPD page number 0x80 to 0xff inclusive. If the -\fI\-\-page=PG\fR option is given then the scan is from 0x80 to -\fIPG\fR inclusive. If this option is given twice then the scan starts at -VPD page 0x0. +scan part of all of the VPD space (page numbers 0x0 to 0xff) and output any +pages found. If this option is given once, the scan starts at page 0x80; +if it is given twice, the scan starts at 0x0; and if given three times the +scan starts at 0xc0. This option takes no notice of the contents of VPD page +0x0 which should contain a list of all supported VPD pages. Some vendors +either forget to list some standard pages or perhaps purposely don't list +vendor specific pages which are in the range 0xc0 to 0xff. +.br +If the \fI\-\-page=PG\fR option is not given then the scan finishes at page +0xff. if the \fI\-\-page=PG\fR option is given then the scan finishes at +page \fIPG\fR. A check is made before the scan to make sure the start page +is less than or equal to the finish page; if not the start and finish page +numbers are swapped. .br The sdparm utility which lists mode and VPD pages also has a \fB\-\-examine\fR -option will similar functionility. +option will similar functionility. Note that T10 has changed most of the +pages that list supported pages (e.g. VPD, mode and log pages; supported +commands) to add the weasel words "may or may not list all ...". .TP \fB\-f\fR, \fB\-\-force\fR As a sanity check, the normal action when fetching VPD pages other than @@ -119,8 +124,8 @@ including a hash mark to the end of line is ignored. If the \fI\-\-raw\fR option is also given then \fIFN\fR is 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; see sg3_utils_json manpage. +output is in JSON format instead of human readable form. See sg3_utils_json +manpage or use '?' for \fIJO\fR for a summary. .TP \fB\-l\fR, \fB\-\-long\fR when decoding some VPD pages, give a little more output. For example the ATA @@ -166,6 +171,23 @@ used. The binary is sent to stdout, and errors are sent to stderr. if used with \fI\-\-inhex=FN\fR then the contents of \fIFN\fR is treated as binary. .TP +\fB\-Q\fR, \fB\-\-sinq_inraw\fR=\fIRFN\fR +where \fIRFN\fR is a filename containing binary standard INQUIRY response +data that matches either \fIDEVICE\fR or \fIFN\fR. Linux places this +standard INQUIRY response in its sysfs pseudo filesystem. A typical +location is at /sys/class/scsi_disk/<hctl>/device/inquiry where <hctl> is +a four part numeric tuple separated by colons. This tuple distinguishes +the device from any others on the system. Linux also places some VPD page +responses in binary in the same directory with names like "vpd_pg83" where +the last two digits form the hexadecimal VPD page number whose binary +contents are therein. +.br +Some VPD pages (e.g. the Extended Inquiry VPD page) depend on knowing +the settings in the standard INQUIRY response to interpret the fields +in that VPD page. This option together with the \fI\-\-all\fR, +\fI\-\-examine\fR or \fI\-\-page=PG\fR allows this utility to process +both the standard INQUIRY response and VPD pages in the same invocation. +.TP \fB\-M\fR, \fB\-\-vendor\fR=\fIVP\fR where \fIVP\fR is a vendor (e.g. "sea" for Seagate) or vendor/product acronym (e.g. "hp3par" for the 3PAR array from HP). Many vendors have |