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

NAME

6       sg_write_buffer - send SCSI WRITE BUFFER commands
7

SYNOPSIS

9       sg_write_buffer  [--bpw=CS]  [--dry-run] [--help] [--id=ID] [--in=FILE]
10       [--length=LEN] [--mode=MO] [--offset=OFF] [--read-stdin]  [--skip=SKIP]
11       [--specific=MS] [--timeout=TO] [--verbose] [--version] DEVICE
12

DESCRIPTION

14       Sends one or more SCSI WRITE BUFFER commands to DEVICE, along with data
15       provided by the user. In some cases no data is required, or data can be
16       read  from the file given in the --in=FILE option, or data is read from
17       stdin when either --read-stdin or --in=- is given.
18
19       Some WRITE BUFFER command variants do not have associated data to  send
20       to  the  device. For example "activate_mc" activates deferred microcode
21       that was sent via prior WRITE BUFFER commands.  There  is  a  different
22       method   used   to   download   microcode   to  SES  devices,  see  the
23       sg_ses_microcode utility.
24

OPTIONS

26       Arguments to long options are mandatory for short options as well.  The
27       options  are  arranged  in  alphabetical order based on the long option
28       name.
29
30       -b, --bpw=CS
31              where CS is the chunk size in bytes. This will  be  the  maximum
32              number  of bytes sent per WRITE BUFFER command. So if CS is less
33              than the effective length then multiple  WRITE  BUFFER  commands
34              are  sent,  each  taking  the  next chunk from the read data and
35              increasing the buffer offset field in the WRITE  BUFFER  command
36              by  the  appropriate  amount.  The  default is a chunk size of 0
37              which is interpreted as a very large number hence only one WRITE
38              BUFFER  command  will  be  sent. This option should only be used
39              with modes that "download microcode, with offsets  ...";  namely
40              either mode 0x6, 0x7, 0xd or 0xe.
41              The number in CS can optionally be followed by ",act" or ",acti‐
42              vate".  In this case after WRITE BUFFER commands have been  sent
43              until  the  effective  length  is exhausted another WRITE BUFFER
44              command with its mode set to "Activate deferred microcode  mode"
45              [mode 0xf] is sent.
46
47       -d, --dry-run
48              Do  all  the command line processing and sanity checks including
49              reading the input file. However at the point where a WRITE  BUF‐
50              FER  SCSI  command(s)  would  be  sent,  step over that call and
51              assume it completed without errors and continue. DEVICE is still
52              opened but can be /dev/null (in Unix).  It is recommended to use
53              --verbose with this option to get an overview of what would have
54              happened.
55
56       -h, --help
57              output  the usage message then exit. If used multiple times also
58              prints the mode names and their acronyms.
59
60       -i, --id=ID
61              this option sets the buffer id field in the cdb. ID is  a  value
62              between 0 (default) and 255 inclusive.
63
64       -I, --in=FILE
65              read data from file FILE that will be sent with the WRITE BUFFER
66              command.  If FILE is '-' then stdin is  read  until  an  EOF  is
67              detected (this is the same action as --read-stdin). Data is read
68              from the beginning of FILE except in the case when it is a regu‐
69              lar file and the --skip=SKIP option is given.
70
71       -l, --length=LEN
72              where  LEN is the length, in bytes, of data to be written to the
73              device.  If not given (and the length  cannot  be  deduced  from
74              --in=FILE  or --read-stdin) then defaults to zero. If the option
75              is given and the length deduced from --in=FILE  or  --read-stdin
76              is less (or no data is provided), then bytes of 0xff are used as
77              fill bytes.
78
79       -m, --mode=MO
80              this option sets the MODE field  in  the  cdb.  MO  is  a  value
81              between 0 (default) and 31 inclusive. Alternatively an abbrevia‐
82              tion can be given.  See the MODES section  below.  To  list  the
83              available  mode  abbreviations  at  run time give an invalid one
84              (e.g. '--mode=xxx') or use the '-hh' option.
85
86       -o, --offset=OFF
87              this option sets the BUFFER OFFSET field in the cdb.  OFF  is  a
88              value between 0 (default) and 2**24-1 . It is a byte offset.
89
90       -r, --read-stdin
91              read data from stdin until an EOF is detected. This data is sent
92              with the WRITE BUFFER command to  DEVICE.  The  action  of  this
93              option  is  the same as using '--in=-'. Previously this option's
94              long name was --raw and it may still be used for  backward  com‐
95              patibility.
96
97       -s, --skip=SKIP
98              this option is only active when --in=FILE is given and FILE is a
99              regular file, rather than stdin. Data is read starting  at  byte
100              offset  SKIP  to  the  end  of  file  (or  the  amount  given by
101              --length=LEN).  If not given the byte offset defaults to 0 (i.e.
102              the start of the file).
103
104       -S, --specific=MS
105              MS  is the MODE SPECIFIC field in the cdb. This is a 3-bit field
106              so the values 0 to 7 are accepted. This field was introduced  in
107              SPC-4  revision  32 and can be used to specify additional events
108              that activate deferred microcode (when MO is 0xD).
109
110       -t, --timeout=TO
111              TO is the command timeout (in seconds)  for  each  WRITE  BUFFER
112              command issued by this utility. Its default value is 300 seconds
113              (5 minutes) and should only be altered if  this  is  not  suffi‐
114              cient.
115
116       -v, --verbose
117              increase the level of verbosity, (i.e. debug output).
118
119       -V, --version
120              print the version string and then exit.
121

MODES

123       Following  is  a  list  of  WRITE  BUFFER command settings for the MODE
124       field.  First is an acronym accepted by the MO argument of  this  util‐
125       ity.   Following  the  acronym in square brackets are the corresponding
126       decimal and hex values that may also be given for MO. The following are
127       listed in numerical order.
128
129       hd  [0, 0x0]
130              Combined header and data (obsolete in SPC-4).
131
132       vendor  [1, 0x1]
133              Vendor specific.
134
135       data  [2, 0x2]
136              Data (was called "Write Data" in SPC-3).
137
138       dmc  [4, 0x4]
139              Download microcode and activate (was called "Download microcode"
140              in SPC-3).
141
142       dmc_save  [5, 0x5]
143              Download microcode, save, and  activate  (was  called  "Download
144              microcode and save" in SPC-3).
145
146       dmc_offs  [6, 0x6]
147              Download  microcode with offsets and activate (was called "Down‐
148              load microcode with offsets" in SPC-3).
149
150       dmc_offs_save  [7, 0x7]
151              Download microcode with offsets, save, and activate (was  called
152              "Download microcode with offsets and save" in SPC-3).
153
154       echo  [10, 0xa]
155              Write data to echo buffer (was called "Echo buffer" in SPC-3).
156
157       dmc_offs_ev_defer  [13, 0xd]
158              Download microcode with offsets, select activation events, save,
159              and defer activate (introduced in SPC-4).
160
161       dmc_offs_defer  [14, 0xe]
162              Download  microcode  with  offsets,  save,  and  defer  activate
163              (introduced in SPC-4).
164
165       activate_mc  [15, 0xf]
166              Activate deferred microcode (introduced in SPC-4).
167
168       en_ex  [26, 0x1A]
169              Enable  expander  communications protocol and Echo buffer (obso‐
170              lete in SPC-4).
171
172       dis_ex  [27, 0x1B]
173              Disable expander communications protocol (obsolete in SPC-4).
174
175       deh  [28, 0x1C]
176              Download application client error history (was called  "Download
177              application log" in SPC-3).
178

NOTES

180       If no --length=LEN is given this utility reads up to 8 MiB of data from
181       the given file FILE (or stdin). If a larger amount of data is  required
182       then the --length=LEN option should be given.
183
184       The user should be aware that most operating systems have limits on the
185       amount of data that can be sent with one SCSI command.  In  Linux  this
186       depends  on the pass through mechanism used (e.g. block SG_IO or the sg
187       driver) and various setting in sysfs in the Linux lk 2.6/3 series (e.g.
188       /sys/block/sda/queue/max_sectors_kb). Devices (i.e. logical units) also
189       typically have limits on the maximum amount of data they can handle  in
190       one  command.  These  two limitations suggest that modes containing the
191       word "offset"  together  with  the  --bpw=CS  option  are  required  as
192       firmware  files  get  larger and larger. And CS can be quite small, for
193       example 4096 bytes, resulting in many WRITE BUFFER commands being sent.
194
195       Attempting to download a microcode/firmware file that is too large  may
196       cause an error to occur in the pass-through layer (i.e. before the SCSI
197       command is issued). In Linux such error reports can be  obscure  as  in
198       "pass  through  os error invalid argument". FreeBSD reports such errors
199       well to the machine's console but returns a cryptic  error  message  to
200       this utility.
201
202       Downloading incorrect microcode into a device has the ability to render
203       that device inoperable. One would hope that the device vendor  verifies
204       the  data  before  activating  it.  If the SCSI WRITE BUFFER command is
205       given values in its cdb (e.g. LEN) that  are  inappropriate  (e.g.  too
206       large)  then  the  device  should  respond  with a sense key of ILLEGAL
207       REQUEST and an additional sense code of INVALID  FIELD  in  CDB.  If  a
208       WRITE BUFFER command (or a sequence of them) fails due to device vendor
209       verification checks then it should respond with a sense key of  ILLEGAL
210       REQUEST and an additional sense code of COMMAND SEQUENCE ERROR.
211
212       All  numbers  given  with  options are assumed to be decimal.  Alterna‐
213       tively numerical values can be given in hexadecimal preceded by  either
214       "0x" or "0X" (or has a trailing "h" or "H").
215

EXAMPLES

217       The following sends new firmware to an enclosure. Sending a 1.5 MB file
218       in one WRITE BUFFER command caused the enclosure to lock up temporarily
219       and  did  not update the firmware. Breaking the firmware file into 4 KB
220       chunks (an educated guess) was more successful:
221
222         sg_write_buffer -b 4k -m dmc_offs_save -I firmware.bin /dev/sg4
223
224       The firmware update occurred in the following  enclosure  power  cycle.
225       With a modern enclosure the Extended Inquiry VPD page gives indications
226       in which situations a firmware upgrade will take place.
227

EXIT STATUS

229       The exit status of sg_write_buffer is 0 when it is  successful.  Other‐
230       wise see the sg3_utils(8) man page.
231

AUTHORS

233       Written by Luben Tuikov and Douglas Gilbert.
234

REPORTING BUGS

236       Report bugs to <dgilbert at interlog dot com>.
237
239       Copyright © 2006-2018 Luben Tuikov and Douglas Gilbert
240       This  software is distributed under a FreeBSD license. There is NO war‐
241       ranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR  PUR‐
242       POSE.
243

SEE ALSO

245       sg_read_buffer, sg_ses_microcode(sg3_utils)
246
247
248
249sg3_utils-1.45                   November 2018              SG_WRITE_BUFFER(8)
Impressum