Trace Offload Methodology - 2025.2 English - UG1076

This section lists the requirements and explains 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: Setting the event tracing port to GMIO prevents HSDP from offloading the AI Engine trace.
• After compiling the AI Engine graph and C/C++ kernels, and packaging any RTL kernels, the v++ --link command links them with the target platform to generate the XSA file. 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.

  This process instantiates a new HSDP IP for AI Engine trace offload and connects all PLIO event trace streams to it.

• Only use the host program with XRT APIs controlling the AI Engine graph 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. You need to connect the Versal device evaluation board when the SmartLynq+ set up is complete.
• You can access the SmartLynq+ module by a host system using the USB 3.0 connection. The USB 3.0 Host Connection provides driver setup information for both Windows and Linux environments.
• 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 device evaluation board, perform the following steps:

1. Power on the Versal device evaluation board and SmartLynq+ module.
2. Observe the Linux boot messages in the minicom application. You can use the SmartLynq+ module as a serial terminal to remotely view the UART output from the Versal device evaluation board. Use the pre-installed minicom application to do this.
3. Launch XSDB from the local directory that contains the Work/ directory of your AI Engine design.
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:all_stalls -work-dir <WORK_DIR> -link-summary <*.xsa.link_summary>

   Note: You can 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. Ensure the xrt.ini file does not contain any AI Engine trace configurations which conflict 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. Use the hw_analyze command to process the dump trace and generate the .wdb file. The .wdb file can be used in the 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. The trace information looks as shown below.
    
    

Limitations

• Hardware supports AI Engine trace offload via HSDP, but hardware emulation does not.
• 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.