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
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.
#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. Supported NVIDIA device types:
|
-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.
NOTE: Exp rom auto detection is done for devices that are already burned with an exp-rom image.
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. |
-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: 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_prog_rw<rw-keywords-file>1,2 | (on Linux only): Program the VPD-W tag (the writable section of the VPD) with the data given in the rw-keywords-file. File lines format: "KEYWORD = VALUE". In order to set binary data to a keyword, add ":BIN" to the keyword name. in this case, the data is a hexadecimal string of even length. White spaces before and after VALUE are trimmed. |
-vpd_rw1,2 | (on Linux only): Display also the read/write section of the PCI VPD of the given device. |
-vpd_set_keyword <keywordassignment>1,2 | Add or change a keyword value in the VPD-W tag (the writable section of the VPD) with the data given in the keyword-assignment string. The string format is identical to a line in the rw-keywordsfile described above. Other keywords in the VPD-W tag are not affected by this operation. |
-wrimage <fw-image-file> | Write the image to the given file. |
-s, --i2c-secondary <address> | Change the I2C secondary address. |
eNote 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.
[ -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.
-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
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:
# 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:
# 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:
# 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:
# 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:
# 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:
# 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:
# 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:
# 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:
# 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:
# 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:
# 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.
# 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.
# 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:
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:
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:
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:
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:
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