xdna-top

Ryzen AI NPU context activity and concurrent iGPU telemetry.

Unified, real-time NPU + iGPU telemetry for Strix Halo — in your terminal, where amd-smi comes up empty.

Interactive telemetry dashboard

---

Why this exists

If you run local AI on an AMD Strix Halo machine, you are flying blind twice over:

You want to know…	amd-smi	nvtop / amdgpu_top	xdna-top
iGPU busy % / power on gfx1151	N/A (ROCm #6035)	partial	✅ live, from kernel sysfs
Is the NPU doing anything at all?	—	—	✅ live contexts + activity
Both, side by side, while two models run	—	—	✅ that's the whole point

When this tool was built, the NPU half was difficult to observe. (GNOME Resources 1.10, Feb 2026, has since added a desktop GUI view of AMD NPUs.) xdna-top focuses on a unified terminal view of Ryzen AI NPU context activity and concurrent iGPU telemetry, with schema-backed workload evidence. It reads per-context ownership and counters through AMD's XRT tooling (xrt-smi), pairs them with iGPU telemetry from sysfs, and uses read-only AMDXDNA interfaces for direct device and power-state facts where the running driver exposes them.

Born from a practical need: while experimenting with concurrent NPU + iGPU local LLM inference on Strix Halo, "is the NPU actually executing?" turned out to be unanswerable with stock tools. So we built the answer. (More war stories in docs/ORIGINS.md.)

What it shows — precisely

Honesty matters in a measurement tool, so here is exactly what each pane is:

• iGPU: busy % and power (W) read from the kernel's amdgpu sysfs endpoints at 5 Hz, with 60-second rolling sparklines. These are the same counters the driver itself maintains — no estimation.
• NPU: hardware context list from xrt-smi examine --report aie-partitions — owning PID, context ID, submission/completion counters, and an activity state derived from counter deltas (a context whose submissions are incrementing is doing work; an in-flight gap between submissions and completions means work is queued right now).
• NPU power state (when available): on driver stacks that export the amdxdna debugfs nodes, snapshot and env-report also report the NPU's active DPM clock state (npuclk / hclk in MHz) and SMU powerstate, read directly from debugfs and independent of xrt-smi. This is a clock-state power level, not a utilization percentage, and it reads unavailable (with a reason) when the nodes aren't exported or aren't readable.
• What it does not show: a made-up generic NPU "utilization %." Newer AMDXDNA stacks may expose direct sensor values such as column utilization, and xdna-top should label those precisely when available. For request attribution, the truthful unprivileged signal remains per-context submission-counter deltas, so that is what we show — and explain in docs/HOW-IT-WORKS.md.

Quick start

pipx install git+https://github.com/boxwrench/xdna-top.git
xdna-top                    # live TUI, q to quit
xdna-top --json             # one fused telemetry reading to stdout, then exit
xdna-top snapshot --out platform.json
xdna-top env-report platform.json --markdown
xdna-top record --duration 60 --interval 0.2 --out telemetry.jsonl
xdna-top mark --out telemetry.jsonl "trial-1-start"      # annotate the stream
xdna-top env-report telemetry.jsonl --markdown           # report from a recording
xdna-top assert telemetry.jsonl --require-npu-activity   # exit 0/1 for CI
xdna-top assert telemetry.jsonl --require-npu-activity \
  --between request-start request-end                    # prove activity *in* the window
xdna-top compare before.json after.json   # flag high-signal platform drift
xdna-top baseline save known-good          # store a named known-good snapshot
xdna-top baseline check known-good         # re-check the platform after updates
xdna-top exporter --port 9477              # serve Prometheus metrics at /metrics
xdna-top workload-check --chat-url http://localhost:8000/v1/chat/completions \
  --model my-model            # JSON stdout; human evidence summary on stderr
xdna-top --theme phosphor   # pick a TUI theme (see --list-themes)
xdna-top --layout stacked   # iGPU above NPU for a narrow terminal
xdna-top --npu-only        # hide the iGPU pane
lemonade-top                # same monitor, lemonade-stand theme

Prefer direct GitHub install for now while package-index publication settles. If you prefer plain pip, this also works:

pip install git+https://github.com/boxwrench/xdna-top.git

lemonade-top is the very same telemetry engine - identical NPU + iGPU signals and --json output - just wearing a lemonade-stand theme. It's purely cosmetic (no extra dependencies, nothing to do with the Lemonade SDK); pick whichever palette you prefer.

Requirements: Linux with the amdxdna driver bound (/dev/accel/accel0), Python ≥ 3.11, and xrt-smi on your PATH for the NPU pane. No ROCm required. Missing a piece? The tool degrades gracefully — panes flag themselves as degraded instead of crashing.

Features

• Unified live view: both engines, one screen, 5 Hz
• Rolling ASCII sparklines for iGPU busy and power
• Per-context NPU table: PID, process name, submissions, completions, derived activity — ordered most-active-first by submission delta
• --json mode for scripts, logging, and dashboards
• snapshot mode for schema-versioned platform and telemetry evidence
• env-report mode for Markdown summaries from captured snapshots or recordings
• record mode for streaming typed JSONL telemetry events over a time window
• mark mode for annotating a recording with named trial markers
• assert mode for named pass/fail evidence checks with CI-friendly exit codes, including --between to require activity within a marked request window
• compare mode for spotting high-signal platform drift between two snapshots
• baseline mode for saving a known-good snapshot and re-checking it after updates
• exporter mode serving Prometheus metrics at /metrics for scraping into Prometheus + Grafana — optional [exporter] extra; see docs/EXPORTER.md
• Direct-AMDXDNA NPU power state when the amdxdna debugfs nodes are readable: active DPM clock state (npuclk/hclk MHz) + SMU powerstate — a clock level, never a utilization %
• workload-check mode: probe an OpenAI-compatible endpoint and report per-context NPU submission/completion deltas across the request window — measured evidence, never a causality claim
• Themes via --theme/XDNA_TOP_THEME (colors only — never the measured values)
• Direct live-view options: --layout stacked and --npu-only
• Pessimistic fallbacks everywhere — built for imperfect driver stacks
• Zero daemon, zero root*, zero ROCm dependency _{*standard sysfs/xrt permissions apply}

Themes

Pick a skin with --theme <name> (or set XDNA_TOP_THEME); run xdna-top --list-themes to see them all. Themes change only colors and chrome — never the metric names, states, units, or measured values — so a screenshot stays claims-accurate in any theme.

Rendered with illustrative values to show the palettes, not the live TUI layout. See docs/THEMES.md for the full list and how to contribute one.

How it works (30 seconds)

sysfs supplies the iGPU's own driver counters; xrt-smi exposes the NPU's hardware-context bookkeeping; xdna-top polls both, derives activity from submission-counter deltas, fuses them into one reading, and renders it with rich. The full guided tour — including an annotated real capture of an LLM generation lighting up the NPU pane — is in docs/HOW-IT-WORKS.md, and the hosted interactive view lives at boxwrench.github.io/xdna-top.

For what the hardware is — the NPU (XDNA 2), iGPU, and CPU spec, how they compare, and exactly which sensors this silicon does and doesn't expose — see docs/HARDWARE.md. For a worked use-case built on this platform, see REM.

Related tools

• amdgpu_top is the mature, broad AMDGPU/APU monitor, with GPU metrics, sensors, fdinfo, process memory views, TUI/GUI/JSON modes, and XDNA device support. If you want a general AMD GPU monitor, start there.

  xdna-top is complementary. It focuses on Ryzen AI workload evidence: NPU context ownership, submission/completion deltas, and what the iGPU was doing at the same time. Its read-only AMDXDNA probes follow the same driver-facing spirit while keeping xdna-top scoped to workload evidence and NPU+iGPU concurrency.

NPU Field Guide

Companion reference for the silicon xdna-top watches — generic NPU knowledge, no application specifics. Start at docs/npu/.

Doc	What it covers
Why the NPU?	XDNA2 as a dataflow/DSP fabric; DRAM bandwidth as the contention surface; GEMM TOPS ceilings.
Software stack	Runtime → kernel-authoring → compiler → driver layers.
Runtime landscape	FastFlowLM, Lemonade Server, Ryzen AI Vitis AI EP, GAIA.
Workload patterns	What a laptop NPU is good/bad at, plus design heuristics.

Roadmap

• v0.2 evidence core: snapshot, env-report, record, mark, assert, compare, baseline, and assert --between windowed activity guard
• Prometheus exporter for scraping NPU+iGPU telemetry into Prometheus/Grafana
• v0.3 read-only direct AMDXDNA backend: debugfs power/clock state + DRM-IOCTL driver/AIE/clocks/firmware identity (validated on real silicon)
• v0.4 supervised workload-check: endpoint probe + per-context NPU submission/completion deltas across the request window
• Active stabilization: coherent single-read samples, truthful direct-backend NPU detection, exporter power-state integration, and clean JSON output
• Next cleanup: retire the unused daemon/cache path and collapse stale planning documents after compatibility checks
• Triggered later: reports, poll-rate controls, live context history, and more hardware support only when a concrete user or tester needs them

See docs/ROADMAP.md for current priorities and docs/SNAPSHOT-SCHEMA.md for the snapshot artifact contract.

Contributing

Issues and PRs welcome — especially captures from other Ryzen AI machines. Read CONTRIBUTING.md first; the one house rule is claims precision: docs never promise a signal the hardware doesn't give.

License & citation

Apache-2.0 © Keith. If this tool helped your research, see CITATION.cff.