xpu-discover

name	xpu-discover
description	Inventory Intel GPUs (Arc, Arc Pro, Data Center GPU Max) on a Linux host. Detect devices, check driver health, list processes using each XPU, run a quick diagnostic, and read live utilisation.

xpu-discover

xpu-smi is Intel's nvidia-smi. Sees only Intel GPUs (Arc, Arc Pro, Battlemage, Flex, Max).

Quickstart

Run in order. If step 1 is empty, stop.

xpu-smi discovery                 # 1. inventory
xpu-smi diag --precheck           # 2. driver/firmware health
xpu-smi ps                        # 3. processes using each GPU
xpu-smi diag -d 0 -l 1            # 4. quick functional test
xpu-smi stats -d 0                # 5. utilisation snapshot
xpu-smi dump -d 0 -m 0,5,18 -i 1  # 6. live CSV stream (Ctrl-C)

All commands accept -j for JSON output (use when parsing).

CUDA -> Intel cheat sheet

CUDA	Intel
nvidia-smi	xpu-smi discovery
nvidia-smi -L	xpu-smi discovery -j
nvidia-smi pmon -c 1	xpu-smi ps
nvidia-smi dmon	xpu-smi dump -d <id> -m 0,5,18 -i 1
nvidia-smi --query-gpu=...	xpu-smi stats -d <id> -j
nvidia-smi topo -m	xpu-smi topology -m
CUDA_VISIBLE_DEVICES=0	ZE_AFFINITY_MASK=0
cuda-memcheck	xpu-smi diag -d 0 -l 1

CUDA refugee footgun: CUDA_VISIBLE_DEVICES=99 silently hides all GPUs; ZE_AFFINITY_MASK=99 crashes the Level Zero loader with an assertion. Always check xpu-smi discovery for valid IDs (start at 0) before setting the mask.

What each subcommand returns

discovery — inventory

One stanza per Intel GPU. Key fields:

• Device ID — small integer, used as -d and as ZE_AFFINITY_MASK value.

• PCI BDF Address — stable across reboots (e.g. 0000:36:00.0).

• DRM Device — /dev/dri/card0, used in --device for Docker.

• Device Name — Battlemage shows Intel(R) Graphics [0xe2XX] rather than the marketing name; driver quirk, not a problem. Map the PCI device ID in brackets to the product SKU:

  PCI device ID	Product SKU	Confirmed
  0xe20b	Arc B580	yes (lspci on hardware)
  0xe211	Arc Pro B60	yes (pci.ids)
  0xe220	Arc Pro B50	yes (pci.ids)
  0xe221	Arc Pro B65	yes (pci.ids)
  0xe223	Arc Pro B70	yes (lspci on hardware)

  Full table provided above. Cross-check with lspci -d 8086: -nn (prints [8086:XXXX]).

Empty output -> kernel didn't enumerate any Intel GPU. See "Troubleshooting".

diag --precheck — driver health

Scans journalctl for known Intel-GPU error categories (GuC/HuC firmware, IOMMU, PCIe, DRM, i915/Xe, Level Zero init).

• All Pass -> proceed.
• Any Critical -> see "Error pattern routing" below.

Scope with --since today / --since yesterday / --listtypes (show every error category).

ps — what's using each GPU

Lists processes holding Level Zero handles + shared/device memory in MiB. Desktop processes (plasmashell, xauth_*) are normal on a workstation; only worry about a stale model server still holding memory.

diag -d <id> -l <level> — does it compute

Level	Time	Impact
-l 1	seconds	safe on a busy box
-l 2	medium	impacts other workloads
-l 3	minutes	impacts performance

Reading on a workstation: the Software Permission sub-test fails when other processes already hold the device, so the overall line says Fail even when Computation Check: Pass. Read per-sub-test rows. For a clean run, log out of the GUI session and run from TTY, or run inside a privileged container.

Pick individual tests with --singletest:

ID	Test	When
1	Computation	does it compute
2	Memory Error	suspected ECC / bit-flip
3	Memory Bandwidth	sanity-check HBM/GDDR
4	Media Codec	video pipelines
5	PCIe Bandwidth	suspected slot/cable issue
6	Power	thermal/TDP investigation
7	Computation functional	quick sanity (lighter than 1)
8	Media Codec functional	lighter media check
9	Xe Link Throughput	multi-GPU peer link
10	Xe Link all-to-all	multi-GPU; needs -d -1

Example: xpu-smi diag -d 0 --singletest 1,3 -j.

stats -d <id> — utilisation snapshot

Many fields show N/A on consumer Battlemage drivers (Arc Pro B70 included) — counter-wiring limitation, not a bug. Memory (column 5) and power (column 18) generally work. For utilisation while running, prefer xpu-smi dump.

dump -d <id> -m <metrics> -i <interval> — live CSV stream

Useful metric IDs for LLM serving:

• 0 GPU utilisation (%)
• 5 GPU memory used (MiB)
• 18 GPU power (W)

xpu-smi dump -d 0 -m 0,5,18 -i 1 > xpu.csv &
# ... run your model ...
kill %1

Privilege note: metric 0 reads MEI telemetry, restricted on consumer parts. Without sudo, that column shows N/A. Metrics 5 and 18 work unprivileged.

topology -m — multi-GPU connectivity

Matrix of Xe Link / PCIe switch / hostbridge between XPU pairs. Only useful on multi-XPU systems.

Error pattern routing

When diag --precheck flags a critical error:

Category	Cause + fix
Level Zero Init Error	Driver/userspace mismatch. Confirm xe (Battlemage) or i915 (older) modules loaded: lsmod | grep -E 'i915|xe'. Reload or reboot.
GuC / HuC Not Running	Missing firmware blob. Check dmesg | grep -i 'GuC|HuC'; install linux-firmware.
IOMMU Catastrophic	Kernel cmdline. On consumer boards: intel_iommu=on iommu=pt.
PCIe Error	Reseat card / check slot; re-run xpu-smi diag -d <id> --singletest 5.
DRM Error	Stuck context from a crashed desktop session. Logout/login (or reboot) clears it.
i915 Not Loaded on Battlemage	Battlemage uses xe, not i915. Confirm modinfo xe; precheck error is misleading on this generation.

Troubleshooting

Symptom	Fix
xpu-smi: command not found	Install Intel level-zero packages (Ubuntu / RHEL / Arch all package xpu-smi). Binary lands at /usr/bin/xpu-smi.
discovery empty but card present	(1) Kernel didn't bind: lspci -k -s <bdf> should show Kernel driver in use:. (2) Bound to vfio: lsmod | grep vfio. (3) Inside container without /dev/dri: add --device /dev/dri --privileged.
diag fails inside container	Container needs --privileged for diag ioctls beyond the standard render-node interface.
Two XPUs present, one visible	printenv ZE_AFFINITY_MASK; unset for full inventory, re-export for workloads.

Env vars

Variable	Purpose
ZE_AFFINITY_MASK	Which XPU(s) a process sees (0, 0,1, ...). Invalid IDs crash the L0 loader (unlike CUDA's silent-hide).
ZE_FLAT_DEVICE_HIERARCHY	FLAT exposes tiles as separate root devices; COMPOSITE (default) groups under one. Battlemage is single-tile, doesn't matter.
ZE_ENABLE_VALIDATION_LAYER=1	L0 loader prints API misuse — useful when something silently returns wrong device count.

References

• xpu-smi source: https://github.com/intel/xpumanager
• Level Zero spec: https://oneapi-src.github.io/level-zero-spec/
• Battlemage / Xe driver: https://docs.kernel.org/gpu/xe/index.html