diff options
Diffstat (limited to 'doc/sg_senddiag.8')
| -rw-r--r-- | doc/sg_senddiag.8 | 300 |
1 files changed, 300 insertions, 0 deletions
diff --git a/doc/sg_senddiag.8 b/doc/sg_senddiag.8 new file mode 100644 index 00000000..e3fa612f --- /dev/null +++ b/doc/sg_senddiag.8 @@ -0,0 +1,300 @@ +.TH SG_SENDDIAG "8" "May 2018" "sg3_utils\-1.43" SG3_UTILS +.SH NAME +sg_senddiag \- performs a SCSI SEND DIAGNOSTIC command +.SH SYNOPSIS +.B sg_senddiag +[\fI\-\-doff\fR] [\fI\-\-extdur\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR] +[\fI\-\-list\fR] [\fI\-\-maxlen=LEN\fR] [\fI\-\-page=PG\fR] [\fI\-\-pf\fR] +[\fI\-\-raw=H,H...\fR] [\fI\-\-raw=\-\fR] [\fI\-\-selftest=ST\fR] +[\fI\-\-test\fR] [\fI\-\-timeout=SECS\fR] [\fI\-\-uoff\fR] [\fI\-\-verbose\fR] +[\fI\-\-version\fR] \fIDEVICE\fR +.PP +.B sg_senddiag +[\fI\-doff\fR] [\fI\-e\fR] [\fI\-h\fR] [\fI\-H\fR] [\fI\-l\fR] [\fI\-pf\fR] +[\fI\-raw=H,H...\fR] [\fI\-raw=\-\fR] [\fI\-s=ST\fR] [\fI\-t\fR] +[\fI\-T=SECS\fR] [\fI\-uoff\fR] [\fI\-v\fR] [\fI\-V\fR] [\fI\-?\fR] +\fIDEVICE\fR +.SH DESCRIPTION +.\" Add any additional description here +.PP +This utility sends a SCSI SEND DIAGNOSTIC command to the \fIDEVICE\fR. It +can issue self\-tests, find supported diagnostic pages or send arbitrary +diagnostic pages. +.PP +When the \fI\-\-list\fR option and a \fIDEVICE\fR are given then the utility +sends a SCSI RECEIVE DIAGNOSTIC RESULTS command to fetch the response (i.e. +the page numbers of supported diagnostic pages). +.PP +When the \fI\-\-list\fR option is given without a \fIDEVICE\fR then a list of +diagnostic page names and their numbers, known by this utility, are listed. +.PP +This utility supports two command line syntax\-es, 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\-d\fR, \fB\-\-doff\fR +set the Device Offline (DevOffL) bit (default is clear). Only significant +when \fI\-\-test\fR option is set for the default self\-test. When set other +operations on any logical units controlled by the this device server (target) +may be affected (delayed) while a default self\-test is underway. +.TP +\fB\-e\fR, \fB\-\-extdur\fR +outputs the expected extended self\-test duration. The duration is given in +seconds (and minutes in parentheses). This figure is obtained from mode page +0xa (i.e. the control mode page). +.TP +\fB\-h\fR, \fB\-\-help\fR +print usage message then exit. +.TP +\fB\-H\fR, \fB\-\-hex\fR +outputs response from RECEIVE DIAGNOSTIC RESULTS in hex rather than decode it. +Only the Supported Diagnostic Pages diagnostic page (i.e. page_code=0) is +decoded; other pages (e.g. those used by SES) are output in hex. +.br +If \fI\-\-hex\fR is used once, the hex output has a relative address at the +start of each line. If \fI\-\-hex\fR is used twice, then ASCII is shown to +the right of each line of hex. If \fI\-\-hex\fR is used three time or more, +only the hex is output, in two character pairs (i.e. a byte) space separated +and up to 16 bytes per line. This latter form, if placed in a file or piped +through to another invocation, is suitable for the \fI\-\-raw=\-\fR option. +.TP +\fB\-l\fR, \fB\-\-list\fR +when a \fIDEVICE\fR is also given lists the names of all diagnostic pages +supported by this device. The request is sent via a SEND DIAGNOSTIC +command (with the "pF" bit set) and the response is fetched by a RECEIVE +DIAGNOSTIC RESULTS command. When used in the absence of a \fI\-\-list\fR +argument then a list of diagnostic page names and their numbers, known +by this utility, are listed. +.TP +\fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR +where \fILEN\fR is the value placed in the parameter list length field of a +SEND DIAGNOSTIC command or in the allocation length field of a RECEIVE +DIAGNOSTIC RESULTS command. This only occurs when the other options imply +there will be data sent or received by the command. The default value +is 4096 bytes. \fILEN\fR cannot exceed 65535 or 0xffff in hexadecimal. +.TP +\fB\-O\fR, \fB\-\-old\fR +Switch to older style options. Please use as first option. +.TP +\fB\-P\fR, \fB\-\-page\fR=\fIPG\fR +where \fIPG\fR is the RECEIVE DIAGNOSTIC RESULTS command page code field. +If this option is given the PCV bit in that command is set. When this option +is given then no SEND DIAGNOSTIC command is sent (unlike \fI\-\-list\fR). +If \fIPG\fR is 0 then the response is decoded as if it is the SPC Supported +Diagnostic pages diagnostic page. Other \fIPG\fR values (i.e. 1 to 255) +have their responses output in hex. +.TP +\fB\-p\fR, \fB\-\-pf\fR +set Page Format (PF) bit. By default it is clear (i.e. 0) unless the +list \fI\-\-list\fR option is given in which case the Page Format +bit is set (as required by SPC\-3). +.TP +\fB\-r\fR, \fB\-\-raw\fR=\fIH,H...\fR +string of comma separated hex numbers each of which should resolve to +a byte value (i.e. 0 to ff inclusive). A (single) space separated string +of hex bytes is also allowed but the list needs to be in quotes. This +sequence forms a diagnostic page to be sent with the SCSI SEND DIAGNOSTIC +command. Mostly likely the \fI\-\-pf\fR option should also be given. +.TP +\fB\-r\fR, \fB\-\-raw=\-\fR +reads sequence of bytes from stdin. The sequence may be comma, space, tab +or linefeed (newline) separated. If a line contains "#" then the remaining +characters on that line are ignored. Otherwise each non separator character +should resolve to a byte value (i.e. 0 to ff inclusive). This sequence forms +a diagnostic page to be sent with the SCSI SEND DIAGNOSTIC command. Mostly +likely the \fI\-\-pf\fR option should also be given. +.TP +\fB\-s\fR, \fB\-\-selftest\fR=\fIST\fR +where \fIST\fR is the self\-test code. The default value is 0 which is +inactive. Some other values: +.br + \fB1\fR : background short self\-test +.br + \fB2\fR : background extended self\-test +.br + \fB4\fR : aborts a (background) self\-test that is in progress +.br + \fB5\fR : foreground short self\-test +.br + \fB6\fR : foreground extended self\-test +.br +This option is mutually exclusive with default self\-test (i.e. +can't have (\fIST\fR > 0) and \fI\-\-test\fR). +.TP +\fB\-t\fR, \fB\-\-test\fR +sets the _default_ Self Test (SelfTest) bit. By default this is clear (0). +The \fI\-\-selftest=ST\fR option should not be active together with this +option. Both the \fI\-\-doff\fR and/or \fI\-\-uoff\fR options can be used +with this option. +.TP +\fB\-T\fR, \fB\-\-timeout\fR=\fISECS\fR +where \fISECS\fR is a timeout value (in seconds) for foreground self\-test +operations. The default value is 7200 seconds (2 hours) and any values +of \fISECS\fR less than the default are ignored. +.TP +\fB\-u\fR, \fB\-\-uoff\fR +set the Unit Offline (UnitOffL) bit (default is clear). Only significant +when \fI\-\-test\fR option is set for the default self\-test. When set other +operations on this logical unit may be affected (delayed) while a default +self\-test is underway. Some devices (e.g. Fujitsu disks) do more tests +when this bit is set. +.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 +All devices should support the default self\-test. The 'short' self\-test +codes should complete in 2 minutes or less. The 'extended' self\-test +codes' maximum duration is vendor specific (e.g. a little over 10 minutes +with the author's disks). The foreground self\-test codes wait until they +are completed while the background self\-test codes return immediately. The +results of both foreground and background self\-test codes are placed in +the 'self\-test results' log page (see sg_logs(8)). The SCSI command timeout +for this utility is set to 60 minutes to allow for slow foreground extended +self\-tests. +.PP +If the \fIDEVICE\fR is a disk then no file systems residing on that disk +should be mounted during a foreground self\-test. The reason is that other +SCSI commands may become queued behind the foreground self\-test and timeout. +.PP +When the \fI\-\-raw=H,H...\fR option is given then self\-tests should not +be selected. However the \fB\-\-pf\fR (i.e. "page format") option should be +given. The length of the diagnostic page to be sent is derived from the +number of bytes given to the \fI\-\-raw=H,H...\fR option. The diagnostic +page code (number) should be the first byte of the sequence (i.e. as +dictated by SPC\-3 diagnostic page format). See the EXAMPLES section below. +.PP +Arbitrary diagnostic pages can be read (in hex) with the sg_ses(8) +utility (not only those defined in SES\-2). +.PP +If the utility is used with no options (e.g. "sg_senddiag /dev/sg1") +Then a degenerate SCSI SEND DIAGNOSTIC command is sent with zero +in all its fields apart from the opcode. Some devices report this +as an error while others ignore it. It is not entirely clear from +SPC\-3 if it is invalid to send such a command. +.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. +.PP +To access SCSI enclosures see the sg_ses(8) utility. sg_ses uses the +SCSI SEND DIAGNOSTIC and RECEIVE DIAGNOSTIC RESULTS commands as outlined +in the SES\-2 (draft) standard. +.SH EXIT STATUS +The exit status of sg_senddiag 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\-doff\fR +set the Device Offline (DevOffL) bit (default is clear). Only significant +when \fI\-t\fR option is set for the default self\-test. Equivalent to +\fI\-\-doff\fR in the main description. +.TP +\fB\-e\fR +outputs the expected extended self\-test duration. Equivalent to +\fI\-\-extdur\fR in the main description. +.TP +\fB\-h\fR +outputs response from RECEIVE DIAGNOSTIC RESULTS in hex rather than decode +it. +.TP +\fB\-H\fR +outputs response from RECEIVE DIAGNOSTIC RESULTS in hex rather than decode it. +.TP +\fB\-l\fR +when a \fIDEVICE\fR is also given lists the names of all diagnostic +pages supported by this device. The request is sent via a SEND DIAGNOSTIC +command (with the "pf" bit set) and the response is fetched by a RECEIVE +DIAGNOSTIC RESULTS command. When used in the absence of a \fIDEVICE\fR +argument then a list of diagnostic page names and their numbers, known +by this utility, are listed. +.TP +\fB-N\fR, \fB\-\-new\fR +Switch to the newer style options. +.TP +\fB\-pf\fR +set Page Format (PF) bit. By default it is clear (i.e. 0) unless +the \fI\-l\fR option is given in which case the Page Format bit is set +(as required by SPC\-3). +.TP +\fB\-raw\fR=\fIH,H...\fR +string of comma separated hex numbers each of which should resolve to +a byte value (i.e. 0 to ff inclusive). This sequence forms a diagnostic +page to be sent with the SCSI SEND DIAGNOSTIC command. Mostly likely +the \fI\-pf\fR option should also be given. +.TP +\fB\-raw=-\fR +reads sequence of bytes from stdin. The sequence may be comma, space, tab +or linefeed (newline) separated. If a line contains "#" then the remaining +characters on that line are ignored. Otherwise each non separator character +should resolve to a byte value (i.e. 0 to ff inclusive). This sequence forms +a diagnostic page to be sent with the SCSI SEND DIAGNOSTIC command. Mostly +likely the \fI\-pf\fR option should also be given. +.TP +\fB\-s\fR=\fIST\fR +where \fIST\fR is the self\-test code. The default value is 0 which is +inactive. A value of 1 selects a background short self\-test; 2 selects +a background extended self\-test; 5 selects a foreground short self\-test; +6 selects a foreground extended test. A value of 4 will abort +a (background) self\-test that is in progress. This option is mutually +exclusive with default self\-test (i.e. \fI\-t\fR). +.TP +\fB\-t\fR +sets the _default_ Self Test (SelfTest) bit. By default this is clear (0). +The \fI\-s=ST\fR option should not be active together with this option. +Both the \fI\-doff\fR and/or \fI\-uoff\fR options can be used with this +option. +.TP +\fB\-T\fR=\fISECS\fR +where \fISECS\fR is a timeout value (in seconds) for foreground self\-test +operations. See the \fI\-\-timeout=SECS\fR option above. +.TP +\fB\-uoff\fR +set the Unit Offline (UnitOffL) bit (default is clear). Equivalent to +\fI\-\-uoff\fR in the 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 sub\-directory in the sg3_utils packages contains two example +scripts that turn on the CJTPAT (jitter pattern) on some SAS disks (one +script for each phy). One possible invocation for phy 1 is: +.PP + sg_senddiag \-\-pf \-\-raw=\- /dev/sg2 < sdiag_sas_p1_cjtpat.txt +.PP +There is also an example script that turns on the IDLE pattern. Once a +test pattern has been started it can be turned off by resetting the phy +or with the STOP phy pattern function: +.PP + sg_senddiag \-\-pf \-\-raw=\- /dev/sg2 < sdiag_sas_p1_stop.txt +.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 2003\-2018 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_ses(8), sg_logs(8), smartmontools(see net) |