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.

DomainMain toolsGuide
Server (BIOS, BMC, CPLD, PSU)BMC Redfish, vendor tools, nvfwupd on DGXHGX firmware, Redfish
HGX baseboard (GPUs, NVSwitches, HMC, ERoT)nvfwupd / Redfish through the BMCHGX firmware
ConnectX NICs, BlueField NIC firmwareMFT: flint, mlxfwmanager, mlxfwresetThis guide
BlueField Arm softwareBFB images via RShim (bfb-install)This guide, section 13
InfiniBand switchesSwitch OS image, UFM, or in-band flintThis guide, section 14
Ethernet switchesSwitch OS image (Cumulus Linux, SONiC)This guide, section 15
Transceivers / active cablesmlxlink / mlxcables / flint (LinkX), switch CLITransceivers
Drivers (GPU, Fabric Manager, DOCA/OFED)Software image (BCM)Bring-up
Firmware management is like servicing a fleet of trucks. Engines, gearboxes, and tires each have their own manuals and tools, but the fleet manager keeps one sheet saying which version of each part every truck should have, and checks every truck against it.
The exam's angle: pick the right tool for the component, know that a burn is not active until a reset or reboot, respect the PSID, keep the cluster on one tested recipe, and verify afterwards.

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.

ToolPurposeTypical command
mstStart the access drivers and list devicesmst start, mst status -v
flintQuery, burn, verify one device's firmware imageflint -d <dev> q
mlxfwmanagerQuery all devices; update from a firmware package/directory, matching PSIDs automaticallymlxfwmanager --query
mlxconfigRead/write non-volatile device settings (port type, SR-IOV, DPU/NIC mode…)mlxconfig -d <dev> q
mlxfwresetReset the device so new firmware/settings load without a full rebootmlxfwreset -d <dev> query
mlxlinkLink status, speed, errors, eye, module infomlxlink -d <dev> -m
mlxcablesAccess cable/module EEPROM and informationmlxcables
mlxdump / mstdumpDiagnostic dumps for supportWhen support asks

Less common tools in the same package that still show up in procedures:

ToolPurpose
mlxburnOlder 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.
mlxarchivePacks 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.
mlxprivhostBlueField 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, mlxregRead 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:

ToolUse
mstdump <dev> [-full] [--ignore_fail] > dump.dmpDump 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|STEDump 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], mlxtraceRead 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>], --setRead or write named access registers. --set and raw --reg_id access can break a working device: only on instruction.
mlxtokengenerator, mlxcableimgen, cpldupdate, mlxfwstressGenerate debug tokens; build cable images; burn a switch CPLD; firmware stress tests (support, OEM, or production use)
Without MFT, the inbox Linux driver can burn an .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.
An open-source subset, mstflint, ships in many Linux distributions with similarly named tools (mstflint, mstconfig, mstfwreset, mstlink). They use PCI addresses instead of /dev/mst devices. DOCA / MLNX_OFED installs usually include MFT or recommend it.
"My Firmware Can Reload Later": mst (find), flint / mlxfwmanager (burn), mlxconfig (configure), mlxfwreset (reload), mlxlink (check the link).

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 IDDeviceFirmware major version
mt4123ConnectX-620.x
mt4125ConnectX-6 Dx22.x
mt4129ConnectX-728.x
mt41686BlueField-224.x
mt41692BlueField-332.x

mst subcommands and options

CommandWhat it doesNotes
mst startLoad 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/stopUseful after a hot-plug or a PCI rescan
mst save / mst loadSave / restore PCI configuration headers in /var/mst_pcimst 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 restartstop + startmlxfwreset does this for you as its last step
mst status / -v / -vvList devices; -v adds PCI, RDMA (mlx5_X), netdev, NUMARun it after every mst start to map names
mst ib add [hca] [port]Add in-band devices (lid-N) discovered on the IB fabricNeeds 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 versionGPU devices through the NVIDIA driver, I2C devices, tool version
mst aggregate addOne 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.

A PSID is like a car's VIN-specific parts list. A brake pad for the same model but a different trim might physically fit, but the dealer won't stand behind it, and sometimes it simply doesn't work.
"The firmware won't burn because of a PSID mismatch, so use --allow_psid_change" is the classic wrong answer. The right answer is to get the image that matches the card's PSID (from NVIDIA or the OEM).

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.

flint subcommands

CommandWhat it does
q / q fullQuery the device or image. full adds more fields (all GUIDs/MACs, image info).
b / burnBurn the -i image, failsafe by default (the new image goes to the alternate location, so the old one survives an interrupted burn)
v / verifyCheck 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)
swresetReset an unmanaged switch to load its new firmware (in-band lid-N only)
checksum / csMD5 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|resetFirmware 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_cfgReset the non-volatile configuration to defaults (the same effect as mlxconfig reset)
brom, drom, rrom, qromBurn, remove, read, or query the expansion ROM (PXE/UEFI boot code) inside the image
sg, sv, smg, set_vpdSet GUIDs/MACs, VSD, manufacture GUIDs, VPD. Production or support use; non-failsafe on current devices.
set_key / hw_access enable|disableHardware 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_reactivationRe-activate the previous flash image (firmware-controlled devices). burn -ir does it as part of a burn.
extract_fw_data, fiExtract the 4 MB firmware data for firmware-controlled updates; fix an image file. Support or production use.
hw query, e, rw/ww, rb/wb, bbRaw flash access and "burn block". Debug or production only: bb skips every check and can brick the card.

flint flags you need to know

FlagUseCaution
-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 / -noAnswer yes / no to every prompt-y also accepts warnings you'd want to read
--skip_if_sameSkip the burn when the device already has this version: safe to re-run across a fleet
-qqQuick 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 bootHandy in scripts and pdsh loops. The old name still works.
--low_cpuSlower query that uses less CPUFor busy production hosts
--allow_psid_change (--apc)Burn an image with a different PSIDSupport direction only: can drop OEM settings or break the card
--allow_rom_changeAllow 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)
-nofsNon-failsafe burnOnly for blank or recovery flash. A power loss mid-burn leaves no good image.
-guid/-guids, -mac/-macs, -uid, -blank_guidsSet 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_romTake 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, -ocrTake device data from the image / don't use the firmware-controlled update / override cache replacementAdvanced; can hang the firmware
-clear_semaphoreForce-clear a stuck flash semaphore after a crashed toolCorrupts flash if another tool is really using it
-silent, -log <file>, -no_flash_verifyNo progress bar / log the burn / skip per-write verifyKeep 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 themRecovery of a device whose flash parameters can't be read
-dual_image, -striped_imageOld two-image burn layout; treat the file as a striped (pre-burn) imageLegacy / production
--cc <file>Burn a Congestion Control componentOnly with an image NVIDIA provides for it
--i2c_secondary <addr>, --use_fw, --cpu_util 1-5Change the I2C secondary address; flash access through firmware (ConnectX-3 only); CPU throttling (Windows only)
--linkx and its optionsQuery or burn the cable/transceiver attached to the device, not the device itselfSee 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)

mlxfwmanager options

OptionUse
--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-contentList what's in an image directory or archive (types, PSIDs, versions) without touching devices
-f / --forceBurn even when the device already has that version
--skip_if_sameSkip devices already on the image's version
-y / --noAnswer 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-deviceDownload images on an internet-connected host, then carry them into an air-gapped cluster
--nofs, --no_fw_ctrl, --clear-semaphoreSame meaning (and caution) as the flint flags
--log, -L <file>, --no-progressLogging 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-pathShow archive names in -l listings; resolve paths relative to the executable (portable bundles)
<bundle> --sfx-extract-dir <dir> --sfx-extract onlyUnpack a vendor self-extracting firmware package (mlxfwmanager-YYYYMMDD-N) without running it, then run its mlxfwmanager -u yourself

8. flint vs mlxfwmanager

flintmlxfwmanager
ScopeOne device you nameAll devices on the host
Image choiceYou supply the exact imageMatches images to devices by PSID
Best forPrecise control, one card, switches in-band, verify/read imageRoutine updates and inventory across many cards
Inventoryflint -d <dev> q per device--query for everything, with "update required" status
flint = a precision tool: one device, one image (a flint is a single spark). mlxfwmanager = the manager walking the whole floor.

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)
SettingPurpose
LINK_TYPE_P1 / _P2Port protocol on VPI adapters: InfiniBand or Ethernet
SRIOV_EN, NUM_OF_VFSVirtual functions for VMs / containers (see the virtualization guide)
ATS_ENABLEDPCIe Address Translation Services, used in some GPUDirect and virtualization setups
BlueField mode parametersDPU mode vs NIC mode (names differ between BlueField-2 and BlueField-3)
Advanced PCIe settingsExposes extra PCIe tuning options on some cards
Running mlxconfig set and immediately testing shows no change. The settings are pending until the device resets.

mlxconfig commands and options

Command / optionUse
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 / rAll parameters back to defaults (Next Boot). Wipes custom settings such as SR-IOV and port types.
i / show_confsList every parameter the device supports, with descriptions and allowed values
-f <file> backup / -f <file> set_raw / get_rawSave 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)
-yAnswer yes (required in pdsh and scripts)
--with_defaultFor set: parameters you don't name go back to defaults. Nothing is written if the result equals the current config.
--forceSkip firmware capability checks
--host_id, --pf_indexTarget per-host / per-PF parameters on multi-host adapters
show_system_conf / set_system_conf <conf>[asic] / validate_system_confPredefined 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_attrsUse 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_sessionChallenge-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_algorithmSigning options for create_conf (signed configuration files)
gen_tlvs_file, g (XML template), xml2raw, raw2xml, xml2bin, create_conf, applyBuild configuration files offline and apply them (often signed) at scale
clear_semaphoreClear 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 familiesWhat they control
PHY_FEC_OVERRIDE_P1/P2, PHY_RATE_MASK_P1/P2 (+ _OVERRIDE), PHY_AUTO_NEG_P1/P2FEC 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_ENHow 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_NUMPCIe 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/P2Network boot (PXE/UEFI) behavior and wake-on-LAN
INTERNAL_CPU_MODEL, ECPF_ESWITCH_MANAGER, ECPF_PAGE_SUPPLIERBlueField: 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_SUPPORTPort 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
After the reset, 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).
Never run 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)
OptionValues
-l / --level0 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_driverDon't stop/start the driver (you stopped it yourself)
-m / --mst_flagsFlags 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_registerClear the multi-host sync register after an aborted reset
-yDon't prompt

11. The NIC firmware lifecycle

1 Queryversion, PSID 2 Get imagerecipe + PSID 3 DrainSlurm / K8s 4 Burnflint / mlxfwmgr 5 Activatemlxfwreset / reboot 6 Verifyq, link, tests One canary node first, then waves; record versions per node.
  1. Query: mlxfwmanager --query (or flint q): current version, PSID, part number.
  2. 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).
  3. Drain the node.
  4. Burn with mlxfwmanager -u or flint burn.
  5. Activate with mlxfwreset or a reboot/power cycle.
  6. Verify: running version, mlxconfig settings, 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.

Outputs are simplified mock-ups modeled on how the real tools behave, not exact copies, and every name, address, and version is a placeholder. Up/Down arrows recall history; Tab completes commands, devices, paths, and hosts. Supported shell features: pipes to grep, head, tail, wc, sort, uniq, and dshbak; > redirects; ; and &&; simple for loops.
Ticket checklist
    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.

    PieceUpdated 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 aloneMFT (flint / mlxfwmanager) from the host or the Arm side
    BlueField-3 BMCIts own Redfish update path
    DPU mode vs NIC modemlxconfig 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

    bfb-install options

    OptionUse
    -b / --bfb <file>The BFB image
    -r / --rshim [ip[:port]:]rshimNLocal 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.cfgCustomize the install (see below). Without it you must change the default ubuntu password at first login.
    -m / --remote-mode scp|nc|ncpipe, -R / --reverse-ncHow a remote push travels (default scp); reverse netcat helps through firewalls
    -u / --runtimeRuntime upgrade (BlueField-3, local RShim)
    -l / --lfwp, -a / --activate 0|1Live firmware patch, and whether to activate it
    -f / --rootfs, -k / --keep-log, -vYocto rootfs; keep the RShim log; verbose
    bf.cfg keyEffect
    WITH_NIC_FW_UPDATE=noSkip 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_RESETReflash even if the version matches; reset the NIC after flashing (default yes); fall back to a level-3 reset
    UPDATE_DPU_OS, UPDATE_ATF_UEFIInstall the Arm OS; update boot firmware (default yes)
    BMC_USER, BMC_PASSWORD, UPDATE_BMC_FW, UPDATE_CEC_FW, BMC_REBOOT=yes, CEC_REBOOT=yesUpdate the DPU's BMC and CEC firmware from the bundle (needs the current BMC credentials; the reboot flags apply it)
    ubuntu_PASSWORD, grub_admin_PASSWORDHashed passwords set during the install
    bfb_pre_install, bfb_modify_os, bfb_post_installShell functions run at those install stages

    14. InfiniBand switch firmware

    Switch typeExampleHow 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 managedQuantum-2 QM9790In-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.

    SwitchOS versionASIC firmware version
    NVOS (Quantum-2 QM9700 and newer)nv show system image (build-id of the current partition); nv show system also shows the versionnv 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 hostNoneflint -d lid-<LID> -qq q (FW Version); find the LID with ibswitches
    Fleet viewUFM: 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
    On a managed switch the ASIC firmware ships inside the OS image. After an OS upgrade, the switch compares the bundled default firmware with what's on the ASIC and burns the default if they differ (login is delayed a few minutes). So verify both after every upgrade: the OS version, then the ASIC firmware. On Onyx, every module in 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.
    NVIDIA's InfiniBand bring-up procedure recommends that firmware and software versions across the cluster be aligned, or at most two versions apart. Sources: NVIDIA Onyx and MLNX-OS user manuals (Chassis Management, Upgrading System Firmware), NVOS IB user manual, IB Cluster Bring-up Procedure ("Confirm Components' Firmware and Software Versions").
    Exact NVOS commands for fetching and installing images vary by release. Learn the workflow: check version → stage image → install → reboot → verify version and links.

    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 OSCheck versionUpgrade path (examples)
    Cumulus Linuxnv show systemInstall a new image (for example through ONIE: onie-install -a -i <image>, then sudo reboot), or the release's supported upgrade method
    SONiCshow versionsonic-installer install <image>, then reboot

    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.

    # 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
    FlagMeaning
    --linkxAct on the cable/transceiver attached to the device, not the device. Required for every command here.
    --downstream_device_ids 1,2,5Ports to query (comma-separated, no spaces)
    --linkx_auto_updateBurn (and/or activate) all supported cables/transceivers connected to the device
    --downstream_device_id_start_index N + --num_of_downstream_devices MA range: M ports starting at port N (start 10, count 6 = ports 10-15), burned one after another
    --download_transferDownload and transfer the image into the modules (not done by default). Needs -i.
    --activateActivate the transferred firmware (not done by default)
    --activate_delay_sec 0-255Wait 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_elsBurn an ELS (external high-power laser) component instead
    --output_file <file>Save the query output
    -d <cable dev> + --activate, --module_password, --module_vendor_dataCMIS 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_imageSwitch the module's running bank / its committed (boot) bank
    Never burn and activate every cable on an unmanaged switch at once. If the cables don't come back up, you lose in-band access to that switch, possibly for good. NVIDIA's procedure: do half, confirm those links are Active again, then do the other half.

    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 optionUse
    -d, -p <port>, --port_type NETWORK|PCIEDevice, port (needed on switches), and which link (PCIe links too)
    -m / -c / -e / --show_fecModule info / counters and BER / eye opening / FEC capabilities
    --show_serdes_tx, --show_device, --show_ber_monitor, --show_external_phy, --show_links, --show_tx_group_mapTransmitter 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.
    --pcClear the counters, then retest
    -a UP|DN|TGPort 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_forceSpeeds 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|LLLoopback: 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, --lanesPRBS 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, --laneEye-margin scan on a lane: a quality check that goes deeper than -e
    --rx_fec_histogram --show_histogram | --clear_histogramFEC 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_overrideChange transmitter (SerDes) tuning per lane, optionally saving it. Advanced, support-guided.
    --cable --ddm | --dump | --read | --write, --prbs_mode --prbs_select MEDIA|HOSTModule 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_amplitudeModule signal-integrity settings (advanced, support-guided)
    --rx_error_injection, --pcie_error_injectionInject errors deliberately to test monitoring and recovery. Never on production links.
    --jsonJSON 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).

    "The NIC firmware is current" says nothing about the module firmware on the same port. Check both when a link misbehaves. More on optics and signal quality in the transceiver guide.

    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

    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

    SymptomLikely causeNext step
    mst status lists no devicesmst start not run; MFT missing for this kernelRun mst start; reinstall MFT matching the kernel
    Burn refused: PSID mismatchImage 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 deviceUnsigned/modified/wrong image; blocked downgradeUse an official image for that device and a supported version
    Version unchanged after burnNot activatedmlxfwreset or reboot/power cycle
    mlxconfig change has no effectStill pending (Next Boot)Reset/reboot; some settings need a power cycle
    mlxfwreset not supportedPlatform or device limitationDrain and reboot (cold if needed)
    Link down after an updateDriver too old for new firmware, port type changed, module issueCheck DOCA/OFED vs firmware compatibility, mlxconfig LINK_TYPE, mlxlink
    Device missing after an interrupted burnIncomplete imageMany adapters keep a recovery path (failsafe image or recovery mode); retry with the correct image; contact support
    Some nodes slower after rolloutPartial rollout / driftFleet 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.

    Illustrative output, not captured from a real system. Hostnames, serial numbers, GUIDs, MAC and IP addresses are invented, and columns and wording vary between versions. Learn the shape of each output and the fields called out under 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) - Success

    What 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 devices

    What 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-fw

    What 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-fw

    What 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-fw

    What 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 parameter

    What 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 Supported

    What 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 ready

    What 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 0

    What 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_0000000A01

    What 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

    ItemMeaning

    23. Flashcards (click to flip)

    24. Exam traps

    1. Burned ≠ running. NIC firmware loads after mlxfwreset or a reboot/power cycle.
    2. PSID mismatch → get the matching image; don't use --allow_psid_change on your own.
    3. OEM cards get firmware from the server vendor.
    4. flint = one device, exact image; mlxfwmanager = all devices, PSID-matched.
    5. mlxconfig changes are pending until the next firmware load.
    6. mlxfwreset resets the whole device (both ports, all VFs); drain first; use query to see supported levels.
    7. nvfwupd is for server/HGX firmware through the BMC; MFT is for NVIDIA networking devices.
    8. BFB via RShim updates BlueField's Arm software (often with NIC firmware in the bundle).
    9. IB switches: managed → switch OS image; unmanaged → UFM or in-band flint -d lid-.
    10. Ethernet switches: upgrade the whole OS image (Cumulus, SONiC).
    11. Module firmware is separate from NIC and switch firmware. It's updated with flint --linkx: --download_transfer then --activate, through the switch or NIC the module is plugged into, and each end of a link separately.
    12. --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.
    13. Re-burning the version a module already has fails ("LinkX downstream transfer failed"): that's the guard, not a broken module.
    14. mlxconfig without -e shows only Next Boot; use -e to see Current. mlxfwreset on a multi-host card with --sync 0 must run on every host.
    15. -nofs, -use_image_guids, bb, -clear_semaphore, and --allow_psid_change are recovery or production flags, not routine ones.
    16. One recipe for the cluster; inventory and compare across nodes.

    25. Practice quiz (35 questions)

    Score: 0 / 0