XRT-SMI Utility#

The xrt-smi utility helps you to verify AIE readiness, DDR connectivity, and kernel execution during the initial board boot. It provides a quick, command-line way to confirm that the hardware, drivers, and runtime stack are correctly installed and operational before deploying AI workloads, making it an essential first step for board bring-up and ongoing system health checks.

Overview#

The XRT System Management Interface (xrt-smi) is a command-line utility included with the XRT runtime package. It provides device configuration, examination, and validation capabilities.

On the AI Engine-ML v2 Board (AMD Versal VEK385), the system exposes two XRT devices:

BDF	Name	Description
`0000:00:00.0`	VE2	AIE2-PS NPU device (aie2ps, 7x36)
`0000:00:00.1`	edge	ZOCL edge device (PL/PS interface)

Important

All AI Engine-ML v2 specific xrt-smi commands must target device 0000:00:00.0 using the -d flag. The edge device (0000:00:00.1) does not support standard validation tests.

Prerequisites#

Before running xrt-smi, the PL + AIE overlay must be loaded:

fpgautil -b /overlay/x_plus_ml.pdi -o /overlay/x_plus_ml.dtbo

General Syntax#

xrt-smi [--help] [--version] [--verbose] [--batch] [--force] [command [commandArgs]]

Available top-level commands:

Command	Description
`configure`	Device and host configuration
`examine`	Status of the system and device
`program`	Download the acceleration program to a given device
`reset`	Resets the given device
`validate`	Validates the basic device acceleration functionality

xrt-smi examine#

Description#

Displays comprehensive system information, XRT software version details, driver versions, and a summary of all discovered XRT devices.

Syntax#

xrt-smi examine

Output Sections#

System Configuration — host-level information about the operating environment.

Field	Description	Example Value
OS Name	Operating system	Linux
Release	Kernel version	6.12.40-xilinx
Machine	CPU architecture	aarch64
CPU Cores	Number of available CPU cores	8
Memory	Total system RAM (MB)	19871 MB
Distribution	Linux distribution name and build	AMD Embedded Development Framework …
GLIBC	GNU C Library version	2.39
Model	Hardware board model	AMD Versal VEK385 revB

XRT — XRT runtime and driver version information.

Field	Description	Example Value
Version	XRT software version	2.23.0
Branch	Git branch of the XRT build	HEAD
Hash	Git commit hash of the XRT build	eb7059812aff4e68177b143b…
Hash Date	Timestamp of the XRT build commit	Thu, 23 Apr 2026 17:00:35 -0700
amdxdna Version	NPU kernel driver version and commit	2.23.0_20260424, 9a27eba…
zocl Version	ZOCL edge driver version and commit	2.23.0, eb70598…
CERT Firmware Version	Microcontroller CERT firmware version	1.1.0.29

Device(s) Present — all discovered XRT devices.

Field	Description
BDF	Bus:Device.Function identifier
Shell	Device shell type (`edge` or device name)
Logic UUID	UUID of the loaded logic/bitstream
Device ID	Device instance identifier
Device Ready	Whether the device is ready for use
Name	Platform name (VE2 for the NPU device)
Architecture	AIE architecture type (aie2ps for AI Engine-ML v2)
Topology	AIE array dimensions (7x36 for AI Engine-ML v2)

Example#

root@amd-edf:~# xrt-smi examine

System Configuration
  OS Name              : Linux
  Release              : 6.12.40-xilinx
  Machine              : aarch64
  CPU Cores            : 8
  Memory               : 19871 MB
  Distribution         : AMD Embedded Development Framework Linux distribution ...
  GLIBC                : 2.39
  Model                : AMD Versal VEK385 revB

XRT
  Version              : 2.23.0
  Branch               : HEAD
  Hash                 : eb7059812aff4e68177b143b183bf54c141e0782
  Hash Date            : Thu, 23 Apr 2026 17:00:35 -0700
  amdxdna Version      : 2.23.0_20260424, 9a27eba307eea1e397e06419ec29f3158982cf0c
  zocl Version         : 2.23.0, eb7059812aff4e68177b143b183bf54c141e0782
  CERT Firmware Version: 1.1.0.29

Device(s) Present
|BDF             |Shell  |Logic UUID  |Device ID     |Device Ready*  |
|----------------|-------|------------|--------------|---------------|
|[0000:00:00.1]  |edge   |0x0         |user(inst=0)  |Yes            |

|BDF             |Name  |Architecture  |Topology  |
|----------------|------|--------------|----------|
|[0000:00:00.0]  |VE2   |aie2ps        |7x36      |

xrt-smi examine –report#

Description#

Generates specific device reports for the AI Engine-ML v2 NPU. The --report flag accepts a report type to produce targeted diagnostic information about the device.

Syntax#

xrt-smi examine -d <BDF> --report <report_type>

Parameters#

Parameter	Required	Description
`-d`, `--device`	Yes	Target device BDF (use `0000:00:00.0` for AI Engine-ML v2)
`-r`, `--report`	Yes	Report type to produce (see the following table)
`-f`, `--format`	No	Output format: `JSON` or `JSON-2020.2`
`-o`, `--output`	No	Write output to the specified file

Available Report Types for AI Engine-ML v2#

To see all available report types, run:

xrt-smi examine -d 0000:00:00.0 --report --help

Report Type	Description
`all`	All known reports are produced
`aie`	AIE metadata in xclbin
`aiemem`	AIE memory tile information
`aieshim`	AIE shim tile status
`aie-partitions`	AIE partition information
`host`	Host information
`platform`	Platforms flashed on the device

–report platform#

Reports platform-specific hardware details including the platform name, power mode support, and AIE array topology.

Output Fields

Field	Description	Example Value
Name	Platform name	VE2
Power Mode	Current power mode	not supported
Total Columns	Total number of AIE columns available	36
Estimated Power	Estimated device power consumption	N/A
Temperature	Current device temperature (Celsius)	N/A

Example

root@amd-edf:~# xrt-smi examine -d 0000:00:00.0 --report platform

----------------------
[0000:00:00.0] : VE2
----------------------
Platform
  Name                   : VE2
  Power Mode             : not supported
  Total Columns          : 36

Estimated Power          : N/A
Temperature (C)          : N/A

Note

Power estimation and temperature monitoring are not currently supported on AI Engine-ML v2. These fields report N/A.

root@amd-edf:~# xrt-smi examine --device 0 --report aie-partitions

---------------------
[0000:00:00.0] : VE2
---------------------
AIE Partitions
  Total Memory Usage: N/A
  Partition Index   : 0
    Columns: [0, 1, 2, 3]
    HW Contexts:
      |PID                 |Ctx ID     |Submissions |Migrations  |Err  |Priority |
      |Process Name        |Status     |Completions |Suspensions |     |GOPS     |
      |Memory Usage        |Instr BO   |            |            |     |FPS      |
      |                    |           |            |            |     |Latency  |
      |====================|===========|============|============|=====|=========|
      |1222                |1          |5632        |0           |0    |Normal   |
      |N/A                 |Active     |5632        |0           |     |1        |
      |105 MB              |N/A        |            |            |     |1        |
      |                    |           |            |            |     |2000     |
      |--------------------|-----------|------------|------------|-----|---------|
  Partition Index   : 1
    Columns: [4, 5, 6, 7]
    HW Contexts:
      |PID                 |Ctx ID     |Submissions |Migrations  |Err  |Priority |
      |Process Name        |Status     |Completions |Suspensions |     |GOPS     |
      |Memory Usage        |Instr BO   |            |            |     |FPS      |
      |                    |           |            |            |     |Latency  |
      |====================|===========|============|============|=====|=========|
      |1222                |2          |5686        |0           |0    |Normal   |
      |N/A                 |Active     |5686        |0           |     |1        |
      |105 MB              |N/A        |            |            |     |1        |
      |                    |           |            |            |     |2000     |
      |--------------------|-----------|------------|------------|-----|---------|
  Partition Index   : 2
    Columns: [8, 9, 10, 11]
    HW Contexts:
      |PID                 |Ctx ID     |Submissions |Migrations  |Err  |Priority |
      |Process Name        |Status     |Completions |Suspensions |     |GOPS     |
      |Memory Usage        |Instr BO   |            |            |     |FPS      |
      |                    |           |            |            |     |Latency  |
      |====================|===========|============|============|=====|=========|
      |1222                |3          |5768        |0           |0    |Normal   |
      |N/A                 |Active     |5768        |0           |     |1        |
      |105 MB              |N/A        |            |            |     |1        |
      |                    |           |            |            |     |2000     |
      |--------------------|-----------|------------|------------|-----|---------|
  Partition Index   : 3
    Columns: [12, 13, 14, 15]
    HW Contexts:
      |PID                 |Ctx ID     |Submissions |Migrations  |Err  |Priority |
      |Process Name        |Status     |Completions |Suspensions |     |GOPS     |
      |Memory Usage        |Instr BO   |            |            |     |FPS      |
      |                    |           |            |            |     |Latency  |
      |====================|===========|============|============|=====|=========|
      |1222                |4          |5802        |0           |0    |Normal   |
      |N/A                 |Idle       |5801        |0           |     |1        |
      |105 MB              |N/A        |            |            |     |1        |
      |                    |           |            |            |     |2000     |
      |--------------------|-----------|------------|------------|-----|---------|

–report all#

Produces all available reports in a single command. This combines the System Configuration, XRT version, device list, and all device-specific reports (AIE core tiles, AIE memory tiles, AIE shim tiles, AIE partitions, and platform).

Output Sections

Section	Description
System Configuration	Host OS, kernel, CPU, memory, board model (same as `xrt-smi examine`)
XRT	XRT version, driver versions, CERT firmware version
Device(s) Present	All discovered devices with BDF, shell, architecture
AIE Core Tiles	Status of AIE core tile columns (active or idle)
AIE Mem Tiles	Status of AIE memory tile columns (active or idle)
AIE Shim Tiles	Status of AIE shim tile columns (active or idle)
AIE Partitions	Active hardware contexts running on the device
Platform	Platform name, power mode, total columns, power, temperature

Note

When no AIE workload is running, the AIE tile sections report “No AIE columns are active on the device” and AIE Partitions reports “No hardware contexts running on device”. These sections become populated when an xclbin is loaded and a hardware context is active.

Example

root@amd-edf:~# xrt-smi examine -d 0000:00:00.0 --report all

System Configuration
  OS Name              : Linux
  Release              : 6.12.40-xilinx
  Machine              : aarch64
  CPU Cores            : 8
  Memory               : 19871 MB
  Distribution         : AMD Embedded Development Framework Linux distribution ...
  GLIBC                : 2.39
  Model                : AMD Versal VEK385 revB

XRT
  Version              : 2.23.0
  Branch               : HEAD
  Hash                 : eb7059812aff4e68177b143b183bf54c141e0782
  Hash Date            : Thu, 23 Apr 2026 17:00:35 -0700
  amdxdna Version      : 2.23.0_20260424, 9a27eba307eea1e397e06419ec29f3158982cf0c
  zocl Version         : 2.23.0, eb7059812aff4e68177b143b183bf54c141e0782
  CERT Firmware Version: 1.1.0.29

Device(s) Present
|BDF             |Shell  |Logic UUID  |Device ID     |Device Ready*  |
|----------------|-------|------------|--------------|---------------|
|[0000:00:00.1]  |edge   |0x0         |user(inst=0)  |Yes            |

|BDF             |Name  |Architecture  |Topology  |
|----------------|------|--------------|----------|
|[0000:00:00.0]  |VE2   |aie2ps        |7x36      |


---------------------
[0000:00:00.0] : VE2
---------------------
AIE Core Tiles
  No AIE columns are active on the device

AIE Mem Tiles
  No AIE columns are active on the device

AIE Shim Tiles
  No AIE columns are active on the device

AIE Partitions
  No hardware contexts running on device

Platform
  Name                   : VE2
  Power Mode             : not supported
  Total Columns          : 36

Estimated Power          : N/A
Temperature (C)          : N/A

xrt-smi validate#

Description#

Runs the complete platform validation test suite on the specified device. For AI Engine-ML v2, this executes two tests sequentially: the latency test followed by the throughput test. Both tests use a no-operation (NOP) AIE kernel to measure the XRT command submission infrastructure overhead, independent of any actual compute workload.

Syntax#

xrt-smi validate -d <BDF> [--verbose] [--batch] [--force]

Parameters#

Parameter	Required	Description
`-d`, `--device`	Yes	Target device BDF (use `0000:00:00.0` for AI Engine-ML v2)
`-r`, `--run`	No	Run a subset of the test suite (default `all`)
`--verbose`	No	Display additional test details (for example, descriptions)
`-f`, `--format`	No	Output format: `JSON` or `JSON-2020.2`
`-o`, `--output`	No	Write output to the specified file

Available Tests on AI Engine-ML v2#

Test Name	Description
`latency`	Run end-to-end latency test
`throughput`	Run end-to-end throughput test

Note

The generic --help output lists many additional test names (aie, dma, pcie-link, etc.) that are applicable to PCIe-based datacenter accelerators. On the AI Engine-ML v2 platform, only latency and throughput are valid. Attempting to run an unsupported test returns ERROR: Invalid test name.

Test Details#

Latency Test

Measures the round-trip latency for a single AIE kernel dispatch-to-completion cycle.

What it measures: End-to-end time from the host issuing a single kernel execution command through the amdxdna driver to the AIE array, executing a NOP instruction, and returning completion status back to the host.
Method: Executes 10,000 iterations of a single NOP kernel run and computes the average latency per iteration.
Pass criteria: The test completes successfully and reports a latency value.
Typical result: ~29-31 microseconds.
What it validates: XRT/amdxdna driver command path, hardware context creation, kernel dispatch mechanism, AIE mailbox/doorbell signaling, and completion interrupt handling.

Throughput Test

Measures the sustained kernel dispatch rate (operations per second).

What it measures: The maximum number of NOP kernel executions that can be dispatched and completed per second.
Method: Executes 10,000 iterations of a single NOP kernel run and computes the operations per second based on total elapsed time.
Pass criteria: The test completes successfully and reports a throughput value.
Typical result: ~100,000-101,000 ops/s.
What it validates: XRT/amdxdna driver sustained dispatch performance, command queue efficiency, and overhead of the full host-to-AIE-to-host round trip.

Example#

root@amd-edf:~# xrt-smi validate -d 0000:00:00.0

Validate Device           : [0000:00:00.0]
    Platform              : VE2
    Power Mode            : default
-------------------------------------------------------------------------------
Test 1 [0000:00:00.0]     : latency
    Details               : Average latency: 31.0 us
    Test Status           : [PASSED]
-------------------------------------------------------------------------------
Test 2 [0000:00:00.0]     : throughput
    Details               : Average throughput: 100929.0 op/s
    Test Status           : [PASSED]
-------------------------------------------------------------------------------
Validation completed

Quick Reference#

Device Selection#

When multiple devices are present, xrt-smi requires explicit device selection. Without -d, it prompts:

NOTE: Multiple devices found. Showing help for 0000:00:00.1 device

ERROR: Please specify a device using --device option
 Available devices:
  [0000:00:00.0] : VE2
  [0000:00:00.1] : edge

Always use -d 0000:00:00.0 for AI Engine-ML v2 NPU operations.

Command Summary#

Command	Purpose
`xrt-smi examine`	System info, XRT version, device list
`xrt-smi examine -d 0000:00:00.0 --report --help`	List available report types for AI Engine-ML v2
`xrt-smi examine -d 0000:00:00.0 --report platform`	AI Engine-ML v2 platform details (columns, etc.)
`xrt-smi examine -d 0000:00:00.0 --report all`	All reports combined (AIE tiles, platform)
`xrt-smi validate -d 0000:00:00.0`	Run all validation tests
`xrt-smi validate -d 0000:00:00.0 -r latency`	Run latency test only
`xrt-smi validate -d 0000:00:00.0 -r throughput`	Run throughput test only
`xrt-smi validate -d 0000:00:00.0 --verbose`	Run all tests with descriptions

Interpreting Results#

Metric	Typical Value	What It Means
Average latency	~30 us	Single kernel dispatch round-trip time
Average throughput	~100,000 ops/s	Sustained kernel dispatch rate

Troubleshooting#

Issue	Cause	Resolution
`ERROR: Invalid test name`	Test not supported on AI Engine-ML v2	Use `latency`, `throughput`, or `all`
`ERROR: Please specify a device`	Multiple devices, no `-d` flag	Add `-d 0000:00:00.0`
`no_such_key` / core dump on `0000:00:00.1`	Edge device does not support this validate	Use `-d 0000:00:00.0` instead
Validation tests not found	PL overlay not loaded	Run `fpgautil -b ... -o ...` first

XRT-SMI Utility

Contents

XRT-SMI Utility#

Overview#

Prerequisites#

General Syntax#

xrt-smi examine#

Description#

Syntax#

Output Sections#

Example#

xrt-smi examine –report#

Description#

Syntax#

Parameters#

Available Report Types for AI Engine-ML v2#

–report platform#

–report all#

xrt-smi validate#

Description#

Syntax#

Parameters#

Available Tests on AI Engine-ML v2#

Test Details#

Example#

Quick Reference#

Device Selection#

Command Summary#

Interpreting Results#

Troubleshooting#