Networking NVIDIA Firmware Tools (MFT) Documentation

Updating Cable Firmware with mlxfwmanager

mlxfwmanager tool can query and update the firmware of NVIDIA cables connected to a switch system. It scans the entire system, including all switch ASICs and their cages, and accesses the cables through the switch firmware. Therefore, there is no need to add cable devices by using mst cable add.

When a firmware update package is provided with -i, the tool matches each cable to the appropriate image in the package, burns and activates the firmware, and verifies that the cable is running the updated version.

  • The tool supports the following modes:

    • --module_query — Lists the cables in the system and their firmware versions

    • --module_dry_run — Displays the update plan without making any changes

    • --module_update — Executes the update plan

  • Only NVIDIA cables are updated. Third-party and counterfeit cables are listed but skipped.

  • The --module_update command does not request confirmation. Run --module_dry_run with the same package first to review the planned updates.

  • Each run prints a report and saves it as module_fw_update_report_<YYYYMMDD_HHMMSS>.txt in the current directory or in the directory specified by --module_report_dir.

  • This feature is supported on NVIDIA NVLink5 Switch ASIC (InfiniBand) and Spectrum-4 (Ethernet) switch systems and later. Update the switch firmware to the latest version before updating cable firmware, because the update flow requires switch firmware that can report burn errors for each cable and stop before any burn if that capability is unavailable.

Command Line Options

Flag

Argument

Description

Pre-existing

--module_query

-

Query the firmware of the cables plugged into the system.

No

--module_dry_run

-

Show the cable update plan without updating anything. Needs -i.

No

--module_update

-

Update the cable firmware from the package given by -i.

No

-i | --image-file

FileName

With --module_dry_run and --module_update: the firmware update package, as a tgz or ZIP file, or a directory holding its contents.

Yes. It now also takes the cable package

--module_activation_wait

Seconds

Seconds to wait between downloading the firmware to the cables and activating it (default 0: download and activate in one step).

No

--module_verify_wait

Seconds

Seconds to let the cables finish re-training before the update is verified (default 5).

No

--module_report_dir

DirectoryName

Directory to write the report to (default: the current directory). It must exist and be writable, or the run stops before touching any device.

No

--module_report_silent

-

Write the report to its file only, without printing it to the screen.

No

--module_report_verbose

-

Add the owning ASIC and the per-ASIC port number to the report.

No

--module_include_service_ports

-

Include the switch's service (FNM) ports in the scan, which skips them by default.

No

--log

-

Create a log file with the run's output.

Yes

-L | --log-file

LogFileName

Use the specified log file.

Yes

-o | --outfile

OutputFileName

Write the output to the specified file.

Yes

The cable modes cannot be combined with each other, with another mlxfwmanager mode, or with -d, -D, --xml, --force, --skip_if_same, --no_fw_ctrl, --lookup, --psid, --component_type and --log-on-update. Such a command line is refused (exit code 3).

Firmware Update Package

The package complies with the OIF CMIS Firmware Update Package Implementation Agreement (IA): it contains firmware images, each paired with a YAML metadata file that specifies which cables the image applies to.

For now, customers should build and maintain the cable firmware update package themselves using the firmware images NVIDIA provides, following the layout and YAML metadata format below. In a future release, NVIDIA will provide and manage these packages.

Package Layout

linkx_pkg.tgz  or  linkx_pkg.zip  or  linkx_pkg/        the same files in any of the three forms
 +-- 980-9IAHB-00XM0N/                                 one folder per cable part number
 |     +-- NVIDIA.070.010.11014_FwUpdate.yaml          metadata: one entry, or a list of entries
 |     +-- fw_70_010_11014.bin                         the image an entry names in FwLoadName
 +-- 980-9IAMA-00XD01/
       +-- NVIDIA.039.230.02014_FwUpdate.yaml
       +-- fw_39_230_02014.bin
  • All .yaml files in the package are loaded, and each folder can contain any number of them

  • FwLoadName is relative to the folder that contains its .yaml file. If the metadata file and the binary file are in the same folder, FwLoadName is the binary file name

  • On aarch64 systems, provide a .tgz package or a directory. ZIP packages are not supported

  • Symbolic links in the package are skipped

Metadata File

One entry:

VendorName: "NVIDIA"
VendorPN: "980-9IAHB-00XM0N"
ModuleActiveFirmwareVersion: "70.*"
FwLoadVersion: "70.10.11014"
FwLoadName: "fw_70_010_11014.bin"
FwUpdateLoadChecksumSHA256: "<SHA-256 of fw_70_010_11014.bin>"

A list of entries in one file, without VendorPN, so the part number is taken from the folder name:

- VendorName: "NVIDIA"
  ModuleActiveFirmwareVersion: "70.*"
  FwLoadVersion: "70.10.11014"
  FwLoadName: "fw_70_010_11014.bin"
  FwUpdateLoadChecksumSHA256: "<SHA-256 of fw_70_010_11014.bin>"
- VendorName: "NVIDIA"
  ModuleActiveFirmwareVersion: "70.*"
  FwLoadVersion: "70.10.11016"
  FwLoadName: "fw_70_010_11016.bin"
  FwUpdateLoadChecksumSHA256: "<SHA-256 of fw_70_010_11016.bin>"

Key

Required

Meaning

VendorName

Yes

The cable vendor name. Matched exactly.

FwLoadName

Yes

The image file path, relative to the .yaml file.

FwLoadVersion

When the image does not state its own version

The image version. If the image contains its own version, the two values must match. The major version must also match the major version of the firmware currently running on the cable.

VendorPN

No

The cable part number. If omitted, the folder name is used. If specified without a wildcard, it must match the folder name exactly.

VendorOUI, VendorRev, VendorSN

No

Restricts the match to cables with this OUI, revision or serial number.

ModuleHardwareMajorRevision, ModuleHardwareMinorRevision

No

Restricts the match to cables with this hardware revision.

ModuleActiveFirmwareVersion

No

Restricts the match to cables running this firmware version.

FwUpdateLoadChecksumSHA256, FwUpdateLoadChecksumSHA512

No, but recommended

The image checksum, verified before any burn operation starts.

  • Match keys other than VendorName may use wildcards: ? matches a single character, and * matches any sequence of characters.

  • If multiple entries match a cable, the entry with the highest FwLoadVersion is used.

  • The image may include the 48-byte cable extended header or omit it. If it is omitted, the tool builds the header from the metadata entry. If it is present, it must match the entry’s part number, revision, version, and size; otherwise, the entry is invalid.

  • Unknown keys are ignored. As a result, a misspelled key is treated as if it were not present.

  • If any entry is invalid, the entire package is rejected: no cables are updated, and the report lists each invalid entry and the reason it is invalid (exit code 9)

Examples

Query the cables in the system:

mlxfwmanager --module_query

Query, with the owning ASIC of each cable, saving the report to /var/log without printing it:

mlxfwmanager --module_query --module_report_verbose --module_report_dir /var/log --module_report_silent

Check a package and see the update plan, changing nothing:

mlxfwmanager --module_dry_run -i /tmp/linkx_pkg.tgz

Update from an extracted package directory, waiting 15 seconds before the result is verified:

mlxfwmanager --module_update -i /tmp/linkx_pkg --module_verify_wait 15

The console of an update, up to the report:

-I- Found 4 switch ASIC(s)
-I- Found 76 port(s), scanning for cables
-I- Skipping 4 service (FNM) port(s): 73, 74, 75, 76; use --module_include_service_ports to include them
-I- Found 6 cable(s), 4 of them updatable
-I- Read 1 firmware image(s) from /tmp/linkx_pkg
-I- Planned 2 cable update(s) in 1 group(s)
-I- Updating 2 cable(s):
      Port 5     980-9IAHB-00XM0N      70.10.11016   -> 70.10.11014  (downgrade)
      Port 53    980-9IAHB-00XM0N      70.10.11016   -> 70.10.11014  (downgrade)
-I- Updating group 1 of 1 on /dev/mst/mt54004_pciconf0
      Downloading the image to the switch - OK
      Transferring the image to the cables - OK
Please wait while activating the transceiver(s) FW ...
      Activating the cables - OK
-I- Group 1 of 1 finished: 2 of 2 cable(s) burned
-I- Waiting 15 second(s) for the cables to finish re-training
...
-I- Report saved to module_fw_update_report_20261005_141502.txt

A package with invalid entries, as the report's update plan shows it:

FW UPDATE PLAN
--------------
Not planned: Found 2 invalid firmware metadata entries in /tmp/linkx_pkg.tgz:
  1. 980-9IAHB-00XM0N/NVIDIA.070.010.11016_FwUpdate.yaml:
     SHA-256 mismatch for 980-9IAHB-00XM0N/fw_70_010_11016.bin: expected <SHA-256 in the metadata>, the image hashes to <SHA-256 of the image>
  2. 980-9IAHB-00XM0N/NVIDIA.070.010.11014_FwUpdate.yaml:
     FwLoadVersion 70.10.11012 does not match 980-9IAHB-00XM0N/fw_70_010_11014.bin, which is 70.10.11014


Last updated: