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

NAME

6       sg_ses_microcode - send microcode to a SCSI enclosure
7

SYNOPSIS

9       sg_ses_microcode     [--bpw=CS]    [--help]    [--id=ID]    [--in=FILE]
10       [--length=LEN]   [--mode=MO]   [--non]   [--offset=OFF]   [--skip=SKIP]
11       [--subenc=MS] [--tlength=TLEN] [--verbose] [--version] DEVICE
12

DESCRIPTION

14       This  utility attempts to download microcode to an enclosure (or one of
15       its sub-enclosures) associated with the DEVICE. The process  for  doing
16       this  is  defined  in  the  SCSI Enclosure Services (SES) standards and
17       drafts maintained by the T10 committee.
18
19       The process is to send one or more sequences  containing  a  SCSI  SEND
20       DIAGNOSTIC  command followed optionally by a RECEIVE DIAGNOSTIC RESULTS
21       command. The former sends a Download microcode Control diagnostic  page
22       (dpage)  and the latter fetches a Download microcode status dpage which
23       can be viewed as a report on the former command.
24
25       The default action (i.e. when the --mode=MO option is not given) is  to
26       fetch  the Download microcode status dpage and decode it. This does not
27       require the microcode (firmware) itself so the --in=FILE option is  not
28       required.
29
30       The  most recent reference for this utility is the draft SCSI Enclosure
31       Services 3 (SES-3) document T10/2149-D Revision 7 at http://www.t10.org
32       .   Existing  standards  for SES and SES-2 are ANSI INCITS 305-1998 and
33       ANSI INCITS 448-2008 respectively.
34
35       Most other support for SES in  this  package  (apart  from  downloading
36       microcode) can be found in the sg_ses utility. Another way of download‐
37       ing firmware to a SCSI device is with the WRITE BUFFER command  defined
38       in SPC-4, see the sg_write_buffer utility.
39

OPTIONS

41       Arguments to long options are mandatory for short options as well.
42
43       -b, --bpw=CS
44              where  CS is the chunk size in bytes and should be a multiple of
45              4.  This will be the maximum number of bytes sent per SEND DIAG‐
46              NOSTIC  command.   So if CS is less than the effective length of
47              the microcode then multiple SEND DIAGNOSTIC commands  are  sent,
48              each taking the next chunk from the read data and increasing the
49              buffer offset field in the Download microcode control  dpage  by
50              the  appropriate  amount. The default is a chunk size of 0 which
51              is interpreted as a very large number hence only one SEND  DIAG‐
52              NOSTIC command will be sent.
53              The number in CS can optionally be followed by ",act" or ",acti‐
54              vate".  In this case after the microcode has  been  successfully
55              sent  to  the  DEVICE,  an additional Download microcode control
56              dpage with its mode set to "Activate deferred  microcode"  [0xf]
57              is sent.
58
59       -h, --help
60              output  the usage message then exit. If used multiple times also
61              prints the mode names and their acronyms.
62
63       -i, --id=ID
64              this option sets the BUFFER ID field in the  Download  microcode
65              control  dpage. ID is a value between 0 (default) and 255 inclu‐
66              sive.
67
68       -I, --in=FILE
69              read data from file FILE that will be sent with the  SEND  DIAG‐
70              NOSTIC  command.  If FILE is '-' then stdin is read until an EOF
71              is detected (this is the same action as  --raw).  Data  is  read
72              from the beginning of FILE except in the case when it is a regu‐
73              lar file and the --skip=SKIP option is given.
74
75       -l, --length=LEN
76              where LEN is the length, in bytes, of data to be written to  the
77              device.   If  not  given  (and the length cannot be deduced from
78              --in=FILE or --raw) then defaults to  zero.  If  the  option  is
79              given and the length deduced from --in=FILE or --raw is less (or
80              no data is provided), then bytes of 0xff are used as fill bytes.
81
82       -m, --mode=MO
83              this option sets the MODE. MO is a value  between  0  (which  is
84              dmc_status  and the default) and 255 inclusive. Alternatively an
85              abbreviation can be given. See the MODES section below. To  list
86              the available mode abbreviations at run time give an invalid one
87              (e.g. '--mode=xxx') or use the '-h' option.
88
89       -N, --non
90              allow for non-standard implementations that reset their Download
91              microcode engine after a RECEIVE DIAGNOSTIC RESULTS command with
92              the Download microcode status dpage is sent. When this option is
93              given  sending  that  command  and  dpage combination is avoided
94              unless an error has already occurred.
95
96       -o, --offset=OFF
97              this option  sets  the  BUFFER  OFFSET  field  in  the  Download
98              microcode  control dpage. OFF is a value between 0 (default) and
99              2**32-1 . It is a byte offset.
100
101       -s, --skip=SKIP
102              this option is only active when --in=FILE is given and FILE is a
103              regular  file,  rather than stdin. Data is read starting at byte
104              offset SKIP  to  the  end  of  file  (or  the  amount  given  by
105              --length=LEN).  If not given the byte offset defaults to 0 (i.e.
106              the start of the file).
107
108       -S, --subenc=SEID
109              SEID is the subenclosure identify. It defaults to 0 which is the
110              primary enclosure identifier.
111
112       -t, --tlength=TLEN
113              TLEN  is  the  total  length in bytes of the microcode to be (or
114              being) downloaded. It defaults to 0 which is okay in most cases.
115              This  option is only needed when sections of microcode and being
116              sent in separate invocations of this utility.
117
118       -v, --verbose
119              increase the level of verbosity, (i.e. debug output).
120
121       -V, --version
122              print the version string and then exit.
123

MODES

125       Following is a list accepted by the MO argument of this utility.  First
126       shown  is  an  acronym followed in square brackets by the corresponding
127       decimal and hex values that may also be given for MO.
128
129       dmc_status  [0, 0x0]
130              Use RECEIVE DIAGNOSTIC RESULTS to fetch the  Download  microcode
131              status dpage and print it out.
132
133       dmc_offs  [6, 0x6]
134              Download microcode with offsets and activate.
135
136       dmc_offs_save  [7, 0x7]
137              Download microcode with offsets, save, and activate.
138
139       dmc_offs_defer  [14, 0xe]
140              Download microcode with offsets, save, and defer activate.
141
142       activate_mc  [15, 0xf]
143              Activate deferred microcode. There is no follow-up RECEIVE DIAG‐
144              NOSTIC RESULTS to fetch  the  Download  microcode  status  dpage
145              since the DEVICE might be resetting.
146
147       Apart  from dmc_status, these are placed in the Download microcode mode
148       field in the Download microcode control dpage. In the case of  dmc_sta‐
149       tus the Download microcode status dpage is fetch with the RECEIVE DIAG‐
150       NOSTIC RESULTS command and decoded.
151

WHEN THE DOWNLOAD FAILS

153       Firstly, if it succeeds, this utility should stay  silent  and  return.
154       Typically vendors will change the "revision" string (which is 4 charac‐
155       ters long) whenever they release new firmware. That can be seen in  the
156       response  to  a  SCSI  INQUIRY command, for example by using the sg_inq
157       utility.  It is possible that the  device  needs  to  be  power  cycled
158       before  the  new  microcode becomes active. Also if mode dmc_offs_defer
159       [0xe] is used to download the microcode, then another  invocation  with
160       activate_mc may be needed.
161
162       If  something  goes wrong, there will typically be messages printed out
163       by this utility. The first thing to check is the  microcode  (firmware)
164       file  itself.  Is  it  designed  for the device model; has it been cor‐
165       rupted, and if downgrading (i.e. trying to re-instate older  firmware),
166       does the vendor allow that?
167
168       Getting  new  firmware  on a device is a delicate operation that is not
169       always well defined by T10's standards and drafts. One might  speculate
170       that  they are deliberately vague. In testing this utility one vendor's
171       interpretation of the  standard  was  somewhat  surprising.  The  --non
172       option  was  added  to  cope with their interpretation. So if the above
173       suggestions don't help, try adding the --non option.
174

NOTES

176       This utility can handle a maximum size of 128  MB  of  microcode  which
177       should be sufficient for most purposes. In a system that is memory con‐
178       strained, such large allocations of memory may fail.
179
180       The user should be aware that most operating systems have limits on the
181       amount  of  data  that can be sent with one SCSI command. In Linux this
182       depends on the pass through mechanism used (e.g. block SG_IO or the  sg
183       driver) and various setting in sysfs in the Linux lk 2.6/3 series (e.g.
184       /sys/block/sda/queue/max_sectors_kb). Devices (i.e. logical units) also
185       typically  have limits on the maximum amount of data they can handle in
186       one command. These two limitations suggest that  modes  containing  the
187       word  "offset"  together  with  the  --bpw=CS  option  are  required as
188       firmware files get larger and larger. And CS can be  quite  small,  for
189       example  4096  bytes,  resulting in many SEND DIAGNOSTIC commands being
190       sent.
191
192       The exact error from the non-standard implementation was a sense key of
193       ILLEGAL  REQUEST  and  an  asc/ascq  code of 0x26,0x0 which is "Invalid
194       field in parameter list". If that is seen  try  again  with  the  --non
195       option.
196
197       Downloading incorrect microcode into a device has the ability to render
198       that device inoperable. One would hope that the device vendor  verifies
199       the data before activating it.
200
201       A  long  (operating system) timeout of 7200 seconds is set on each SEND
202       DIAGNOSTIC command.
203
204       All numbers given with options are assumed  to  be  decimal.   Alterna‐
205       tively  numerical values can be given in hexadecimal preceded by either
206       "0x" or "0X" (or has a trailing "h" or "H").
207

EXAMPLES

209       If no microcode/firmware file is given then this  utility  fetches  and
210       decodes  the  Download microcode status dpage which could possibly show
211       another initiator in the process of updating  the  microcode.  Even  if
212       that  is happening, fetching the status page should not cause any prob‐
213       lems:
214
215         sg_ses_microcode /dev/sg3
216       Download microcode status diagnostic page:
217         number of secondary subenclosures: 0
218         generation code: 0x0
219          subenclosure identifier: 0 [primary]
220            download microcode status:  No  download  microcode  operation  in
221       progress [0x0]
222            download microcode additional status: 0x0
223            download microcode maximum size: 1048576 bytes
224            download microcode expected buffer id: 0x0
225            download microcode expected buffer id offset: 0
226
227       The  following  sends new microcode/firmware to an enclosure. Sending a
228       1.5 MB file in one command caused the enclosure to lock up  temporarily
229       and  did  not update the firmware. Breaking the firmware file into 4 KB
230       chunks (an educated guess) was more successful:
231
232         sg_ses_microcode -b 4k -m dmc_offs_save -I firmware.bin /dev/sg4
233
234       The firmware update occurred in the following  enclosure  power  cycle.
235       With a modern enclosure the Extended Inquiry VPD page gives indications
236       in which situations a firmware upgrade will take place.
237

EXIT STATUS

239       The exit status of sg_ses_microcode is 0 when it is successful.  Other‐
240       wise see the sg3_utils(8) man page.
241

AUTHORS

243       Written by Douglas Gilbert.
244

REPORTING BUGS

246       Report bugs to <dgilbert at interlog dot com>.
247
249       Copyright © 2014 Douglas Gilbert
250       This  software is distributed under a FreeBSD license. There is NO war‐
251       ranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR  PUR‐
252       POSE.
253

SEE ALSO

255       sg_ses, sg_write_buffer(sg3_utils)
256
257
258
259sg3_utils-1.40                   October 2014              SG_SES_MICROCODE(8)
Impressum