XRT Support for Event APIs - 2025.2 English - UG1076

XRT provides the xrt::aie::profiling class to support event profiling. XRT Event Profile APIs are recommended for hardware flows to obtain accurate, absolute throughput and latency measurements.

In hardware emulation (hw_emu), these APIs are functionally supported for trend analysis (for example, comparing design iterations to assess relative improvements or regressions). However, because hw_emu executes on QEMU (untimed) and uses abstracted memory/interconnect models, measurements are not cycle-accurate and should not be used for absolute performance claims. Timing deviations are larger when designs use GMIO or external memory paths (DDR/LPDDR). Always validate absolute performance on hardware.

. The XRT API header file xrt/xrt_aie.h defines class xrt::aie::profiling to support event profiling. The xrt::aie::profiling class member functions start, read, and stop are used to start profiling, read profiling results, and stop profiling.

enum class profiling_option : int 
  { 
    io_total_stream_running_to_idle_cycles = 0, 
    io_stream_start_to_bytes_transferred_cycles = 1,
    io_stream_start_difference_cycles = 2,
    io_stream_running_event_count = 3 
  };

The start function has the following parameters:

int start(profiling_option option, const std::string& port1_name, const std::string& port2_name, uint32_t value) const; //meaning of value depends on option.

An example host code to use XRT API to profile follows:

#include "xrt/xrt_aie.h"
......
auto ghdl=xrt::graph(device,uuid,"gr");
xrt::aie::profiling handle(device);
handle.start(xrt::aie::profiling::profiling_option::io_stream_start_to_bytes_transferred_cycles, "gr.dataout", "", output_size_in_bytes);
......
long long cycle_count = handle.read();
handle.stop();