XSDB Flow - XSDB Flow - 2026.1 English - UG1076

AI Engine Tools and Flows User Guide (UG1076)
Document ID
UG1076
Release Date
2026-06-23
Version
2026.1 English
Set up xsdb as described in the following steps to connect to the device hardware.
  1. When running the application, counters capture the profile data. Debugging and profiling IP can retrieve these counters. To capture and evaluate this data, connect to the hardware device using xsdb.

    Use this command 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. To capture valid statistics, the XSDB aieprofile script must be running and sampling while the design application runs and until the application finishes. 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 you do not specify this option, 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> Allows you to set project Work directory. This is a mandatory option if config-file is not specified.
-interval Allows you to set the number of sample interval in milliseconds (default 20).
-samples Allows you to 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>] 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>] 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> 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>] 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>] 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>] 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>] 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 is 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> 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.