path: root/doc/sg_senddiag.8

.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)