XSDB Flow - XSDB Flow - 2025.1 English - UG1076

AI Engine Tools and Flows User Guide (UG1076)
Document_ID
UG1076
Release_Date
2025-05-29
Version
2025.1 English
Set up xsdb as described in the following steps to connect to the device hardware.
  1. When running the application, the profile data is captured in counters that can be retrieved by the debugging and profiling IP. To capture and evaluate this data, you must connect to the hardware device using xsdb. This command is typically used to program the device and debug applications. Connect your system to the hardware platform or device over JTAG, launch the xsdb command in a command shell, and run the following sequence of commands:
    xsdb% connect
xsdb% ta 1
xsdb% source $::env(XILINX_VITIS)/scripts/vitis/util/aie_profile.tcl
xsdb% aieprofile start -graphs myGraph -work-dir ./Work \
      -graph-based-aie-metrics "dut:kernel1:heat_map" \
      -tile-based-aie-metrics "all:stalls" \
      -graph-based-aie-memory-metrics "dut:all:write_throughputs" \
      -tile-based-aie-memory-metrics "{4,1}:{6,2}:conflicts; {8,3}:dma_locks" \
      -tile-based-interface-tile-metrics "2:10:input_throughputs:3" \
      -interval 20  -samples 100

    where:

    • connect: Launches the hw_server and connects xsdb to the device.
    • source $::env(XILINX_VITIS)/scripts/vitis/util/aie_profile.tcl: Sources the Tcl trace command to set up the xsdb environment.
  2. Run the design on hardware to generate hardware profile data. The XSDB aieprofile script should still be running and sampling while the design application runs and until application finishes in order to capture valid statistics. The -samples and -interval switches can be adjusted accordingly to ensure this.
  3. Use vitis_analyzer to import and analyze the data, as described Viewing Profile Results in the Vitis IDE.

aieprofile Command Synopsis

aieprofile start [options] -tiles <tile-list>
aieprofile start [options] -graphs <graph-list>
Table 1. aieprofile Options
Option Name Description
-config-file <json-file> The JSON file generated by the AI Engine compiler at Work/ps/c_rts/aie_trace_config.json with profile configuration data. This file can also be created for custom profile configuration. You can alternatively specify the -work-dir option instead of config-file.
start AI Engine profiling starts. Instructs the DPA IP to begin capturing profile data based on configuration.
-graphs <graph-list> This option allows you to set one or more graphs used in the AI Engine application. If this option is not specified, profiling is enabled for all available graphs.
-tiles <tile-list> This option allows you to select one or more tiles to profile. Tiles can be in the format of col, row (for example, 0,1 or 2,5). All the tiles in a row or column can be specified using wildcard '*' (for example, 0,* to select all tiles in column 0).
# This example profiles tile (10,2) and all tiles in column 5
xsdb% aieprofile start [options] -tiles 10,2;5,*
Note: The column index starts at 0. The row index starts at 1 and not at 0.
-work-dir <dir-path> This option lets you set project Work directory. This is a mandatory option if config-file is not specified.
-interval This option lets you set the number of sample interval in milliseconds (default 20).
-samples This option lets you set the exact number of counter samples (default 100) used in profiling the application.
-graph-based-aie-metrics <graph name|all>:<kernel name|all>:<metric_set>[:<channel>] This option allows you to set the AI Engine counter metrics set for specified graphs and kernels. Valid values are heat_map, stalls, execution, floating-point, stream_put_get,s2mm_throughputs, mm2s_throughputs and aie_trace.
Note: You can specify multi-level hierarchy graphs, as follows: -graph-based-aie-metrics <graph.subgraph1.subgraph2/all>:<kernel_name|all>:<metric_set>
-tile-based-aie-metrics <{<column>,<row>}|all>:<metric_set>[:<channel>] Sets the AI Engine counter metrics set for specified tiles. Valid metrics as above.
-tile-based-aie-metrics {<mincolumn,<minrow>}:{<maxcolumn>,<maxrow>}:<metric_set>[:<channel>] Sets the AI Engine counter metrics set for specified tiles in a range. Valid metrics as above.
-graph-based-aie-memory-metrics <graph name|all>:<kernel name|all>:<metric_set>[:<channel>] This option allows you to set the AI Engine memory module counter metrics set for specified graphs and kernels. Valid values are conflicts, dma_locks, dma_stalls_s2mm, dma_stalls_mm2s, s2mm_throughputs and mm2s_throughputs.
-graph-based-aie-memory-metrics <graph name|all>:<buffer|all>:start_to_bytes_transferred:<bytes> This options allows you to measure the throughput of a buffer from 0 to bytes transferred for all or a specific buffer in all or a specific graph.
-tile-based-aie-memory-metrics = <{<column>,<row>}|all>:<metric_set>[:<channel>] This option allows you to set the AI Engine memory module counter metrics set for specified tiles. Valid metrics as above.
-tile-based-aie-memory-metrics = {<mincolumn,<minrow>}:{<maxcolumn>,<maxrow>}:<metric_set>[:<channel>] Sets the AI Engine memory module counter metrics set for specified tiles in a range. Valid metrics as above.
-graph-based-interface-tile-metrics = <graph name|all>:<port name|all>:<metric_set>[:<channel>] This options allows you to set the AI Engine Array Interface counter metrics set for specified graph port name. Valid metrics are input_throughputs (mm2s_throughputs), output_throughputs (s2mm_throughputs), input_stalls (mm2s_stalls), output_stalls (s2mm_stalls),packets.
-tile-based-aie-metrics <column|all>:<metric_set>[:<channel>] This option allows you to set the AI Engine interface tile counter metrics set for specified tiles. Valid metrics as above.
-tile-based-aie-metrics <mincolumn>:<maxcolumn>:<metric_set>[:<channel>] This option allows you to set the AI Engine interface tile counter metrics set for specified tiles. Valid metrics as above.
AIE-ML Specific Options
-graph-based-memory-tile-metrics "<graph name|all>:<buffer name|all>:<metric_set>[:<channel>]" This option configures the Memory Tile metric to apply to one or more buffers in one or more graphs for a specified channel ID. If the channel ID is omitted, a default channel will be taken. Valid metrics are input_channels (s2mm_channels), output_channels (mm2s_channels), input_channels_details (s2mm_channels_details), output_channels_details (mm2s_channels_details), memory_stats, input_throughputs (s2mm_throughputs), output_throughputs (mm2s_throughputs), conflict_stats1 to conflict_stats4.
-graph-based-memory-tile-metrics <graph name|all>:<port|all>:start_to_bytes_transferred:<bytes> This options allows you to measure the throughput of a port from 0 to bytes transferred for all or a specific port in all or a specific graph.
-tile-based-memory-tile-metrics "<{<column>,<row>}|all>:<metric set>[:<channel>]" This option configures the Memory Tile metric to apply to one or more columns for a specified channel ID. If the channel ID is omitted, a default channel is taken. Valid metrics as above.
-tile-based-memory-tile-metrics "{<mincolumn>,<minrow>}:{<maxcolumn>,<maxrow>}:<metric set>[:<channel>]" This option configures the Memory Tile metric to apply for a range of columns for a specified channel ID. If the channel ID is omitted, a default channel is taken. Valid metrics as above.
Table 2. aieprofile Options for Latency Measurement
Option Name Description
-interface-tile-latency graph1:port1:graph2:port2:<tranx_no> This option configures the interface tiles specified by graph1:port1 and graph2:port2 to allow the latency of the nth transaction from input to output of the AI Engine Array to be measured.