1SG_RAW(8) SG3_UTILS SG_RAW(8)
2
6 sg_raw - send arbitrary SCSI or NVMe command to a device
7
9 sg_raw [--binary] [--cmdfile=CF] [--cmdset=CS] [--enumerate] [--help]
10 [--infile=IFILE] [--nosense] [--nvm] [--outfile=OFILE] [--raw] [--read‐
11 only] [--request=RLEN] [--scan=FO,LO] [--send=SLEN] [--skip=KLEN]
12 [--timeout=SECS] [--verbose] [--version] DEVICE [CDB0 CDB1 ...]
13
15 This utility sends an arbitrary SCSI command (between 6 and 256 bytes)
16 to the DEVICE. There may be no associated data transfer; or data may be
17 read from a file and sent to the DEVICE; or data may be received from
18 the DEVICE and then displayed or written to a file. If supported by the
19 pass through, bidirectional commands may be sent (i.e. containing both
20 data to be sent to the DEVICE and received from the DEVICE).
21 The SCSI command may be between 6 and 256 bytes long. Each command byte
23 is specified in plain hex format (00..FF) without a prefix or suffix.
24 The command can be given either on the command line or via the --cmd‐
25 file=CF option. See EXAMPLES section below.
26 The commands pass through a generic SCSI interface which is implemented
28 for several operating systems including Linux, FreeBSD and Windows.
29 Experimental support has been added to send NVMe Admin and NVM commands
31 to the DEVICE. Since all NVMe commands are 64 bytes long it is more
32 convenient to use the --cmdfile=CF option rather than type the 64 bytes
33 of the NVMe command on the command line. See the section on NVME below.
34 A heuristic based on command length is used to decide if the given com‐
35 mand is SCSI or NVMe, to override this heuristic use the --cmdset=CS
36 option.
37
39 Arguments to long options are mandatory for short options as well. The
40 options are arranged in alphabetical order based on the long option
41 name.
42 -b, --binary
44 Dump data in binary form, even when writing to stdout.
45 -c, --cmdfile=CF
47 CF is the name of a file which contains the command to be exe‐
48 cuted. Without this option the command must be given on the
49 command line, after the options and the DEVICE.
50 -C, --cmdset=CS
52 CS is a number to indicate which command set (i.e. SCSI or NVMe)
53 to use. 0, the default, causes a heuristic based on command
54 length to be used. Use a CS of 1 to override that heuristic and
55 choose the SCSI command set. Use a CS of 2 to override that
56 heuristic and choose the NVMe command set.
57 -h, --help
59 Display usage information and exit.
60 -i, --infile=IFILE
62 Read data from IFILE instead of stdin. This option is ignored if
63 --send is not specified.
64 -n, --nosense
66 Don't display SCSI Sense information.
67 -N, --nvm
69 When sending NVMe commands, the Admin command set is assumed. To
70 send the NVM command set (e.g. the Read and Write (user data)
71 commands) this option needs to be given.
72 -o, --outfile=OFILE
74 Write data received from the DEVICE to OFILE. The data is writ‐
75 ten in binary. By default, data is dumped in hex format to std‐
76 out. If OFILE is '-' then data is dumped in binary to stdout.
77 This option is ignored if --request is not specified.
78 -w, --raw
80 interpret CF (i.e. the command file) as containing binary. The
81 default is to assume that it contains ASCII hexadecimal.
82 -R, --readonly
84 Open DEVICE read-only. The default (without this option) is to
85 open it read-write.
86 -r, --request=RLEN
88 Expect to receive up to RLEN bytes of data from the DEVICE.
89 RLEN may be suffixed with 'k' to use kilobytes (1024 bytes) in‐
90 stead of bytes. RLEN is decimal unless it has a leading '0x' or
91 a trailing 'h'.
92 If RLEN is too small (i.e. either smaller than indicated by the
93 cdb (typically the "allocation length" field) and/or smaller
94 than the DEVICE tries to send back) then the HBA driver may com‐
95 plain. Making RLEN larger than required should cause no prob‐
96 lems. Most SCSI "data-in" commands return a data block that con‐
97 tains (in its early bytes) a length that the DEVICE would "like"
98 to send back if the "allocation length" field in the cdb is
99 large enough. In practice, the DEVICE will return no more bytes
100 than indicated in the "allocation length" field of the cdb.
101 -Q, --scan=FO,LO
103 Scan a range of opcodes (i.e. first byte of each command). The
104 first opcode in the scan is FO (which is decimal unless it has a
105 '0x' prefix or 'h' suffix). The last opcode in the scan is LO.
106 The maximum value of LO is 255. The remaining bytes of the
107 SCSI/NVMe command are as supplied at invocation.
108 Warning: this option can be dangerous. Sending somewhat arbi‐
109 trary commands to a device can have unexpected results. It is
110 recommended that this option is used with the --cmdset=CS option
111 where CS is 1 or 2 in order to stop the command set possibly
112 changing during the scan.
113 -s, --send=SLEN
115 Read SLEN bytes of data, either from stdin or from a file, and
116 send them to the DEVICE. In the SCSI transport, SLEN becomes the
117 length (in bytes) of the "data-out" buffer. SLEN is decimal un‐
118 less it has a leading '0x' or a trailing 'h'.
119 It is the responsibility of the user to make sure that the
120 "data-out" length implied or stated in the cdb matches SLEN.
121 Note that some common SCSI commands such as WRITE(10) have a
122 "transfer length" field whose units are logical blocks (which
123 are usually 512 or 4096 bytes long).
124 -k, --skip=KLEN
126 Skip the first KLEN bytes of the input file or stream. This op‐
127 tion is ignored if --send is not specified. If --send is given
128 and this option is not given, then zero bytes are skipped.
129 -t, --timeout=SECS
131 Wait up to SECS seconds for command completion (default: 20).
132 Note that if a command times out the operating system may start
133 by aborting the command and if that is unsuccessful it may at‐
134 tempt to reset the device.
135 -v, --verbose
137 Increase level of verbosity. Can be used multiple times.
138 -V, --version
140 Display version and license information and exit.
141
143 The sg_inq utility can be used to send an INQUIRY command to a device
144 to determine its peripheral device type (e.g. '1' for a streaming de‐
145 vice (tape drive)) which determines which SCSI command sets a device
146 should support (e.g. SPC and SSC). The sg_vpd utility reads and decodes
147 a device's Vital Product Pages which may contain useful information.
148 The ability to send more than a 16 byte CDB (in some cases 12 byte CDB)
150 may be restricted by the pass-through interface, the low level driver
151 or the transport. In the Linux series 3 kernels, the bsg driver can
152 handle longer CDBs, block devices (e.g. /dev/sdc) accessed via the
153 SG_IO ioctl cannot handle CDBs longer than 16 bytes, and the sg driver
154 can handle longer CDBs from lk 3.17 .
155 The CDB command name defined by T10 for the given CDB is shown if the
157 '-vv' option is given. The command line syntax still needs to be cor‐
158 rect, so /dev/null may be used for the DEVICE since the CDB command
159 name decoding is done before the DEVICE is checked.
160 The intention of the --scan=FO,LO option is to slightly simplify the
162 process of finding hidden or undocumented commands. It should be used
163 with care; for example checking for vendor specific SCSI commands:
164 'sg_raw --cmdset=1 --scan=0xc0,0xff /dev/sg1 0 0 0 0 0 0'.
165
167 Support for NVMe (a.k.a. NVM Express) is currently experimental. NVMe
168 concepts map reasonably well to the SCSI architecture. A SCSI logical
169 unit (LU) is similar to a NVMe namespace (although LUN 0 is very common
170 in SCSI while namespace IDs start at 1). A SCSI target device is simi‐
171 lar to a NVMe controller. SCSI commands vary from 6 to 260 bytes long
172 (although SCSI command descriptor blocks (cdb_s) longer than 32 bytes
173 are uncommon) while all NVMe commands are currently 64 bytes long. The
174 SCSI architecture makes a clear distinction between an initiator (often
175 called a HBA) and a target (device) while (at least on the PCIe trans‐
176 port) the NVMe controller plays both roles. This utility defaults to
177 assuming the user provided 64 byte command belongs to NVMe's Admin com‐
178 mand set. To issue commands from the "NVM" command set, the --nvm op‐
179 tion must be given. Admin and NVM commands are sent to submission queue
180 0.
181 One significant difference is that SCSI uses a big endian representa‐
183 tion for integers that are longer than 8 bits (i.e. longer than 1 byte)
184 while NVMe uses a little endian representation (like most things that
185 have originated from the Intel organisation). NVMe specifications talk
186 about Words (16 bits), Double Words (32 bits) and sometimes Quad Words
187 (64 bits) and has tighter alignment requirements than SCSI.
188 One difference that impacts this utility is that NVMe places pointers
190 to host memory in its commands while SCSI leaves this detail to which‐
191 ever transport it is using (e.g. SAS, iSCSI, SRP). Since this utility
192 takes the command from the user (either on the command line or in a
193 file named CF) but this utility allocates a data-in or data-out buffer
194 as required, the user does not know in advance what the address of that
195 buffer will be. Some special addresses have been introduced to help
196 with this problem: the address 0xfffffffffffffffe is interpreted as
197 "use the data-in buffer's address" while 0xfffffffffffffffd is inter‐
198 preted as "use the data-out buffer's address". Since NVMe uses little
199 endian notation then that first address appears in the NVMe command
200 byte stream as "fe" followed by seven "ff"s. A similar arrangement is
201 made for the length of that buffer (in bytes), but since that is a 32
202 byte quantity, the first 4 bytes (all "ff"s) are removed.
203 Several command file examples can be found in the examples directory of
205 this package's source tarball: nvme_identify_ctl.hex,
206 nvme_dev_self_test.hex, nvme_read_ctl.hex and nvme_write_ctl.hex .
207 Beware: the NVMe standard often refers to some of its fields as "0's
209 based". They are typically counts of something like the number of
210 blocks to be read. For example in NVMe Read command, a "0's based"
211 number of blocks field containing the value 3 means to read 4 blocks!
212 No, this is not a joke.
213
215 These examples, apart from the last one, use Linux device names. For
216 suitable device names in other supported Operating Systems see the
217 sg3_utils(8) man page.
218 sg_raw /dev/scd0 1b 00 00 00 02 00
220 Eject the medium in CD drive /dev/scd0.
221 sg_raw -r 1k /dev/sg0 12 00 00 00 60 00
223 Perform an INQUIRY on /dev/sg0 and dump the response data (up to
224 1024 bytes) to stdout.
225 sg_raw -s 512 -i i512.bin /dev/sda 3b 02 00 00 00 00 00 02 00 00
227 Showing an example of writing 512 bytes to a sector on a disk is
228 a little dangerous. Instead this example will read i512.bin (as‐
229 sumed to be 512 bytes long) and use the SCSI WRITE BUFFER com‐
230 mand to send it to the "data" buffer (that is mode 2). This is a
231 safe operation.
232 sg_raw -r 512 -o o512.bin /dev/sda 3c 02 00 00 00 00 00 02 00 00
234 This will use the SCSI READ BUFFER command to read 512 bytes
235 from the "data" buffer (i.e. mode 2) then write it to the
236 o512.bin file. When used in conjunction with the previous exam‐
237 ple, if both commands work then 'cmp i512.bin o512.bin' should
238 show a match.
239 sg_raw --infile=urandom.bin --send=512 --request=512 --outfile=out.bin
241 "/dev/bsg/7:0:0:0" 53 00 00 00 00 00 00 00 01 00
242 This is a bidirectional XDWRITEREAD(10) command being sent via a
243 Linux bsg device. Note that data is being read from "uran‐
244 dom.bin" and sent to the device (data-out) while resulting data
245 (data-in) is placed in the "out.bin" file. Also note the length
246 of both is 512 bytes which corresponds to the transfer length of
247 1 (block) in the cdb (i.e. the second last byte). urandom.bin
248 can be produced like this:
249 dd if=/dev/urandom bs=512 count=1 of=urandom.bin
250 sg_raw.exe PhysicalDrive1 a1 0c 0e 00 00 00 00 00 00 e0 00 00
252 This example is from Windows and shows a ATA STANDBY IMMEDIATE
253 command being sent to PhysicalDrive1. That ATA command is con‐
254 tained within the SCSI ATA PASS-THROUGH(12) command (see the SAT
255 or SAT-2 standard at http://www.t10.org). Notice that the
256 STANDBY IMMEDIATE command does not send or receive any addi‐
257 tional data, however if it fails sense data should be returned
258 and displayed.
259
261 The exit status of sg_raw is 0 when it is successful. Otherwise see the
262 sg3_utils(8) man page.
263
265 Written by Ingo van Lil
266
268 Report bugs to <inguin at gmx dot de> or to <dgilbert at interlog dot
269 com>.
270
272 Copyright © 2001-2021 Ingo van Lil
273 This software is distributed under the GPL version 2. There is NO war‐
274 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
275 POSE.
276
278 sg_inq, sg_vpd, sg3_utils (sg3_utils), plscsi
279sg3_utils-1.46 January 2021 SG_RAW(8)