Using Vitis IDE and Reports - 2022.1 English

AI Engine Kernel Coding Best Practices Guide (UG1079)

Document ID
UG1079
Release Date
2022-05-25
Version
2022.1 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 window.

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 window 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 button Open New View 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/disassembler 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 (Col_Row.cc) 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

Linker memory map reports for AI Engines cores can be found in Work/aie/core_ID/Release/core_id.map. It lists the locations of the program and data memories by functions, static variables, and the software stack. From these reports, the stack size, program memory size, and global buffers, as well as their sizes can be extracted. An xml version of the linker report (core_id.map.xml) can be generated by specifying the option -Xchess=\"main:bridge.xargs=-fB\" to the AI Engine compiler.

Work/<name>.aiecompile_summary is the compilation summary that can be opened by Vitis Analyzer. Work/reports contains multiple reports for the graph compilation result such as, kernels and buffers mapping result. Refer to the Versal ACAP AI Engine Programming Environment User Guide (UG1076) for additional information about AI Engine compiler outputs.