mstflint: Burning a Firmware Image

NVIDIA Firmware Tools (MFT) Documentation v4.26.1 LTS

The mstflint utility enables you to burn the Flash from a binary image.To burn the entire Flash from a raw binary image, use the following command line:

Copy
Copied!
            

# mstflint -d <device> -i <fw-file> [-guid <GUID> | -guids <4 GUIDS> | -mac <MAC> | -macs <2 MACs>] burn

where:

device

Device on which the flash is burned.

fw-file

Binary firmware file.

GUID(s)

Optional, for InfiniBand adapters and 4th generation (Group I) switches. One or four GUIDs.

  • If 4 GUIDS are provided (-guids flag), they will be assigned as node, Port 1, Port 2 and sys- tem image GUIDs, respectively.

  • If only one GUID is provided (-guid flag), it will be assigned as node GUID. Its values +1, +2 and +3 will be assigned as Port 1, Port 2 and system image GUID, respectively.

  • If no -guid/-guids flag is provided, the current GUIDs will be preserved on the device.

NOTE: For 4th generation (Group I), four GUIDs must be specified but Ports 1 and 2 GUIDs are ignored and should be set to 0.

NOTE: A GUID is a 16-digit hexadecimal number. If less than 16 digits are provided, leading zeros will be inserted.

MAC(s)

Optional, for Ethernet and VPI adapters and switches.

  • If 2 MACs are provided (-macs flag), they will be assigned to Port 1 and Port 2, respectively.

  • If only one MAC is provided (-mac flag), it will be assigned to Port 1; MAC+1 will be assigned to Port 2.

  • If no -mac/-macs flag is provided, the current LIDs will be preserved on the device.

NOTE: A MAC is a 12-digit hexadecimal number. If less than 12 digits are provided, leading zeros will be inserted.

To burn a firmware image:

  1. Update the firmware on the device, keeping the current GUIDs and VSD. (Note: This is the common way to use the tool.

    Copy
    Copied!
                

    # mstflint -d 41:00.0 -i fw-4099-2_42_5000-MCX354A-FCB_A2.bin burn

  2. Update the firmware on the device, specifying the GUIDs to burn.

    Copy
    Copied!
                

    # mstflint -d 41:00.0 -i fw-4099-2_42_5000-MCX354A-FCB_A2.bin -guid 1234567deadbeef burn

  3. Update the firmware on the device, specifying the MACs to burn.

    Copy
    Copied!
                

    # mstflint -d 41:00.0 -i fw-4099-2_42_5000-MCX354A-FCB_A2.bin -mac 1234567deadbeef burn

  4. Burn the image on a blank Flash device. This means that no GUIDs are currently burnt on the device, therefore they must be supplied (with -guid/-guids) by the burning command. Moreover, the burn process cannot be failsafe when burning a blank Flash, therefore the -nofs flag must be specified.

    Copy
    Copied!
                

    burn# mstflint -d 41:00.0 -i fw-4099-2_42_5000-MCX354A-FCB_A2.bin -nofs -guid 12345678 burn

  5. Read FW from the device and save it as an image file.

    Copy
    Copied!
                

    # mstflint -d 41:00.0 ri Flash_Image_Copy.bin

  6. MT58100 SwitchX switch:
    Burn the image on a blank Flash device. Meaning, no GUIDs/MACs are currently burnt on the device, therefore they must be supplied (with -guid/-guids and -mac/-macs) by the burning command. Moreover, the burn process cannot be failsafe when burning a blank Flash, therefore the -nofs flag must be specified.

    Copy
    Copied!
                

    # mstflint -d 41:00.0 -i /tmp/fw-sx.bin -nofs -guids 000002c900002100 0 0 000002c900002100 -macs 0002c9002100 0002c9002101 b

Burning the MFA2 images enables the user to extract (i.e. unzip) 4MB images from MFA2 archive that matches the device type and device PSID. If there are more than one matching images, the user may use the --latest_fw flag and burn the latest firmware, or choose the required image from the user menu.

Warning

The device flash MUST have all relevant device information (signatures, PSID, VPD, DEV_INFO, MFG_INFO, etc.) valid since MFA2 format does not have that information and without the burn process will fail.

#mstflint -d <device> -i <mfa2 file> --psid <PSID string> (optionally) --latest_fw (optionally) –silent (optionally) b (or burn)

  • Burning the MFA2 Images when the Device Includes a Valid Image

    In this scenario, the user may (optional) provide a “—psid” flag and extract from the MFA2 archive the image that matches this flag, and this way actually change the PSID on the device.

  • Burning the MFA2 Images when in Live Fish Mode

    In this scenario, the user must provide a “—psid” flag and extract from the MFA2 archive the image that matches this flag, and this way actually change the PSID on the device.

Warning

Burning mfa2 requires installing mstflint with --enable-fw-mgr option.

Warning

This capability is supported only hosts with NVIDIA ConnectX-6 adapter cards.

The In-Field-Firmware-Update (IFFU) tool works via the HCAs in the datacenters and is intended for remote control. The tool is used to update cables transceivers' firmware.

Optical Cables and Transceivers are active network components which run firmware, and as any component running firmware, the ability to update firmware is mandatory. Transceiver firmware update is a system flow which requires the following elements:

  • Tool/Manager which will perform the firmware update

  • HCA firmware management used as a middleman between the Manager and the cable transceiver

  • Transceiver firmware: target for upgrade

The figure below shows the tool/manager which runs on a remotely controlled HCA on host shown as ‘Device’.

The manager can query the transceivers type and the current running firmware to understand if an update is required. When an update is required, the manager can apply set of commands that will send the remote host device a new firmware images for the specific transceiver(s) and activate a firmware update flow. The set of commands is defined with low level primitives to support full flexibility for the user. High level script can be applied on top of the manager and allow system wide update.

image2020-12-6_9-52-52-version-1-modificationdate-1707133788309-api-v2.png

The Tool/Manager host must have MST rev. 4.16.00 or later installed.
Remote control from outside the cluster (data center) requires access to the host being used as Tool/Manager. When the cluster has many HCAs, multiple hosts may be engaged in the upgrade process. The host(s) can be remotely controlled via VNC access.

Firmware Burning Across a Cluster (Data Center)

The IFFU function described below works on one switch. Cluster-wide firmware updating is done by use of a script which initiates the update procedure in multiple switches in parallel by initiating an instance of the flint command for each switch. In large clusters the script can be executed on multiple hosts, each handling a different part of the cluster.

Cable Burn Command

Copy
Copied!
            

# mstflint -d <device> --linkx <flags> <commands>

where:

Flags:

<device>

The name of the target switch (one only).

--downstream_device_id_start_index <downstream_device_id_start_index>

The port number of the first LinkX cable/transceiver. (min. port number = 1)

--num_of_downstream_devices <num_of_downstream_devices>

The number of cables/transceivers to burn. They are burnt sequentially.

--linkx_auto_update

Use this flag to burn all supported cables/transceivers connected to the HCA.

--download_transfer

Use this flag to perform download and transfer of all cable data for cables.

Download and transfer are not performed by default. This flag is only relevant for cable components.

--activate

Use this flag to apply the activation of the new firmware in the updated devices.

Activation is not performed by default.

--activate_delay_sec <timeout in seconds>

Use this flag to activate all cable devices connected to host with delay, acceptable values are between 0 and 255 (default - 1, immediately). Important: 'activate' flag must be set. This flag is relevant only for cable components.

-i <image>

‘i’ indicates ‘binary Image’ followed by the path and file name of the bin file to download into the cable/transceiver.

--downstream_device_ids <list of ports>

Use this flag to specify the LNKX ports to perform query. List must be only comma-separated numbers, without spaces

Commands:

b[urn]

Burn flash

q[uery]

Query misc. flash/firmware characteristics.


Updating the Firmware

Burning a firmware cable transceiver connected to the host is done using the "mstflint" tool. To do so, the user should use the "–linkx" flag.

Firmware can be burnt in follow one of the methods:

  • Burn with Auto-update:

  1. Transfer the data from the host.

    Copy
    Copied!
                

    # mstflint -d <device> --linkx --linkx_auto_update --download_transfer -i <image> b

    Example:

    Copy
    Copied!
                

    # mstflint -d /dev/mst/mt4123_pciconf0 --linkx --linkx_auto_update --download_transfer -i image.bin b

  2. Activate the firmware.

    Copy
    Copied!
                

    # mstflint -d <device> --linkx --linkx_auto_update –-activate b

    Example:

    Copy
    Copied!
                

    # mstflint -d /dev/mst/mt4123_pciconf0 --linkx --linkx_auto_update --activate b

    Transfer and Activate Example:

    Copy
    Copied!
                

    # mstflint -d /dev/mst/mt4123_pciconf0 --linkx --linkx_auto_update --download_transfer --activate -i image.bin b

  • Burning a specific port in the HCA using the 'Range':

  1. Transfer the data from the host.

    Copy
    Copied!
                

    # mstflint -d <device> --linkx --downstream_device_id_start_index <port_number> --num_of_downstream_devices 1 --download_transfer -i <image> b

  2. Activate the firmware.

    Copy
    Copied!
                

    # mstflint -d <device> --linkx --downstream_device_id_start_index <port_number> --num_of_downstream_devices 1 --activate b

    Example of Download Transfer with Activation, range is 1 to 2:

    Copy
    Copied!
                

    # mstflint -d /dev/mst/mt4123_pciconf0 --linkx --downstream_device_id_start_index 1 --num_of_downstream_devices 2 download_transfer --activate -i image.bin b

    This will update 2 AOCs/Transceivers starting from port 1, i.e. all ports in the range 1…2.

    Warning

    You cannot ‘overburn’ the same firmware version into a transceiver/AOC as the one already installed. This is to prevent wasting time re-burning transceivers in a large cluster.

    Example of successful update of 1 AOC:

    Copy
    Copied!
                

    -I- Downloading FW ... FSMST_INITIALIZE - OK Writing COMPID_LINKX component - OK FSMST_LOCKED - OK FSMST_DOWNSTREAM_DEVICE_TRANSFER - OK FSMST_LOCKED - OK Please wait while activating the transceiver(s) FW ... FSMST_ACTIVATE - OK..] -I- Cable burn finished successfully.

    Warning

    Downloading and burning takes approx. 1½ minute + activation ½ minute for one cable.

Querying Vendor Specific Firmware Information from a NVIDIA AOC / Transceiver

Querying a firmware cable transceiver is done using the "mstflint" tool.

Warning

In case the Vendor Specific query command is not support by the firmware, it will run the CMIS standard query implemented by the firmware.

Copy
Copied!
            

# mstflint -d <cable device> q


Querying Firmware Information from an AOC / Transceiver

Querying a firmware cable transceiver connected to the host is done using the "mstflint" tool. To do so, the user should use the "–linkx" flag.

Copy
Copied!
            

# mstflint -d <device> --linkx --downstream_device_ids <ids> [--output_file <file_name>] q

Query ports 1,2,5 Example:

Copy
Copied!
            

# mstflint -d <device> --linkx --downstream_device_ids 1,2 q

The system responds with information about the firmware version loaded into the transceivers.

Checking successful burning and operation - Example:

It is essential to check that the links come up AFTER the cable FW is updated and reactivated. This can be done as follows:

Copy
Copied!
            

# for i in {1..2}; do echo $i; mstlink -d /dev/mst/mt4123_pciconf0 -p $i -m | grep 'Part\|FW\|State'; done

The ‘State’ parameter was added to the query. The response has the following format (example):

Copy
Copied!
            

# 1   State : Active Vendor Part Number : MFS1S00-H010 FW Version : 38.100.59   2   State : Active Vendor Part Number : MFS1S00-H010 FW Version : 38.100.59


© Copyright 2023, NVIDIA. Last updated on Mar 21, 2024.