Event Trace Build Flow - 2024.1 English

AI Engine Tools and Flows User Guide (UG1076)

Document ID
UG1076
Release Date
2024-05-30
Version
2024.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:

    v++ --c --mode aie --verbose --pl-freq=100 --workdir=./myWork \
    --event-trace-port=gmio --event-trace=runtime \
    --num-trace-streams=8 --xlopt=0 --include="./" \ 
    --include="./src" --include="./src/kernels" --include="./data" \
    ./src/graph.cpp

    For examples using the unified command line interface, see Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393).

    Note:
    • 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.
      • gmio is the AI Engine NoC event pathway. GMIO is the default event trace port configuration.
      • plio is the AI Engine to PL event trace pathway. Event data get transferred to the PL where it is stored within BRAMs and URAMs resources. This PL resource add-on can induce timing errors on the hardware design side.
      Note: The compiler option --graph-iterator-event should be used to delay the event trace data based on the graph iteration. For more information on delaying the event trace, see Table 1 in XSDB Flow, or Table 1 in XRT Flow.
  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 Building and Running the System in Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393). 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 Versal Designs in Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393). 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 in AI Engine Kernel and Graph Programming Guide (UG1079).

    A feature of the AI Engine compiler --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 runtime: functions, partial_stalls, and 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 partial_stalls 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 cascade stream Input or due to backpressure on the cascade 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.
    Note: Metrics <functions_all_stalls> and <functions_partial_stalls> are renamed to all_stalls and partial_stalls respectively for runtime configuration.