228 lines
10 KiB
Groff
228 lines
10 KiB
Groff
.TH SG_WRITE_BUFFER "8" "November 2018" "sg3_utils\-1.45" SG3_UTILS
|
|
.SH NAME
|
|
sg_write_buffer \- send SCSI WRITE BUFFER commands
|
|
.SH SYNOPSIS
|
|
.B sg_write_buffer
|
|
[\fI\-\-bpw=CS\fR] [\fI\-\-dry\-run\fR] [\fI\-\-help\fR] [\fI\-\-id=ID\fR]
|
|
[\fI\-\-in=FILE\fR] [\fI\-\-length=LEN\fR] [\fI\-\-mode=MO\fR]
|
|
[\fI\-\-offset=OFF\fR] [\fI\-\-read\-stdin\fR] [\fI\-\-skip=SKIP\fR]
|
|
[\fI\-\-specific=MS\fR] [\fI\-\-timeout=TO\fR] [\fI\-\-verbose\fR]
|
|
[\fI\-\-version\fR] \fIDEVICE\fR
|
|
.SH DESCRIPTION
|
|
.\" Add any additional description here
|
|
.PP
|
|
Sends one or more SCSI WRITE BUFFER commands to \fIDEVICE\fR, along with data
|
|
provided by the user. In some cases no data is required, or data can be read
|
|
from the file given in the \fI\-\-in=FILE\fR option, or data is read from
|
|
stdin when either \fI\-\-read\-stdin\fR or \fI\-\-in=\-\fR is given.
|
|
.PP
|
|
Some WRITE BUFFER command variants do not have associated data to send to the
|
|
device. For example "activate_mc" activates deferred microcode that was sent
|
|
via prior WRITE BUFFER commands. There is a different method used to download
|
|
microcode to SES devices, see the sg_ses_microcode utility.
|
|
.SH OPTIONS
|
|
Arguments to long options are mandatory for short options as well.
|
|
The options are arranged in alphabetical order based on the long
|
|
option name.
|
|
.TP
|
|
\fB\-b\fR, \fB\-\-bpw\fR=\fICS\fR
|
|
where \fICS\fR is the chunk size in bytes. This will be the maximum number
|
|
of bytes sent per WRITE BUFFER command. So if \fICS\fR is less than the
|
|
effective length then multiple WRITE BUFFER commands are sent, each taking
|
|
the next chunk from the read data and increasing the buffer offset field
|
|
in the WRITE BUFFER command by the appropriate amount. The default is
|
|
a chunk size of 0 which is interpreted as a very large number hence only
|
|
one WRITE BUFFER command will be sent. This option should only be used with
|
|
modes that "download microcode, with offsets ..."; namely either mode 0x6,
|
|
0x7, 0xd or 0xe.
|
|
.br
|
|
The number in \fICS\fR can optionally be followed by ",act" or ",activate".
|
|
In this case after WRITE BUFFER commands have been sent until the
|
|
effective length is exhausted another WRITE BUFFER command with its mode
|
|
set to "Activate deferred microcode mode" [mode 0xf] is sent.
|
|
.TP
|
|
\fB\-d\fR, \fB\-\-dry\-run\fR
|
|
Do all the command line processing and sanity checks including reading
|
|
the input file. However at the point where a WRITE BUFFER SCSI command(s)
|
|
would be sent, step over that call and assume it completed without errors
|
|
and continue. \fIDEVICE\fR is still opened but can be /dev/null (in Unix).
|
|
It is recommended to use \fI\-\-verbose\fR with this option to get an
|
|
overview of what would have happened.
|
|
.TP
|
|
\fB\-h\fR, \fB\-\-help\fR
|
|
output the usage message then exit. If used multiple times also prints
|
|
the mode names and their acronyms.
|
|
.TP
|
|
\fB\-i\fR, \fB\-\-id\fR=\fIID\fR
|
|
this option sets the buffer id field in the cdb. \fIID\fR is a value between
|
|
0 (default) and 255 inclusive.
|
|
.TP
|
|
\fB\-I\fR, \fB\-\-in\fR=\fIFILE\fR
|
|
read data from file \fIFILE\fR that will be sent with the WRITE BUFFER
|
|
command. If \fIFILE\fR is '\-' then stdin is read until an EOF is
|
|
detected (this is the same action as \fI\-\-read\-stdin\fR). Data is read
|
|
from the beginning of \fIFILE\fR except in the case when it is a regular file
|
|
and the \fI\-\-skip=SKIP\fR option is given.
|
|
.TP
|
|
\fB\-l\fR, \fB\-\-length\fR=\fILEN\fR
|
|
where \fILEN\fR is the length, in bytes, of data to be written to the device.
|
|
If not given (and the length cannot be deduced from \fI\-\-in=FILE\fR or
|
|
\fI\-\-read\-stdin\fR) then defaults to zero. If the option is given and the
|
|
length deduced from \fI\-\-in=FILE\fR or \fI\-\-read\-stdin\fR is less (or no
|
|
data is provided), then bytes of 0xff are used as fill bytes.
|
|
.TP
|
|
\fB\-m\fR, \fB\-\-mode\fR=\fIMO\fR
|
|
this option sets the MODE field in the cdb. \fIMO\fR is a value between
|
|
0 (default) and 31 inclusive. Alternatively an abbreviation can be given.
|
|
See the MODES section below. To list the available mode abbreviations at
|
|
run time give an invalid one (e.g. '\-\-mode=xxx') or use the '\-hh' option.
|
|
.TP
|
|
\fB\-o\fR, \fB\-\-offset\fR=\fIOFF\fR
|
|
this option sets the BUFFER OFFSET field in the cdb. \fIOFF\fR is a value
|
|
between 0 (default) and 2**24\-1 . It is a byte offset.
|
|
.TP
|
|
\fB\-r\fR, \fB\-\-read\-stdin\fR
|
|
read data from stdin until an EOF is detected. This data is sent with
|
|
the WRITE BUFFER command to \fIDEVICE\fR. The action of this option is the
|
|
same as using '\-\-in=\-'. Previously this option's long name was
|
|
\fI\-\-raw\fR and it may still be used for backward compatibility.
|
|
.TP
|
|
\fB\-s\fR, \fB\-\-skip\fR=\fISKIP\fR
|
|
this option is only active when \fI\-\-in=FILE\fR is given and \fIFILE\fR is
|
|
a regular file, rather than stdin. Data is read starting at byte offset
|
|
\fISKIP\fR to the end of file (or the amount given by \fI\-\-length=LEN\fR).
|
|
If not given the byte offset defaults to 0 (i.e. the start of the file).
|
|
.TP
|
|
\fB\-S\fR, \fB\-\-specific\fR=\fIMS\fR
|
|
\fIMS\fR is the MODE SPECIFIC field in the cdb. This is a 3\-bit field
|
|
so the values 0 to 7 are accepted. This field was introduced in SPC\-4
|
|
revision 32 and can be used to specify additional events that activate
|
|
deferred microcode (when \fIMO\fR is 0xD).
|
|
.TP
|
|
\fB\-t\fR, \fB\-\-timeout\fR=\fITO\fR
|
|
\fITO\fR is the command timeout (in seconds) for each WRITE BUFFER command
|
|
issued by this utility. Its default value is 300 seconds (5 minutes) and
|
|
should only be altered if this is not sufficient.
|
|
.TP
|
|
\fB\-v\fR, \fB\-\-verbose\fR
|
|
increase the level of verbosity, (i.e. debug output).
|
|
.TP
|
|
\fB\-V\fR, \fB\-\-version\fR
|
|
print the version string and then exit.
|
|
.SH MODES
|
|
Following is a list of WRITE BUFFER command settings for the MODE field.
|
|
First is an acronym accepted by the \fIMO\fR argument of this utility.
|
|
Following the acronym in square brackets are the corresponding decimal and
|
|
hex values that may also be given for \fIMO\fR. The following are listed
|
|
in numerical order.
|
|
.TP
|
|
hd [0, 0x0]
|
|
Combined header and data (obsolete in SPC\-4).
|
|
.TP
|
|
vendor [1, 0x1]
|
|
Vendor specific.
|
|
.TP
|
|
data [2, 0x2]
|
|
Data (was called "Write Data" in SPC\-3).
|
|
.TP
|
|
dmc [4, 0x4]
|
|
Download microcode and activate (was called "Download microcode" in SPC\-3).
|
|
.TP
|
|
dmc_save [5, 0x5]
|
|
Download microcode, save, and activate (was called "Download microcode and
|
|
save" in SPC\-3).
|
|
.TP
|
|
dmc_offs [6, 0x6]
|
|
Download microcode with offsets and activate (was called "Download microcode
|
|
with offsets" in SPC\-3).
|
|
.TP
|
|
dmc_offs_save [7, 0x7]
|
|
Download microcode with offsets, save, and activate (was called "Download
|
|
microcode with offsets and save" in SPC\-3).
|
|
.TP
|
|
echo [10, 0xa]
|
|
Write data to echo buffer (was called "Echo buffer" in SPC\-3).
|
|
.TP
|
|
dmc_offs_ev_defer [13, 0xd]
|
|
Download microcode with offsets, select activation events, save, and defer
|
|
activate (introduced in SPC\-4).
|
|
.TP
|
|
dmc_offs_defer [14, 0xe]
|
|
Download microcode with offsets, save, and defer activate (introduced in
|
|
SPC\-4).
|
|
.TP
|
|
activate_mc [15, 0xf]
|
|
Activate deferred microcode (introduced in SPC\-4).
|
|
.TP
|
|
en_ex [26, 0x1A]
|
|
Enable expander communications protocol and Echo buffer (obsolete in SPC\-4).
|
|
.TP
|
|
dis_ex [27, 0x1B]
|
|
Disable expander communications protocol (obsolete in SPC\-4).
|
|
.TP
|
|
deh [28, 0x1C]
|
|
Download application client error history (was called "Download application
|
|
log" in SPC\-3).
|
|
.SH NOTES
|
|
If no \fI\-\-length=LEN\fR is given this utility reads up to 8 MiB of data
|
|
from the given file \fIFILE\fR (or stdin). If a larger amount of data is
|
|
required then the \fI\-\-length=LEN\fR option should be given.
|
|
.PP
|
|
The user should be aware that most operating systems have limits on the
|
|
amount of data that can be sent with one SCSI command. In Linux this
|
|
depends on the pass through mechanism used (e.g. block SG_IO or the sg
|
|
driver) and various setting in sysfs in the Linux lk 2.6/3
|
|
series (e.g. /sys/block/sda/queue/max_sectors_kb). Devices (i.e. logical
|
|
units) also typically have limits on the maximum amount of data they can
|
|
handle in one command. These two limitations suggest that modes
|
|
containing the word "offset" together with the \fI\-\-bpw=CS\fR option
|
|
are required as firmware files get larger and larger. And \fICS\fR
|
|
can be quite small, for example 4096 bytes, resulting in many WRITE
|
|
BUFFER commands being sent.
|
|
.PP
|
|
Attempting to download a microcode/firmware file that is too large may
|
|
cause an error to occur in the pass\-through layer (i.e. before the
|
|
SCSI command is issued). In Linux such error reports can be obscure as
|
|
in "pass through os error invalid argument". FreeBSD reports such
|
|
errors well to the machine's console but returns a cryptic error message
|
|
to this utility.
|
|
.PP
|
|
Downloading incorrect microcode into a device has the ability to render
|
|
that device inoperable. One would hope that the device vendor verifies
|
|
the data before activating it. If the SCSI WRITE BUFFER command is given
|
|
values in its cdb (e.g. \fILEN\fR) that are inappropriate (e.g. too large)
|
|
then the device should respond with a sense key of ILLEGAL REQUEST and
|
|
an additional sense code of INVALID FIELD in CDB. If a WRITE BUFFER
|
|
command (or a sequence of them) fails due to device vendor verification
|
|
checks then it should respond with a sense key of ILLEGAL REQUEST and
|
|
an additional sense code of COMMAND SEQUENCE ERROR.
|
|
.PP
|
|
All numbers given with options are assumed to be decimal.
|
|
Alternatively numerical values can be given in hexadecimal preceded by
|
|
either "0x" or "0X" (or has a trailing "h" or "H").
|
|
.SH EXAMPLES
|
|
The following sends new firmware to an enclosure. Sending a 1.5 MB
|
|
file in one WRITE BUFFER command caused the enclosure to lock up
|
|
temporarily and did not update the firmware. Breaking the firmware file
|
|
into 4 KB chunks (an educated guess) was more successful:
|
|
.PP
|
|
sg_write_buffer \-b 4k \-m dmc_offs_save \-I firmware.bin /dev/sg4
|
|
.PP
|
|
The firmware update occurred in the following enclosure power cycle. With
|
|
a modern enclosure the Extended Inquiry VPD page gives indications in which
|
|
situations a firmware upgrade will take place.
|
|
.SH EXIT STATUS
|
|
The exit status of sg_write_buffer is 0 when it is successful. Otherwise
|
|
see the sg3_utils(8) man page.
|
|
.SH AUTHORS
|
|
Written by Luben Tuikov and Douglas Gilbert.
|
|
.SH "REPORTING BUGS"
|
|
Report bugs to <dgilbert at interlog dot com>.
|
|
.SH COPYRIGHT
|
|
Copyright \(co 2006\-2018 Luben Tuikov and Douglas Gilbert
|
|
.br
|
|
This software is distributed under a BSD\-2\-Clause license. There is NO
|
|
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
|
.SH "SEE ALSO"
|
|
.B sg_read_buffer, sg_ses_microcode(sg3_utils)
|