nvpcie is a command-line diagnostic utility used to collect and display PCIe information for PCIe switch devices. It helps users verify PCIe configuration, connectivity, and link status, as well as debug and troubleshoot PCIe-related issues. The tool is available on Linux for NVIDIA ConnectX-8 and above devices operating as a PCIe switch.
The events command requires firmware that exposes the PCIE_EVENTS resource in its resource dump menu (see resourcedump query). Otherwise, the tool generates the following error message:
Error: Failed DumpCommand - Dump type: PCIE_EVENTS is not supported. Exiting...
nvpcie Usage
nvpcie [-h] [-v] [-d DEVICE] {counters,events,link,trace} ...
where:
|
events Beta Level: This command is under active development and may be unstable. We recommend using it with caution. |
Fetch the PCIe event log To enable this feature, run:
Recommended value: |
|
link |
Show the operational state of the PCIe links |
|
counters |
Show the performance counters of the PCIe link |
|
trace ltssm Beta Level: This command is under active development and may be unstable. We recommend using it with caution. |
Decode the PCIe LTSSM history |
|
-d, --device |
The device to work on. Must precede the command. Required by every command, except events and trace ltssm given --dump-file |
|
-h, --help |
Show help message and exit |
|
-v, --version |
Show tool version and exit |
nvpcie Events Usage
nvpcie [-d DEVICE] events [-h] [--view {all,critical} | --dump-file FILENAME]
[--format {text,json}] [-o FILENAME] [--clear] [--yes]
where:
|
--view |
The event view to fetch: "critical" for crash related events, "all" for all the other events (default: critical) |
|
--dump-file |
Present the events of a dump saved earlier instead of dumping the device. Not allowed with --view. A device given with it only labels the report |
|
--format |
The output format: "text" for the human readable event log, "json" to serialize the events (default: text) |
|
-o, --out |
Write the output to FILENAME instead of the screen |
|
--clear |
Erase the event log of the selected view instead of presenting it, after a confirmation. Supported for the "critical" view only. Not allowed with --dump-file, -o/--out or --format json |
|
--yes |
Answer the confirmation of --clear, so that it is not asked. Allowed only with --clear |
|
-h, --help |
Show help message and exit |
Examples:
-
Fetch the crash related events:
# nvpcie -d /dev/mst/mt4131_pciconf0 events -
Fetch all the other events into a JSON file:
# nvpcie -d /dev/mst/mt4131_pciconf0 events --view all --format json -o events.json write to file: events.json -
Present a dump saved earlier:
The dump file must be a valid resourcedump output, either in hex (each dword written as 0x followed by eight hex digits, as resourcedump prints it) or binary (big-endian, as resourcedump dump --bin writes it), with each event encapsulated in its own 0x107c resource segment. Its command segment must state a request for the PCIE_EVENTS resource (0x1098), whose index1 names the view: 0 for critical, 1 for all. For the info, command and terminate segments that wrap the resource segments, and for the general form of a resource segment, see the "Resource Dump" chapter of the PRM.
# nvpcie events --dump-file pcie_events.dump PCIe Event Log Device : N/A Event view : critical FW version : 20.33.0830 Events : 8 [2026-08-13 06:30:01.500000] [CRITICAL] **Link status change** BDF 18:1f.2 link UP x16 Gen5 | dl active | flit enabled perst none | directed no … -
Erase the critical event log:
# nvpcie -d /dev/mst/mt4131_pciconf0 events --clear The "critical" event log of /dev/mst/mt4131_pciconf0 will be erased. Continue? [y/N] y The "critical" event log was erased.
nvpcie Link Usage
The link command shows the PCIe operational information that mlxlink shows for --port_type PCIE, for every PCIe link of the device, or for the link that --port or --dpn names.
nvpcie -d DEVICE link [-h] [--port PORT | --dpn D/P/N]
where:
|
--port |
Local port of the PCIe link, as "mlxlink --port_type PCIE --show_links" lists it |
|
--dpn |
Depth, PCIe index and node of the PCIe link, e.g. 0/0/0. Not allowed with --port |
|
-h, --help |
Show help message and exit |
Examples:
-
Show the operational state of every PCIe link:
# nvpcie -d /dev/mst/mt4131_pciconf0 link -
Show the operational state of one PCIe link:
# nvpcie -d /dev/mst/mt4131_pciconf0 link --dpn 0/0/0
nvpcie Counters Usage
The counters command shows the PCIe performance counters that mlxlink shows for --port_type PCIE --show_counters, for the first PCIe link of the device, or for the link that --port or --dpn names.
nvpcie -d DEVICE counters [-h] [--port PORT | --dpn D/P/N]
where:
|
--port |
Local port of the PCIe link, as "mlxlink --port_type PCIE --show_links" lists it |
|
--dpn |
Depth, PCIe index and node of the PCIe link, e.g. 0/0/0. Not allowed with --port |
|
-h, --help |
Show help message and exit |
Examples:
-
Show the performance counters of one PCIe link:
# nvpcie -d /dev/mst/mt4131_pciconf0 counters --dpn 0/0/0
nvpcie Trace ltssm Usage
The trace ltssm command decodes the LTSSM (Link Training and Status State Machine) history that the device logged for a PCIe link, out of an mstdump output. Without --dump-file, it dumps the device into a temporary file and removes it afterwards.
nvpcie [-d DEVICE] trace ltssm [-h] [--dump-file FILENAME]
[--lport LPORT]
[-o FILENAME]
where:
|
--dump-file |
Decode an mstdump output taken earlier instead of dumping the device |
|
--lport |
Local port of the PCIe link, as "mlxlink --port_type PCIE --show_links" lists it |
|
-o, --out |
Write the output to FILENAME instead of the screen |
|
-h, --help |
Show help message and exit |
Examples:
-
Dump the device and decode the LTSSM history of its first link:
# nvpcie -d /dev/mst/mt4131_pciconf0 trace ltssm -
Decode an mstdump output taken earlier:
# nvpcie trace ltssm --dump-file mt4131_pciconf0.dump Dump: mt4131_pciconf0.dump (ConnectX8) Ring: 128 slots, oldest first, next write slot 76, tick 1024 ns Slot Speed Width State Exit reason Dwell ---- ----- ----- -------------------------------------- --------------------- ------------ -- Perst deasserted -- 0 Gen0 x1 0xfe LTSSM_FW_EVENT_PERST_DEASSERTED Framing Error 33.55 ms or more 1 Gen1 x16 0x00 DETECT_RESET Framing Error 33.55 ms or more … 75 Gen3 x16 0x1a RECOVERY_IDLE EIEOS 0.00 ms CUR Gen3 x16 0x1b L0 - -
Last updated: