Topology

Get the system topology, showing how GPUs are interconnected and connected to the CPU.

Synopsis

xpu-smi topology -d [deviceId]
xpu-smi topology --device [deviceId]
xpu-smi topology --device [pciBdfAddress]
xpu-smi topology --device [deviceId] -j
xpu-smi topology -f [filename]
xpu-smi topology -m
xpu-smi topology --p2p [capability]

Options

-h, --help

Print this help message and exit.

-j, --json

Print result in JSON format.

-d <deviceId>, --device <deviceId>, --id <deviceId>

The device ID or PCI BDF address to query. Accepts a comma-separated list to query several devices at once (e.g., -d 0,1,4).

-f <filename>, --file <filename>

Generate the system topology with GPU info and write it to an XML file.

-m, --matrix

Print the CPU/GPU topology matrix showing interconnect types between all devices.

The matrix uses the following symbols:

Symbol

Meaning

S

Self

MDF

Connected with Multi-Die Fabric Interface

PIX

Connected via PCIe switch (≥3 common bridge ancestors)

PXB

Connected via multiple PCIe bridges (2 common ancestors)

PHB

Connected via PCIe host bridge (1 common ancestor)

NODE

Connected within a NUMA node

SYS

Worst-case connectivity (cross-NUMA or topology unknown)

Symbols are assigned by a priority-ordered decision chain, best (fastest) connectivity first:

  1. S — self (same device and tile).

  2. MDF — both GPU tiles on the same physical device.

  3. PIX — PCIe paths share ≥3 common bridge ancestors (same PCIe switch).

  4. PXB — PCIe paths share exactly 2 common ancestors (same root port).

  5. PHB — PCIe paths share exactly 1 common ancestor (same host bridge).

  6. NODE — no common PCIe ancestor (or a PCIe path is unavailable) but both devices resolve to the same NUMA node.

  7. SYS — everything else: different NUMA nodes, or NUMA/topology unknown.

Note

When two devices share a NUMA node but sit under different PCIe root complexes (no common PCIe ancestor), they are classified as NODE rather than SYS. NUMA locality is used as the tiebreaker whenever the PCIe paths do not share an ancestor.

--p2p <capability>

Print the peer-to-peer (P2P) capability matrix between GPU devices for the requested capability.

The capability argument selects which P2P property to probe:

Value

Meaning

r

P2P read/write access (w accepted as an alias; Level Zero reports this as a single unified capability)

n

MDF fabric connectivity

a

P2P atomic operations

p

PCIe P2P access

The matrix uses the following symbols:

Symbol

Meaning

X

Self

OK

Capability supported

NS

Not supported

?

Query failed (driver or device error)

Examples

Show topology for device 0:

xpu-smi topology --device 0

Show topology in JSON format:

xpu-smi topology --device 0 -j

Export topology to XML file:

xpu-smi topology -f system_topology.xml

Print the full CPU/GPU interconnect matrix:

xpu-smi topology -m

Print the P2P read/write capability matrix between GPUs:

xpu-smi topology --p2p r