Event Trace Build Flow - 2022.1 English

Versal ACAP AI Engine Programming Environment User Guide (UG1076)

Document ID
Release Date
2022.1 English

The event trace build flow is as follows.

  1. Compile the graph with --event-trace and other appropriate flags.

    An example of the AI Engine compiler command for event tracing is as follows:

    aiecompiler --verbose --pl-freq=100 --workdir=./myWork \
    --event-trace-port=gmio --event-trace=runtime \
    --num-trace-streams=1 --xlopt=0 --include="./" \ 
    --include="./src" --include="./src/kernels" --include="./data" \
    • The preceding example illustrates compiling the design with--event-trace=runtime configuration. When you use this option, you can configure the type of events that AI Engine captures during runtime.
    • The --event-trace-port=gmio option uses GMIO to capture event trace data. This option uses the AI Engine-to-NoC event trace pathway. The alternative is to use PLIO which uses the AI Engine-PL pathway to capture event trace data. This uses programming logic resources to capture data from AI Engine to DDR.
    • Xilinx recommends using gmio option as the event-trace-port configuration. This option uses the AI Engine to NoC event trace pathway. This avoids the usage of programming logic resources and avoids timing errors caused by the PL resource usage.
    • GMIO = AI Engine NoC event pathway. GMIO is the default event trace port configuration.
    • PLIO = AI Engine to PL event trace pathway, in addition to also using PL resources to capture trace data.
  2. Compile and link the design using the Vitis compiler.

    After compiling the AI Engine graph application, you must build the other elements of the system as described in Integrating the Application Using the Vitis Tools Flow. With --event-trace enabled in the libadf.a file from the AI Engine compiler, the system hardware generated by the Vitis compiler includes the compiled ELF file for the PS application, the compiled ELF files for the AI Engine processors, and the XCLBIN file for the PL. These are the elements you need to run the system on hardware.

  3. After linking to create the device binary, run the Vitis compiler --package step to create the sd_card folder and files needed to boot the device, as described in Packaging. This step packages everything needed to build the BOOT.BIN file for the system. When packaging the boot files for the device, you must also specify the --package.defer_aie_run to load the AI Engine application with the ELF file, but wait to run it until graph.run directs it, as described in Graph Execution Control.

    A feature of the aiecompiler --event-trace option is that you can compile your design to capture data using the runtime argument. Using this option, you can compile the AI Engine graph to be set up for event trace, and specify the type of profile data to capture at run-time: functions, functions_partial_stalls, and functions_all_stalls. Therefore, you do not need to recompile the design to capture a different type of data. Using this feature reduces the need to recompile the graph and re-package the design.

    Table 1. Events Supported in Predefined Event Trace Levels
    Event Type Predefined Event Trace Level
    functions functions_partial_stalls functions_all_stalls
    Functions Calls/Returns Captured Captured Captured
    Stream Stalls NA Captured Captured
    Cascade Stalls NA Captured Captured
    Lock Stalls NA Captured Captured
    Memory Stalls NA NA Captured
    Functions Calls/Returns
    Event generated when kernel functions are being invoked and returned.
    Stream Stalls
    Event generated when core gets stalled. This can be due to either NO data at Input or backpressure on the stream output from the core.
    Cascade Stalls
    Event generated when core gets stalled. This can be due to either NO data at Input or due to backpressure on the stream output from the core.
    Lock Stalls
    Event generated when the core gets stalled due to the lock already being acquired.
    Memory Stalls
    Event generated when core gets stalled due to a memory conflict.