AI Engine Stall Analysis in the Vitis IDE - 2025.2 English - UG1076

The following stall logic sources can stall AI Engine execution:

External memory-mapped AXI4 master

Any external AXI4 master (for example, PS) can issue a stall signal to a specific AI Engine.

Lock modules

AI Engine has access to locks for hardware synchronization. When acquiring a lock, if the core does not get a lock, the AI Engine stalls until the lock becomes unlocked.

Empty or full AXI4-Stream interfaces

The AI Engine can stall when reading from an empty input FIFO or writing to a full output FIFO.

Data memory collisions

Memory stall can occur between two different AI Engines or when one AI Engine tries to access a single memory bank. (For example, trying to load and store in the same cycle to the same memory bank.)

Event actions from the event unit

Event actions from the event unit can stall the AI Engine.

When an AI Engine stalls, all memory interfaces to AI Engine including program memory interface also stall. The stall resolves when the cause of the stall is fixed.

The IDE can use the VCD trace from AI Engine simulation to do stall analysis that shows an overview of the stall status in metrics. It also helps you detect where the stall happens and the possible causes.

You can perform stall analysis in the IDE. To perform stall analysis, run the AI Engine simulator with --online -wdb -text options. Running this command generates event trace information in the background.

aiesimulator --pkg-dir=./Work --online -wdb -text

aiesimulator --pkg-dir=./Work --dump-vcd foo
vcdanalyze --vcd=foo.vcd --wdb --text

For the steps to launch the IDE to view the AI Engine simulation result, see Viewing the Run Summary in the Vitis IDE.

vitis -a ./aiesimulator_output/default.aierun_summary

For AI Engine stall analysis in the Vitis IDE working in the HW emulation flow, you need to apply the following additional settings:

1. Write a simulator option file (for example, sim_options.txt) with content:

   AIE_PKG_DIR=<ABSOLUTE_PRJ_PATH>/Work
   AIE_DUMP_VCD=foo

2. Launch HW emulation with options:

   ./launch_hw_emu.sh -aie-sim-options <ABSOLUTE_PATH_TO>/sim_options.txt

3. Optionally run vcdanalyze:

   cd ./sim/behav_waveform/xsim/; vcdanalyze --pkg-dir=../../../Work --vcd=foo.vcd --wdb –text

4. Launch the Vitis IDE:

   vitis -a ./sim/behav_waveform/xsim/default.aierun_summary

   Note: The system generates default.run_summary for third-party simulators as follows:

   • AI Engine: Generated for Questa, Vcs, Xcelium, and Riviera
   • AI Engine-ML: Generated for Questa, and VCS only