Trace Support for DFX Designs - Trace Support for DFX Designs - 2026.1 English - UG1702

Vitis Reference Guide (UG1702)
Document ID
UG1702
Release Date
2026-06-23
Version
2026.1 English

Vitis supports AI Engine event-trace collection on Versal Dynamic Function eXchange (DFX) platforms with the AI Engine array residing in the Reconfigurable Partition (RP). The flow captures event trace continuously across Reconfigurable Module (RM) swaps through the GMIO offload pathway, which lets you observe the AI Engine across hot-swap workflows without rebuilding the static region. Build the design with the GMIO trace flags described below, run the application using the standard register_xclbin and xrt::hw_context flow, and analyze the resulting trace files in the Vitis Analyzer using the same procedures as non-DFX trace. For the underlying platform mechanics, see DFX Based Hardware Platform in the Embedded Design Development Using Vitis (UG1701) . For the host-code hot-swap pattern, see the Runtime Control and Reload of AI Engine Partitions in the AI Engine Tools and Flows User Guide (UG1076) .

Supported Configurations

Item Value
Reference platform xilinx_vck190_base_dfx_202610_1.xpfm
DFX topology Single Reconfigurable Partition; AI Engine resides inside the RP.
Trace offload pathway GMIO (AI Engine to NoC to DDR)
Runtime control Linux with Xilinx Runtime, or xsdb
Hardware emulation Not supported

Build Flow

Compile the AI Engine graph of each Reconfigurable Module with GMIO event tracing enabled:

aiecompiler \
  --event-trace=runtime \
  --event-trace-port=gmio \
  --num-trace-streams=1 \
  --enable-partition=<start_col:num_cols> \
  --partition-isolation=0 \
  --target=hw \
  --platform=<dfx_platform>.xpfm \
  --output-archive=<aie_archive>.a \
  <project_root>/src/graph.cpp

The --enable-partition flag declares the AI Engine partition that maps to the Reconfigurable Partition. Use the same partition coordinates across every RM. --target=hw is required; the compiler rejects hardware emulation targets. For the full per-flag reference, see Event Tracing Options.

Link and package each RM into its own xclbin using the standard DFX flow described in the Packaging for DFX Platforms topic in Packaging for DFX Platforms in the Embedded Design Development Using Vitis (UG1701) .

Runtime

Use the xrt::device::register_xclbin and xrt::hw_context pattern to load each RM. Destroy the hw_context before reloading the next RM to quiesce the partition. Trace flows continuously to DDR through the AI Engine GMIO ports across RM boundaries. You do not need to modify the static region or the host code between RMs. For the host-code pattern, see the Runtime Control and Reload of AI Engine Partitions in the AI Engine Tools and Flows User Guide (UG1076) .

Set aie_trace=true under the [Debug] group of xrt.ini and configure capture under [AIE_trace_settings] as for a non-DFX design. For the full settings reference, see xrt.ini File.

Limitations

  • PLIO trace offload is not supported on DFX platforms. The v++ linker rejects --event-trace-port=plio for DFX targets.
  • Hardware emulation is not supported for AI Engine trace, with or without DFX. For the underlying restriction, see Runtime Control and Reload of AI Engine Partitions in the AI Engine Tools and Flows User Guide (UG1076) .
  • The reuse_buffer runtime setting is PLIO-only and has no effect on DFX (GMIO) trace. Size the GMIO trace buffer for the full capture window.
  • Multi-RP DFX designs are not supported. The AI Engine must reside in the single Reconfigurable Partition.
  • Multi-AI Engine-partition designs build successfully, but only one partition is supported at runtime per RM.
  • No unified system-wide common-timestamp view is available across AI Engine and PL trace.