XRT Flow - XRT 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
  1. Burn the generated sd_card.img to the physical SD card.
  2. Create the xrt.ini file in the same location as the PS host application. An example of xrt.ini file is as follows:
    [Debug]
#
# Profile Counters
#
aie_profile = true

[AIE_profile_settings]
# Sample interval (in usec)
interval_us = 100
#   All tiles
tile_based_aie_metrics = all:heat_map
tile_based_aie_memory_metrics = all:conflicts
tile_based_interface_tile_metrics = all:s2mm_throughputs:0

    where:

    • [Debug]: Specifies the debug section for XRT, this is case sensitive.
    • aie_profile: Enables profile configuration.
    • [aie_profile_settings]: Specifies profile settings for XRT.
    • aie_profile_interval_us: Profiles data collection interval in microseconds.
    • tile_based_aie_metrics: Configures metric to be applied to the AI Engine on a tile basis.
    • tile_based_aie_memory_metrics: Configures memory metric to be applied on a tile basis.
    • tile_based_interface_tile_metrics: Configures interface metric to be applied on a tile basis.
  3. Run the design on hardware to capture profile data.
  4. Copy the generated profile files, aie_profile_*.csv, summary.csv, and xrt.run_summary, from the SD card to your design at the same level as the Work directory. Ensure the files are at the same location as the host application on the SD card.
  5. Use the Vitis IDE to import and analyze the data as described in Viewing Profile Results in the Vitis IDE.

xrt.ini Specification

[Debug]
#
# Profile Counters
#
aie_profile = true

# Subsection for AIE profile settings
[AIE_profile_settings]
# Interval in between reading counters (in us)
interval_us = 1000

# Graph/Kernel/Buffer name
graph_based_aie_metrics = <graph name|all>:<kernel name|all>:<off|heat_map|stalls|execution|floating_point|s2mm_throughputs|mm2s_throughputs|aie_trace>[:<channel>] 
graph_based_aie_memory_metrics = <graph name|all>:<kernel name|all>:<off|conflicts|dma_locks|dma_stalls_s2mm|dma_stalls_mm2s|s2mm_throughputs|mm2s_throughputs>[:<channel>]
graph_based_aie_memory_metrics = <graph name|all>:<buffer|all>:start_to_bytes_transferred:<bytes>

# AI Engine Core Metrics : Configuration can be used only once : Multiple values can be specified on a single line separated with ';'
# Single or all tiles
tile_based_aie_metrics = <{<column>,<row>}|all>:<off|heat_map|stalls|execution|floating_point|mm2s_throughputs|s2mm_throughputs|aie_trace>[:<channel>]
# Range of tiles
tile_based_aie_metrics = {<mincolumn,<minrow>}:{<maxcolumn>,<maxrow>}:<off|heat_map|stalls|execution|floating_point|mm2s_throughputs|s2mm_throughputs|aie_trace>[:<channel>]

# AI Engine Memory Metrics : Configuration can be used only once : Multiple values can be specified on a single line separated with ';'
# Single or all tiles
tile_based_aie_memory_metrics = <{<column>,<row>}|all>:<off|conflicts|dma_locks|dma_stalls_s2mm|dma_stalls_mm2s|s2mm_throughputs|mm2s_throughputs>[:<channel>]
# Range of tiles
tile_based_aie_memory_metrics = {<mincolumn,<minrow>}:{<maxcolumn>,<maxrow>}:<off|conflicts|dma_locks|dma_stalls_s2mm|dma_stalls_mm2s|s2mm_throughputs|mm2s_throughputs>[:<channel>]


# Memory Tile Metrics : Configuration can be used only once : Multiple values can be specified on a single line separated with ';'
# AIE-ML only
#     Graph/kernel based
graph_based_memory_tile_metrics = <graph name|all>:<buffer name|all>:<off|s2mm_channels|s2mm_channels_details|mm2s_channels|mm2s_channels_details|memory_stats|s2mm_throughputs|mm2s_throughputs|conflict_stats1|...|conflict_stats4>[:<channel>]
graph_based_memory_tile_metrics = <graph name|all>:<port|all>:start_to_bytes_transferred:<bytes>

#     Single or all columns
tile_based_memory_tile_metrics = <{<column>,<row>}|all>:<off|s2mm_channels|s2mm_channels_details|mm2s_channels|mm2s_channels_details|memory_stats|s2mm_throughputs|mm2s_throughputs|conflict_stats1|...|conflict_stats4>[:<channel>]
#     Range of columns
tile_based_memory_tile_metrics = {<mincolumn>,<minrow>}:{<maxcolumn>,<maxrow>}:<off|s2mm_channels|s2mm_channels_details|mm2s_channels|mm2s_channels_details|memory_stats|s2mm_throughputs|mm2s_throughputs|conflict_stats1|...|conflict_stats4>[:<channel>]

# Interface Tiles
#Graph port name
graph_based_interface_tile_metrics = <graph name|all>:<port name|all>:<off|s2mm_throughputs|mm2s_throughputs|packets>[:<channel>]
# Single or all columns
tile_based_interface_tile_metrics = <column|all>:<off|s2mm_throughputs|mm2s_throughputs|packets>[:<channel>]
# Range of columns
tile_based_interface_tile_metrics = <mincolumn>:<maxcolumn>:<off|s2mm_throughputs|mm2s_throughputs|packets>[:<channel>]
# Latency Measurement
interface_tile_latency = graph1:port1:graph2:port2:<transaction_no>
Table 1. XRT Profiling Options
Option Name Description
[Debug] This option specifies debug section for XRT, this is case sensitive.
aie_profile Enables profile configuration.
[AIE_profile_settings] This option specifies profile settings for XRT, this is case sensitive.
interval_us This option lets you set the number of sample interval in micro-seconds (default 20).
graph_based_aie_metrics = <graph name|all>:<kernel name|all>:<metric_set>[:<channel>] This option configures the AI Engine metric to be applied for all or a specific kernel in all or a specific graph. The metric is applied to the tile, even if the kernel is not alone in it.
graph_based_aie_memory_metrics = <graph name|all>:<kernel name|all>:<metric_set>[:<channel>] This option configures memory metric to be applied for all or a specific kernel in all or a specific graph. The metric is applied to the tile, even if the kernel is not alone in it.
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.
graph_based_interface_tile_metrics = <graph name|all>:<port name|all>:<metric_set>[:<channel>] This option configures the AI Engine Array Interface counter metrics set for specified graph port name.
tile_based_aie_metrics = <{<column>,<row>}|all>:<metric_set>[:<channel>] This option configures the AI Engine metric to be applied for a single tile or all tiles.
tile_based_aie_metrics = {<mincolumn,<minrow>}:{<maxcolumn>,<maxrow>}:<metric_set>[:<channel>] This option configures the AI Engine metric to be applied for all tiles in a range.
tile_based_aie_memory_metrics = <{<column>,<row>}|all>:<metric_set>[:<channel>] This option configures the AI Engine memory metric to be applied for a single tile or all tiles.
tile_based_aie_memory_metrics = {<mincolumn,<minrow>}:{<maxcolumn>,<maxrow>}:<metric_set>[:<channel>] This option configures the AI Engine memory metric to be applied for all tiles in a range.
tile_based_interface_tile_metrics = <column|all>:<metric_set>[:<channel>] This option configures the AI Engine Interface metric to be applied for a single tile or all tiles on a specified channel ID. If the channel ID is omitted, a default channel is taken.
tile_based_interface_tile_metrics = <mincolumn>:<maxcolumn>:<metric_set>[:<channel>] This option configures the AI Engine Interface metric to be applied for all tiles on a range for a specified channel ID. If the channel ID is omitted, a default channel is taken.
AI Engine-ML Only
graph_based_memory_tile_metrics = <graph name|all>:<buffer name|all>:<metric_set>[:<channels>] This option configures the Memory Tile metric to be applied for all or a specific buffer in all or a specific graph for a specified channel ID. If the channel ID is omitted, a default channel is taken.
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>[:<channels>] This option configures the Memory Tile metric to be applied for a single column or all columns for a specified channel ID. If the channel ID is omitted, a default channel is taken
tile_based_memory_tile_metrics = {<mincolumn>,<minrow>}:{<maxcolumn>,<maxrow>}:<metric_set>[:<channels>] This option configures the Memory Tile metric to be applied for a range of columns for a specified channel ID. If the channel ID is omitted, a default channel is taken
Table 2. XRT 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.

xrt.ini Examples

In the following example, no tile or graph selection is done before extracting profiling information. All used tiles are profiled with default metric sets:

[AIE_profile_settings]
tile_based_aie_metrics = all:heat_map
tile_based_aie_memory_metrics = all:conflicts
tile_based_interface_tile_metrics = s2mm_throughputs:0

This example demonstrates bounding box and tile selection:

[AIE_profile_settings]
tile_based_aie_metrics = {4,1}:{6,2}:stalls; {10,4}:execution
tile_based_aie_memory_metrics = {4,1}:dma_locks

This example bases the kernel selection on graph names. Make multiple selections on a single line separated by a semicolon:

[AIE_profile_settings]
graph_based_aie_metrics = tx_chain_0:all:execution; tx_chain_1:all:floating_point
graph_based_aie_memory_metrics = tx_chain_2:all:s2mm_throughputs

This example demonstrates how to profile multi-level hierarchical graphs:

[AIE_profile_settings]
graph-based_aie_metrics = dut.dlbf0.bf1:all:execution
Note: If the total number of performance counters used exceeds the number of available performance counters, the API does not acquire a performance counter. The API fails and displays the following error message on console.
[AIE ERROR]:    Failed to request resource 0
[AIE WARNING]:  Unable to request resources. RscType: 0
XAIEFAL: WARN: perfcount _reserve (6,1) Expect Mod= 1 resource not available.
…
Note: If you need to apply different metric sets to various kernel or tile selections, concatenate the metric sets in a single line, using semicolons to separate each set.