| blob | 3eac6f868941b21acbc0f4f36980c968a66883d2 |
1 '\" te
2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH FWFLASH 1M "Nov 4, 2008"
7 .SH NAME
8 fwflash \- firmware query and update utility
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/usr/sbin/fwflash\fR [\fB-l\fR [\fB-c\fR \fIdevice_class\fR | \fBALL\fR ]]
13 | [\fB-v\fR] | [\fB-h\fR]
14 .fi
16 .LP
17 .nf
18 \fBfwflash\fR [\fB-f\fR \fIfile1\fR,\fIfile2\fR,\fIfile3\fR,... | \fB-r\fR \fIfile\fR]
19 [\fB-y\fR] [\fB-d\fR \fIdevice_path\fR]
20 .fi
22 .SH DESCRIPTION
23 .sp
24 .LP
25 The \fBfwflash\fR command writes a binary image file to supported flashable
26 devices attached to a Solaris host. It also provides the ability to read
27 firmware to a file if supported by the device. Because changing the firmware in
28 a device can have significant impact on the stability of a system, only users
29 with the privilege \fBAll\fR are allowed to execute this command. Users
30 authorized to run \fBfwflash\fR can be granted the "Firmware Flash Update"
31 Rights Profile.
32 .sp
33 .LP
34 The first form of the command, above, provides information about devices. It
35 lists all devices currently available on the system that are supported by
36 \fBfwflash\fR for firmware upgrade. You can filter the list operation, to
37 display only specified classes of devices. The second form of the command
38 provides the operations to read or write the firmware images to specific
39 devices.
40 .SH OPTIONS
41 .sp
42 .LP
43 The following options are supported:
44 .sp
45 .ne 2
46 .na
47 \fB\fB-c\fR \fIdevice_class\fR\fR
48 .ad
49 .sp .6
50 .RS 4n
51 An optional parameter, valid only when used with the \fB-l\fR option. This
52 option causes the command to list only devices of a specific class type.
53 Currently supported classes are \fBIB\fR, \fBses\fR, \fBsesgen\fR, or
54 \fBALL\fR. If \fB-c\fR is not specified for the \fB-l\fRoption, the class
55 defaults to \fBALL\fR.
56 .RE
58 .sp
59 .ne 2
60 .na
61 \fB\fB-d\fR \fIdev_path\fR\fR
62 .ad
63 .sp .6
64 .RS 4n
65 The \fIdev_path\fR is absolute path name of the device that the user wants to
66 modify with the \fB-f\fRor \fB-r\fR operation. If the device cannot be found,
67 the command fails. If the \fB-d\fR option is specified, then either \fB-f\fR or
68 \fB-r\fR must also be specified.
69 .RE
71 .sp
72 .ne 2
73 .na
74 \fB\fB-f\fR \fIfile1\fR,\fIfile2\fR,\fIfile3\fR,...\fR
75 .ad
76 .sp .6
77 .RS 4n
78 Specify the path to one or more binary firmware image files you want to write
79 to the device. \fBfwflash\fR will verify that each file is a valid firmware
80 image for the specified device. If it is not, the command fails with an
81 appropriate error message.
82 .sp
83 If multiple firmware image files are specified, each image is verified and
84 flashed to the device in the order given on the command line. If any of the
85 specified files cannot be successfully flashed, then an appropriate message is
86 displayed.
87 .sp
88 After a new firmware image is flashed to a device, a reboot is required to
89 correctly activate the new firmware.
90 .RE
92 .sp
93 .ne 2
94 .na
95 \fB\fB-h\fR\fR
96 .ad
97 .sp .6
98 .RS 4n
99 Display the command line usage message for \fBfwflash\fR.
100 .RE
102 .sp
103 .ne 2
104 .na
105 \fB\fB-l\fR\fR
106 .ad
107 .sp .6
108 .RS 4n
109 List the devices on a system available for firmware upgrade and display
110 information specific to each device or device class.
111 .sp
112 For InfiniBand (IB) devices, the list operation displays the \fBguid\fRs
113 (Globally Unique Identifier) currently set for the HCA, as well as the current
114 firmware revision installed. There are four separate \fBguid\fRs on the HCA;
115 two of them can be set with the same value.
116 .sp
117 For SCSI Enclosure Services (\fBses\fR or \fBsgen\fR) devices, an identifying
118 target-port worldwide name is displayed, if available.
119 .RE
121 .sp
122 .ne 2
123 .na
124 \fB\fB-r\fR \fIfile\fR\fR
125 .ad
126 .sp .6
127 .RS 4n
128 Specify the path to a file to create when reading the firmware from the device.
129 The \fB-f\fR and \fB-r\fR options are mutually exclusive.
130 .sp
131 Not all flashable devices support reading firmware images back from the device.
132 At present, only InfiniBand (IB) devices are supported for this operation. A
133 message will be displayed if the selected device does not support this
134 operation.
135 .RE
137 .sp
138 .ne 2
139 .na
140 \fB\fB-v\fR\fR
141 .ad
142 .sp .6
143 .RS 4n
144 Display \fBfwflash\fR version information and exit.
145 .RE
147 .sp
148 .ne 2
149 .na
150 \fB\fB-y\fR\fR
151 .ad
152 .sp .6
153 .RS 4n
154 Valid only when a flash read (\fB-r\fR) or write (\fB-f\fR) operation is
155 specified. This option causes \fBfwflash\fR not to prompt for confirmation
156 during operation and operate non-interactively. Note that there is no option
157 that allows you to forcibly flash an incompatible firmware image onto a device.
158 .RE
160 .SH EXAMPLES
161 .LP
162 \fBExample 1 \fREntering Command Without Arguments
163 .sp
164 .LP
165 The following command shows \fBfwflash\fR when the command is entered without
166 arguments.
168 .sp
169 .in +2
170 .nf
171 example# \fBfwflash\fR
172 Usage:
173 Usage:
174 fwflash [-l [-c device_class | ALL]] | [-v] | [-h]
175 fwflash [-f file1,file2,file3,... | -r file] [-y] -d device_path
177 -l list flashable devices in this system
178 -c device_class limit search to a specific class
179 eg IB for InfiniBand, ses for SCSI Enclosures
180 -v print version number of fwflash utility
181 -h print this usage message
183 -f file1,file2,file3,...
184 firmware image file list to flash
185 -r file file to dump device firmware to
186 -y answer Yes/Y/y to prompts
187 -d device_path pathname of device to be flashed
189 If -d device_path is specified, then one of -f <files>
190 or -r <file> must also be specified
192 If multiple firmware images are required to be flashed
193 they must be listed together, separated by commas. The
194 images will be flashed in the order specified.
195 .fi
196 .in -2
197 .sp
199 .LP
200 \fBExample 2 \fRListing Devices Available to Flash
201 .sp
202 .LP
203 The following command lists the devices available to be flashed.
205 .sp
206 .in +2
207 .nf
208 example# \fBfwflash -l\fR
209 List of available devices:
210 Device[0], /devices/pci@0,0/pci8086,3595@2/pci8086,32a@0,2/\e
211 pci15b3,5a46@c/pci15b3,5a44@0:devctl
212 Class [IB]
213 GUID: System Image - 0002c901081e33b3
214 Node - 0000000000003446
215 Port 1 - 0002c901081e33b1
216 Port 2 - 0002c901081e33b2
217 Firmware revision: 3.3.0002
218 No hardware information available for this device
220 Device[1], /devices/pci@0,0/pci8086,3597@4/pci15b3,6278@0:devctl
221 Class [IB]
222 GUID: System Image - 0002c9010a99e3b3
223 Node - 0002c9010a99e3b0
224 Port 1 - 0002c9010a99e3b1
225 Port 2 - 0002c9010a99e3b2
226 Firmware revision: 4.8.00c8
227 Product : MTLP25208-CF256T (Lion cub)
228 PSID : MT_00B0000001
229 .fi
230 .in -2
231 .sp
233 .sp
234 .LP
235 Alternatively, for a SAS Expander presented as a SCSI Enclosure Services device
236 , we might see output such as this:
238 .sp
239 .in +2
240 .nf
241 example# \fBfwflash -l\fR
242 List of available devices:
243 Device[0] /devices/pci@0/pci@0/pci@2/scsi@0/ses@3,0:ses
244 Class [sgen]
245 Target port WWN : 500605b00002453d
246 Vendor : SUN
247 Product : 16Disk Backplane
248 Firmware revision: 5021
249 .fi
250 .in -2
251 .sp
253 .LP
254 \fBExample 3 \fRFlash Upgrading an IB HCA Device
255 .sp
256 .LP
257 The following command flash upgrades an IB HCA device.
259 .sp
260 .in +2
261 .nf
262 example# \fBfwflash -f ./version.3.2.0000 \e
263 -d /devices/pci@0,0/pci8086,3597@4/pci15b3,6278@0:devctl\fR
264 About to update firmware on:
265 /devices/pci@0,0/pci8086,3597@4/pci15b3,6278@0:devctl
266 Continue (Y/N): \fBY\fR
268 Updating . . . . . . . . . . . .
269 Done. New image will be active after the system is rebooted.
270 .fi
271 .in -2
272 .sp
274 .sp
275 .LP
276 Note that you are prompted before the upgrading proceeds and that it is
277 mandatory that you reboot your host to activate the new firmware image.
279 .sp
280 .LP
281 The following command adds the \fB-y\fR option to the command.
283 .sp
284 .in +2
285 .nf
286 example# \fBfwflash -y -f ./version.3.2.0000 \e
287 -d /devices/pci@0,0/pci8086,3597@4/pci15b3,6278@0:devctl\fR
288 About to update firmware on:
289 /devices/pci@0,0/pci8086,3597@4/pci15b3,6278@0:devctl
291 Updating . . . . . . . . . . . .
292 Done. New image will be active after the system is rebooted.
293 .fi
294 .in -2
295 .sp
297 .LP
298 \fBExample 4 \fRReading Device Firmware to File
299 .sp
300 .LP
301 The command shown below reads the device firmware to a file. The command uses
302 the \fB-y\fR option so that read occurs without prompting.
304 .sp
305 .in +2
306 .nf
307 example# \fBfwflash -y -r /firmware.bin \e
308 -d /devices/pci@1d,700000/pci@1/pci15b3,5a44@0:devctl\fR
309 About to read firmware on:
310 /devices/pci@1d,700000/pci@1/pci15b3,5a44@0:devctl
311 to filename: /firmware.bin
313 Reading . . .
314 Done.
315 .fi
316 .in -2
317 .sp
319 .LP
320 \fBExample 5 \fRWhen No Flashable Devices Are Found
321 .sp
322 .LP
323 The command output shown below informs the user that there are no supported
324 flashable devices found in the system:
326 .sp
327 .in +2
328 .nf
329 example# \fBfwflash -l\fR
330 fwflash: No flashable devices attached with the ses driver in this system
331 fwflash: No flashable devices attached with the sgen driver in this system
332 fwflash: No flashable devices attached with the tavor driver in this system
333 fwflash: No flashable devices in this system
334 .fi
335 .in -2
336 .sp
338 .sp
339 .LP
340 Each plugin found in \fB/usr/lib/fwflash/identify\fR is loaded in turn, and
341 walks the system device tree, determining whether any currently-attached
342 devices can be flashed. For the list of device types and drivers that are
343 currently supported, please see the \fBNOTES\fR section below.
345 .SH RETURN VALUES
346 .sp
347 .LP
348 The \fBfwflash\fR command returns the following values:
349 .sp
350 .ne 2
351 .na
352 \fB\fB0\fR\fR
353 .ad
354 .sp .6
355 .RS 4n
356 Success
357 .RE
359 .sp
360 .ne 2
361 .na
362 \fB\fB1\fR\fR
363 .ad
364 .sp .6
365 .RS 4n
366 Failure
367 .RE
369 .SH ATTRIBUTES
370 .sp
371 .LP
372 See \fBattributes\fR(5) for descriptions of the following attributes:
373 .sp
375 .sp
376 .TS
377 box;
378 c | c
379 l | l .
380 ATTRIBUTE TYPE ATTRIBUTE VALUE
381 _
382 Interface Stability Committed
383 .TE
385 .SH SEE ALSO
386 .sp
387 .LP
388 \fBattributes\fR(5), \fBhermon\fR(7D), \fBses\fR(7D), \fBtavor\fR(7D)
389 .sp
390 .LP
391 The InfiniBand Trade Association website, http://www.infinibandta.org
392 .sp
393 .LP
394 The SCSI Storage Interfaces committee website, http://www.t10.org
395 .sp
396 .LP
397 \fISCSI Primary Commands-4, SPC4\fR
398 .sp
399 .LP
400 \fISCSI Enclosure Services-2, SES2\fR
401 .sp
402 .LP
403 \fISerial Attached SCSI-2, SAS2\fR
404 .SH NOTES
405 .sp
406 .LP
407 The \fBfwflash\fR command supports:
408 .RS +4
409 .TP
410 .ie t \(bu
411 .el o
412 InfiniBand Host Channel Adapters (IB HCAs) containing either the AMD or the
413 Intel parallel flash parts.
414 .RE
415 .RS +4
416 .TP
417 .ie t \(bu
418 .el o
419 SCSI Enclosure Services devices such as SAS Expanders, attached with
420 \fBses\fR(7D) drivers.
421 .RE