diff options
Diffstat (limited to 'doc/sg_write_buffer.8')
| -rw-r--r-- | doc/sg_write_buffer.8 | 227 |
1 files changed, 227 insertions, 0 deletions
diff --git a/doc/sg_write_buffer.8 b/doc/sg_write_buffer.8 new file mode 100644 index 00000000..23913e37 --- /dev/null +++ b/doc/sg_write_buffer.8 @@ -0,0 +1,227 @@ +.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) |