301 lines
13 KiB
Groff
301 lines
13 KiB
Groff
|
.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)
|