AI Engine Stall Analysis in Vitis Analyzer - 2022.1 English

Versal ACAP AI Engine Programming Environment User Guide (UG1076)

Document ID
Release Date
2022.1 English

AI Engine execution can be stalled by stall logic from multiple sources include the following.

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, then the AI Engine will be stalled until the lock becomes unlocked.
Empty or full AXI4-Stream interfaces
The AI Engine can be stalled 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
The AI Engine can be stalled by event actions from the event unit.

When an AI Engine stalls, all memory interfaces to AI Engine including program memory interface are stalled. The stall is resolved when the cause of the stall has been fixed.

Vitis Analyzer 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.

For Vitis Analyzer to do stall analysis, it is advised to run AI Engine simulator with --online -wdb -ctf options to generate event trace information in the background.

aiesimulator --pkg-dir=./Work --online -wdb -ctf
Note: If the VCD file is needed for analysis, --dump-vcd option of AI Engine simulator can be used instead. However, note that Vitis Analyzer takes time to generate event trace from the VCD file. Especially when the design is large, the time becomes non-negligible. Therefore, it is recommended to use vcdanalyze together with AI Engine simulator to prepare event trace for Vitis Analyzer to do AI Engine stall analysis.
aiesimulator --pkg-dir=./Work --dump-vcd foo
vcdanalyze --vcd=foo.vcd --wdb --ctf
Note: Do not use --outdir option of vcdanalyze to place output data in directories other than default.

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

vitis_analyzer ./aiesimulator_output/default.aierun_summary

The following additional settings are required for AI Engine stall analysis in Vitis Analyzer working in the HW emulation flow.

  1. Write a simulator option file (for example, sim_options.txt) with content:
  2. Launch HW emulation with options:
    ./ -aie-sim-options ./sim_options.txt -add-env AIE_COMPILER_WORKDIR=<ABSOLUTE_PRJ_PATH>/Work
  3. Optionally run vcdanalyze:
    cd ./sim/behav_waveform/xsim/; vcdanalyze --pkg-dir=../../../Work --vcd=foo.vcd --wdb –ctf
  4. Launch Vitis Analyzer:
    vitis_analyzer ./sim/behav_waveform/xsim/default.aierun_summary