mlxburn – Firmware Image Generator and Burner

mlxburn is a tool for firmware (FW) image generation and/or for burning a firmware image to the Flash/EEPROM attached to an NVIDIA device. Both functions or a single function of mlxburn can be activated by means of command line options (see mlxburn Synopsis). It can also query for firmware attributes (e.g., firmware version, GUIDs, etc.) and VPD info of adapter cards and switch systems.

mlxburn allows for customization of standard NVIDIA firmware for OEM specific needs (e.g., a specific adapter board type). See Customizing Firmware.

The mlxburn firmware update flow is composed of two separate stages: image generation and image burning. In the image generation stage, a given NVIDIA firmware release in .mlx format is processed together with a board-specific configuration (.ini) file to generate a ‘burnable’ firmware image. This image is burnt to the Flash/EERPROM attached to an NVIDIA device in the second stage. The burning process retains device specific data such as GUIDs, UIDs, MACs, VSD, and BSN. Also, the burn process is failsafe by default.

FW Generation and Burning

image2019-3-20_12-1-44-version-1-modificationdate-1702306822227-api-v2.png

mlxburn runs both stages by default, but it may perform only one by means of command options. If ‘-wrimage’ is specified (see mlxburn Synopsis), only image generation is performed. Specifying the ‘-image’ option skips the image generation stage and loads the provided image (generated in a previous run of mlxburn using the ‘-wrimage’ option).

An NVIDIA firmware image can be customized (usually) to fit a specific board type. The customization is done by using a FW parameter-set file in the image generation stage. This file has a .ini format. Each parameter-set file has a unique parameter-set ID (PSID), which is kept in the device Flash/EEPROM and allows retaining device configuration during future FW updates.

During a device FW update, mlxburn reads the PSID from the device and uses the corresponding .ini file when generating the FW image. mlxburn searches for the files in the same directory of the FW release. When mlxburn is used to generate an image file, or when no corresponding parameter-set file is found, the user should explicitly specify which parameter-set file to use.

To produce an image file the user needs to provide the option ‘-wrimage <target file>’. To actually burn the image to the Flash/EEPROM attached to an NVIDIA adapter or switch device, the user needs to specify the option ‘-dev <mst device>’ (see the synopsis section below).

If run in burning mode, mlxburn auto-detects the firmware parameter-set with which the device was previously burnt. It locates and uses this parameter-set file to generate the appropriate image for the device (by merging the FW release with the specific parameter-set required).

To inhibit image generation, the ‘-image <pre-generated-image-file>’ should be used. It instructs mlxburn to use the given file for burning the device.

Copy
Copied!
            

#mlxburn [-h][-v] <-dev mst-device|-wrimage fw-image> <-fw mellanox-fw-file|-image fw-image|-img_dir img_direcory|-fw_dir fw_dir> [-conf fw-conf-file][-nofs][-nofs_img][-striped_image][-format BINARY|IMAGE] [-dev_type device type] [-exp_rom <exp_rom_file>][-exp_rom_dir <exp_rom_dir>] [-force][-conf_dir <conf_dir>] [-gb_bin_file <gb_bin_file>] [-fwver][-vpd][-vpd_rw][-vpd_prog_rw <rw-keywords-file>] [-vpd_set_keyword <keyword-assignment>] [-set_pxe_en <(port1|port2)=(enable|disable)>] [-prof_file <profiles file>] [-query] [-conf_dir_list <dir1,dir2,...,dirn>] [-noencrypt]

Note: The “-fwver” flag is not supported in Connect-IB, Switch-IB, ConnectX-4, and ConnectX-5 devices.

where:

-dev_type <mellanox-device-number>

mlxburn must know the device type in order to work properly. Use this flag if device type auto-detection fails.

Example: -dev_type 23108

Supported NVIDIA device types:

  • HCAs/NICs: 25408, 25418, 26418, 26428, 25448, 26448, 26468, 26478, 25458, 26458, 26438, 26488, 4099, 4103, 4113, 4115, 4117, 4119, 4121, 41680, 41681, 41682.

  • Switches: 48436, 48437, 48438, 51000, 52000, 52100, 53000, 53100.

-fw <mellanox-fw-file>

Specify NVIDIA FW released Firmware File to use (file extension is .mlx)

-conf <parameter-set-file>

FW configuration file (.ini). Needed when generating image (not using -dev flag) or if configuration auto detection fails.

-conf_dir <dir>

When specified, the auto detected configuration files will be looked for in the given directory, instead of in the firmware file directory. Applicable for burn operation.

-gb_bin_file <gb_bin_file>

Integrate the given gearbox binary file to the FW image.

-dev <mst-dev>

Burn the image using the given mst device

-exp_rom <exp-rom-file>

Integrate the given expansion rom file to the FW image. The given file may be in .img or bin/.rom (raw binary) format.

  • If the exp-rom-file is set to "AUTO", expansion rom file is auto detected from the files rom in the exp_rom_dir (see below).

NOTE: Exp rom auto detection is done for devices that are already burned with an exp-rom image.

  • If "-exp_rom AUTO" is specified for a device with no exp-rom, it would be burnt with no exp rom.

To add exp-rom to a device, manually supply the exp rom file to use.

-exp_rom_dir <exp_rom_dir>

The directory in which to look for expansion rom file when "-exp_rom AUTO" is specified. By default, exp-rom files are searched in <fw file directory>/exp_rom/*

-force

None interactive mode. Assume "yes" for all user questions.

-format <BINARY|IMAGE>

Specify which image format to use. Can be specified only with the -wrimage flag. Default is BINARY.

-fw_dir <dir>

When specified, the auto detected fw files will be looked for in the given directory. Applicable for burn operation.

-conf_dir_list <dir1,dir2,...,dirn>

When specified, the auto detected configuration files will be looked for in the given directories, instead of in the firmware file directory. Applicable for burn operation.

-fwver

When a device is given: Display current loaded firmware version.

When a FW file is given (-fw flag): Display the file FW version.

Note: The “-fwver” flag is not supported in Connect-IB devices.

-h

Display a short help text

-image <fw-image-file>

Do not generate image. Use the given fw image instead

-img_dir <image directory>

Do not generate image. Select the image to burn from the *.bin in the given directory

-nofs

When specified, burn process will not be failsafe.

-nofs_img

When specified, generated image will not be failsafe, and burn process will not be failsafe

-striped_image

When specified, generated image will be in striped format, and will indicate that the image is in striped format when queried.

-query

Query the HCA/Switch device for firmware details, e.g. Firmware Version, GUIDs, etc.

In addition to the above flags, Mlxburn can also accept the following flags/options, which are passed to the underlying burning tool:

-banks -use_image_ps -skip_is

-mac(s) -guid(s) -sysguid

-vsd -ndesc -bsn

-pe_i2c -se_i2c -is3_i2c

-no -uid(s)

-log -blank_guids -flash_params

-allow_psid_change -no_flash_verify

-use_image_rom -override_cache_replacement

-use_image_guids

See the flint tool documentation for HCA/4th gen switches/Bridge burning options.

-v

Print version info and exit

-V <INFORM|WARNING|DEBUG>

Set verbosity level. Default is WARNING

-vpd 1,2

Display the read only section of the PCI VPD (Vital Product Data) of the given device

-vpd_rw1,2

(on Linux only): Display also the read/write section of the PCI VPD of the given device.

-wrimage <fw-image-file>

Write the image to the given file.

-s, --i2c-secondary <address>

Change the I2C secondary address.

Note 1. The VPD query may not be enabled on certain board types. Also, VPD operations are available only for devices with a PCI interface.

Note 2. Running multiple VPD access commands in parallel on the same device, by mlxburn or any other VPD access tool, may cause the commands to fail. VPD access commands should be run one at a time.

Connect-IB, Switch-IB, Switch-IB 2, NVIDIA Spectrum, ConnectX-4, and ConnectX-4 Lx Initial Burning Options

The following options are relevant when generating an image for initial burning. The image contains the VPD and the GUIDs that are in a read-only area on flash.

Copy
Copied!
            

[ -vpd_r_file <vpd_r_file>] [ -base_guid <GUID>] 

where:

-vpd_r_file <vpd_r_file>

Embed the given VPD Read-Only section in the generated image. The vpd_r_file should contain the vpd read only section and the first dword of the vpd writeable section.

The file is in binary format, and its size must be a multiple of 4 bytes. Please refer to PCI base spec for VPD structure info.

-base_guid <GUID>

Set the given GUID as the image base GUID. The base GUID is used to derive GUIDs and MACs for the HCA ports. It is assumed that 16 GUIDs (base_guid to base_guid + 15) are reserved for the card.

Note: On ConnectX-4/ConnectX-4 Lx/ConnectX-5/ConnectX-5 Ex, only GUIDs will be derived according to the HCA configuration.

-base_mac <MAC>

Set the given MAC as the image base MAC. The base MAC is used to derive MACs for the HCA ports according to the device configuration (ConnectX-4/ConnectX-4 Lx/ConnectX-5/ConnectX-5 Ex).

-vsd <string>

Write this string, of up to 208 characters, to VSD section.


Additional mlxburn Options

The following is a list of additional options. Please see .mlxfwmanager – Firmware Update and Query Tool v4.18.1 for the HCA options.

Copy
Copied!
            

-banks -use_image_ps -skip_is -mac(s) -guid(s) -sysguid -ndesc -bsn -use_image_guids -pe_i2c -se_i2c -is3_i2c -no -qq -uid(s) -log -blank_guids -flash_params -allow_psid_change -no_flash_verify -use_image_rom -override_cache_replacement -ocr -ignore_dev_data -use_dev_rom -no_fw_ctrl

Warning

The arguments of the -guids and -macs flags must be provided within quotation marks; for example, mlxburn -macs “0002c900001 0002c900002”.


Host Channel Adapter Examples

To update firmware on an MT25408 ConnectX adapter device with the configuration file (.ini) auto-detected, enter:

Copy
Copied!
            

# mlxburn -fw ./fw-ConnectX3-rel.mlx -dev /dev/mst/mt4099_pci_cr0

To generate a failsafe image file for the same adapter above without burning, enter:

Copy
Copied!
            

# mlxburn -fw ./fw-ConnectX3-rel.mlx -conf ./MCX354A-FCB_A2-A5.ini -wrimage ./fw-4099.bin

To update firmware on the same adapter above with the configuration file (.ini) explicitly specified, enter:

Copy
Copied!
            

# mlxburn -fw ./fw-ConnectX3-rel.mlx -dev /dev/mst/mt4099_pci_cr0 -conf ./CX354A-FCB_A2- A5.ini


ConnectX-5 Examples

To generate a failsafe image file for ConnectX-5 device without burning, enter:

# mlxburn -fw FW/fw-ConnectX-5.mlx -conf FW/CX515A-CCA_Ax.ini -wrimage fw-ConnectX-5-CX515A- CCA_Ax.bin -base_guid 0x002c90330123e00

To update firmware on a ConnectX-5 device, enter:

Copy
Copied!
            

# mlxburn -i fw-ConnectX-5-CX515A-CCA_Ax.bin -d /dev/mst/mt4115_pciconf0


ConnectX-4 Examples

To generate a failsafe image file for ConnectX-4 device without burning, enter:

Copy
Copied!
            

# mlxburn -fw FW/fw-ConnectX-4.mlx -conf FW/MCX456A-ECA_Ax.ini -wrimage fw-ConnectX-4-MCX- 456A-ECA_Ax.bin -base_guid 0x0002c903002ef500

To update firmware on a ConnectX-4 device, enter:

Copy
Copied!
            

# mlxburn –i fw-ConnectX-4-MCX456A-ECA_Ax.bin –d /dev/mst/mt4113_pciconf0


ConnectX-4 Lx Examples

To generate a failsafe image file for ConnectX-4 Lx device without burning, enter:

Copy
Copied!
            

# mlxburn -fw FW/fw-ConnectX4Lx.mlx -conf FW/MCX4131A-GCA_Ax.ini -wrimage fw-ConnectX-4LX- MCX4131A-GCA_Ax.bim -base_guid 0xe41d2d0300ab2a4e -base_mac 0000e41d2dab2a4e

To update firmware on a ConnectX-4 Lx device, enter:

Copy
Copied!
            

# mlxburn -i fw-ConnectX-4LX-MCX4131A-GCA_Ax.bim -d /dev/mst/mt4117_pciconf0


Connect-IB Examples

To generate a failsafe image file for Connect-IB device without burning, enter:

# mlxburn -fw FW/fw-ConnectIB.mlx -c FW/MCB194A-FCA_A1.ini -wrimage fw-ConnectIB-MCB194A- FCA_A1.bin -base_guid 0x0002c903002ef500

To update firmware on a Connect-IB device, enter:

Copy
Copied!
            

# mlxburn –i fw-ConnectIB-MCB194A-FCA_A1.bin –d /dev/mst/mt4113_pciconf0


SwitchX Switch Examples

Burn an MT51000 switch system using the In-Band access method:

Copy
Copied!
            

# mlxburn -dev /dev/mst/SW_MT51000_000002c900002100_lid-0x000E -fw ./fw-sx.mlx

Generate an MT51000 image and perform an In-Band update of the device with LID 0xE:

Copy
Copied!
            

# mlxburn -dev lid-0x000E -fw ./fw-sx.mlx

Generate and burn a new MT51000 via I2C:
Set the I2C network to access the SwitchX switch.

Copy
Copied!
            

# mlxi2c -d /dev/mst/mtusb-1 p SX

Burn the new image (the flash is still blank) specifying the Node GUID, system GUID, base MAC and Switch MAC. Note that 4 guids (in quotes) should be specified as an argument to the -guids flag. The 2 middle GUIDs are ignored by SwitchX and should be set to 0.

Copy
Copied!
            

# mlxburn -d /dev/mst/mtusb-1 -fw ./fw-sx.mlx -conf MSX6025F_A1.ini -guids "000002c900002100 0 0 000002c900002100" -macs "0002c9002100 0002c9002101" -nofs


NVIDIA Spectrum Examples

To generate a failsafe image file for a NVIDIA Spectrum device without burning, enter:

mlxburn -fw FW/fw-SwitchEN.mlx -c FW/MSN2700-Cxxx_Ax.ini -wrimage fw-Spectrum-MSN2700-Cxxx-_Ax.bin -base_guid e41d2d030045a240 -base_mac 0000e41d2d45a240

To update firmware on a Spectrum device, enter:

Copy
Copied!
            

mlxburn -i fw-Spectrum-MSN2700-Cxxx_Ax.bin -d /dev/mst/mt52100_pciconf0


Switch-IB Examples

To generate a failsafe image file for a Switch-IB device without burning, enter:

Copy
Copied!
            

mlxburn -fw FW/fw-SwitchIB.mlx -c FW/MSB7700-E_Ax.ini -wrimage fw-SwitchIB-MSB7700-E_Ax.bin - base_guid 0x0002c903002ef500

To update firmware on a Switch-IB device, enter:

Copy
Copied!
            

mlxburn -i fw-SwitchIB-MSB7700-E_Ax.bin -d /dev/mst/SW_MT52000_000011111101a24c_lid- 0x0006,mlx4_0,1

Switch-IB 2 Examples

To generate a failsafe image file for a Switch-IB 2 device without burning, enter:

Copy
Copied!
            

mlxburn -fw FW/fw-SwitchIB-2.mlx -c FW/MSB7800-Exxx_Ax.ini -wrimage fw-SwitchIB-2- MSB7800- Exxx_Ax.bin -base_guid 7cfe900300a5a620

To update firmware on a Switch-IB 2 device, enter:

Copy
Copied!
            

mlxburn -i fw-SwitchIB-2- MSB7800-Exxx_Ax.bin -d /dev/mst/mt53000_pciconf0


The following exit values are returned:

  • 0 - successful completion

  • >0 - an error occurred

© Copyright 2023, NVIDIA. Last updated on Feb 5, 2024.