Using System Trace - Using System Trace - 2026.1 English - UG1702

Building for Trace Capture

System Timeline Trace requires two build-time steps:

• Enable AI Engine event trace in an AI Engine compiler --config file.
• Enable PL data trace at the v++ link stage.

The AI Engine compiler configuration file selects the trace transport. AMD recommends the GMIO option because it uses the AI Engine-to-NoC path and does not consume PL resources:

[aie]
event-trace=runtime
broadcast-enable-core=true
event-trace-port=gmio
xlopt=0

The PLIO option uses the AI Engine-to-PL path. It supports more aggregate trace bandwidth, but it uses PL logic and block RAM or UltraRAM:

[aie]
event-trace=runtime
broadcast-enable-core=true
event-trace-port=plio
num-trace-streams=4
trace-plio-width=128
xlopt=0

The following table summarizes the AI Engine compiler flags that affect System Timeline Trace. For the full reference, see Event Tracing Options in the AI Engine Tools and Flows User Guide (UG1076) .

The broadcast-enable-core flag controls cross-tile alignment in System Timeline Trace. Without this setting, AI Engine kernels can start more than 100 clock cycles apart, which is about 100 ns at a 1 GHz AI Engine clock. When you enable this setting, all kernels associated with a graph start within a few clock cycles of each other. For background information, see Troubleshooting Event Trace in Hardware in the AI Engine Tools and Flows User Guide (UG1076) .

The num-trace-streams setting is a bandwidth versus routing trade-off. Start with the default value of 4 and increase it only if the run time drops trace events or if you need more capture bandwidth. For example, increasing the value from 4 to 16 gives large designs more room to capture events. Larger values reduce trace stream contention, but they also use more PL routing and DMA resources, which can create routing challenges for the application logic. The following table provides guidance based on the number of active AI Engine cores.

Enable the PL trace data path at the v++ link stage by adding --profile.data all:all:all to the link command. This option monitors data on all kernels and compute units in the design. For the full v++ profile reference, see --profile Options in this guide.

Runtime Configuration in xrt.ini

At run time, the xrt.ini file controls which trace data the run time captures and how it offloads that data from the device. The following configuration enables the domains required for System Timeline Trace:

[Debug]
aie_trace = true
host_trace = true
device_trace = fine
continuous_trace = true
trace_buffer_size = 32M
trace_buffer_offload_interval_ms = 5

[AIE_trace_settings]
reuse_buffer = true
periodic_offload = true
buffer_offload_interval_us = 50
buffer_size = 100M
tile_based_aie_tile_metrics = all:functions
enable_system_timeline = true
# poll_timers_interval_us = <N>

The following settings are the most relevant for System Timeline Trace:

• aie_trace = true enables AI Engine event trace capture at run time.
• host_trace = true enables host-side XRT API event capture.
• device_trace = fine enables fine-grained PL device trace.
• continuous_trace = true continuously offloads trace data so reports update in Vitis Analyzer while the application runs.

The enable_system_timeline key under [AIE_trace_settings] defaults to true in Vitis 2026.1, which is the first production release of System Timeline Trace. Set this key explicitly in xrt.ini whenever you capture trace for the unified timeline view. This approach makes the configuration self-documenting and matches the recommended practice of explicitly setting trace-related parameters, such as broadcast-enable-core at build time. If you set this key to false, the tool disables the post-processing step that creates the unified timeline view and produces only per-domain timelines.

For the full reference for the [Debug] and [AIE_trace_settings] keys, including enable_system_timeline and poll_timers_interval_us, see the xrt.ini File topic in this guide.

Viewing the Unified Timeline

After you run the application on hardware and copy the trace files back to the development machine, open the run summary in Vitis Analyzer:

vitis_analyzer xrt.run_summary

In Vitis 2026.1, the unified system timeline opens automatically when the required trace files are present. In releases earlier than 2026.1, this view was an early-access preview that you had to enable from Vitis > New Feature Preview > System Timeline. You no longer need that step. The Timeline Trace view shows host activity, including Native API Host Trace rows, PL activity, including compute unit execution and stream activity rows, and per-tile AI Engine activity, including core function execution rows, on a shared time axis.

Tuning Event Alignment

Cross-domain alignment in the System Timeline Trace view depends on how often the run time polls and offloads trace data. Two xrt.ini keys control this trade-off. Smaller polling intervals improve alignment between domains, but they also increase trace file size and run-time overhead.

• buffer_offload_interval_us under [AIE_trace_settings] controls how often the run time reads PLIO-mode AI Engine trace from the device into host memory.
• poll_timers_interval_us under [AIE_trace_settings] controls how often the run time polls timers to align cross-domain timestamps in the unified timeline view.

Start with the default values. Reduce these intervals only if the timeline shows visible misalignment between host, PL, and AI Engine events.

Limitations

System Timeline Trace in Vitis 2026.1 supports the standard heterogeneous embedded design flow. This release does not support the following scenarios:

• Designs that load PL-only and AI Engine-only .xclbin files separately, including dynamic AI Engine partition swap
• Hardware emulation flows. System Timeline Trace runs on hardware only.