mlxburn(1)

NAME
mlxburn - Burn, query or generate FW image for the local Mellanox HCA/Switch device.

SYNOPSIS
mlxburn
  [-h | -v][-V INFORM|WARNING|DEBUG]
  [-dev <mst-device> | -wrimage <fw-image-file>][-dev_type device-type]
  [-fw <mellanox-fw-file> [-format BINARY|IMAGE] | -image <fw-image-file>]
  [-conf <parameter-set-file>][-conf_dir <dir>][-nofs][-nofs_img][-exp_rom <exp-rom-file>]
  [-force][-fwver][-vpd][-vpd_rw][-vpd_prog_rw <rw-fields-file>][-query][-inband]
  [-sw_sys rhino|reindeer|trex|gazelle [-pattern <geo-addr> | -list]]

DESCRIPTION
mlxburn is a firmware update tool for Mellanox devices.
The FW update flow goes through two stages: image generation and burning.

1.  Image generation:
    Process the given Mellanox FW release (in .mlx or .BIN format) and generate a 'burnable' FW image.

2.  Burn the FW image to the device: The burn process retains device specific data such as GUIDs, VSD and BSN. The burn process is failsafe (by default).

mlxburn runs both stages by default, but it may perform only one of the stages, according to the given command line options:
If -dev is not provided the actual device burning will be skipped.
Providing the -image flag will skip the image generation phase and load the provided image (that should be generated by previous run with the -wrimage flag). Firmware Customization:
Mellanox FW release 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 .brd or a .ini format. Each parameter-set file has a unique parameter set ID (PSID), which is kept in the device and allows retaining configuration in future FW updates.
During device FW update, mlxburn reads the PSID from the device and uses the corresponding .brd or .ini file when generating the FW image. The files are searched 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, user should explicitly specify which parameter-set file to use. Device Query:
In addition to FW burning and generation, mlxburn can also query and display the HCA/Switch FW data (-fwver and -query flags), and the PCI VPD (Vital Product Data, -vpd/-vpd_rw flags) of the HCA board. Inband Access:
mlxburn has the ability to query/update an MT47396 (InfiniScale III) device via the InfiniBand fabric using the -inband flag. In that case the target device is specified by the LID assigned to it by the Subnet Manager. See MFT user manual for further information regarding inband access. Switch Systems:
mlxburn can query/update a full or partial switch system with a single command for a number of known InfiniBand switch systems - reindeer (24/16 ports), gazelle (96 ports), rhino (144 ports) and trex (288 ports). Given a pattern (-pattern flag), mlxburn will access all matching devices. Running in List mode, mlxburn will provide a pattern-list of the devices detected in the system.

OPTIONS

Burn Options

-dev      <mst-dev>
    Burn the image using the given MST device.

-fw       <mellanox-fw-file>
    Specify Mellanox FW released Firmware File to use (file extension is .mlx or .BIN).

-image    <fw-image-file>
    Don't generate image. Use the given fw image instead.

-conf     <parameter-set-file>
    FW configuration file (.br d or .ini). Needed when generating image (not using -dev flag) or if configuration auto detection fails.

-wrimage  <fw-image-file>
    Write the image to the given file.

Query Options (-dev flag must be also specified with these options)

-query
    Prints firmware information for Mellanox devices (HCAs and MT47396 switch device).

-fwver
    Prints the loaded firmware version on the Mellanox device.

-vpd
    Displays the Read Only section of the PCI VPD (Vital Product Data) of the given device.

-vpd_rw
    Displays the Read Only and Read/Write sections of the PCI VPD of the given device.

NOTE:
    The VPD feature may not be supported on certain board types. VPD query must be run as root.

-query
    Queries the HCA/Switch device for firmware information such as F.W. Version, GUIDs etc. Info Options

-h  Display a help message.

-V         <INFORM|WARNING|DEBUG>
    Set verbosity level. Default is INFORM.

-v  Print version info and exit.

ADVANCED OPTIONS

-nofs
    When specified, the burn process will not be failsafe. Non-failsafe burn is required on the rare occasion when a new firmware version has modifications in the "invariant" sector.

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

-exp_rom  <exp-rom-file>
    Integrate the given expansion rom file to the FW image. The given file may be in .img or .bin (raw binary) format.

-conf_dir <dir>
    Instructs the burn operation to look for auto-detected configuration files under the specified directory rather than under the firmware file directory.

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

-dev_type  <mellanox-device-number>
    mlxburn must know the device type in order to work properly. Use this flag if device type auto-detection (taken from the FW file name) fails.

-vpd_prog_rw <rw-fields-file>
    Program the VPD-W tag (the writable section of the VPD) with the data given in the rw-fields-file.
    File lines format: "FIELD = VALUE".
    White spaces before and after VALUE are trimmed. A field name should have 2 letters exactly (for example: "YA" , "V1"). The field name "RW" is reserved and should not be used.

-force
    Runs mlxburn in non-interactive mode.

-inband
    Use inband burning method, this is applicable only when burning an MT47396 switch device. When this flag is given, the argument to the -dev flag should be the LID of the target device.

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

HCA devices: -byte_mode -use_image_ps -skip_is -mac(s) -guid(s) -sysguid -vsd
MT47396 switch: -guid(s) -ndesc -bsn -pe_i2c -se_i2c -is3_i2c
See the flint tool documentation for HCA burning options.
See the spark tool documentation for Switch burning options.

SWITCH SYSTEMS

-sw_sys <rhino|reindeer|trex|gazelle>
    Run mlxburn in switch system mode. In this mode there is an option to perform burn and query operations on multiple devices using a geographical address pattern, e.g. L3I1 (Device number 1 on Leaf 3), S2I1 (Device number 1 on Spine 2), L* (All Leaf devices).

-pattern <geo-addr>
    Specify a pattern for mlxburn to access on the system. Default pattern is Run 'isw -h' for further information about patterns.

-list
    List only mode. List all switch devices found on the system by their patterns.

EXAMPLES

Update FW on a MT23108 device. Parameter-set-file is auto-detected:
    mlxburn -fw ./fw-23108-a1-rel.mlx -dev /dev/mst/mt23108_pci_cr0

Generate image without burning:
    mlxburn -fw ./fw-23108-a1-rel.mlx -conf ./MHXL-CF128-T.ini -wrimage ./fw-23108.bin

List all detected board patterns that are currently connected to the Rhino system chassis:
    mlxburn -dev /dev/mst/mtusb-1 -sw_sys rhino -list

Full query of a rhino switch system:
    mlxburn -dev /dev/mst/mtusb-1 -sw_sys rhino -pattern -query

Generate and burn an MT47396 image for device number 3 on Spine number 1 of the Trex system:
    mlxburn -dev /dev/mst/mtusb-1 -sw_sys trex -pattern S1I3 -fw ./IS3FW.BIN

Generate an image for an MT43132 device, configured for a gazelle (96 port switch system) Spine:
    mlxburn -sw_sys gazelle -pattern S1I1 -fw ./ucode-43132-5.6.0.RC2 -conf MTEK43132-4X-RevC -wrimage ./my.img

Generate an MT47396 image and perform an inband update of the device with LID 0x11:
    mlxburn -dev 0x11 -fw ./IS3FW.BIN -inband

EXIT STATUS
The following exit values are returned:

0         Successful completion.

>0        An error occurred.

KNOWN ISSUES
Supports burning Mellanox boards only. For other vendor boards please consult with the board manufacturer.