1SG_RAW(8)                          SG3_UTILS                         SG_RAW(8)
2
3
4

NAME

6       sg_raw - send arbitrary SCSI or NVMe command to a device
7

SYNOPSIS

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

DESCRIPTION

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
22       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
27       The commands pass through a generic SCSI interface which is implemented
28       for several operating systems including Linux, FreeBSD and Windows.
29
30       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

OPTIONS

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
43       -b, --binary
44              Dump data in binary form, even when writing to stdout.
45
46       -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
51       -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
58       -h, --help
59              Display usage information and exit.
60
61       -i, --infile=IFILE
62              Read data from IFILE instead of stdin. This option is ignored if
63              --send is not specified.
64
65       -n, --nosense
66              Don't display SCSI Sense information.
67
68       -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
73       -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
79       -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
83       -R, --readonly
84              Open DEVICE read-only. The default (without this option)  is  to
85              open it read-write.
86
87       -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
102       -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
114       -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
125       -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
130       -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
136       -v, --verbose
137              Increase level of verbosity. Can be used multiple times.
138
139       -V, --version
140              Display version and license information and exit.
141

NOTES

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
149       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
156       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
161       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

NVME SUPPORT

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
182       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
189       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
204       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
208       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

EXAMPLES

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
219       sg_raw /dev/scd0 1b 00 00 00 02 00
220              Eject the medium in CD drive /dev/scd0.
221
222       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
226       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
233       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
240       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
251       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

EXIT STATUS

261       The exit status of sg_raw is 0 when it is successful. Otherwise see the
262       sg3_utils(8) man page.
263

AUTHOR

265       Written by Ingo van Lil
266

REPORTING BUGS

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

SEE ALSO

278       sg_inq, sg_vpd, sg3_utils (sg3_utils), plscsi
279
280
281
282sg3_utils-1.46                   January 2021                        SG_RAW(8)
Impressum