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

NAME

6       sg_raw - send arbitrary SCSI command to a device
7

SYNOPSIS

9       sg_raw     [--binary]     [--cmdfile=CF]     [--enumerate]     [--help]
10       [--infile=IFILE]     [--nosense]     [--outfile=OFILE]     [--readonly]
11       [--request=RLEN]  [--send=SLEN]  [--skip=KLEN] [--timeout=SECS] [--ver‐
12       bose] [--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 commands to the
31       DEVICE. Since all NVMe commands are 64 bytes long it is more convenient
32       to  use  the  --cmdfile=CF  option rather than type the 64 bytes of the
33       NVMe command on the command line. See the section on NVME below.
34

OPTIONS

36       Arguments to long options are mandatory for short options as well.  The
37       options  are  arranged  in  alphabetical order based on the long option
38       name.
39
40       -b, --binary
41              Dump data in binary form, even when writing to stdout.
42
43       -c, --cmdfile=CF
44              CF is the name of a file which contains the command to  be  exe‐
45              cuted.   Without  this  option  the command must be given on the
46              command line, after the options and the DEVICE.
47
48       -h, --help
49              Display usage information and exit.
50
51       -i, --infile=IFILE
52              Read data from IFILE instead of stdin. This option is ignored if
53              --send is not specified.
54
55       -n, --nosense
56              Don't display SCSI Sense information.
57
58       -o, --outfile=OFILE
59              Write  data received from the DEVICE to OFILE. The data is writ‐
60              ten in binary. By default, data is dumped in hex format to  std‐
61              out.   If  OFILE is '-' then data is dumped in binary to stdout.
62              This option is ignored if --request is not specified.
63
64       -R, --readonly
65              Open DEVICE read-only. The default (without this option)  is  to
66              open it read-write.
67
68       -r, --request=RLEN
69              Expect  to  receive  up  to  RLEN bytes of data from the DEVICE.
70              RLEN may be suffixed with 'k'  to  use  kilobytes  (1024  bytes)
71              instead  of  bytes. RLEN is decimal unless it has a leading '0x'
72              or a trailing 'h'.
73              If RLEN is too small (i.e. either smaller than indicated by  the
74              cdb  (typically  the  "allocation  length" field) and/or smaller
75              than the DEVICE tries to send back) then the HBA driver may com‐
76              plain.  Making  RLEN  larger than required should cause no prob‐
77              lems. Most SCSI "data-in" commands return a data block that con‐
78              tains (in its early bytes) a length that the DEVICE would "like"
79              to send back if the "allocation length"  field  in  the  cdb  is
80              large  enough. In practice, the DEVICE will return no more bytes
81              than indicated in the "allocation length" field of the cdb.
82
83       -s, --send=SLEN
84              Read SLEN bytes of data, either from stdin or from a  file,  and
85              send them to the DEVICE. In the SCSI transport, SLEN becomes the
86              length (in bytes) of the  "data-out"  buffer.  SLEN  is  decimal
87              unless it has a leading '0x' or a trailing 'h'.
88              It  is  the  responsibility  of  the  user to make sure that the
89              "data-out" length implied or stated in  the  cdb  matches  SLEN.
90              Note  that  some  common  SCSI commands such as WRITE(10) have a
91              "transfer length" field whose units are  logical  blocks  (which
92              are often 512 bytes long).
93
94       -k, --skip=KLEN
95              Skip  the  first  KLEN  bytes  of the input file or stream. This
96              option is ignored if --send is not specified. If --send is given
97              and this option is not given, then zero bytes are skipped.
98
99       -t, --timeout=SECS
100              Wait  up  to  SECS seconds for command completion (default: 20).
101              Note that if a command times out the operating system may  start
102              by  aborting  the  command  and  if  that is unsuccessful it may
103              attempt to reset the device.
104
105       -v, --verbose
106              Increase level of verbosity. Can be used multiple times.
107
108       -V, --version
109              Display version and license information and exit.
110

NOTES

112       The sg_inq utility can be used to send an INQUIRY command to  a  device
113       to  determine  its  peripheral  device  type  (e.g. '1' for a streaming
114       device (tape drive)) which determines which SCSI command sets a  device
115       should support (e.g. SPC and SSC). The sg_vpd utility reads and decodes
116       a device's Vital Product Pages which may contain useful information.
117
118       The ability to send more than a 16 byte CDB (in some cases 12 byte CDB)
119       may  be  restricted by the pass-through interface, the low level driver
120       or the transport. In the Linux series 3 kernels,  the  bsg  driver  can
121       handle  longer  CDBs,  block  devices  (e.g. /dev/sdc) accessed via the
122       SG_IO ioctl cannot handle CDBs longer than 16 bytes, and the sg  driver
123       can handle longer CDBs from lk 3.17 .
124
125       The  CDB  command name defined by T10 for the given CDB is shown if the
126       '-vv' option is given. The command line syntax still needs to  be  cor‐
127       rect,  so  /dev/null  may  be used for the DEVICE since the CDB command
128       name decoding is done before the DEVICE is checked.
129

NVME SUPPORT

131       Support for NVMe (a.k.a. NVM Express) is currently  experimental.  NVMe
132       concepts  map  reasonably well to the SCSI architecture. A SCSI logical
133       unit (LU) is similar to a NVMe namespace (although LUN 0 is very common
134       in  SCSI while namespace IDs start at 1). A SCSI target device is simi‐
135       lar to a NVMe controller. SCSI commands vary from 6 to 260  bytes  long
136       (although  SCSI  command descriptor blocks (cdb_s) longer than 32 bytes
137       are uncommon) while all NVMe commands are currently 64 bytes long.  The
138       SCSI architecture makes a clear distinction between an initiator (often
139       called a HBA) and a target (device) while (at least on the PCIe  trans‐
140       port)  the  NVMe controller plays both roles. At this time this utility
141       only supports "Admin" commands (i.e. it does not support  the  I/O  (or
142       "NVM")  command  set).  Admin  commands  are sent to submission queue 0
143       while non-admin commands are sent to submissions greater than 0.
144
145       One significant difference is that SCSI uses a big  endian  representa‐
146       tion for integers that are longer than 8 bits (i.e. longer than 1 byte)
147       while NVMe uses a little endian representation (like most  things  that
148       have  originated from the Intel organisation). NVMe specifications talk
149       about Words (16 bits), Double Words (32 bits) and sometimes Quad  Words
150       (64 bits) and has tighter alignment requirements than SCSI.
151
152       One  difference  that impacts this utility is that NVMe places pointers
153       to host memory in its commands while SCSI leaves this detail to  which‐
154       ever  transport  it is using (e.g. SAS, iSCSI, SRP). Since this utility
155       takes the command from the user (either on the command  line  or  in  a
156       file  named CF) but this utility allocates a data-in or data-out buffer
157       as required, the user does not know in advance what the address of that
158       buffer  will  be.  Some  special addresses have been introduced to help
159       with this problem: the address  0xfffffffffffffffe  is  interpreted  as
160       "use  the  data-in buffer's address" while 0xfffffffffffffffd is inter‐
161       preted as "use the data-out buffer's address". Since NVMe  uses  little
162       endian  notation  then  that  first address appears in the NVMe command
163       byte stream as "fe" followed by seven "ff"s. A similar  arrangement  is
164       made  for  the length of that buffer, but since that is a 32 byte quan‐
165       tity, the first 4 bytes (all "ff"s) are removed.
166
167       Two command file examples can be found in  the  examples  directory  of
168       this    package's    source    tarball:    nvme_identify_ctl.hex    and
169       nvme_dev_self_test.hex .
170

EXAMPLES

172       These examples, apart from the last one, use Linux  device  names.  For
173       suitable  device  names  in  other  supported Operating Systems see the
174       sg3_utils(8) man page.
175
176       sg_raw /dev/scd0 1b 00 00 00 02 00
177              Eject the medium in CD drive /dev/scd0.
178
179       sg_raw -r 1k /dev/sg0 12 00 00 00 60 00
180              Perform an INQUIRY on /dev/sg0 and dump the response data (up to
181              1024 bytes) to stdout.
182
183       sg_raw -s 512 -i i512.bin /dev/sda 3b 02 00 00 00 00 00 02 00 00
184              Showing an example of writing 512 bytes to a sector on a disk is
185              a little dangerous. Instead  this  example  will  read  i512.bin
186              (assumed  to  be  512  bytes long) and use the SCSI WRITE BUFFER
187              command to send it to the "data" buffer (that is mode  2).  This
188              is a safe operation.
189
190       sg_raw -r 512 -o o512.bin /dev/sda 3c 02 00 00 00 00 00 02 00 00
191              This  will  use  the  SCSI READ BUFFER command to read 512 bytes
192              from the "data" buffer (i.e.  mode  2)  then  write  it  to  the
193              o512.bin file.  When used in conjunction with the previous exam‐
194              ple, if both commands work then 'cmp i512.bin  o512.bin'  should
195              show a match.
196
197       sg_raw  --infile=urandom.bin --send=512 --request=512 --outfile=out.bin
198       "/dev/bsg/7:0:0:0" 53 00 00 00 00 00 00 00 01 00
199              This is a bidirectional XDWRITEREAD(10) command being sent via a
200              Linux  bsg  device.  Note  that  data  is being read from "uran‐
201              dom.bin" and sent to the device (data-out) while resulting  data
202              (data-in)  is placed in the "out.bin" file. Also note the length
203              of both is 512 bytes which corresponds to the transfer length of
204              1 (block) in the cdb (i.e.  the second last byte).
205
206       sg_raw.exe PhysicalDrive1 a1 0c 0e 00 00 00 00 00 00 e0 00 00
207              This  example  is from Windows and shows a ATA STANDBY IMMEDIATE
208              command being sent to PhysicalDrive1. That ATA command  is  con‐
209              tained within the SCSI ATA PASS-THROUGH(12) command (see the SAT
210              or  SAT-2  standard  at  http://www.t10.org).  Notice  that  the
211              STANDBY  IMMEDIATE  command  does  not send or receive any addi‐
212              tional data, however if it fails sense data should  be  returned
213              and displayed.
214

EXIT STATUS

216       The exit status of sg_raw is 0 when it is successful. Otherwise see the
217       sg3_utils(8) man page.
218

AUTHOR

220       Written by Ingo van Lil
221

REPORTING BUGS

223       Report bugs to <inguin at gmx dot de>.
224
226       Copyright © 2001-2018 Ingo van Lil
227       This software is distributed under the GPL version 2. There is NO  war‐
228       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
229       POSE.
230

SEE ALSO

232       sg_inq, sg_vpd, sg3_utils (sg3_utils), plscsi
233
234
235
236sg3_utils-1.43                     May 2018                          SG_RAW(8)
Impressum