NVIDIA Networking Firmware (MFT)
The NVIDIA Firmware Tools family (mst, flint, mlxfwmanager, mlxconfig, mlxfwreset, mlxlink, mlxcables), PSIDs, the NIC firmware lifecycle (query, burn, activate, verify), BlueField bundles, InfiniBand and Ethernet switch upgrades, and keeping a whole cluster on one recipe. Complements the HGX firmware guide, which covers the server side. Objectives 1.4, 2.1, and 4.6.
1. The big picture: firmware across the whole cluster
An AI cluster runs firmware in every box: server BIOS and BMC, the HGX GPU baseboard, every NIC and DPU, every switch, every active cable or transceiver, every drive. Different tools update different parts, and every part has its own activation rule.
| Domain | Main tools | Guide |
|---|---|---|
| Server (BIOS, BMC, CPLD, PSU) | BMC Redfish, vendor tools, nvfwupd on DGX | HGX firmware, Redfish |
| HGX baseboard (GPUs, NVSwitches, HMC, ERoT) | nvfwupd / Redfish through the BMC | HGX firmware |
| ConnectX NICs, BlueField NIC firmware | MFT: flint, mlxfwmanager, mlxfwreset | This guide |
| BlueField Arm software | BFB images via RShim (bfb-install) | This guide, section 13 |
| InfiniBand switches | Switch OS image, UFM, or in-band flint | This guide, section 14 |
| Ethernet switches | Switch OS image (Cumulus Linux, SONiC) | This guide, section 15 |
| Transceivers / active cables | mlxlink / mlxcables / flint (LinkX), switch CLI | Transceivers |
| Drivers (GPU, Fabric Manager, DOCA/OFED) | Software image (BCM) | Bring-up |
2. Interactive firmware matrix: which tool for which component
3. The MFT tool family
MFT (NVIDIA Firmware Tools, formerly Mellanox Firmware Tools) is a package of command-line tools for NVIDIA networking devices: ConnectX adapters, BlueField DPUs/SuperNICs, and switches.
| Tool | Purpose | Typical command |
|---|---|---|
mst | Start the access drivers and list devices | mst start, mst status -v |
flint | Query, burn, verify one device's firmware image | flint -d <dev> q |
mlxfwmanager | Query all devices; update from a firmware package/directory, matching PSIDs automatically | mlxfwmanager --query |
mlxconfig | Read/write non-volatile device settings (port type, SR-IOV, DPU/NIC mode…) | mlxconfig -d <dev> q |
mlxfwreset | Reset the device so new firmware/settings load without a full reboot | mlxfwreset -d <dev> query |
mlxlink | Link status, speed, errors, eye, module info | mlxlink -d <dev> -m |
mlxcables | Access cable/module EEPROM and information | mlxcables |
mlxdump / mstdump | Diagnostic dumps for support | When support asks |
Less common tools in the same package that still show up in procedures:
| Tool | Purpose |
|---|---|
mlxburn | Older generate-and-burn tool. Still handy for mlxburn -d <dev> -vpd (read the PCI VPD: part number, serial; -vpd_rw includes the writable fields) and -fwver. -query works like flint q. Building an image takes -fw <mlx> or -img_dir, with -base_guid/-base_mac/-conf, and -wrimage <file> writes a file instead of burning. It passes burn flags such as -allow_psid_change through to flint. |
mlxarchive | Packs several .bin images into one .mfa2 archive: mlxarchive --bins-dir <dir> --version 1.0.0 --out-file fw.mfa2 (-m <file> queries an archive). flint and mlxfwmanager pick the image that matches the device from it. Only installed when MFT is installed with --oem. |
mlxprivhost | BlueField zero-trust mode, run from the Arm side (Linux only). r (restrict) stops the host from flashing firmware or changing settings; add --disable_rshim (needs a power cycle), --disable_tracer, --disable_counter_rd, --disable_port_owner (each needs a firmware reset) to block more. p (privilege) undoes it. q [--full] shows the state. |
mlxvpd, mget_temp, mlxreg | Read VPD, read ASIC temperature, read or write device registers (support-directed). |
Debug utilities. You'll mostly run them when NVIDIA support asks for their output:
| Tool | Use |
|---|---|
mstdump <dev> [-full] [--ignore_fail] > dump.dmp | Dump the chip's internal configuration registers for support. -full dumps a longer address list; --ignore_fail keeps going past addresses that fail to read. |
mlxdump -d <dev> fsdump --type FT|STE | Dump the hardware steering (flow) tables: what is actually programmed, compared with what the software thinks. Deprecated since late 2023 in favor of the matching resourcedump segment. |
mget_temp -d <dev> | Chip temperature in °C. Module temperature comes from mlxlink -m / --cable --ddm. |
mlxuptime -d <dev> | How long the device has run since its last reset, plus its core frequency: shows whether a reset really happened |
fwtrace -d <dev> [--tracer_mode FIFO|MEM] [--real_ts], mlxtrace | Read firmware trace messages. On secure firmware, /sys/kernel/debug/tracing/events/mlx5/fw_tracer/enable must be 1. |
resourcedump dump|query -d <dev> -s <segment> | Dump a specific firmware object (a QP, CQ, or other resource) |
mlxreg -d <dev> --show_regs, --reg_name <R> --get [-i <indexes>], --set | Read or write named access registers. --set and raw --reg_id access can break a working device: only on instruction. |
mlxtokengenerator, mlxcableimgen, cpldupdate, mlxfwstress | Generate debug tokens; build cable images; burn a switch CPLD; firmware stress tests (support, OEM, or production use) |
.mfa2 placed under /lib/firmware: devlink dev flash pci/0000:17:00.0 file <name>.mfa2 (or ethtool -f <netdev> <name>.mfa2). The path is relative to /lib/firmware, and activation still needs a reset or reboot.mstflint, mstconfig, mstfwreset, mstlink). They use PCI addresses instead of /dev/mst devices. DOCA / MLNX_OFED installs usually include MFT or recommend it.4. mst: finding devices
sudo mst start # load access modules, create /dev/mst/* devices
sudo mst status -v # devices with PCI address, RDMA name (mlx5_X), netdev
# DEVICE_TYPE MST PCI RDMA NET
# ConnectX7(rev:0) /dev/mst/mt4129_pciconf0 17:00.0 mlx5_0 net-ibp23s0
# BlueField3(rev:1) /dev/mst/mt41692_pciconf0 a1:00.0 mlx5_8 net-ens7f0np0
sudo mst ib add # add InfiniBand switches reachable in-band (for flint -d lid-...)
Output is illustrative; columns vary by MFT version.
| mst device ID | Device | Firmware major version |
|---|---|---|
mt4123 | ConnectX-6 | 20.x |
mt4125 | ConnectX-6 Dx | 22.x |
mt4129 | ConnectX-7 | 28.x |
mt41686 | BlueField-2 | 24.x |
mt41692 | BlueField-3 | 32.x |
- Most MFT tools also accept a PCI address (
-d 17:00.0) instead of the/dev/mstpath. - A dual-port adapter appears as one device for firmware purposes: one firmware image serves both ports. Updating it affects both.
mst statusshowing nothing usually meansmst startwasn't run, or MFT isn't installed for this kernel.
mst subcommands and options
| Command | What it does | Notes |
|---|---|---|
mst start | Load the MST kernel modules and create /dev/mst/* | Options: --with_unknown (don't check the device ID: try it when a new card isn't listed), --with_i2cdev (embedded I2C master), --with_lpcdev, --with_fpga / --with_fpga_fw_access (FPGA cards, through the driver / the firmware), --with_msix. The same options work on mst restart. Rules in /etc/mft/mst.conf rename devices. |
mst add <dbdf> [--start_driver] / mst rm <dbdf> | Add or remove one device by PCI address without a full start/stop | Useful after a hot-plug or a PCI rescan |
mst save / mst load | Save / restore PCI configuration headers in /var/mst_pci | mst start saves them automatically |
mst stop [--force] [--device <dev>] | Remove the devices and unload the modules | --force stops even when a tool is using it |
mst restart | stop + start | mlxfwreset does this for you as its last step |
mst status / -v / -vv | List devices; -v adds PCI, RDMA (mlx5_X), netdev, NUMA | Run it after every mst start to map names |
mst ib add [hca] [port] | Add in-band devices (lid-N) discovered on the IB fabric | Needs an active IB port. --discover-tool ibnetdiscover|ibdiagnet (default ibdiagnet), --topo-file <file> (use a saved topology instead of scanning), --use-ibdr (access by direct-route MADs; only with ibnetdiscover), --add-non-mlnx, --planarized (planarized devices; mlxlink only). mst ib del removes them. |
mst cable add [--with_ib] | Add cable/module devices (..._cable_0) for mlxcables and CMIS flint | --with_ib also adds cables reachable in-band. --with_retimer adds retimers, --cdb_discovery finds retimers through CDB commands. mst cable del removes them. |
mst server start [-p port] [-s] / mst remote add <host>[:port] | Run MFT tools against another machine's devices (default port 23108) | -s sets or provides the passphrase (random if omitted). mst server stop, mst remote del undo it. |
mst gpu add|del, mst i2c add [--with_retimer] [--with_chipset], mst version | GPU devices through the NVIDIA driver, I2C devices, tool version | |
mst aggregate add | One aggregated device over several ASICs (matched by serial and position) | Newer MFT, ConnectX-9: lets one mlxconfig set_system_conf configure all ASICs on the board |
5. PSIDs and OEM cards
Every adapter carries a PSID (Parameter-Set ID), for example MT_0000000XXX for an NVIDIA-branded card. It identifies the exact board variant and its configuration defaults. Firmware images are built per PSID.
flintandmlxfwmanagercheck that the image's PSID matches the card's PSID and refuse a mismatch by default.- Cards sold by server vendors (OEM cards) have OEM PSIDs. Their firmware comes from the server vendor's support site, not NVIDIA's generic downloads.
flint ... --allow_psid_changeforces a different PSID's image. It can remove OEM-specific settings, break support, or leave the card unusable. Only do it under explicit vendor or NVIDIA support direction.
6. flint: query, burn, verify
sudo flint -d /dev/mst/mt4129_pciconf0 q
# Image type: FS4
# FW Version: 28.AA.BBBB
# FW Version(Running): 28.XX.YYYY <- only shown when a newer image is burned but not yet active
# PSID: MT_0000000XXX
# Security Attributes: secure-fw
# Base GUID / Base MAC: ...
sudo flint -i fw-ConnectX7-<version>.bin q # query an image FILE: version and PSID before burning
sudo flint -d /dev/mst/mt4129_pciconf0 -i fw-ConnectX7-<version>.bin burn
sudo flint -d /dev/mst/mt4129_pciconf0 verify # check the image on flash is intact
sudo flint -d /dev/mst/mt4129_pciconf0 ri backup.bin # read the current image to a file (where permitted)
sudo flint -d lid-<switch-LID> q # in-band query of an InfiniBand switch (after mst ib add)
Version numbers and output fields are placeholders; the layout varies by device and MFT version.
- Burning writes flash; it does not change the running firmware. The card keeps running the old version until it's reset (
mlxfwreset) or the server is rebooted/power-cycled. FW Version(Running)differing fromFW Versionmeans an activation is pending.- Secure firmware (
secure-fw) devices only accept NVIDIA-signed images; a modified or wrong image is rejected. - Abbreviations:
q= query,b= burn,v= verify.-yanswers yes to prompts (scripted use). - Exit codes:
0success,1error,7the burn was declined at the prompt. Scripts that loop over nodes should check them.
flint subcommands
| Command | What it does |
|---|---|
q / q full | Query the device or image. full adds more fields (all GUIDs/MACs, image info). |
b / burn | Burn the -i image, failsafe by default (the new image goes to the alternate location, so the old one survives an interrupted burn) |
v / verify | Check the image on flash (or a file with -i) is intact and bootable |
ri <file> | Read the image from flash into a file (back up before risky work) |
swreset | Reset an unmanaged switch to load its new firmware (in-band lid-N only) |
checksum / cs | MD5 of the firmware: compare across nodes to prove identical images |
bc / binary_compare (with -i) | Byte-compare the firmware on the device with an image file: proves the flash holds exactly that image |
dc [file] / dh [file] | Dump the image's firmware configuration (INI) / its hash file |
timestamp / ts set|query|reset | Firmware timestamps on multi-host adapters: once set, the device refuses images older than the "Next timestamp", so one host can't downgrade what another host burned. flint -i <img> ts set stamps an image; -d <dev> ts query shows Current/Next. |
qc / query_components --component_type <type> | Query a firmware-managed component (for example sync_clock, dpa_component, digital_cacert) through the firmware |
reset_cfg | Reset the non-volatile configuration to defaults (the same effect as mlxconfig reset) |
brom, drom, rrom, qrom | Burn, remove, read, or query the expansion ROM (PXE/UEFI boot code) inside the image |
sg, sv, smg, set_vpd | Set GUIDs/MACs, VSD, manufacture GUIDs, VPD. Production or support use; non-failsafe on current devices. |
set_key / hw_access enable|disable | Hardware access key that locks out flash and register access |
qbfb / query_bfb_components [--pending] | BlueField: versions of the components delivered by a BFB (and pending ones) |
ir / image_reactivation | Re-activate the previous flash image (firmware-controlled devices). burn -ir does it as part of a burn. |
extract_fw_data, fi | Extract the 4 MB firmware data for firmware-controlled updates; fix an image file. Support or production use. |
hw query, e, rw/ww, rb/wb, bb | Raw flash access and "burn block". Debug or production only: bb skips every check and can brick the card. |
flint flags you need to know
| Flag | Use | Caution |
|---|---|---|
-d <dev> | Device: /dev/mst/..., PCI address, lid-N (in-band switch), or a cable device | |
-i <file> | Image: .bin, .mfa2 archive, or a PLDM .fwpkg (with --component_type FW) | Query the file first: flint -i <file> q |
-y / -no | Answer yes / no to every prompt | -y also accepts warnings you'd want to read |
--skip_if_same | Skip the burn when the device already has this version: safe to re-run across a fleet | |
-qq | Quick query without full image integrity checks (fast over slow links such as I2C or in-band) | |
--flashed_version (older name: --next_boot_fw_ver) | With q: print only the version on flash, which is what loads at the next boot | Handy in scripts and pdsh loops. The old name still works. |
--low_cpu | Slower query that uses less CPU | For busy production hosts |
--allow_psid_change (--apc) | Burn an image with a different PSID | Support direction only: can drop OEM settings or break the card |
--allow_rom_change | Allow adding or removing the expansion ROM when a product version is present | |
--latest_fw, --psid <PSID> | With an .mfa2: take the newest matching image; pick by PSID (required when the card is in livefish/recovery mode) | |
-nofs | Non-failsafe burn | Only for blank or recovery flash. A power loss mid-burn leaves no good image. |
-guid/-guids, -mac/-macs, -uid, -blank_guids | Set identities while burning (blank flash or board repair) | Normal burns keep the device's current GUIDs and MACs |
-use_image_guids, -use_image_ps, -use_image_rom, -use_dev_rom | Take GUIDs / VSD / ROM from the image instead of keeping the device's | -use_image_guids gives every card the same GUIDs: never on a fleet |
-vsd <string> | Write a vendor-specific string (up to 208 characters) while burning | |
-ignore_dev_data, --no_fw_ctrl, -ocr | Take device data from the image / don't use the firmware-controlled update / override cache replacement | Advanced; can hang the firmware |
-clear_semaphore | Force-clear a stuck flash semaphore after a crashed tool | Corrupts flash if another tool is really using it |
-silent, -log <file>, -no_flash_verify | No progress bar / log the burn / skip per-write verify | Keep the verify on. NVIDIA only suggests skipping it for very slow links (MTUSB-1), and then nothing confirms the image burned correctly. |
-flash_params <type,log2size,num>, -banks <n> | Tell flint the flash type and size instead of reading them | Recovery of a device whose flash parameters can't be read |
-dual_image, -striped_image | Old two-image burn layout; treat the file as a striped (pre-burn) image | Legacy / production |
--cc <file> | Burn a Congestion Control component | Only with an image NVIDIA provides for it |
--i2c_secondary <addr>, --use_fw, --cpu_util 1-5 | Change the I2C secondary address; flash access through firmware (ConnectX-3 only); CPU throttling (Windows only) | |
--linkx and its options | Query or burn the cable/transceiver attached to the device, not the device itself | See section 16 |
Signing commands (sign, rsa_sign, --private_key, --hsm, set_public_keys, set_forbidden_versions) are for building custom signed images and aren't part of routine operations.
7. mlxfwmanager: package-based updates
sudo mlxfwmanager --query # every device: type, PSID, current version, available version, status
# Device Type: ConnectX7
# Part Number: <part-number>
# PSID: MT_0000000XXX
# Versions: Current Available
# FW 28.XX.YYYY 28.AA.BBBB
# Status: Update required
sudo mlxfwmanager -u -i fw-ConnectX7-<version>.bin # update from one image
sudo mlxfwmanager -u -D /path/to/fw-images/ -y # pick the right image per device from a directory
sudo mlxfwmanager --online -u # download matching firmware from NVIDIA (needs internet)
- Walks all devices on the host and matches each to an image by PSID.
- The vendor-provided self-extracting firmware packages for a platform often wrap
mlxfwmanager. - Air-gapped clusters: stage the images on the head node or an internal share and use
-D;--onlineneeds internet access. - After an update it tells you to reboot (or use
mlxfwreset) to load the new firmware.
mlxfwmanager options
| Option | Use |
|---|---|
--query [-d <dev>] | Inventory: type, part number, PSID, current vs available version, status. Several devices: -d "dev1;dev2" (quoted). |
--query-format XML, -o <file> | Machine-readable inventory written to a file, for fleet tooling |
-u with -i <img> or -D <dir> | Update from one image, or the matching image in a directory. Always name the source; otherwise it searches its default image location. |
-l / --list-content | List what's in an image directory or archive (types, PSIDs, versions) without touching devices |
-f / --force | Burn even when the device already has that version |
--skip_if_same | Skip devices already on the image's version |
-y / --no | Answer yes / no to prompts (-y for pdsh and scripts) |
--online, --online-query-psid <PSIDs> | Fetch matching firmware from NVIDIA's server / ask the server what's available for these PSIDs. Both need internet. |
--download <dir>, --download-default, --download-type MFA|self_extractor, --download-os, --download-device | Download images on an internet-connected host, then carry them into an air-gapped cluster |
--nofs, --no_fw_ctrl, --clear-semaphore | Same meaning (and caution) as the flint flags |
--log, -L <file>, --no-progress | Logging for change records; quiet output for scripts |
--component_type <name> | Pick the component to extract from a PLDM package |
--get-download-opt OS|Device, --key <key>, --ssl-certificate <file> | List what can be downloaded; a key for custom downloads; a CA certificate for the HTTPS connection |
--archive-names, --exe-rel-path | Show archive names in -l listings; resolve paths relative to the executable (portable bundles) |
<bundle> --sfx-extract-dir <dir> --sfx-extract only | Unpack a vendor self-extracting firmware package (mlxfwmanager-YYYYMMDD-N) without running it, then run its mlxfwmanager -u yourself |
- mlxfwmanager only scans PCI devices on the host. In-band switches (
lid-N) go through flint or UFM. - The query also lists PXE and UEFI expansion-ROM versions under FW; an update can change those too.
- With several adapters, recent versions query and update them in parallel through the
fwctlkernel driver (upstream Linux 6.15+, or from DOCA) when it's loaded.
8. flint vs mlxfwmanager
| flint | mlxfwmanager | |
|---|---|---|
| Scope | One device you name | All devices on the host |
| Image choice | You supply the exact image | Matches images to devices by PSID |
| Best for | Precise control, one card, switches in-band, verify/read image | Routine updates and inventory across many cards |
| Inventory | flint -d <dev> q per device | --query for everything, with "update required" status |
9. mlxconfig: NIC settings in non-volatile memory
mlxconfig changes settings stored on the adapter itself. They survive OS reinstalls and apply at the next firmware load.
sudo mlxconfig -d /dev/mst/mt4129_pciconf0 -e q # all settings: Default / Current / Next Boot
sudo mlxconfig -d /dev/mst/mt4129_pciconf0 q LINK_TYPE_P1 LINK_TYPE_P2
sudo mlxconfig -d /dev/mst/mt4129_pciconf0 set LINK_TYPE_P1=2 # 1 = InfiniBand, 2 = Ethernet (VPI cards)
sudo mlxconfig -d /dev/mst/mt4129_pciconf0 set SRIOV_EN=1 NUM_OF_VFS=8
sudo mlxconfig -d /dev/mst/mt4129_pciconf0 reset # restore defaults (careful)
| Setting | Purpose |
|---|---|
LINK_TYPE_P1 / _P2 | Port protocol on VPI adapters: InfiniBand or Ethernet |
SRIOV_EN, NUM_OF_VFS | Virtual functions for VMs / containers (see the virtualization guide) |
ATS_ENABLED | PCIe Address Translation Services, used in some GPUDirect and virtualization setups |
| BlueField mode parameters | DPU mode vs NIC mode (names differ between BlueField-2 and BlueField-3) |
| Advanced PCIe settings | Exposes extra PCIe tuning options on some cards |
- Changes land in the Next Boot column. They apply after
mlxfwreset, a reboot, or (for some settings) a full power cycle. - Every node of a type should have the same settings; include
mlxconfigqueries in your inventory.
mlxconfig set and immediately testing shows no change. The settings are pending until the device resets.mlxconfig commands and options
| Command / option | Use |
|---|---|
q [PARAM ...] | Query. Without -d it queries every device on the host. Name parameters to show only those. |
-e (--enable_verbosity) | Show the Default, Current, and Next Boot columns. Without it you only see Next Boot, which hides pending changes. |
set / s PARAM=VAL ... | Write to Next Boot. Values can be numbers or names (LINK_TYPE_P1=IB). |
reset / r | All parameters back to defaults (Next Boot). Wipes custom settings such as SR-IOV and port types. |
i / show_confs | List every parameter the device supports, with descriptions and allowed values |
-f <file> backup / -f <file> set_raw / get_raw | Save the whole configuration to a file and restore it later. Do this before a reset or an RMA swap. |
-j <file> (--json_format) | Write the query to a JSON file (inventory scripts) |
-y | Answer yes (required in pdsh and scripts) |
--with_default | For set: parameters you don't name go back to defaults. Nothing is written if the result equals the current config. |
--force | Skip firmware capability checks |
--host_id, --pf_index | Target per-host / per-PF parameters on multi-host adapters |
show_system_conf / set_system_conf <conf>[asic] / validate_system_conf | Predefined board profiles (port split, link type, planes, PFs). Newer MFT (4.36+), ConnectX-9 only; use an mst aggregate add device to set every ASIC at once, reboot, then validate. |
-b / --db <file>, -a / --all_attrs | Use a specific parameter database; show every attribute in an XML template |
token_supported, challenge_request -tkn <type>, remote_token_keep_alive, query_token_session, end_token_session | Challenge-based tokens: NVIDIA support issues a signed token (made with mlxtokengenerator) that temporarily unlocks restricted debug access on a secured card |
-p, -u, --openssl_engine, --aws_hsm, --sign_algorithm | Signing options for create_conf (signed configuration files) |
gen_tlvs_file, g (XML template), xml2raw, raw2xml, xml2bin, create_conf, apply | Build configuration files offline and apply them (often signed) at scale |
clear_semaphore | Clear the tool's semaphore after a crashed run |
Parameters you'll meet often: LINK_TYPE_P1/P2, SRIOV_EN, NUM_OF_VFS (the firmware caps it; 127 on current adapters), ATS_ENABLED, ADVANCED_PCI_SETTINGS, PCI_ATOMIC_MODE, INTERNAL_CPU_OFFLOAD_ENGINE (BlueField DPU vs NIC mode), EXP_ROM_*_ENABLE (PXE/UEFI boot ROMs). show_confs is the source of truth for a given card.
| More parameter families | What they control |
|---|---|
PHY_FEC_OVERRIDE_P1/P2, PHY_RATE_MASK_P1/P2 (+ _OVERRIDE), PHY_AUTO_NEG_P1/P2 | FEC mode, allowed speeds, and auto-negotiation per port, stored in non-volatile memory like every mlxconfig setting |
SRIOV_IB_ROUTING_MODE_P1, ROCE_NEXT_PROTOCOL, MULTI_PORT_VHCA_EN | How IB VFs are routed (GUID vs LID); the UDP protocol number used for RoCE; one virtual HCA spanning several ports |
PF_LOG_BAR_SIZE, PF_BAR2_ENABLE/_SIZE, NON_PREFETCHABLE_PF_BAR, STRICT_VF_MSIX_NUM | PCIe BAR sizes and MSI-X allocation (platform-specific tuning) |
BOOT_OPTION_ROM_EN_P1, LEGACY_BOOT_PROTOCOL_P1, BOOT_VLAN, BOOT_RETRY_CNT_P1, WOL_MAGIC_EN_P1/P2 | Network boot (PXE/UEFI) behavior and wake-on-LAN |
INTERNAL_CPU_MODEL, ECPF_ESWITCH_MANAGER, ECPF_PAGE_SUPPLIER | BlueField: whether the Arm side or the host owns the embedded switch and supplies memory pages (DPU-mode details) |
PCI_BUS*_HIERARCHY_TYPE/_WIDTH/_SPEED, PCI_SWITCH0_* | BlueField-3 PCIe bifurcation: the card as a PCIe switch for NVMe ("CPU is root complex") or as the root complex itself |
SPLIT_MODE, SPLIT_PORT, NO_SPLIT_SUPPORT | Port splitting on devices that support it |
10. mlxfwreset: activating without a reboot
mlxfwreset resets the adapter so it loads the newly burned firmware and pending mlxconfig settings, without rebooting the whole server.
sudo mlxfwreset -d /dev/mst/mt4129_pciconf0 query # supported reset levels/types and what each affects
sudo mlxfwreset -d /dev/mst/mt4129_pciconf0 reset # default (recommended) level
sudo mlxfwreset -d /dev/mst/mt4129_pciconf0 -l <level> -y reset # a specific level, no prompt
- Reset levels range from a live update that keeps the driver and links up, through a driver restart with PCI reset, to a warm reboot. Which ones work depends on the device, firmware, and server platform.
querytells you; don't memorize numbers. - The reset affects the whole device: both ports, every PCI function, every VF. RDMA traffic, storage mounts, and IPoIB on those ports are interrupted.
- On BlueField, some resets also affect the Arm side; follow the DPU documentation.
- If
mlxfwresetisn't supported on the platform, fall back to a reboot. Some changes need a cold reboot or power cycle; a warm reboot may keep the adapter powered and running old firmware on some servers.
flint -d <dev> q shows only one FW version (no separate "Running" line) at the new version, mlxfwmanager --query shows "Up to date", mlxconfig -e q shows Current = Next Boot, and the links are back up (ibstat / mlxlink).mlxfwreset on a node with running jobs. Drain first: the device disappears from the OS briefly, and anything using it fails.mlxfwreset options
mlxfwreset -d <dev> q # supported levels / types / sync, and the default
mlxfwreset -d <dev> status [--json] # what the pending change needs: level 3, warm reboot, or power cycle (beta)
mlxfwreset -d <dev> -y -l 3 --sync 2 --method 1 r # hot-reset the PCIe switch above the card (ConnectX-7 / BlueField)
mlxfwreset -d <dev> -y reset # default level
mlxfwreset -d <dev> -y -l 3 -t 0 --sync 1 reset # explicit level, type, sync
mlxfwreset -d <BlueField> -y -l 3 --sync 1 r # BlueField: driver-owned sync (the BF2/BF3 default)
| Option | Values |
|---|---|
-l / --level | 0 live-patch (driver, PCI link, network link stay up) · 1 immediate reset (only the Arm side goes down) · 3 driver restart + PCI reset (the usual default) · 4 warm reboot of the server |
-t / --type (levels 1, 3, 4) | 0 full chip · 1 PHY-less "port alive" (not supported) · 2 NIC only (SoC devices) · 3 Arm only · 4 Arm OS shutdown |
--sync (level 3, multi-host) | 0 the tool coordinates: run it on every host at once (3-minute join timeout) · 1 the driver coordinates: run on one host · 2 firmware coordinates (used for PCIe-switch hot reset) |
--method (level 3) | 0 link disable · 1 hot reset (SBR) |
-s / --skip_driver | Don't stop/start the driver (you stopped it yourself) |
-m / --mst_flags | Flags for the mst restart step, for example --mst_flags="--with_fpga" |
--ignore_list "drv1,drv2" / --ignore_file <file> | For the PCIe-switch hot reset (--sync 2 --method 1): every driver bound below the switch must be unbound first, or the tool exits and lists them with their PCI addresses. These options skip drivers you know survive a reset (for example pcieport). |
reset_fsm_register | Clear the multi-host sync register after an aborted reset |
-y | Don't prompt |
- A level that
queryreports as "Not Supported" fails with an error; pick one that's supported, or reboot. - If flint finishes a burn without printing
-I- To load new FW run mlxfwreset or reboot machine, a reboot is required. - If mlxfwreset fails between "Stopping driver" and "Starting driver", the driver stays down: start it by hand.
- Some mlxconfig changes print
-W- PCI rescan is required after device reset. - Switches: no level/type/sync options, and it doesn't work in-band or remotely (for unmanaged switches use
flint -d lid-N swreset). It also doesn't run on NVOS, SONiC, or Cumulus. - BlueField: level 3 with sync 1. On BlueField-2 and BlueField-3, sync 1 is the default and sync 0 isn't supported. Level 4 alone needs mlxfwreset on both the host and the Arm side; the Arm must be shut down first.
11. The NIC firmware lifecycle
- Query:
mlxfwmanager --query(orflint q): current version, PSID, part number. - Get the image for that PSID at the version your recipe specifies (DGX/OEM release notes; NIC firmware must match the DOCA/OFED driver's supported range).
- Drain the node.
- Burn with
mlxfwmanager -uorflint burn. - Activate with
mlxfwresetor a reboot/power cycle. - Verify: running version,
mlxconfigsettings, link state and speed, then a quick fabric test (ib_write_bw, nccl-tests) before returning the node to service.
12. Hands-on lab: six simulated tickets
A mock cluster you work like the real thing. Pick a ticket, start with cat notes.txt, and type help on any host for its commands. State carries through: burned firmware stays pending until activated, mlxconfig changes sit in Next Boot, resetting a busy node fails its job, rebooted switches drop out of the fabric for a moment, and a reinstalled switch comes back with a blank config.
- FW-1024: one node, ConnectX-7 and BlueField-3 firmware plus a port type fix (guided; start here).
- INC-2087: from the head node, use
pdshanddshbakto find three different stragglers in an 8-node fleet and fix them. - NET-3307: InfiniBand switches: in-band
flintfor unmanaged leaves, NVOS for the managed spine, one at a time, thenibdiagnet. - NET-4410: Ethernet switch OS: a Cumulus MLAG pair through ONIE (backup and restore) and a SONiC switch.
- DPU-5150: a BlueField-3 stuck in NIC mode, then a BFB bundle upgrade over RShim.
- CBL-6060: LinkX transceiver firmware with
flint --linkx: a leaf switch's modules in two halves (range burn), a port that doesn't come back by itself, and the host-side module with--linkx_auto_update.
grep, head, tail, wc, sort, uniq, and dshbak; > redirects; ; and &&; simple for loops.Answer key for this ticket (spoilers)
One clean path. Other orders work too; the checklist tracks results, not exact commands. Where a step says "answer y", type y at the prompt.
13. BlueField: BFB bundles, NIC firmware, modes
A BlueField DPU has two worlds: the NIC part (ConnectX firmware, like any adapter) and the Arm computer running its own OS (Ubuntu with DOCA) plus boot firmware (ATF/UEFI). BlueField-3 also has its own BMC.
| Piece | Updated with |
|---|---|
| Arm OS + DOCA software (and often boot firmware and NIC firmware too) | BFB (BlueField Bootstream) image, pushed from the host over RShim: bfb-install --bfb <image>.bfb --rshim rshim0 |
| NIC firmware alone | MFT (flint / mlxfwmanager) from the host or the Arm side |
| BlueField-3 BMC | Its own Redfish update path |
| DPU mode vs NIC mode | mlxconfig parameters, applied after a power cycle |
ls /dev/rshim* # RShim devices on the host (rshim service running)
sudo bfb-install --bfb <bf-bundle>.bfb --rshim rshim0
# then follow the release notes: usually a host power cycle so the new NIC firmware loads
sudo flint -d /dev/mst/mt41692_pciconf0 q # confirm the NIC firmware version afterwards
- A BFB bundle keeps the Arm OS, DOCA, and NIC firmware versions consistent with each other: the preferred way to move a DPU to a new release.
.bfbis a BlueField image, not a server firmware package (.fwpkgis for DGX/HGX).- Don't restart the host or the DPU while bfb-install runs. An interrupted install can leave the Arm side unreachable; rerun bfb-install to recover.
bfb-install options
| Option | Use |
|---|---|
-b / --bfb <file> | The BFB image |
-r / --rshim [ip[:port]:]rshimN | Local rshim0 on the host, or a remote RShim such as the DPU's BMC: 10.0.0.5:rshim0 (default port 9527) |
-c / --config bf.cfg | Customize the install (see below). Without it you must change the default ubuntu password at first login. |
-m / --remote-mode scp|nc|ncpipe, -R / --reverse-nc | How a remote push travels (default scp); reverse netcat helps through firewalls |
-u / --runtime | Runtime upgrade (BlueField-3, local RShim) |
-l / --lfwp, -a / --activate 0|1 | Live firmware patch, and whether to activate it |
-f / --rootfs, -k / --keep-log, -v | Yocto rootfs; keep the RShim log; verbose |
| bf.cfg key | Effect |
|---|---|
WITH_NIC_FW_UPDATE=no | Skip the bundled NIC firmware (default yes). Use it when the NIC reset that follows isn't supported on the platform. |
FORCE_NIC_FW_UPDATE, NIC_FW_RESET, FORCE_NIC_FW_RESET | Reflash even if the version matches; reset the NIC after flashing (default yes); fall back to a level-3 reset |
UPDATE_DPU_OS, UPDATE_ATF_UEFI | Install the Arm OS; update boot firmware (default yes) |
BMC_USER, BMC_PASSWORD, UPDATE_BMC_FW, UPDATE_CEC_FW, BMC_REBOOT=yes, CEC_REBOOT=yes | Update the DPU's BMC and CEC firmware from the bundle (needs the current BMC credentials; the reboot flags apply it) |
ubuntu_PASSWORD, grub_admin_PASSWORD | Hashed passwords set during the install |
bfb_pre_install, bfb_modify_os, bfb_post_install | Shell functions run at those install stages |
- Check the result on the Arm side with
bfverorcat /etc/mlnx-release, and the NIC withflint q.flint -d <dev> query_bfb_componentslists BFB component versions from the host. - More on DPU modes and the Arm side in the bring-up guide's BlueField objective.
14. InfiniBand switch firmware
| Switch type | Example | How firmware is updated |
|---|---|---|
| Managed (has its own CPU and switch OS) | Quantum-2 QM9700 running NVOS (older generations: MLNX-OS / Onyx) | Install a new switch OS image (it includes the ASIC firmware) through the switch CLI, web UI, or API; reboot the switch per the release notes |
| Unmanaged / externally managed | Quantum-2 QM9790 | In-band over the fabric: UFM firmware upgrade, or flint -d lid-<LID> -i <img> burn from a host with MFT |
ibswitches # list switches: GUID, LID, description
sudo mst ib add # make in-band switch devices visible to MFT
sudo flint -d lid-<LID> -qq q # switch firmware version and PSID (-qq: quick query)
Two versions to confirm: switch OS and ASIC firmware
A managed switch has a switch OS (NVOS, or MLNX-OS / Onyx on older systems) running on its management CPU, and firmware on the switch chip (the ASIC) that actually forwards packets. Objective 4.6 asks you to confirm both against the cluster's recipe. An unmanaged switch has no OS, only ASIC firmware.
| Switch | OS version | ASIC firmware version |
|---|---|---|
| NVOS (Quantum-2 QM9700 and newer) | nv show system image (build-id of the current partition); nv show system also shows the version | nv show platform firmware ASIC (actual-firmware); nv show platform firmware lists ASIC, BIOS, CPLD, SSD together |
| MLNX-OS / Onyx (older managed switches) | show version (Product release) | show asic-version (one line per module: Module, Device, Version), any CLI mode |
| Unmanaged (QM9790), from a host | None | flint -d lid-<LID> -qq q (FW Version); find the LID with ibswitches |
| Fleet view | UFM: Managed Elements → Devices lists the ASIC firmware of every switch; Network Map shows each managed switch's OS version | |
# NVOS
admin@ib-leaf01:~$ nv show platform firmware ASIC
operational applied
--------------- ------------------- -------
part-number MQM9700-NS2X-NS_Ax
actual-firmware 31.2014.1000
auto-update enabled enabled
fw-source default default
# MLNX-OS / Onyx
switch (config) # show asic-version
===================================================
Module Device Version
===================================================
MGMT QTM 31.2014.1000
switch (config) # show asic-version | include QTM # filter like grep
show asic-version should show the same, default version; otherwise it warns "Some subsystems are not updated with a default firmware". NVOS can also load a different ASIC firmware without changing the OS (fw-source custom), which is why the two can drift.- Upgrade one switch at a time (or one per redundancy group) and let the fabric reconverge. A rail-optimized fabric has redundancy at the spine layer, but a leaf reboot takes down that rail for its nodes.
- Keep every switch of the same role on the same version; version mismatches cause odd adaptive-routing or SHARP behavior.
- The Subnet Manager (UFM / OpenSM) version is part of the recipe too.
15. Ethernet switch OS upgrades
Spectrum Ethernet switches run a network OS that includes the ASIC firmware. You upgrade the whole OS image, not the firmware separately.
| Switch OS | Check version | Upgrade path (examples) |
|---|---|---|
| Cumulus Linux | nv show system | Install a new image (for example through ONIE: onie-install -a -i <image>, then sudo reboot), or the release's supported upgrade method |
| SONiC | show version | sonic-installer install <image>, then reboot |
- Back up the configuration first (Cumulus: NVUE config; SONiC:
config_db.json). - Upgrade redundant pairs one at a time; check BGP/MLAG, RoCE QoS, and link state after each (see the RoCE guide's switch section).
- For Spectrum-X, switch OS, SuperNIC firmware, and DOCA versions are released together; upgrade them as a set.
16. LinkX cable and transceiver firmware (flint --linkx)
Optical transceivers and active optical cables (AOCs) run their own firmware, separate from both NIC and switch firmware. NVIDIA calls the in-field update IFFU: flint sends the image to the NIC or switch, and that device passes it to the modules plugged into it.
- Through a switch (
-d lid-N, in-band, works on unmanaged switches) or a host NIC (-d /dev/mst/..., over the PCI register interface). Managed switches can also run it from the switch itself. - Each device only updates the modules plugged into it. A link has two ends: the far end (the other switch, or the host NIC) needs its own run.
--downstream_device_idsand the range options use port numbers (from 1). Passive copper (DAC) has no firmware and shows as not present.- Two stages: transfer (download the image into the module's inactive bank) and activate (switch banks; the link flaps). Neither happens unless you ask for it.
- You can't burn the version a module already has. That fails with
Cable burn failed, error is LinkX downstream transfer failed for device index N, which saves time in large clusters. - Plan about 1.5 minutes per module for the transfer, plus about 30 seconds to activate.
# 1. Query: firmware banks, running image, versions (ports 1, 2, 5)
sudo flint -d lid-1 --linkx --downstream_device_ids 1,2,5 q # comma-separated, NO spaces
sudo flint -i <cable-image>.bin q # version and part number in the image file
# 2a. Range: half the ports first (here ports 1-4), transfer then activate
sudo flint -d lid-1 --linkx --downstream_device_id_start_index 1 --num_of_downstream_devices 4 --download_transfer -i <img> b
sudo flint -d lid-1 --linkx --downstream_device_id_start_index 1 --num_of_downstream_devices 4 --activate b
for p in 1 2 3 4; do sudo mlxlink -d lid-1 -p $p -m | grep -E "State|Part|FW"; done # links back up?
# 2b. Auto-update: every supported module on the device in one go
sudo flint -d <dev> --linkx --linkx_auto_update --download_transfer -i <img> b
sudo flint -d <dev> --linkx --linkx_auto_update --activate b
sudo flint -d <dev> --linkx --linkx_auto_update --download_transfer --activate -i <img> b # both in one command
sudo flint -d <dev> --linkx --linkx_auto_update --activate --activate_delay_sec 10 b # delayed activation
| Flag | Meaning |
|---|---|
--linkx | Act on the cable/transceiver attached to the device, not the device. Required for every command here. |
--downstream_device_ids 1,2,5 | Ports to query (comma-separated, no spaces) |
--linkx_auto_update | Burn (and/or activate) all supported cables/transceivers connected to the device |
--downstream_device_id_start_index N + --num_of_downstream_devices M | A range: M ports starting at port N (start 10, count 6 = ports 10-15), burned one after another |
--download_transfer | Download and transfer the image into the modules (not done by default). Needs -i. |
--activate | Activate the transferred firmware (not done by default) |
--activate_delay_sec 0-255 | Wait before activating (needs --activate). The default is 1 second so the port carrying your own session isn't cut mid-command; 0 is the legacy immediate behavior. |
--linkx_els | Burn an ELS (external high-power laser) component instead |
--output_file <file> | Save the query output |
-d <cable dev> + --activate, --module_password, --module_vendor_data | CMIS modules that support the CDB update procedure, burned directly as a cable device (after mst cable add). --activate without -i just runs and commits the burned image. |
--run_module_image / --commit_module_image | Switch the module's running bank / its committed (boot) bank |
mlxlink and mlxcables for modules
sudo mlxlink -d mlx5_0 -m # host NIC port: state, module part number, FW version
sudo mlxlink -d lid-1 -p 7 -m # switch port 7, in-band
sudo mlxlink -d lid-1 -p 7 -a TG # toggle the port (DN / UP / TG)
for i in $(seq 1 40); do echo $i; sudo mlxlink -d lid-1 -p $i -m | grep -E "State|Part|FW"; done
sudo mlxlink -d mlx5_0 --cable --ddm # DDM: temperature, voltage, Rx/Tx power, bias
sudo mlxlink -d mlx5_0 --cable --dump # raw EEPROM pages
sudo mst cable add; sudo mlxcables -q # cable devices; query them all
sudo mlxcables -d <cable dev> --DDM # DDM through mlxcables
sudo mlxcables -d <cable dev> -r -p 0 -o 165 -l 3 # read bytes (page 0, offset 165, length 3)
| mlxlink option | Use |
|---|---|
-d, -p <port>, --port_type NETWORK|PCIE | Device, port (needed on switches), and which link (PCIe links too) |
-m / -c / -e / --show_fec | Module info / counters and BER / eye opening / FEC capabilities |
--show_serdes_tx, --show_device, --show_ber_monitor, --show_external_phy, --show_links, --show_tx_group_map | Transmitter settings per lane, device info, BER-monitor state, external PHY (retimer/gearbox), every link on the device, and switch TX port groups |
--depth, --pcie_index, --node (with --port_type PCIE) | Pick a PCIe link: depth in the PCIe tree, PCIe index, node. Use them to find a link running below its expected width or speed. |
--pc | Clear the counters, then retest |
-a UP|DN|TG | Port state: up, down, toggle. Never take down the port that connects the host to an unmanaged switch: you lose in-band access to it. |
-s <speeds> (for example 400G_4X,200G_2X), --link_mode_force | Speeds to advertise (lane count after the underscore); force the speed with auto-negotiation off. Both ends must agree, or the link won't come up. |
-k AU|NF|FC|RS|LL|DF-RS|DF-LL, --fec_speed <speed> | FEC: auto, no FEC, Firecode, Reed-Solomon, low-latency RS, and the interleaved RS variants; optionally only for one speed (default: the active speed) |
-l NO|RM|PH|EX|LL | Loopback: none, remote PHY (Rx to Tx), internal PHY (Tx to Rx), external (needs a loopback plug), link layer. Lab/debug only; on ConnectX-7 and later the link must be fully down first. |
--test_mode EN|DS|TU + --rx_prbs/--tx_prbs <pattern>, --rx_rate/--tx_rate, --invert_rx/--invert_tx, --lanes | PRBS test: enable, disable, or tune; the pattern and rate (both ends must match); invert polarity; pick lanes. The link is down while PRBS runs. |
-b / --ber_collect <csv>, --amber_collect <csv>, --ber_limit Nominal|Corner|Drift, --iteration <n> | Write BER data / the full "amBER" link and module report to a CSV (what NVIDIA support asks for), with a pass/fail limit and repeat count |
--margin, --eye_select, --measure_time, --lane | Eye-margin scan on a lane: a quality check that goes deeper than -e |
--rx_fec_histogram --show_histogram | --clear_histogram | FEC histogram: how many symbol errors each corrected codeword had. Errors in the high bins mean the link is near its FEC limit. |
--serdes_tx <params> --serdes_tx_lane <n> [--database], --tx_params_override | Change transmitter (SerDes) tuning per lane, optionally saving it. Advanced, support-guided. |
--cable --ddm | --dump | --read | --write, --prbs_mode --prbs_select MEDIA|HOST | Module DDM, raw pages, byte read/write; PRBS run inside the module on its media or host side. --cable has no short form (-m is --show_module). These operations are rejected without --cable, only one is allowed per command, and --read/--write need --page and --offset (--length is for reads, default 1 byte). Details: transceiver guide. |
--control_parameters with --tx_equalization, --rx_emphasis, --rx_post_emphasis, --rx_amplitude | Module signal-integrity settings (advanced, support-guided) |
--rx_error_injection, --pcie_error_injection | Inject errors deliberately to test monitoring and recovery. Never on production links. |
--json | JSON output for scripts |
mlxcables only reads and writes module memory, and gets no new features; mlxlink --cable is the way forward. Its options: -q (query all cables), --DDM, --dump, -r/-w with -p <page> -o <offset> -l <len> (or -a <address>), -b <bytes per line>, --print_raw, and --read_reg/--read_all_regs/--show_all_regs to decode named fields. Page and offset follow SFF-8636 for QSFP and SFF-8472 for SFP (the A0/A2 addresses).
17. Fleet inventory and drift
A cluster stays healthy when every node of a type runs the same versions. Inventory regularly and after every maintenance window.
# Parallel query across nodes (pdsh, or BCM's parallel execution from the head node)
pdsh -w node[001-064] 'mlxfwmanager --query | grep -E "Device Type|PSID|FW "' | dshbak -c
pdsh -w node[001-064] 'flint -d /dev/mst/mt4129_pciconf0 q | grep -E "FW Version|PSID"' | dshbak -c
# Switches
ibswitches; for l in <LIDs>; do flint -d lid-$l q | grep -E "FW Version|PSID"; done
dshbak -cgroups nodes with identical output: one group means no drift; several groups show the outliers.- Record a per-node inventory (NIC firmware, mlxconfig settings, switch versions, module firmware) next to the server-side inventory from the BMC.
- In BCM, install MFT in the software image so every node has the same tool version, and keep firmware images on the head node for air-gapped updates.
18. Interactive drift checker
Paste lines of node device version psid (any whitespace). The checker finds the most common version per device type and PSID, and flags outliers. Example data uses placeholder names.
19. Failures and recovery
| Symptom | Likely cause | Next step |
|---|---|---|
mst status lists no devices | mst start not run; MFT missing for this kernel | Run mst start; reinstall MFT matching the kernel |
| Burn refused: PSID mismatch | Image for a different board variant (or OEM card) | Get the image for the card's PSID; don't force it |
| Burn refused on a secure-fw device | Unsigned/modified/wrong image; blocked downgrade | Use an official image for that device and a supported version |
| Version unchanged after burn | Not activated | mlxfwreset or reboot/power cycle |
mlxconfig change has no effect | Still pending (Next Boot) | Reset/reboot; some settings need a power cycle |
mlxfwreset not supported | Platform or device limitation | Drain and reboot (cold if needed) |
| Link down after an update | Driver too old for new firmware, port type changed, module issue | Check DOCA/OFED vs firmware compatibility, mlxconfig LINK_TYPE, mlxlink |
| Device missing after an interrupted burn | Incomplete image | Many adapters keep a recovery path (failsafe image or recovery mode); retry with the correct image; contact support |
| Some nodes slower after rollout | Partial rollout / drift | Fleet inventory; bring stragglers to the recipe |
20. Sample outputs
What the commands in this guide print. Expand a command to see a typical result and what to check in it.
sudo mst startLoad MST modules, create /dev/mst devices
Starting MST (Mellanox Software Tools) driver set
Loading MST PCI module - Success
Loading MST PCI configuration module - Success
Create devices
Unloading MST PCI module (unused) - SuccessWhat to look at: Each line should end in Success, after which /dev/mst/ is populated. If later commands say Cannot open /dev/mst/..., MST was never started on this host (PCI addresses like 18:00.0 still work without it).
sudo mst status -vMap MST devices to PCI, RDMA, netdev
MST modules:
------------
MST PCI module is not loaded
MST PCI configuration module loaded
PCI devices:
------------
DEVICE_TYPE MST PCI RDMA NET NUMA
ConnectX7(rev:0) /dev/mst/mt4129_pciconf0 18:00.0 mlx5_0 net-ibp24s0 0
ConnectX7(rev:0) /dev/mst/mt4129_pciconf1 40:00.0 mlx5_3 net-ibp64s0 0
ConnectX7(rev:0) /dev/mst/mt4129_pciconf2 4f:00.0 mlx5_4 net-ibp79s0 0
ConnectX7(rev:0) /dev/mst/mt4129_pciconf3 5e:00.0 mlx5_5 net-ibp94s0 0
...
BlueField3(rev:1) /dev/mst/mt41692_pciconf0 29:00.0 mlx5_1 net-enp41s0f0np0 0
BlueField3(rev:1) /dev/mst/mt41692_pciconf0.1 29:00.1 mlx5_2 net-enp41s0f1np1 0
BlueField3(rev:1) /dev/mst/mt41692_pciconf1 aa:00.0 mlx5_7 net-enp170s0f0np0 1
...What to look at: Use this table to translate between names: mt4129 is ConnectX-7, mt41692 is BlueField-3, and each row gives the PCI address, mlx5_N RDMA name, and net-ib* interface. A DGX H100 compute port missing from the list usually means a card or driver problem, not an MFT problem.
sudo mst ib addAdd in-band InfiniBand switch devices
-I- Discovering the fabric - Running: /usr/sbin/ibnetdiscover -s
-I- Added 3 in-band devicesWhat to look at: After this, mst status lists lid-N devices and flint -d lid-N works. A warning that no active InfiniBand port was found means the local port is down or set to Ethernet, so in-band access is impossible from this host.
sudo flint -d /dev/mst/mt4129_pciconf0 qDevice firmware, PSID, pending image
Image type: FS4
FW Version: 28.43.1014
FW Version(Running): 28.39.2048
FW Release Date: 4.9.2024
Product Version: 28.43.1014
Rom Info: type=UEFI version=14.36.16 cpu=AMD64,AARCH64
type=PXE version=3.7.500 cpu=AMD64
Description: UID GuidsNumber
Base GUID: 000000000a010001 8
Base MAC: 00000a010001 8
Image VSD: N/A
Device VSD: N/A
PSID: MT_0000000A01
Security Attributes: secure-fwWhat to look at: FW Version is what is on flash; FW Version(Running) appears only when it differs, meaning a burned image is waiting for mlxfwreset or a reboot. Note the PSID: an image built for a different PSID is the wrong image for this card.
sudo flint -i fw-ConnectX7-28.43.1014-MT_0000000A01.bin qInspect an image file before burning
Image type: FS4
FW Version: 28.43.1014
FW Release Date: 4.9.2024
Product Version: 28.43.1014
Rom Info: type=UEFI version=14.36.16 cpu=AMD64,AARCH64
type=PXE version=3.7.500 cpu=AMD64
Description: UID GuidsNumber
Base GUID: N/A 8
Base MAC: N/A 8
Image VSD: N/A
Device VSD: N/A
PSID: MT_0000000A01
Security Attributes: secure-fwWhat to look at: Compare this PSID and version with the device query before you burn. A PSID that differs from the card (for example an OEM_ PSID) or Security Attributes N/A on a secure-fw card means stop: wrong or unsigned image.
sudo flint -d /dev/mst/mt4129_pciconf0 -i fw-ConnectX7-28.43.1014-MT_0000000A01.bin burnBurn firmware to flash
Current FW version on flash: 28.39.2048
New FW version: 28.43.1014
FSMST_INITIALIZE - OK
Writing Boot image component - OK
-I- To load new FW run mlxfwreset or reboot machine.What to look at: OK on every step plus the -I- line means the image is on flash but not running yet. A PSID mismatch error, or a signature failure on a secure-fw card, means the image was refused and nothing was written.
sudo flint -d /dev/mst/mt4129_pciconf0 verifyCheck flash image integrity
FS4 failsafe image
/0x00000000-0x0000001f (0x000020)/ (HW_POINTERS) - OK
/0x00010000-0x0001ffff (0x010000)/ (BOOT2) - OK
/0x00500000-0x00dfffff (0x900000)/ (ITOC) - OK
...
-I- FW image verification succeeded. Image is bootable.What to look at: Every section must say OK and the last line must read Image is bootable. Any FAILED section means a corrupt flash image; reburn a known-good image before resetting the device.
sudo flint -d lid-1 qIn-band query of an IB switch
Image type: FS5
FW Version: 31.2012.1000
FW Release Date: 14.2.2024
Description: UID GuidsNumber
Base GUID: 000000000000f001 1
Base MAC: N/A 1
PSID: MT_0000000S01
Security Attributes: secure-fwWhat to look at: This reads the Quantum-2 switch at LID 1 through the fabric (after mst ib add). Compare FW Version and PSID across all switches; for managed NVOS switches the ASIC firmware comes with the switch OS image rather than a flint burn.
sudo mlxfwmanager --queryCurrent vs available firmware, all devices
Querying Mellanox devices firmware ...
Device #1:
----------
Device Type: ConnectX7
Part Number: MCX75310AAS-NEAT_Ax
Description: NVIDIA ConnectX-7 HHHL Adapter Card; 400GbE / NDR IB (default mode); Single-port OSFP; PCIe 5.0 x16
PSID: MT_0000000A01
PCI Device Name: /dev/mst/mt4129_pciconf0
Base GUID: 000000000a010001
Versions: Current Available
FW 28.39.2048 28.43.1014
PXE 3.7.0500 3.7.0500
UEFI 14.36.0016 14.36.0016
Status: Update required
Device #2:
----------
Device Type: ConnectX7
Part Number: MCX75310AAS-NEAT_Ax
Description: NVIDIA ConnectX-7 HHHL Adapter Card; 400GbE / NDR IB (default mode); Single-port OSFP; PCIe 5.0 x16
PSID: MT_0000000A01
PCI Device Name: /dev/mst/mt4129_pciconf1
Base GUID: 000000000a010009
Versions: Current Available
FW 28.43.1014 28.43.1014
PXE 3.7.0500 3.7.0500
UEFI 14.36.0016 14.36.0016
Status: Up to date
...What to look at: Status: Update required means the image found for this PSID is newer than what is on flash; Up to date is the goal. No matching image found means no image for this PSID was available, which is typical for OEM-branded cards.
sudo mlxfwmanager -u -D /path/to/fw-images/ -yUpdate every device from an image directory
Querying Mellanox devices firmware ...
Device #1:
----------
Device Type: ConnectX7
Part Number: MCX75310AAS-NEAT_Ax
PSID: MT_0000000A01
PCI Device Name: /dev/mst/mt4129_pciconf0
Versions: Current Available
FW 28.39.2048 28.43.1014
Status: Update required
...
---------
Found 3 device(s) requiring firmware update...
Device #1: Updating FW ...
FSMST_INITIALIZE - OK
Writing Boot image component - OK
Done
Device #2: Updating FW ...
...
Done
Restart needed for updates to take effect.What to look at: Every device should end in Done, followed by Restart needed. That last line is the exam point: the new firmware is staged on flash and only runs after mlxfwreset or a reboot.
sudo mlxconfig -d /dev/mst/mt4129_pciconf0 -e qAll NV settings: Default/Current/Next Boot
Device #1:
----------
Device type: ConnectX7
Name: MCX75310AAS-NEAT_Ax
Description: NVIDIA ConnectX-7 HHHL Adapter Card; 400GbE / NDR IB (default mode); Single-port OSFP; PCIe 5.0 x16
Device: /dev/mst/mt4129_pciconf0
Configurations: Default Current Next Boot
MEMIC_BAR_SIZE 0 0 0
MEMIC_SIZE_LIMIT _256KB(1) _256KB(1) _256KB(1)
...
NUM_OF_VFS 0 0 0
SRIOV_EN False(0) False(0) False(0)
LINK_TYPE_P1 IB(1) IB(1) IB(1)
...
ADVANCED_PCI_SETTINGS False(0) False(0) False(0)
ATS_ENABLED False(0) False(0) False(0)
...
The '*' shows parameters with next value different from default/current value.What to look at: Read the three columns: Current is active now, Next Boot is what applies after a reset. A line starting with * has a pending change; LINK_TYPE_P1 ETH(2) on a DGX compute port would explain an IB port that came up as Ethernet.
sudo mlxconfig -d /dev/mst/mt4129_pciconf0 q LINK_TYPE_P1 LINK_TYPE_P2Query port protocol settings
Device #1:
----------
Device type: ConnectX7
Name: MCX75310AAS-NEAT_Ax
Description: NVIDIA ConnectX-7 HHHL Adapter Card; 400GbE / NDR IB (default mode); Single-port OSFP; PCIe 5.0 x16
Device: /dev/mst/mt4129_pciconf0
Configurations: Next Boot
LINK_TYPE_P1 IB(1)
-E- The Device doesn't support LINK_TYPE_P2 parameterWhat to look at: IB(1) means InfiniBand and ETH(2) means Ethernet. The error for LINK_TYPE_P2 is expected on a single-port card; on a dual-port VPI card you would see a value for both ports.
sudo mlxconfig -d /dev/mst/mt4129_pciconf0 set SRIOV_EN=1 NUM_OF_VFS=8Change NV settings for next boot
Device #1:
----------
Device type: ConnectX7
Name: MCX75310AAS-NEAT_Ax
Description: NVIDIA ConnectX-7 HHHL Adapter Card; 400GbE / NDR IB (default mode); Single-port OSFP; PCIe 5.0 x16
Device: /dev/mst/mt4129_pciconf0
Configurations: Next Boot New
SRIOV_EN False(0) True(1)
NUM_OF_VFS 0 8
Apply new Configuration? (y/n) [n] : y
Applying... Done!
-I- Please reboot machine to load new configurations.What to look at: The New column is what will be written. Nothing changes until a reset or reboot, so a later -e q showing Current False(0) and Next Boot True(1) is normal, not a failure.
sudo mlxfwreset -d /dev/mst/mt4129_pciconf0 querySupported reset levels and types
Reset-levels:
0: Driver, PCI link, network link will remain up ("live-Patch") -Not Supported
1: Only ARM side will not remain up ("Immediate reset") -Not Supported
3: Driver restart and PCI reset -Supported (default)
4: Warm Reboot -Supported
Reset-type (relevant only for reset-levels 1,3,4):
0: Full chip reset -Supported (default)
1: Phy-less reset (keep network port active during reset) -Not Supported
2: NIC only reset (for SoC devices) -Not Supported
3: ARM only reset -Not Supported
4: ARM OS shut down -Not Supported
Reset-sync (relevant only for reset-level 3):
0: Tool is the owner -Supported
1: Driver is the owner -Supported (default)
2: FW is the owner -Not SupportedWhat to look at: Level 3 (driver restart and PCI reset) is the usual default and is enough to load new firmware without a reboot. If level 3 is Not Supported, plan a warm reboot (level 4) or a full power cycle instead.
sudo mlxfwreset -d /dev/mst/mt4129_pciconf0 resetActivate new firmware without a reboot
The reset level for device, /dev/mst/mt4129_pciconf0 is:
3: Driver restart and PCI reset
Continue with reset?[y/N] y
-I- Sending Reset Command To Fw -Done
-I- Stopping Driver -Done
-I- Resetting PCI -Done
-I- Starting Driver -Done
-I- Restarting MST -Done
-I- FW was loaded successfully.What to look at: FW was loaded successfully is the pass; a new flint q should no longer show FW Version(Running). Because the driver restarts, links on this port drop, so drain the node in Slurm first.
sudo bfb-install --bfb bf-bundle-2.9.0-lab_ubuntu-22.04_prod.bfb --rshim rshim0Install a BFB bundle on BlueField-3
Pushing bfb
1.42GiB 0:02:04 [11.7MiB/s] [================================>] 100%
Collecting BlueField booting status. Press Ctrl+C to stop...
INFO[PSC]: PSC BL1 START
INFO[BL2]: start
INFO[BL2]: boot mode (rshim)
INFO[BL31]: start
INFO[UEFI]: UEFI loaded
INFO[MISC]: Ubuntu installation started
INFO[MISC]: Installation finished
INFO[MISC]: Updating NIC firmware...
INFO[MISC]: NIC firmware update done
INFO[MISC]: Linux up
INFO[MISC]: DPU is readyWhat to look at: Wait for NIC firmware update done and DPU is ready. An ERR line (for example a failed NIC firmware update) means the bundle did not finish; per the release notes the host usually needs a power cycle before flint shows the new NIC firmware.
ibswitchesList switches: GUID, LID, description
Switch : 0x000000000000f001 ports 129 "MF0;ib-leaf01:MQM9790/U1" enhanced port 0 lid 1 lmc 0
Switch : 0x000000000000f002 ports 129 "MF0;ib-leaf02:MQM9790/U1" enhanced port 0 lid 2 lmc 0
Switch : 0x000000000000f003 ports 129 "MF0;ib-spine01:MQM9700/U1" enhanced port 0 lid 3 lmc 0What to look at: Each line gives the switch GUID, its description, and the LID you pass to flint -d lid-N. A switch missing from this list after an upgrade has not rejoined the fabric yet, so do not take the next one down.
sudo mlxlink -d mlx5_0 -mPort state and module info
Operational Info
----------------
State : Active
Physical state : LinkUp
Speed : IB-NDR
Width : 4x
FEC : Standard_RS-FEC - (544,514)
Loopback Mode : No Loopback
Auto Negotiation : ON
Supported Info
--------------
Enabled Link Speed : 0x00000080 (NDR)
Supported Cable Speed : 0x000000c0 (HDR,NDR)
Troubleshooting Info
--------------------
Status Opcode : 0
Group Opcode : N/A
Recommendation : No issue was observed
Tool Information
----------------
Firmware Version : 28.43.1014
amBER Version : 3.4
MFT Version : mft 4.30.0-139
Module Info
-----------
Identifier : OSFP
Cable Technology : 1310 nm DFB
Cable Type : Optical Module (separated)
Vendor Name : NVIDIA
Vendor Part Number : MMA4Z00-NS400
Vendor Serial Number : MT2400FT00001
FW Version : 47.120.0020
...What to look at: Healthy is State Active, Physical state LinkUp, the expected speed (IB-NDR) and width 4x, with Recommendation No issue was observed. Polling, a lower speed or width, or a non-zero Status Opcode with a recommendation means a cable, module, or peer-port problem.
sudo mlxlink -d mlx5_0 --cable --ddmTransceiver DDM: temperature, power, bias
Module Info
-----------
Temperature [C] : 52
Voltage [mV] : 3291.3
Bias Current [mA] : 7.012,7.051,7.003,6.998
Rx Power Current [dBm] : 1.21,0.98,1.05,1.12
Tx Power Current [dBm] : 1.53,1.48,1.60,1.51
...What to look at: Compare per-lane values with each other and with the module's alarm thresholds. One lane with Rx power several dB lower than the others, or a very high module temperature, points to a dirty or failing optic.
pdsh -w node[001-064] 'flint -d /dev/mst/mt4129_pciconf0 q | grep -E "FW Version|PSID"' | dshbak -cFleet firmware drift check
----------------
node[001-002,004-064]
----------------
FW Version: 28.43.1014
PSID: MT_0000000A01
----------------
node003
----------------
FW Version: 28.43.1014
FW Version(Running): 28.39.2048
PSID: MT_0000000A01What to look at: dshbak -c folds identical output, so a healthy fleet collapses into one group. Any node in its own group is drift: here node003 has the new image on flash but still runs the old one and needs mlxfwreset or a reboot.
21. Scenarios
22. Searchable reference
| Item | Meaning |
|---|
23. Flashcards (click to flip)
24. Exam traps
- Burned ≠ running. NIC firmware loads after
mlxfwresetor a reboot/power cycle. - PSID mismatch → get the matching image; don't use
--allow_psid_changeon your own. - OEM cards get firmware from the server vendor.
- flint = one device, exact image; mlxfwmanager = all devices, PSID-matched.
- mlxconfig changes are pending until the next firmware load.
mlxfwresetresets the whole device (both ports, all VFs); drain first; usequeryto see supported levels.- nvfwupd is for server/HGX firmware through the BMC; MFT is for NVIDIA networking devices.
- BFB via RShim updates BlueField's Arm software (often with NIC firmware in the bundle).
- IB switches: managed → switch OS image; unmanaged → UFM or in-band
flint -d lid-. - Ethernet switches: upgrade the whole OS image (Cumulus, SONiC).
- Module firmware is separate from NIC and switch firmware. It's updated with
flint --linkx:--download_transferthen--activate, through the switch or NIC the module is plugged into, and each end of a link separately. --linkx_auto_update= every supported module on the device. On an unmanaged switch, use a range (--downstream_device_id_start_index+--num_of_downstream_devices) and do half at a time.- Re-burning the version a module already has fails ("LinkX downstream transfer failed"): that's the guard, not a broken module.
mlxconfigwithout-eshows only Next Boot; use-eto see Current.mlxfwreseton a multi-host card with--sync 0must run on every host.-nofs,-use_image_guids,bb,-clear_semaphore, and--allow_psid_changeare recovery or production flags, not routine ones.- One recipe for the cluster; inventory and compare across nodes.