Generating AI Engine Status using XSDB - 2025.2 English - UG1076

AI Engine Tools and Flows User Guide (UG1076)
Document ID
UG1076
Release Date
2025-11-20
Version
2025.2 English

You can examine the status of the AI Engine using XSDB on both Linux and Bare-metal operating systems. You can use this status to debug applications and detect the status of the AI Engine when the board is in a deadlock or hung state. Unlike the xrt-smi command, the XSDB command is run independently 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.

Details about the XSDB command aiestatus examine and options are explained below.

Command

aiestatus examine

Supported Options

aiestatus examine [-graphs] <graph-list> [-work-dir] <dir-path> [-aie-version] <version> [-file] <file-name> [-run-summary] [-target-name] <target-name> [-tiles] <tile-list>

The following table details the supported options.

Table 1. Supported Options
Options Description
-graphs Specify the list of one or more graphs used in the AI Engine application. If this option is not specified, the command targets all graphs in the design.
-work-dir Specify the AI Engine project Work directory. This is a mandatory option.
-aie-version Specify the AI Engine hardware generation number, available as hw_gen value in Work/ps/c_rts/aie_trace_config.json file.
Note: Required when no work directory is provided. The default value is 1.
-file Specify the name of the output file in .json format generated by the command. This is not a mandatory option.
-run-summary Enables option to generate a run summary file in addition to the .json file. This is not a mandatory option.
-target-name Specify the name of target to connect.
Note: Default target is Versal. To see different targets available, type the command connect followed by targets in XSDB terminal.
-tiles Specify a list of one or more tiles used by the AI Engine application and that will be monitored by the command. Tiles can be in the format of col,row (ex. 0,0; 0,1). All the tiles in a row or column can be specified using wildcard '*' (ex. 0,*; *,1; *,*)

Command Examples

Source the aie_status Tcl script in XSDB terminal as shown in the following two examples.
xsdb% source $::env(XILINX_VITIS)/scripts/vitis/util/aie_status.tcl
Example 1
Specifying graph and work directory.
aiestatus examine -work-dir ./Work -graphs dut

This example examines and reports the status of the graph named dut.

Example 2
Specifying tiles.
aiestatus examine -tiles 10,2;5,*

This example examines and reports the status of tile (10,2) and all tiles in column 5.

You can run the above commands before, during, or after the application runs. This applies whether the board is running the design, is deadlocked, or is in hung state. The command produces a JSON file, <aie_status_<date_time>.json>, in the directory where you run the command. An example file name is aie_status_2022_08_11_113542.json. This JSON file can be opened in the AMD Vitis™ IDE, and you can view and analyze the status. Run the aiestatus command to read the status registers of AI Engine tiles prior to running the host application on the board.

The following figure shows the sample XSDB console after running the aiestatus examine command.

Figure 1. XSDB Console
Note: The sample XSDB console above does not specify the option -graphs. The command targets all graphs in the AI Engine application.

Also observe that the command returns the status registers of all the AI Engine tiles corresponding to the graph specified in the command.

Opening the JSON file in the Vitis IDE

  1. Open the Vitis IDE, and select the Import xrt-smi/Xsdb JSON output option.
  2. In the dialog box, specify the .json file, as well as the AI Engine Compile Summary file and Run Summary file to generate.
    Figure 2. Import xrt-smi/Xsdb JSON Output
  3. Click OK. The current working directory updates with a new summary file. The Analysis view opens the summary file as shown below.
    Figure 3. Summary View

You can navigate to the Graph or Array view, and observe the status of the AI Engine tiles. The following figure shows the status of stalled AI Engine tiles.

Figure 4. Array View

You can use the aie_status.run_summary file to view and analyze the status results in Vitis IDE.

Alternatively, you can also run the aiestatus command with the -run-summary option as shown below. 

aiestatus examine -work-dir ./Work -graphs dut -run-summary

This command generates the aie_status.run_summary and .json files, which can be opened in the IDE.

Recommended: Use -run-summary option along with -work-dir option to seamlessly open and analyze the summary file in the Vitis IDE.