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 |
|
Yes |
|
Access Register — SET |
|
Yes |
|
Query HCA capability |
|
Yes |
|
Set HCA capability |
|
Yes |
|
Device ID read |
synthesised from the fwctl device |
Yes |
|
CR-space read ( |
— |
No — |
|
CR-space write ( |
— |
No — |
|
CR-space block read/write |
— |
No — |
|
VSEC / PCI config access |
— |
No — |
|
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 |
|
Lockdown-compatible. Does not taint the kernel. Discloses no sensitive data. |
|
Register write |
|
Requires |
|
HCA capability query/set |
|
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 whereCAP_SYS_RAW_IOis 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 |
|---|---|
|
|
Enumerate fwctl nodes from sysfs; no device access needed |
|
|
Access Register is its entire function |
|
|
Reads the MTMP register |
|
|
Register-based (PTYS/PAOS/PDDR/…). See caveat below |
|
|
Cable access via the MCIA register |
|
|
Has a dedicated register-access fetcher |
|
|
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. |
|
|
|
|
|
|
|
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 |
|---|---|
|
|
CR-space block reads are the dump mechanism |
|
|
CR-space based dumps |
|
|
CR space and ICMD |
|
|
ICMD-based |
|
Any flow using Direct Flash Access |
DFA is CR-space based |
Requires hardware validation before publishing
|
Command |
Open question |
|---|---|
|
|
Uses the MFRL register plus PCI-level operations; the PCI half is not available over fwctl. |
Prerequisites
-
A system kernel that provides the
fwctlsubsystem 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: