XRT Flow - 2022.2 English

AI Engine Tools and Flows User Guide (UG1076)

Document ID

UG1076

Release Date

2022-10-19

Version

2022.2 English

The XRT flow is as follows:

Burn the generated sd_card.img to the physical SD card.

Create the xrt.ini file in the sd_card folder as described in this section to enable xrt flow.

An example xrt.ini file is shown below.


# Main switch to turn on aie trace
[Debug]
aie_trace = true
# Continuous trace knobs
[AIE_trace_settings]
reuse_buffer = true
periodic_offload = true
# Time to wait between trace reads
buffer_offload_interval_us = 100
# Total amount of device memory shared between trace streams
buffer_size = 16M
# granularity
graph_based_aie_tile_metrics = all:all:functions

Run the design on hardware to trace hardware events.
Copy the captured trace data from the sd_card folder to your design at same level as the design Work directory. The trace data is generated in the same location as the host application on the SD card. They are xrt.run_summary, aie_event_runtime_config.json, and aie_trace_N.txt.
Use the Vitis Analyzer to import and analyze data with this command.
```
vitis_analyzer xrt.run_summary
```

Note: The aie_trace_* settings in the .ini file will be deprecated in a future release. It is recommended to use the equivalent settings in the [AIE_trace_settings] section as shown.

XRT.INI Specification

[Debug]
aie_trace = true 

# Section for AIE trace settings
[AIE_trace_settings]

# Size of AIE trace buffer in DDR (Format: <Integer>[K|k|M|m|G|g]; Default: 1M)
buffer_size = 100M 

# Graph/Kernel name
graph_based_aie_tile_metrics = <graph name|all>:all:<off|functions|functions_partial_stalls|functions_all_stalls>[:memory_stalls|stream_stalls|cascasde_stalls|lock_stalls>] 

# AI Engine Tiles
# Single or all tiles
tile_based_aie_tile_metrics = <{<column>,<row>}|all>:<off|functions|functions_partial_stalls|functions_all_stalls>[:<memory_stalls|stream_stalls|cascasde_stalls|lock_stalls>]

# Range of tiles
tile_based_aie_tile_metrics = {<mincolumn,<minrow>}:{<maxcolumn>,<maxrow>}:<off|functions|functions_partial_stalls|functions_all_stalls>[:<memory_stalls|stream_stalls|cascasde_stalls|lock_stalls>]

Table 1. XRT Trace Options
Option	Description
`aie_trace=true`	Enables AI Engine event trace during application execution.
`trace_buffer_size=100M`	Sets the size of the event trace buffer in DDR memory.
`reuse_buffer = true`	Enables the reuse of trace buffer in DDR memory. When this option is enabled, the DDR trace buffer is treated as a circular buffer, and trace data is continuously offloaded from XRT. This option only applies to event trace data being captured using PLIO trace. Default is `false`.
`periodic_offload = true / false`	Enable offloading of trace data from DDR to XRT at regular intervals while the application is running. The default option is set to true. This option when used in combination with the "reuse_buffer" option enables continuous offloading of trace data, while not running out of trace buffer memory. This option only applies to event trace data being captured using PLIO trace.
`offload_interval_us = 10`	Specify the frequency, in milliseconds, of how often the trace events data is read from the trace buffers in DDR memory to the buffers in XRT. This option is effective only when `periodic_offload=true`.This option only applies to event trace data being captured using PLIO trace. Default is `100`
`file_dump_interval_s = 3`	Specify the frequency, in seconds, of how often the trace events data is read from the trace buffer in XRT and appended to the event trace files in the SD card. This option is effective only when `periodic_offload=true`. Default is `5`
`graph_based_aie_tile_metrics = <graph name\|all>:all:<off\|functions\|functions_partial_stalls\|functions_all_stalls>`	This option configures the AI Engine event trace metric to be applied for all kernels in all or a specific graph. The metric is applied to the tile, even if there are multiple kernels running on the tile.
`tile_based_aie_tile_metrics = <{<column>,<row>}\|all>:<off\|functions\|functions_partial_stalls\|functions_all_stalls>`	This option configures the AI Engine event trace metric to be applied for a single tile or all tiles.
`tile_based_aie_tile_metrics = {<mincolumn,<minrow>}:{<maxcolumn>,<maxrow>}:<off\|functions\|functions_partial_stalls\|functions_all_stalls>`	This option configures the AI Engine event trace metric to be applied for all tiles in a range.

XRT.INI Examples

# Example 1 : trace function events for all tiles used in the AI Engine array 
[AIE_trace_settings]
tile_based_aie_tile_metrics = all:functions 

# Example 2 : trace function events in all the kernels in all graphs (Similar to the example above)
[AIE_trace_settings]
graph_based_aie_tile_metrics = all:all:functions 

# Example 3 : trace all function stalls events on all used tiles 
[AIE_trace_settings]
tile_based_aie_tile_metrics = all:functions:functions_all_stalls 

# Example 4 : trace function events within the bounding box of tiles or on specific tiles
[AIE_trace_settings]
tile_based_aie_tile_metrics = {4,1}:{6,2}:functions_all_stalls; {4,1}:functions 

# Example 5 : trace events specified by graph name
[AIE_trace_settings]
graph_based_aie_tile_metrics = chain_0:all:functions; chain_1:all:functions_all_stalls; chain_2:all:functions_partial_stall 

# Example 6 : trace functions_all_stalls events all kernels in all graphs and trace function events occuring in all kernels  in the graph chain_0 
[AIE_trace_settings]
graph_based_aie_tile_metrics = all:all:functions_all_stalls; chain_0:all:functions 

# Example 7 : Trace graphs and all kernels function events and override tile 4,1 with functions all stalls
[AIE_trace_settings]
graph_based_aie_tile_metrics = all:all:functions
tile_based_aie_tile_metrics = {4,1}:functions_all_stalls 

# Example 8 : Trace all graphs and all kernels function events and turn off trace in tile 4,1
[AIE_trace_settings]
graph_based_aie_tile_metrics = all:all:functions
tile_based_aie_tile_metrics = {4,1}:off