Networking NVIDIA Firmware Tools (MFT) Documentation

nvpcie Utility

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:

mlxconfig -d <mst> set OPER_LOG_BUFFER_SIZE=LOG_2KB

Recommended value: LOG_2KB.

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.
    

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: