1SG_SENDDIAG(8) SG3_UTILS SG_SENDDIAG(8)
2
6 sg_senddiag - performs a SCSI SEND DIAGNOSTIC command
7
9 sg_senddiag [--doff] [--extdur] [--help] [--hex] [--list]
10 [--maxlen=LEN] [--page=PG] [--pf] [--raw=H,H...] [--raw=-] [--self‐
11 test=ST] [--test] [--uoff] [--verbose] [--version] DEVICE
12 sg_senddiag [-doff] [-e] [-h] [-H] [-l] [-pf] [-raw=H,H...] [-raw=-]
14 [-s=ST] [-t] [-uoff] [-v] [-V] [-?] DEVICE
15
17 This utility sends a SCSI SEND DIAGNOSTIC command to the DEVICE. It can
18 issue self-tests, find supported diagnostic pages or send arbitrary
19 diagnostic pages.
20 When the --list option and a DEVICE are given then the utility sends a
22 SCSI RECEIVE DIAGNOSTIC RESULTS command to fetch the response (i.e.
23 the page numbers of supported diagnostic pages).
24 When the --list option is given without a DEVICE then a list of diag‐
26 nostic page names and their numbers, known by this utility, are listed.
27 This utility supports two command line syntax-es, the preferred one is
29 shown first in the synopsis and explained in this section. A later sec‐
30 tion on the old command line syntax outlines the second group of
31 options.
32
34 Arguments to long options are mandatory for short options as well.
35 -d, --doff
37 set the Device Offline (DevOffL) bit (default is clear). Only
38 significant when --test option is set for the default self-test.
39 When set other operations on any logical units controlled by the
40 this device server (target) may be affected (delayed) while a
41 default self-test is underway.
42 -e, --extdur
44 outputs the expected extended self-test duration. The duration
45 is given in seconds (and minutes in parentheses). This figure is
46 obtained from mode page 0xa (i.e. the control mode page).
47 -h, --help
49 print usage message then exit.
50 -H, --hex
52 outputs response from RECEIVE DIAGNOSTIC RESULTS in hex rather
53 than decode it. Only the Supported Diagnostic Pages diagnostic
54 page (i.e. page_code=0) is decoded; other pages (e.g. those used
55 by SES) are output in hex.
56 If --hex is used once, the hex output has a relative address at
57 the start of each line. If --hex is used twice, then ASCII is
58 shown to the right of each line of hex. If --hex is used three
59 time or more, only the hex is output, in two character pairs
60 (i.e. a byte) space separated and up to 16 bytes per line. This
61 latter form, if placed in a file or piped through to another
62 invocation, is suitable for the --raw=- option.
63 -l, --list
65 when a DEVICE is also given lists the names of all diagnostic
66 pages supported by this device. The request is sent via a SEND
67 DIAGNOSTIC command (with the "pF" bit set) and the response is
68 fetched by a RECEIVE DIAGNOSTIC RESULTS command. When used in
69 the absence of a --list argument then a list of diagnostic page
70 names and their numbers, known by this utility, are listed.
71 -m, --maxlen=LEN
73 where LEN is the value placed in the parameter list length field
74 of a SEND DIAGNOSTIC command or in the allocation length field
75 of a RECEIVE DIAGNOSTIC RESULTS command. This only occurs when
76 the other options imply there will be data sent or received by
77 the command. The default value is 4096 bytes. LEN cannot exceed
78 65535 or 0xffff in hexadecimal.
79 -O, --old
81 switch to older style options.
82 -P, --page=PG
84 where PG is the RECEIVE DIAGNOSTIC RESULTS command page code
85 field. If this option is given the PCV bit in that command is
86 set. When this option is given then no SEND DIAGNOSTIC command
87 is sent (unlike --list). If PG is 0 then the response is
88 decoded as if it is the SPC Supported Diagnostic pages diagnos‐
89 tic page. Other PG values (i.e. 1 to 255) have their responses
90 output in hex.
91 -p, --pf
93 set Page Format (PF) bit. By default it is clear (i.e. 0) unless
94 the list --list option is given in which case the Page Format
95 bit is set (as required by SPC-3).
96 -r, --raw=H,H...
98 string of comma separated hex numbers each of which should
99 resolve to a byte value (i.e. 0 to ff inclusive). A (single)
100 space separated string of hex bytes is also allowed but the list
101 needs to be in quotes. This sequence forms a diagnostic page to
102 be sent with the SCSI SEND DIAGNOSTIC command. Mostly likely the
103 --pf option should also be given.
104 -r, --raw=-
106 reads sequence of bytes from stdin. The sequence may be comma,
107 space, tab or linefeed (newline) separated. If a line contains
108 "#" then the remaining characters on that line are ignored. Oth‐
109 erwise each non separator character should resolve to a byte
110 value (i.e. 0 to ff inclusive). This sequence forms a diagnostic
111 page to be sent with the SCSI SEND DIAGNOSTIC command. Mostly
112 likely the --pf option should also be given.
113 -s, --selftest=ST
115 where ST is the self-test code. The default value is 0 which is
116 inactive. Some other values:
117 1 : background short self-test
118 2 : background extended self-test
119 4 : aborts a (background) self-test that is in progress
120 5 : foreground short self-test
121 6 : foreground extended self-test
122 This option is mutually exclusive with default self-test (i.e.
123 can't have (ST > 0) and --test).
124 -t, --test
126 sets the _default_ Self Test (SelfTest) bit. By default this is
127 clear (0). The --selftest=ST option should not be active
128 together with this option. Both the --doff and/or --uoff options
129 can be used with this option.
130 -u, --uoff
132 set the Unit Offline (UnitOffL) bit (default is clear). Only
133 significant when --test option is set for the default self-test.
134 When set other operations on this logical unit may be affected
135 (delayed) while a default self-test is underway. Some devices
136 (e.g. Fujitsu disks) do more tests when this bit is set.
137 -v, --verbose
139 increase level of verbosity. Can be used multiple times.
140 -V, --version
142 print out version string then exit.
143
145 All devices should support the default self-test. The 'short' self-test
146 codes should complete in 2 minutes or less. The 'extended' self-test
147 codes' maximum duration is vendor specific (e.g. a little over 10 min‐
148 utes with the author's disks). The foreground self-test codes wait
149 until they are completed while the background self-test codes return
150 immediately. The results of both foreground and background self-test
151 codes are placed in the 'self-test results' log page (see sg_logs(8)).
152 The SCSI command timeout for this utility is set to 60 minutes to allow
153 for slow foreground extended self-tests.
154 If the DEVICE is a disk then no file systems residing on that disk
156 should be mounted during a foreground self-test. The reason is that
157 other SCSI commands may become queued behind the foreground self-test
158 and timeout.
159 When the --raw=H,H... option is given then self-tests should not be
161 selected. However the --pf (i.e. "page format") option should be given.
162 The length of the diagnostic page to be sent is derived from the number
163 of bytes given to the --raw=H,H... option. The diagnostic page code
164 (number) should be the first byte of the sequence (i.e. as dictated by
165 SPC-3 diagnostic page format). See the EXAMPLES section below.
166 Arbitrary diagnostic pages can be read (in hex) with the sg_ses(8)
168 utility (not only those defined in SES-2).
169 If the utility is used with no options (e.g. "sg_senddiag /dev/sg1")
171 Then a degenerate SCSI SEND DIAGNOSTIC command is sent with zero in all
172 its fields apart from the opcode. Some devices report this as an error
173 while others ignore it. It is not entirely clear from SPC-3 if it is
174 invalid to send such a command.
175 In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic
177 (sg) device. In the 2.6 series block devices (e.g. SCSI disks and DVD
178 drives) can also be specified.
179 To access SCSI enclosures see the sg_ses(8) utility. sg_ses uses the
181 SCSI SEND DIAGNOSTIC and RECEIVE DIAGNOSTIC RESULTS commands as out‐
182 lined in the SES-2 (draft) standard.
183
185 The exit status of sg_senddiag is 0 when it is successful. Otherwise
186 see the sg3_utils(8) man page.
187
189 The options in this section were the only ones available prior to
190 sg3_utils version 1.23 . In sg3_utils version 1.23 and later these
191 older options can be selected by either setting the SG3_UTILS_OLD_OPTS
192 environment variable or using '--old' (or '-O) as the first option.
193 -doff set the Device Offline (DevOffL) bit (default is clear). Only
195 significant when -t option is set for the default self-test.
196 Equivalent to --doff in the main description.
197 -e outputs the expected extended self-test duration. Equivalent to
199 --extdur in the main description.
200 -h outputs response from RECEIVE DIAGNOSTIC RESULTS in hex rather
202 than decode it.
203 -H outputs response from RECEIVE DIAGNOSTIC RESULTS in hex rather
205 than decode it.
206 -l when a DEVICE is also given lists the names of all diagnostic
208 pages supported by this device. The request is sent via a SEND
209 DIAGNOSTIC command (with the "pf" bit set) and the response is
210 fetched by a RECEIVE DIAGNOSTIC RESULTS command. When used in
211 the absence of a DEVICE argument then a list of diagnostic page
212 names and their numbers, known by this utility, are listed.
213 -N switch to the newer style options.
215 -pf set Page Format (PF) bit. By default it is clear (i.e. 0) unless
217 the -l option is given in which case the Page Format bit is set
218 (as required by SPC-3).
219 -raw=H,H...
221 string of comma separated hex numbers each of which should
222 resolve to a byte value (i.e. 0 to ff inclusive). This sequence
223 forms a diagnostic page to be sent with the SCSI SEND DIAGNOSTIC
224 command. Mostly likely the -pf option should also be given.
225 -raw=- reads sequence of bytes from stdin. The sequence may be comma,
227 space, tab or linefeed (newline) separated. If a line contains
228 "#" then the remaining characters on that line are ignored. Oth‐
229 erwise each non separator character should resolve to a byte
230 value (i.e. 0 to ff inclusive). This sequence forms a diagnostic
231 page to be sent with the SCSI SEND DIAGNOSTIC command. Mostly
232 likely the -pf option should also be given.
233 -s=ST where ST is the self-test code. The default value is 0 which is
235 inactive. A value of 1 selects a background short self-test; 2
236 selects a background extended self-test; 5 selects a foreground
237 short self-test; 6 selects a foreground extended test. A value
238 of 4 will abort a (background) self-test that is in progress.
239 This option is mutually exclusive with default self-test (i.e.
240 -t).
241 -t sets the _default_ Self Test (SelfTest) bit. By default this is
243 clear (0). The -s=ST option should not be active together with
244 this option. Both the -doff and/or -uoff options can be used
245 with this option.
246 -uoff set the Unit Offline (UnitOffL) bit (default is clear). Equiva‐
248 lent to --uoff in the main description.
249 -v increase level of verbosity. Can be used multiple times.
251 -V print out version string then exit.
253 -? output usage message. Ignore all other parameters.
255
257 The examples sub-directory in the sg3_utils packages contains two exam‐
258 ple scripts that turn on the CJTPAT (jitter pattern) on some SAS disks
259 (one script for each phy). One possible invocation for phy 1 is:
260 sg_senddiag --pf --raw=- /dev/sg2 < sdiag_sas_p1_cjtpat.txt
262 There is also an example script that turns on the IDLE pattern. Once a
264 test pattern has been started it can be turned off by resetting the phy
265 or with the STOP phy pattern function:
266 sg_senddiag --pf --raw=- /dev/sg2 < sdiag_sas_p1_stop.txt
268
270 Written by Douglas Gilbert
271
273 Report bugs to <dgilbert at interlog dot com>.
274
276 Copyright © 2003-2015 Douglas Gilbert
277 This software is distributed under the GPL version 2. There is NO war‐
278 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
279 POSE.
280
282 sg_ses(8), sg_logs(8), smartmontools(see net)
283sg3_utils-1.41 April 2015 SG_SENDDIAG(8)