Using Vitis IDE and Reports - 2022.2 English

AI Engine Kernel and Graph Programming Guide (UG1079)

Document ID
Release Date
2022.2 English

Vitis IDE manages the system project with an AI Engine graph, PL kernels, and PS application. Vitis IDE provides visual views for AI Engine kernel development and it is essential in kernel, as well as PS application debugging.

Vitis IDE provides a single node graph example that can be used as a starting point for single kernel development. Vitis IDE has a debug view which displays registers, variables, available breakpoints, variables to register/memory mapping, internal/external memory contents and disassembly view for instructions. And for a single AI Engine tile design, it also shows the instruction pipeline (Pipeline view) and Runtime Statistics view.

When launching the debug perspective, if Generate Profile is selected in debug configurations, it will show the printf output in console and the Runtime Statistics view will show real-time cycle count when stepping through instructions. The Generate Trace check box in debug configurations is for generating event trace data which helps better understand when and how events such as memory stall and stream stall have occurred. Event trace is helpful in performance tuning.

Figure 1. Debug Configurations

In debug perspective, debug commands resume, and step into, as well as step over are available. The AI Engine source code is shown and it is possible to set breakpoint by double-clicking lines. The windows Variables, Breakpoints, and Registers are available to look into data memory or register status. The Disassembly view is helpful in understanding how intrinsics are used, especially how they are scheduled in pipeline. In the Disassembly view, the Open New View button can be used to open a new active window. Pipeline view allows you to correlate instructions executed in a specific clock cycle with the labels in the microcode/Disassembly view.

Note: The pipeline view is only available for single AI Engine design and it is only enabled when the Generate Profile check box is checked when debug is started.
Figure 2. Debug Code

The generated code for an AI Engine ( includes the AI Engine kernels in the core and wrapper code. From the AI Engine wrapper code, you can step into the AI Engine kernel code by clicking multiple step-in buttons. Alternatively, you can also open the AI Engine kernel source file from the design perspective and set breakpoints in the file. Multiple views, such as the disassembly view, pipeline view, memory view, register view, and variables view can be used for debug, as well as performance tuning.

Note: The number of breakpoints are limited to four for each tile. To set new breakpoints, beyond the number allowed, you must clear existing breakpoints. The tool will issue error messages if you try and set breakpoints beyond the number allowed.

The disassembly view displays the compiler generated microcode target to the hardware. C/C++ source code can also be embedded between the lines for source code referencing. The microcode helps understand the compiled result, especially the loop pipelining result. The following figure shows the microcode generated for a pipelined loop. By scrolling or stepping in the disassembly view, the loop in the kernel can be found. The loop iterates from zero-overhead loop start (ZLS) to zero-overhead loop end (ZLE). It can be seen how load instructions and MAC instructions are placed to be pipelined. The preamble and postamble instructions are placed before and after the zero-overhead loop body to fill and flush the pipeline stages.

Figure 3. Disassembly View for Loop Pipelining