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

MODES

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

NOTES

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

EXAMPLES

203       The following sends new firmware to an enclosure. Sending a 1.5 MB file
204       in one WRITE BUFFER command caused the enclosure to lock up temporarily
205       and did not update the firmware. Breaking the firmware file into  4  KB
206       chunks (an educated guess) was more successful:
207
208         sg_write_buffer -b 4k -m dmc_offs_save -I firmware.bin /dev/sg4
209
210       The  firmware  update  occurred in the following enclosure power cycle.
211       With a modern enclosure the Extended Inquiry VPD page gives indications
212       in which situations a firmware upgrade will take place.
213

EXIT STATUS

215       The  exit  status of sg_write_buffer is 0 when it is successful. Other‐
216       wise see the sg3_utils(8) man page.
217

AUTHORS

219       Written by Luben Tuikov and Douglas Gilbert.
220

REPORTING BUGS

222       Report bugs to <dgilbert at interlog dot com>.
223
225       Copyright © 2006-2015 Luben Tuikov and Douglas Gilbert
226       This software is distributed under a FreeBSD license. There is NO  war‐
227       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
228       POSE.
229

SEE ALSO

231       sg_read_buffer, sg_ses_microcode(sg3_utils)
232
233
234
235sg3_utils-1.41                   February 2015              SG_WRITE_BUFFER(8)
Impressum