diff options
Diffstat (limited to 'doc/sg_opcodes.8')
| -rw-r--r-- | doc/sg_opcodes.8 | 339 |
1 files changed, 339 insertions, 0 deletions
diff --git a/doc/sg_opcodes.8 b/doc/sg_opcodes.8 new file mode 100644 index 00000000..21d148be --- /dev/null +++ b/doc/sg_opcodes.8 @@ -0,0 +1,339 @@ +.TH SG_OPCODES "8" "September 2022" "sg3_utils\-1.48" SG3_UTILS +.SH NAME +sg_opcodes \- report supported SCSI commands or task management functions +.SH SYNOPSIS +.B sg_opcodes +[\fI\-\-alpha\fR] [\fI\-\-compact\fR] [\fI\-\-enumerate\fR] [\fI\-\-help\fR] +[\fI\-\-hex\fR] [\fI\-\-inhex=FN\fR] [\fI\-\-json[=JO]\fR] [\fI\-\-mask\fR] +[\fI\-\-mlu\fR] [\fI\-\-no-inquiry\fR] [\fI\-\-opcode=OP[,SA]\fR] +[\fI\-\-pdt=DT\fR] [\fI\-\-raw\fR] [\fI\-\-rctd\fR] [\fI\-\-repd\fR] +[\fI\-\-sa=SA\fR] [\fI\-\-tmf\fR] [\fI\-\-unsorted\fR] [\fI\-\-verbose\fR] +[\fI\-\-version\fR] \fIDEVICE\fR +.PP +.B sg_opcodes +[\fI\-a\fR] [\fI\-c\fR] [\fI\-e\fR] [\fI\-H\fR] [\fI\-i=FN\fR] [\fI\-j\fR] +[\fI\-m\fR] [\fI\-M\fR] [\fI\-n\fR] [\fI\-o=OP\fR] [\fI\-p=DT\fR] [\fI\-q\fR] +[\fI\-R\fR] [\fI\-s=SA\fR] [\fI\-t\fR] [\fI\-u\fR] [\fI\-v\fR] [\fI\-V\fR] +[\fI\-?\fR] \fIDEVICE\fR +.SH DESCRIPTION +.\" Add any additional description here +.PP +This utility sends a SCSI REPORT SUPPORTED OPERATION CODES or a REPORT +SUPPORTED TASK MANAGEMENT FUNCTIONS command to the \fIDEVICE\fR and then +outputs the response. The default action is to report supported operation +codes. In this mode it will either list all supported commands or give +detailed information on a specific command identified by the +\fI\-\-opcode=OP\fR option (perhaps with additional information from the +\fI\-\-sa=SA\fR option). +.PP +The name of a SCSI command depends on its peripheral device type (e.g. a +disk). The REPORT SUPPORTED OPERATION CODES and REPORT SUPPORTED TASK +MANAGEMENT FUNCTIONS commands are not supported in the MMC command set for +CD and DVD devices. This utility does an INQUIRY to obtain the peripheral +device type and prints out the vendor, product and revision strings. +.PP +A similar facility to query supported operation codes previously was available +via the CmdDt bit in the SCSI INQUIRY command (see sg_inq(8)). However that +facility was made obsolete and replaced by the REPORT SUPPORTED OPERATION +CODES command in SPC\-3 (revision 4) during February 2002. +.PP +This utility supports two command line syntaxes, the preferred one is +shown first in the synopsis and explained in this section. A later section +on the old command line syntax outlines the second group of options. +.SH OPTIONS +Arguments to long options are mandatory for short options as well. +.TP +\fB\-a\fR, \fB\-\-alpha\fR +when all supported commands are being listed there is no requirement for +the device server (i.e. the \fIDEVICE\fR) to sort the list of commands. When +this option is given the list of supported commands is sorted by +name (alphabetically). When this option and the \fB\-\-unsorted\fR option are +both _not_ given then the list of supported commands is sorted +numerically (first by operation code and then by service action). +.TP +\fB\-c\fR, \fB\-\-compact\fR +some command names, especially those associated with some service actions, +are getting longer. This may cause line wrap in the one line per command +mode on some terminals. When this option is given the opcode and service +action fields are combined into a single field with the service action, +prefixed by a comma shown directly after the opcode. If there is no service +action associated with the command, then the comma and the service action +are not shown after the opcode. The CDB size field is not shown when this +option is given. +.TP +\fB\-e\fR, \fB\-\-enumerate\fR +this option prints the name of the SCSI command based on the given opcode, +peripheral device type and optionally the service action. If given, +\fIDEVICE\fR is ignored. The opcode, peripheral device type and service +action default to zero if not given. Thus if this option is the only option +given then "Test Unit ready" is output since its opcode is 0, it has no +service action and it is common to all peripheral device types since it is +defined in the SCSI Primary Commands (SPC) standard(s). +.TP +\fB\-h\fR, \fB\-\-help\fR +outputs the usage message summarizing command line options +then exits. Ignores \fIDEVICE\fR if given. +.TP +\fB\-H\fR, \fB\-\-hex\fR +outputs the response in ASCII hexadecimal to stdout. When used once or +twice, each line starts with a relative (hex) address starting at 0 +on the first hex line output. The difference is when used twice the +hexadecimal bytes are rendered in ASCII at the right of each line; +non\-printable characters are replaced by "." . +.br +When used three or more times, there is no leading relative address +on each line. This output is suitable for being redirected to a file +which can later by given to the \fI\-\-inhex=FN\fR option. +.TP +\fB\-i\fR, \fB\-\-inhex\fR=\fIFN\fR +where \fIFN\fR is a file name whose contents are assumed to be ASCII +hexadecimal. If \fIDEVICE\fR is also given then \fIDEVICE\fR is ignored, +a warning is issued and the utility continues, decoding the file named +\fIFN\fR. See the "FORMAT OF FILES CONTAINING ASCII HEX" section in the +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. 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 +a 12 byte hexadecimal mask. If the hexadecimal is expanded (mentally) +to binary then a "1" means the corresponding position in the cdb may +be set. And "0" means the corresponding position in the cdb must not +be set. For "0" mask positions that a user tries to set in a cdb, the +device may either ignore it or report an error, typically with a +sense key of "illegal request". +.TP +\fB\-M\fR, \fB\-\-mlu\fR +additionally prints out an indication (0 or 1) whether the command +effects all logical units in the containing target. MLU (Multiple Logical +Units) is a bit in the REPORT SUPPORTED OPERATION CODES response +introduced by proposal 18\-045r1 (and possibly in spc5r20). Without +the option, the default output format which lists all opcodes, does +not include a MLU indication. +.TP +\fB\-n\fR, \fB\-\-no-inquiry\fR +Prior to calling a SCSI REPORT SUPPORTED OPERATION CODES or a REPORT +SUPPORTED TASK MANAGEMENT FUNCTIONS command, a SCSI INQUIRY command +is performed. The reason is to determine the peripheral device type (pdt) +of the \fIDEVICE\fR as this is helpful in translating operation codes +to the command names. By default this utility prints a summary of INQUIRY +command response on stdout. If this option (or the \fI\-\-raw\fR option) +is given then that summary is not printed on stdout. +.TP +\fB\-O\fR, \fB\-\-old\fR +Switch to older style options. Please use as first option. +.TP +\fB\-o\fR, \fB\-\-opcode\fR=\fIOP[,SA]\fR +the \fIDEVICE\fR will be queried for the given operation code (i.e. the +\fIOP\fR value) which is the first byte of a SCSI command. Optionally, if +a \fISA\fR value is given, it will be used as that SCSI command's service +action. Note that \fIOP\fR and \fIOP,0\fR are not the same thing, as SCSI +does allow the service action to be 0 (but not in this command). \fIOP\fR +and \fISA\fR are decimal unless prefixed by "0x" or they have a +trailing "h". \fIOP\fR should be in the range 0 to 255 (0xff) inclusive. +\fISA\fR should be in the range 0 to 65535 (0xffff) inclusive. When this +option is not given then all available SCSI commands supported by the +\fIDEVICE\fR are listed. +.TP +\fB\-p\fR, \fB\-\-pdt\fR=\fIDT\fR +where \fIDT\fR is the peripheral device type. This is used together with +the \fI\-\-enumerate\fR to differentiate when a command opcode (and perhaps +service action) is shared by multiple device types. +.br +This option may also be used with the \fI\-\-no-inquiry\fR option to +suppress this utility doing an INQUIRY command since the main reason +for doing that is to find the peripheral device type of the \fIDEVICE\fR. +.TP +\fB\-r\fR, \fB\-\-raw\fR +output response in binary (to stdout) unless the \fI\-\-inhex=FN\fR option +is also given. In that case the input file name (\fIFN\fR) is decoded as +binary (and the output is _not_ in binary (but may be hex)). +.TP +\fB\-R\fR, \fB\-\-rctd\fR +set report command timeout descriptor (RCTD) bit in the cdb. The response +may or may not contain command timeout descriptors. If available they are +output. If supported there are two values: a nominal command timeout +and a recommended command timeout. Both have units of seconds. A value +of zero means that no timeout is indicated and this is shown in +the corresponding decoded output as "\-". +.TP +\fB\-q\fR, \fB\-\-repd\fR +set read extended parameter data (REPD) bit in the report task management +functions cdb. 16 bytes rather than the default 4 bytes expected in the +response. This was added in SPC\-4 (revision 26). +.TP +\fB\-s\fR, \fB\-\-sa\fR=\fISA\fR +the \fIDEVICE\fR will be queried for a command with the given service +action (i.e. the \fISA\fR value). Used in conjunction with the +\fI\-\-opcode=OP\fR option. If this option is not given, \fI\-\-opcode=OP\fR +is given and the command in question does have a service action then a value +of 0 will be assumed. \fISA\fR is decimal and expected to be in the range 0 +to 65535 (0xffff) inclusive. +.TP +\fB\-t\fR, \fB\-\-tmf\fR +list supported task management functions. This is done with the SCSI REPORT +SUPPORTED TASK MANAGEMENT FUNCTIONS command. When this option is chosen +the \fI\-\-alpha\fR, \fI\-\-opcode=OP\fR, \fI\-\-rctd\fR, \fI\-\-sa=SA\fR +and \fI\-\-unsorted\fR options are ignored. +.TP +\fB\-u\fR, \fB\-\-unsorted\fR +when all supported commands are being listed there is no requirement for +the device server (i.e. the \fIDEVICE\fR) to sort the list of commands. When +this option is given the list of supported commands is in the order given by +the \fIDEVICE\fR. When this option is not given the supported commands +are sorted numerically (first by operation code and then by service action). +.TP +\fB\-v\fR, \fB\-\-verbose\fR +increase level of verbosity. Can be used multiple times. +.TP +\fB\-V\fR, \fB\-\-version\fR +print out version string then exit. +.SH NOTES +As of SPC\-5 revision 8 the recognized task management functions are: +abort set, abort task set, clear ACA, clear task set, logical unit reset, +query task, query asynchronous event, query task set, and I_T nexus reset. +In SPC\-4 revision 26 target reset and wakeup task management functions +were made obsolete. +.PP +In the 2.4 series of Linux kernels the \fIDEVICE\fR must be a SCSI +generic (sg) device. In the 2.6 series block devices (e.g. SCSI disks +and DVD drives) can also be specified. For example "sg_opcodes /dev/sda" +will work in the 2.6 series kernels. +.SH EXIT STATUS +The exit status of sg_opcodes is 0 when it is successful. Otherwise see +the sg3_utils(8) man page. +.SH OLDER COMMAND LINE OPTIONS +The options in this section were the only ones available prior to sg3_utils +version 1.23 . Since then this utility defaults to the newer command line +options which can be overridden by using \fI\-\-old\fR (or \fI\-O\fR) as the +first option. See the ENVIRONMENT VARIABLES section for another way to +force the use of these older command line options. +.TP +\fB\-a\fR +sort command alphabetically. Equivalent to \fI\-\-alpha\fR in main +description. +.TP +\fB\-c\fR +see the \fI\-\-compact\fR option above. +.TP +\fB\-e\fR +see the \fI\-\-enumerate\fR option above. +.TP +\fB\-H\fR +see the \fI\-\-hex\fR option above. +.TP +\fB\-m\fR +see the \fI\-\-mask\fR option above. +.TP +\fB\-n\fR +don't print a summary of the SCSI INQUIRY response on stdout. +.TP +\fB-N\fR, \fB\-\-new\fR +Switch to the newer style options. +.TP +\fB\-o\fR=\fIOP\fR +the \fIDEVICE\fR will be queried for the given operation code (i.e. +\fIOP\fR) which is the first byte of a SCSI command. \fIOP\fR is +hexadecimal and expected to be in the range 0 to ff inclusive. +When this option is not given then all available SCSI commands supported +by the \fIDEVICE\fR are listed. +.TP +\fB\-p\fR=\fIDT\fR +see the \fI\-\-pdt=DT\fR option above. +.TP +\fB\-q\fR +set the read extended parameter data (REPD) bit in report TMF cdb. +Equivalent to \fI\-\-repd\fR in main description. +.TP +\fB\-R\fR +set the report command timeout descriptor (RCTD) bit in cdb. Equivalent +to \fI\-\-rctd\fR in main description. +.TP +\fB\-s\fR=\fISA\fR +the \fIDEVICE\fR will be queried for a command with the given service +action (i.e. \fISA\fR). Used in conjunction with the \fI\-o=OP\fR +option. If this option is not given, \fI\-o=OP\fR is given and the command +in question does have a service action then a value of 0 will be assumed. +\fISA\fR is hexadecimal and expected to be in the range 0 to ffff inclusive. +.TP +\fB\-t\fR +list supported task management functions. Equivalent to \fI\-\-tmf\fR in +the main description. +.TP +\fB\-u\fR +output all supported commands in the order given by \fIDEVICE\fR. +Equivalent to \fI\-\-unsorted\fR in main description. +.TP +\fB\-v\fR +increase level of verbosity. Can be used multiple times. +.TP +\fB\-V\fR +print out version string then exit. +.TP +\fB\-?\fR +output usage message. Ignore all other parameters. +.SH EXAMPLES +The examples in this page use Linux device names. For suitable device +names in other supported Operating Systems see the sg3_utils(8) man page. +.PP +To see the information about a specific command give its operation +code to the '\-\-op=' option. A command line invocation is shown first +followed by a typical response: +.PP + # sg_opcodes \-\-op=93h /dev/sdb +.PP + Opcode=0x93 +.br + Command_name: Write same(16) +.br + Command supported [conforming to SCSI standard] +.br + Usage data: 93 e2 00 00 00 00 ff ff ff ff 00 00 ff ff 00 00 +.PP +The next example shows the supported task management functions: +.PP + # sg_opcodes \-\-tmf \-n /dev/sdb +.PP +Task Management Functions supported by device: +.br + Abort task +.br + Abort task set +.br + Clear ACA +.br + Clear task set +.br + Logical unit reset +.br + Query task +.PP +Enumerate can be used to look up a SCSI command name in the absence of a +device that supports that command. The opcode and service action (if +required) should be supplied: +.PP + # sg_opcodes \-\-enumerate \-\-op=0x9b,0xa +.PP + SCSI command: +.br + Read buffer(16), read data from echo buffer +.br +.SH ENVIRONMENT VARIABLES +Since sg3_utils version 1.23 the environment variable SG3_UTILS_OLD_OPTS +can be given. When it is present this utility will expect the older command +line options. So the presence of this environment variable is equivalent to +using \fI\-\-old\fR (or \fI\-O\fR) as the first command line option. +.SH AUTHOR +Written by Douglas Gilbert +.SH "REPORTING BUGS" +Report bugs to <dgilbert at interlog dot com>. +.SH COPYRIGHT +Copyright \(co 2004\-2022 Douglas Gilbert +.br +This software is distributed under the GPL version 2. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +.SH "SEE ALSO" +.B sg_inq,sg3_utils_json(sg3_utils) |