Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, February 9, 2022
 
 

fwflash(8)

Name

fwflash - firmware query and update utility

Synopsis

/usr/sbin/fwflash [-l [-c
 device_class | ALL ]]
     | [-h]
fwflash [-f file1,
file2,file3,... | -r 
file]
     [-y] [-d device_path]

Description

The fwflash command writes a binary image file to supported flashable devices attached to a Solaris host. It also provides the ability to read firmware to a file if supported by the device. Because changing the firmware in a device can have significant impact on the stability of a system, only users with the privilege All are allowed to execute this command. Users authorized to run fwflash can be granted the “Firmware Flash Update” Rights Profile.

The first form of the command, above, provides information about devices. It lists all devices currently available on the system that are supported by fwflash for firmware upgrade. You can filter the list operation, to display only specified classes of devices. The second form of the command provides the operations to read or write the firmware images to specific devices.

Options

The following options are supported:

–c device_class

An optional parameter, valid only when used with the –l option. This option causes the command to list only devices of a specific class type. No other device classes are enumerated. Currently supported classes are IB, ETH, enclosure, disk, or ALL. If –c is not specified for the –l option, the class defaults to ALL.

This option limits search to a specific class. Use IB for InfiniBand, ETH for Ethernet, enclosure for SCSI enclosures, and disk for SCSI/SATA/SAS/FC disks.

–d dev_path

The dev_path is absolute path name of the device that the user wants to modify with the –for – r operation. If the device cannot be found, the command fails. If the –d option is specified, then either –f or –r must also be specified.

–f file1, file2,file3,...

Specify the path to one or more binary firmware image files you want to write to the device. fwflash will verify that each file is a valid firmware image for the specified device. If it is not, the command fails with an appropriate error message. Cards running secure firmware have additional restrictions (see NOTES section below).

If multiple firmware image files are specified, each image is verified and flashed to the device in the order given on the command line. If any of the specified files cannot be successfully flashed, then an appropriate message is displayed.

After a new firmware image is flashed to a device, a reboot is required to correctly activate the new firmware.

–h

Display the command line usage message for fwflash.

–l

List the devices on a system available for firmware upgrade and display information specific to each device or device class.

For InfiniBand (IB) and Ethernet (ETH) devices, the list operation displays the guids (Globally Unique Identifier) and MAC addresses currently set for the device, as well as the current firmware revision installed. There are four separate guids on the device; two of them can be set with the same value. Typically, there are two MAC addresses, one for each port on the device. Secure firmware cards will also show the firmware security attributes (see NOTES section below).

For SCSI Enclosure Services (ses or sgen) devices, an identifying target-port worldwide name is displayed, if available.

–r file

Specify the path to a file to create when reading the firmware from the device. The –f and –r options are mutually exclusive.

Not all flashable devices support reading firmware images back from the device. At present, only InfiniBand (IB) and Ethernet (ETH) devices are supported for this operation. A message will be displayed if the selected device does not support this operation. Cards running secure firmware do not support this operation (see NOTES section below).

–y

Valid only when a flash read (–r) or write (–f) operation is specified. This option causes fwflash not to prompt for confirmation during operation and operate non-interactively. Note that there is no option that allows you to forcibly flash an incompatible firmware image onto a device.

Examples

Example 1 Entering Command Without Arguments

The following command shows fwflash when the command is entered without arguments.

example# fwflash
Usage:
Usage:
      fwflash [-l [-c device_class | ALL]] | [-h]
      fwflash [-f file1,file2,file3,... | -r file] [-y] -d device_path

      -l              list flashable devices in this system
      -c device_class limit search to a specific class
                      eg IB for InfiniBand, ses for SCSI Enclosures
      -h              print this usage message

      -f file1,file2,file3,...
                      firmware image file list to flash
      -r file         file to dump device firmware to
      -y              answer Yes/Y/y to prompts
      -d device_path  pathname of device to be flashed

      If -d device_path is specified, then one of -f <files>
      or -r <file> must also be specified

      If multiple firmware images are required to be flashed
      they must be listed together, separated by commas. The
      images will be flashed in the order specified.
Example 2 Listing Devices Available to Flash

The following command lists the devices available to be flashed.

example# fwflash -l
List of available devices:
Device[0],  /devices/pci@0,0/pci8086,3595@2/pci8086,32a@0,2/\
            pci15b3,5a46@c/pci15b3,5a44@0:devctl
    Class [IB]
        GUID: System Image - 0002c901081e33b3
              Node         - 0000000000003446
              Port 1       - 0002c901081e33b1
              Port 2       - 0002c901081e33b2
        Firmware revision: 2.7.8100
               Product            : 375-3606-03
               PSID               : SUN0150000009
               Description        : Sun Falcon QDR
Device[1],  /devices/pci@0,0/pci8086,3597@4/pci15b3,6278@0:devctl
    Class [IB]
        GUID: System Image - 0002c9010a99e3b3
              Node         - 0002c9010a99e3b0
              Port 1       - 0002c9010a99e3b1
              Port 2       - 0002c9010a99e3b2
        Firmware revision: 2.7.8100
               Product            : 375-3606-03
               PSID               : SUN0150000009
               Description        : Sun Falcon QDR
Device[2],  /devices/pci@0,0/pci8086,2f04@2/pci15b3,16@0:devctl
    Class [ETH]
        GUID: System Image - ec0d9a0300d8f62a
                Node       - ec0d9a0300d8f62a
                Port 1     - ec0d9a0300d8f62a
                Port 2     - ec0d9a0300d8f62b
                Mac 1      - 0000ec0d9ad8f62a
                Mac 2      - 0000ec0d9ad8f62b
	Firmware revision  : 16.21.2024
	Product            : MCX556A-EDAS_C14
	PSID               : ORC0000000003
	Description        : CX556A - ConnectX-5 QSFP28
	Security attributes: secure-fw signed

Alternatively, for a SAS Expander presented as a SCSI Enclosure Services device, we might see output such as this:

example# fwflash -l
List of available devices:
Device[0] /devices/pci@0/pci@0/pci@2/scsi@0/ses@3,0:ses
  Class [sgen]
        Target port WWN  : 500605b00002453d
        Vendor           : SUN
        Product          : 16Disk Backplane
        Firmware revision: 5021
Example 3 Flash Upgrading an IB HCA Device

The following command flash upgrades an IB HCA device.

example# fwflash -f ./version.3.2.0000 \
   -d /devices/pci@0,0/pci8086,3597@4/pci15b3,6278@0:devctl
About to update firmware on:
  /devices/pci@0,0/pci8086,3597@4/pci15b3,6278@0:devctl
Continue (Y/N): Y

Updating . . . . . . . . . . . .
Done.  New image will be active after the system is rebooted.

Note that you are prompted before the upgrading proceeds and that it is mandatory that you reboot your host to activate the new firmware image.

The following command adds the –y option to the command.

example# fwflash -y -f ./version.3.2.0000 \
   -d /devices/pci@0,0/pci8086,3597@4/pci15b3,6278@0:devctl
About to update firmware on:
  /devices/pci@0,0/pci8086,3597@4/pci15b3,6278@0:devctl

Updating . . . . . . . . . . . .
Done.  New image will be active after the system is rebooted.
Example 4 Flash Upgrading an ETH Device

The following command flash upgrades an ETH device.

example# fwflash -f \
 fw-ConnectX5-rel-16_22_1002-MCX556A-EDAS_C14_Ax-FlexBoot-3.5.403.bin \
 -d /devices/pci@0,0/pci8086,2f04@2/pci15b3,16@0:devctl
Verify firmware image
    Current HCA firmware version: 16.21.2024
        Security attributes: secure-fw signed
    Will be updated to firmware : 16.22.1002
        Security attributes: secure-fw signed
About to update firmware on /devices/pci@0,0/pci8086,2f04@2/pci15b3,16@0:devctl
with file fw-ConnectX5-rel-16_22_1002-MCX556A-EDAS_C14_Ax-FlexBoot-3.5.403.bin.
Do you want to continue (Y/N): Y
Updating firmware: this takes about 40 seconds, so please be patient.
Updating firmware: Success!
fwflash: New firmware will be activated after you reboot
Example 5 Reading Device Firmware to File

The command shown below reads the device firmware to a file. The command uses the –y option so that read occurs without prompting.

example# fwflash -y -r /firmware.bin \
   -d /devices/pci@1d,700000/pci@1/pci15b3,5a44@0:devctl
About to read firmware on:
         /devices/pci@1d,700000/pci@1/pci15b3,5a44@0:devctl
to filename: /firmware.bin

Reading . . .
Done.

Example 6 When No Flashable Devices Are Found

The command output shown below informs the user that there are no supported flashable devices found in the system:

example# fwflash -l
fwflash: No flashable devices attached with the ses driver in this system
fwflash: No flashable devices attached with the sgen driver in this system
fwflash: No flashable devices attached with the hermon driver in this system
fwflash: No flashable devices in this system

Each plugin found in /usr/lib/fwflash/identify is loaded in turn, and walks the system device tree, determining whether any currently-attached devices can be flashed. For the list of device types and drivers that are currently supported, please see the NOTES section below.

Return Values

The fwflash command returns the following values:

0

Success

1

Failure

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/firmware-utilities
Interface Stability
Committed

See Also

hermon(4D), mlxne(4D), ses(4D), attributes(7)

The InfiniBand Trade Association website, https://www.infinibandta.org

The SCSI Storage Interfaces committee website, https://www.t10.org

SCSI Primary Commands-4, SPC4

SCSI Enclosure Services-2, SES2

Serial Attached SCSI-2, SAS2

Notes

As of version 1.1, fwflash supports only one type of flash part in InfiniBand HCA devices. When an unsupported HCA device is encountered, the following message is issued:

The fwflash command supports:

  • InfiniBand Host Channel Adapters (IB HCAs) containing either the AMD or the Intel parallel flash parts.

  • SCSI Enclosure Services devices such as SAS Expanders, attached with ses(4D) drivers.

  • Some Oracle OEM Mellanox adapters (e.g. ConnectX-5) use so-called "secure firmware" (SF). This feature is meant to restrict firmware usage to only officially approved versions. SF image files are digitally signed and verified when attempting to write the image to a card.

    If the signature cannot be verified, the writing (-f) operation is blocked, and an error message will be printed. Once a card running SF is written with a new firmware image, the new image must be activated (via reboot), before the card can be written again with a new image.

    Cards supporting SF will show "Security attributes" with the list (-l) option. Production SF will have the "secure-fw" and "signed" attributes. Development SF will also show the "dev" attribute. Debug SF will also have the "debug" attribute. Production and Development SF use different keys. A card running Production SF cannot be written with Development SF without using a special hardware procedure.

    Cards running SF do not support the read (-r) option to read firmware from the card.