Accelerated Processing Unit. An AMD processor package containing CPU cores, integrated graphics (iGPU), and dedicated AI accelerators (NPU) on a single die.
Why it matters: System monitors traditionally look at CPU and GPU separately. An APU fuses these alongside an NPU, necessitating tools like xdna-top that look at both compute layers side by side to ensure resources aren't bottlenecking.
Neural Processing Unit. A specialized hardware accelerator built specifically for machine learning inference tasks, optimized for low power and high matrix throughput.
Why it matters: Running local LLM inference on an NPU rather than the GPU saves system memory bandwidth and power, allowing the iGPU to be dedicated to other tasks like graphics rendering.
Integrated Graphics Processing Unit. The onboard GPU engine within the APU. In Strix Halo, this is the Radeon 8060S (RDNA 3.5 gfx1151) boasting massive compute capability.
Why it matters: Because the Strix Halo iGPU is so large, developers frequently use it alongside the NPU to run concurrent local model inference, making dual-telemetry critical.
An architectural model where compute cells (AIE tiles) are physically arranged, routing stream data directly through circuits rather than executing temporal instructions.
Why it matters: Because data flows through pre-routed cells rather than competing for scheduler cycles, standard "utilization percentage" metrics are useless. You either stream data through a context or you do not.
An active partition of AI Engine tiles allocated on the XDNA NPU fabric for an application. A context is registered to a unique process PID.
Why it matters: The driver status flags a context as "Active" whenever a process holds the partition. xdna-top parses this table to find which PIDs own NPU space.
The logic routine used by xdna-top to determine true NPU execution. It diffs cumulative context submission counters across discrete samples.
Why it matters: Prevents false positives. A loaded model context will report "Active" state to the OS even when completely idle; tracking sample-to-sample deltas surfaces true processor activity.
A state where the number of submissions sent to the NPU is strictly greater than the completions reported back, indicating active hardware processing.
Why it matters: Seeing jobs "in-flight" verifies that work is currently queued on AIE tiles at the exact instant the telemetry sample was taken.
A virtual filesystem provided by the Linux kernel that exposes device driver statistics, parameters, and telemetry nodes to user space.
Why it matters: xdna-top bypasses broken or empty amd-smi commands on APUs by reading directly from raw sysfs files like gpu_busy_percent.
Direct Rendering Manager. The Linux kernel subsystem that exposes GPU and accelerator devices, including file descriptors and driver-specific control operations.
Why it matters: The AMDXDNA NPU driver uses DRM-style device interfaces. Reading through this layer lets xdna-top ask the kernel for device and sensor facts directly instead of depending only on command output.
Input/output control. A structured userspace-to-kernel request used when a device needs operations richer than ordinary file reads and writes.
Why it matters: For newer AMDXDNA stacks, IOCTLs can query driver version and NPU sensors directly from /dev/accel/*. This is more robust than scraping a CLI when the kernel exposes the signal.
Linux device-node namespace for accelerator devices. AMD XDNA NPUs appear here as entries such as /dev/accel/accel0.
Why it matters: Opening the accel device gives user-space tools a file descriptor they can use for direct AMDXDNA DRM IOCTL probes, while preserving the project's zero-root goal when normal device permissions allow access.
The planned direct NPU telemetry backend that asks the AMD XDNA kernel driver for device, driver, power, and column-utilization sensor data.
Why it matters: Direct kernel probes reduce dependence on external tools. xrt-smi remains useful for compatibility and per-context attribution until equivalent direct PID/counter data is available.
A direct AMDXDNA sensor value representing utilization for NPU columns when the kernel driver exposes that sensor.
Why it matters: This is a real sensor when available, but it is not the same as proof that a specific request used the NPU. For request attribution, xdna-top still prefers PID-owned context deltas.
Metadata that records which backend produced each telemetry signal, such as sysfs, AMDXDNA IOCTL, or xrt-smi.
Why it matters: Evidence is only useful when reviewers know where it came from. Snapshot and record artifacts should say whether a value came from direct kernel probing, a sysfs node, or an external compatibility tool.
Xilinx Runtime. The unified library and tooling layer AMD uses to configure, load, and inspect AI Engines and Ryzen AI NPU cores.
Why it matters: XRT remains an important compatibility path. The xrt-smi utility exposes partition reports with PID, context ID, submission, and completion counters, which are still the best unprivileged attribution signal today.
A versioned, machine-readable capture of platform and telemetry facts that can be reread later without the original machine. xdna-top produces two: a snapshot JSON object and a record JSONL stream.
Why it matters: Pretty output is for humans; evidence artifacts make a measured claim reproducible across scripts, devlogs, bug reports, and CI gates. Every other evidence command is a view over one of these artifacts.
A point-in-time JSON record of host, devices, backends, one fused telemetry reading, and degraded flags. Produced by xdna-top snapshot and rendered to Markdown by xdna-top env-report.
Why it matters: A stable snapshot schema is the foundation for comparison and baselines. env-report summarizes captured facts only — it never re-probes the machine, so a report stays reproducible.
A JSONL stream of typed events (meta, telemetry, summary) captured over a time window by xdna-top record. Each telemetry line carries a fused reading and per-context NPU data.
Why it matters: A recording captures counter movement over a request window, which is the strongest evidence that the NPU did work — far stronger than a single snapshot's instantaneous reading.
A typed mark event appended to a recording with xdna-top mark "<label>", tagging a moment in the stream (for example trial-1-start).
Why it matters: Markers let a script annotate exactly when a trial, request, or transformation step happened, so later analysis can line up telemetry deltas with the events that caused them.
A named pass/fail check over a snapshot or recording, run with xdna-top assert. Each check prints the observed value next to its requirement and the process exits non-zero if any check fails.
Why it matters: Assertions turn evidence into a CI gate, for example --require-npu-activity. Unavailable signals fail honestly rather than being converted into guessed values.
A diff of two snapshots that surfaces only high-signal platform drift (kernel, accel device, backend/sensor availability, NPU BDF, sysfs paths, degraded regressions) via xdna-top compare.
Why it matters: Compare highlights drift that affects trust in an experiment instead of drowning you in generic JSON noise. Like git diff --exit-code, it exits non-zero when meaningful drift is found.
A named known-good snapshot saved locally with xdna-top baseline save and re-checked with baseline check after a kernel, BIOS, distro, or XRT update.
Why it matters: A baseline turns an upgrade into a checkable event: baseline check reuses the compare rules and exit codes to tell you whether an update silently changed how the platform exposes telemetry.
An explicit version string stamped on every artifact (schema_version) so that comparison and tooling can evolve the format without misreading older captures.
Why it matters: Versioning the schema is what keeps a snapshot saved today comparable to one captured after a future update, and lets compare flag a schema change itself as high-signal drift.
A machine-readable marker (with reasons) set when a signal source is missing or unreadable, instead of substituting a guessed value. Present in readings, snapshots, and recordings.
Why it matters: A monitoring tool's first duty is to not lie about whether it is monitoring. Degraded data stays visible and machine-readable so reviewers and assertions can treat a missing signal as a result, not an excuse to invent one.
The NPU's active Dynamic Power Management clock state — npuclk and hclk in MHz — plus the SMU powerstate, read straight from the amdxdna debugfs nodes, independent of xrt-smi.
Why it matters: It is the first direct AMDXDNA telemetry signal — it climbs under load and drops at idle, real evidence beyond submission-counter deltas. It is a clock-state power level, never a utilization %, and reads unavailable (with a reason) when the debugfs nodes aren't exported or aren't readable.
The xdna-top exporter subcommand serves the same fused NPU+iGPU reading as Prometheus metrics at /metrics, read fresh on each scrape so Prometheus owns the history.
Why it matters: It turns point-in-time telemetry into a time series you can graph in Grafana and alert on. A failed hardware read is reported as up=0 rather than a vanished target, and it binds to loopback by default since /metrics is unauthenticated.