Deadlock Detection using XSDB - 2022.2 English

AI Engine Tools and Flows User Guide (UG1076)
Document ID
UG1076
Release Date
2022-10-19
Version
2022.2 English

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 xbutil 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.

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 support options are defined as follows:

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_control_config.json file.
Note: Needed only when no work directory is provided. The default value used 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 two examples below.
xsdb% source $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.

The commands above can be run anytime before, during or after running the application, where the board is running the design or is in a deadlocked or hung state. The command produces a JSON file, <aie_status_<date_time>.json>, which is located in the directory where you run the command. An example file name is aie_status_2022_08_11_113542.json. This file can be opened in Vitis™ Analyzer, and the status can be viewed and analyzed. To read the status registers of AI Engine tiles before running the application, run the aiestatus command prior to running the host application on the board.

The sample XSDB console after running the aiestatus examine command is shown below.

Figure 1. XSDB Console
Note: In the sample XSDB console above, the option -graphs is not specified and the command targets all graphs in the AI Engine application.

Also observe 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 Vitis Analyzer

  1. Open Vitis™ Analyzer, and select File > Import Xbutil/Xsdb JSON output.
  2. In the dialog box, specify the .json file, as well as the AI Engine Compile Summary file and Run Summary file to be generated.
    Figure 2. Import Xbutil/Xsdb JSON Output
  3. After you click OK, a new summary file is generated in current working directory. The Vitis Analyzer window opens the summary file as shown below.
    Figure 3. Summary View in Vitis Analyzer

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

Figure 4. Array View

This aie_status.run_summary file can be used to view and analyze the status results in Vitis Analyzer in the future.

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 file along with the .json file, which can be opened in Vitis analyzer.

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