Enabling AI Engine Status Generation - 2025.2 English - UG1701

Embedded Design Development Using Vitis User Guide (UG1701)
Document ID
UG1701
Release Date
2025-11-20
Version
2025.2 English

The AI Engine provides the ability to output a summary of AI Engine status, which include error events that have occurred. Warnings are also issued when a deadlock is detected in the hardware. The status and warnings can be further analyzed in the AMD Vitis™ IDE for debug purposes.

There are two ways to output AI Engine status when running designs in hardware.

Automated and periodic AI Engine status output
After initial setup in xrt.ini, this method requires minimal user intervention, because the tool will output periodic status at specified time intervals.
Manual output the AI Engine status
You must run a command each time you want a status output report.

Next, you can open the status output in the IDE for further analysis.

The following section covers the steps needed to obtain status output, and analysis of that output. For more details on understanding stalls, see the chapter on AI Engine Stall Analysis in AI Engine Tools and Flows User Guide (UG1076).

Periodic AI Engine Status Output Using XRT

You can enable the runtime deadlock detection and status output using the xrt.ini file. This is a one-time set up, which results in periodic output of status data, including deadlock detection. To turn on this feature, add the following to the xrt.ini file: 
[Debug]
aie_status=true
To specify the interval of probing and analysis the AI Engine status, use the code below.
[Debug]
aie_status=true
aie_status_interval_us=1000

The AI Engine status is copied to the following files when the host program is running.

  • xrt.run_summary: Run summary information that can be used by the IDE. 
  • aie_status_<device>_<current time>.json: Status of AI Engine, AI Engine memory and AI Engine Interface tiles.
  • summary.csv: Always created for other profiling capabilities, like guidance.

For more details, see the chapter on Generating AI Engine Status in AI Engine Tools and Flows User Guide (UG1076).

Generating AI Engine Status Using XSDB

It is possible to examine the status of the AI Engine using XSDB both on Linux and Bare metal operating systems. This feature allows you to debug applications and detect the status of the AI Engine in situations where the board is in a deadlock or hung state. Unlike the xrt-smi command which requires XRT, the XSDB command is run independent of XRT.

XSDB reports the AI Engine status in .json file format using the aiestatus examine command. You can use this command before, during and after running the application.

XSDB command is very simple:aiestatus examine

For all available options, see the chapter on Generating AI Engine Status using XSDB in AI Engine Tools and Flows User Guide (UG1076).