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_updatecommand does not request confirmation. Run--module_dry_runwith the same package first to review the planned updates. -
Each run prints a report and saves it as
module_fw_update_report_<YYYYMMDD_HHMMSS>.txtin 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 |
|---|---|---|---|
|
|
- |
Query the firmware of the cables plugged into the system. |
No |
|
|
- |
Show the cable update plan without updating anything. Needs |
No |
|
|
- |
Update the cable firmware from the package given by |
No |
|
|
FileName |
With |
Yes. It now also takes the cable package |
|
|
Seconds |
Seconds to wait between downloading the firmware to the cables and activating it (default 0: download and activate in one step). |
No |
|
|
Seconds |
Seconds to let the cables finish re-training before the update is verified (default 5). |
No |
|
|
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 |
|
|
- |
Write the report to its file only, without printing it to the screen. |
No |
|
|
- |
Add the owning ASIC and the per-ASIC port number to the report. |
No |
|
|
- |
Include the switch's service (FNM) ports in the scan, which skips them by default. |
No |
|
|
- |
Create a log file with the run's output. |
Yes |
|
|
LogFileName |
Use the specified log file. |
Yes |
|
|
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
.yamlfiles in the package are loaded, and each folder can contain any number of them -
FwLoadNameis relative to the folder that contains its.yamlfile. If the metadata file and the binary file are in the same folder,FwLoadNameis the binary file name -
On
aarch64systems, provide a.tgzpackage 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 |
|---|---|---|
|
|
Yes |
The cable vendor name. Matched exactly. |
|
|
Yes |
The image file path, relative to the |
|
|
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. |
|
|
No |
The cable part number. If omitted, the folder name is used. If specified without a wildcard, it must match the folder name exactly. |
|
|
No |
Restricts the match to cables with this OUI, revision or serial number. |
|
|
No |
Restricts the match to cables with this hardware revision. |
|
|
No |
Restricts the match to cables running this firmware version. |
|
|
No, but recommended |
The image checksum, verified before any burn operation starts. |
-
Match keys other than
VendorNamemay use wildcards:?matches a single character, and*matches any sequence of characters. -
If multiple entries match a cable, the entry with the highest
FwLoadVersionis 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: