Networking NVIDIA Firmware Tools (MFT) Documentation

MFT over fwctl

Overview

fwctl is an upstream kernel subsystem that exposes a narrow, audited channel to device firmware. For NVIDIA NICs, the backing driver is the mlx5 fwctl driver, which publishes one character device per function:

/dev/fwctl/fwct0
/dev/fwctl/fwct1
...

This path avoids the MFT kernel modules (mst_pci and mst_pciconf) as well as raw PCI configuration access and /dev/mem, making it the supported mechanism on Secure Boot lockdown systems.

As a result, on fwctl-capable systems, supported MFT commands can operate without running mst start, because MFT discovers fwctl devices through /sys/class/fwctl/ and opens /dev/fwctl/* directly.

Identifying and Addressing a fwctl Device

Listing

mst status -v and mdevices_info always print a FWCTL column for PCI devices, populated by matching each device's PCI BDF against /sys/class/fwctl/*/device:

mst status -v
mdevices_info
mst status --json     # exposes the path under the "fwctl" key

A device that has a fwctl character device shows its path (e.g. /dev/fwctl/fwctl0); one that does not shows an empty column.

Addressing

Pass the fwctl node directly to any tool's -d / --device argument:

<MFT tool> -d /dev/fwctl/fwctl0 ...

MFT recognizes a device as fwctl when the name contains /dev/fwctl/ or begins with fwctl.
No other flag is needed; the transport is selected automatically.

MFT Capabilities over fwctl

MFT operation

fwctl RPC

Supported

Access Register — GET

MLX5_CMD_OP_ACCESS_REG (read)

Yes

Access Register — SET

MLX5_CMD_OP_ACCESS_REG (write)

Yes

Query HCA capability

MLX5_CMD_OP_QUERY_HCA_CAP

Yes

Set HCA capability

MLX5_CMD_OP_SET_HCA_CAP

Yes

Device ID read

synthesised from the fwctl device

Yes

CR-space read (mread4)

—

No — EOPNOTSUPP

CR-space write (mwrite4)

—

No — EOPNOTSUPP

CR-space block read/write

—

No — EOPNOTSUPP

VSEC / PCI config access

—

No — EOPNOTSUPP

ICMD / Tools-HCR mailbox

—

No (requires CR space)

Direct Flash Access (DFA)

—

No (requires CR space)

MFT commands that require CR-space access, ICMD, VSEC/PCI configuration access, or direct flash access are not supported over fwctl.

Secure Boot Lockdown Behavior

fwctl RPCs carry a scope that the kernel enforces. MFT uses three of them, and they do not behave the same under lockdown:

MFT operation

Scope used

Lockdown behavior

Register read

FWCTL_RPC_DEBUG_READ_ONLY

Lockdown-compatible. Does not taint the kernel. Discloses no sensitive data.

Register write

FWCTL_RPC_DEBUG_WRITE_FULL

Requires CAP_SYS_RAW_IO and taints the kernel. Explicitly not bound by lockdown principles.

HCA capability query/set

FWCTL_RPC_CONFIGURATION

Configuration scope; device remains in a fully supported state.

What this means in practice

  • Read-only / query commands are the safe set. They run under the lockdown compatible scope and are the commands that can be relied on in a hardened deployment.

  • Any command that writes a register goes through the full-debug scope.
    On a system where CAP_SYS_RAW_IO is restricted, those commands can fail even though the same tool's query path succeeds. They also taint the kernel, which some support policies treat as a reportable event.

This read/write asymmetry is the single most important thing for an end user to understand, and it is the likely source of "the tool works for --query but fails for --set" reports.

Tool-by-tool Support Matrix

Verdicts below are derived from code analysis of the access primitives each tool uses.
Confidence is marked per row — see limitations below before publishing the rows marked Needs validation.

Supported — register-only (code-verified)

Command

Description

mst status -v, mdevices_info

Enumerate fwctl nodes from sysfs; no device access needed

mlxreg

Access Register is its entire function

mget_temp

Reads the MTMP register

mlxlink

Register-based (PTYS/PAOS/PDDR/…). See caveat below

mlxcables

Cable access via the MCIA register

resourcedump

Has a dedicated register-access fetcher

flint

Flash access can run over the MFBA/MFPA registers, which fwctl permits — but the MFBA-vs-DFA selection logic and at least one direct CR read in the device-ID path need checking on real hardware. Query vs burn may differ.

mlxfwmanager


mlxconfig


HCA capabilities (MFT SDK)

fwctl-only by design — rejects non-fwctl transports

mlxlink caveat: mlxlink touches CR space only when the user explicitly passes a GVMI address on the command line. In that mode it will fail over fwctl. Default operation does not use CR space.

Not supported — require CR space / ICMD (code-verified)

Command

Description

mstdump / mstregdump

CR-space block reads are the dump mechanism

mlxdump

CR-space based dumps

fwtrace, mlxtrace

CR space and ICMD

wqdump

ICMD-based

Any flow using Direct Flash Access

DFA is CR-space based

Requires hardware validation before publishing

Command

Open question

mlxfwreset

Uses the MFRL register plus PCI-level operations; the PCI half is not available over fwctl.

Prerequisites

  • A system kernel that provides the fwctl subsystem and the mlx5 fwctl driver, with fwctl device nodes available under /dev/fwctl/

  • MFT user-space tools installed. No MFT kernel module is required for the fwctl path, and you do not need to run mst start

Last updated: