1SG_WRITE_BUFFER(8) SG3_UTILS SG_WRITE_BUFFER(8)
2
6 sg_write_buffer - send SCSI WRITE BUFFER commands
7
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
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 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
26 Arguments to long options are mandatory for short options as well.
27 -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 -h, --help
46 output the usage message then exit. If used multiple times also
47 prints the mode names and their acronyms.
48 -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 -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 -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 -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 -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 -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 -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 -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 -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 -v, --verbose
103 increase the level of verbosity, (i.e. debug output).
104 -V, --version
106 print the version string and then exit.
107
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 hd [0, 0x0]
116 Combined header and data (obsolete in SPC-4).
117 vendor [1, 0x1]
119 Vendor specific.
120 data [2, 0x2]
122 Data (was called "Write Data" in SPC-3).
123 dmc [4, 0x4]
125 Download microcode and activate (was called "Download microcode"
126 in SPC-3).
127 dmc_save [5, 0x5]
129 Download microcode, save, and activate (was called "Download
130 microcode and save" in SPC-3).
131 dmc_offs [6, 0x6]
133 Download microcode with offsets and activate (was called "Down‐
134 load microcode with offsets" in SPC-3).
135 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 echo [10, 0xa]
141 Write data to echo buffer (was called "Echo buffer" in SPC-3).
142 dmc_offs_ev_defer [13, 0xd]
144 Download microcode with offsets, select activation events, save,
145 and defer activate (introduced in SPC-4).
146 dmc_offs_defer [14, 0xe]
148 Download microcode with offsets, save, and defer activate
149 (introduced in SPC-4).
150 activate_mc [15, 0xf]
152 Activate deferred microcode (introduced in SPC-4).
153 en_ex [26, 0x1A]
155 Enable expander communications protocol and Echo buffer (obso‐
156 lete in SPC-4).
157 dis_ex [27, 0x1B]
159 Disable expander communications protocol (obsolete in SPC-4).
160 deh [28, 0x1C]
162 Download application client error history (was called "Download
163 application log" in SPC-3).
164
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 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 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 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 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
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 sg_write_buffer -b 4k -m dmc_offs_save -I firmware.bin /dev/sg4
209 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
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
219 Written by Luben Tuikov and Douglas Gilbert.
220
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
231 sg_read_buffer, sg_ses_microcode(sg3_utils)
232sg3_utils-1.41 February 2015 SG_WRITE_BUFFER(8)