Trace Offload Methodology - 2023.2 English

AI Engine Tools and Flows User Guide (UG1076)

Document ID
Release Date
2023.2 English

This section lists out the requirements and explain how to build a system that uses the SmartLynq+ module and the HSDP.

Compile, Link, and Package

  • Compile the AI Engine design using the -event-trace-port=plio option. This sets the event tracing port to PLIO.
    Note: If the event tracing port is set to GMIO, the AI Engine trace cannot be offloaded via HSDP.
  • After the AI Engine graph and the C/C++ kernels are compiled, and any RTL kernels are packaged, the Vitis v++ --link command links them with the target platform to build the platform file (XSA). For offloading the AI Engine trace via HSDP, it is required to add the –profile.aie_trace_offload=HSDP option to the v++ -link command.

    With this, a new HSDP IP gets instantiated for AI Engine trace offload and all the PLIO event trace streams are connected to the HSDP IP.

  • Only the host program with XRT APIs controlling the AI Engine graph should be used for offloading AI Engine trace via HSDP.
  • Package the HSDP enabled XSA file generated during linking step and libadf.a to generate a sd_card image.

Setup SmartLynq+ Module, and Connect to Versal Device

  • You must download and install the latest microSD card image and SmartLynq+ application package to set up the SmartLynq+ module correctly. For more information on this installation process, see Downloading and Installing SW Tools. Once the setup of SmartLynq+ is done, you need to connect the Versal device evaluation board.
  • The SmartLynq+ module can be accessed by a host system using the USB 3.0 connection. The driver setup information for both Windows and Linux environments is provided in the USB 3.0 Host Connection.
  • For more information on connecting the Versal device evaluation board, see Connection to Versal Evaluation Boards SmartLynq+ Module User Guide (UG1514).
    Note: Embedded Design Tutorial walks you through a system design example for High-Speed Debug Port with SmartLynq+ module.
  • Additional information on overview of the SmartLynq+ module for the Versal adaptive SoCs is available in SmartLynq+ Module User Guide (UG1514).

Launch XSDB, and Offload Trace Information

After loading the HSDP enabled Linux image on Versal Evaluation board board,

  1. Power on the Versal Evaluation board and SmartLynq+ module.
  2. Observe the Linux boot messages in the minicom application (SmartLynq+ module can be used as a serial terminal to remotely view the UART output from the Versal board using the pre-installed minicom application).
  3. Launch XSDB from your local directory, where the AI Engine design Work/ directory is located.
  4. Source the aie_trace.tcl script using the command source $::env(XILINX_VITIS)/scripts/vitis/util/aie_trace.tcl.
  5. Start the AI Engine trace using the following command:
    aietrace start -graphs <GRAPH_NAME> -graph -based -aie -tile -metrics all:all:functions_all_stalls- work-dir <WORK_DIR> - link -summary <*.xsa.link_summary>
    Sample XSDB console should look as follows.

    Note: You should be able to use all the options specified in XSDB Flow. However, the options -base-address and -depth are not applicable for HSDP offload. XSDB issues an error if you try to use these options.
  6. Run the application on the hardware. Make sure xrt.ini file does not contain any AI Engine trace configurations which conflicts with the configuration given by XSDB.
  7. Stop AI Engine trace using the command aietrace stop. You should see the file hsdp_event_trace0.txt corresponding to the AI Engine trace and a JSON file that contains event configuration.

  8. Now, the dumped trace should be processed using the hw_analyze command to generate the .wdb file which can be used in Vitis IDE.
    hwanalyze --pkg-dir=<WORK_DIR> --trace=hsdp_event_trace_aie.txt --trace_config=<PATH_TO_JSON> -wdb
  9. Launch the Vitis IDE and open the .wdb file to analyze the event trace.
  10. Currently, new Vitis IDE analysis view do not support invoking the standalone waveform debug files (.wdb,.wcfg). To use this feature, use vitis_analyzer --classic.
  11. The trace information looks as shown below.


  • The AI Engine trace offload via HSDP is supported only in Hardware and not for Hardware emulation.
  • Supported only for non-DFx platform.
  • Supports only when the -event-trace-port is set to PLIO and not GMIO.
  • XRT-based trace offload is not supported.