xrt.ini File

The Xilinx runtime (XRT) library uses various control parameters to specify debugging, profiling, and message logging when running the host application and kernel execution. These control parameters are specified in a runtime initialization file, xrt.ini and used to configure features of XRT at start-up.

If you are a command line user, the xrt.ini file needs to be created manually and saved to the same directory as the host executable. The runtime library checks if xrt.ini exists in the same directory as the host executable and automatically reads the file to configure the runtime.

TIP: The Vitis IDE creates the xrt.ini file automatically based on your run configuration and saves it with the host executable.

Runtime Initialization File Format

The xrt.ini file is a simple text file with groups of keys and their values. Any line beginning with a semicolon (;) or a hash (#) is a comment. The group names, keys, and key values are all case sensitive.

The following is an example xrt.ini file that enables the timeline trace feature, and directs the runtime log messages to the Console view.

#Start of Debug group 
[Debug] 
timeline_trace = true

#Start of Runtime group 
[Runtime] 
runtime_log = console

There are three groups of initialization keys:

  • Runtime
  • Debug
  • Emulation

The following tables list all supported keys for each group, the supported values for each key, and a short description of the purpose of the key.

Table 1. Runtime Group
Key Valid Values Description
api_checks [true|false] Enables or disables OpenCL API checks.
  • true: Enable. This is the default value.
  • false: Disable.
cpu_affinity {N,N,...} Pins all runtime threads to specified CPUs. Example:
cpu_affinity = {4,5,6}
ert_polling [true|false] Specifies the use of polling as a mechanism to interrupt compute unit (CU) processing on the acceleration platform. The default value is false, using existing interrupt signals on the platform rather than polling.
exclusive_cu_context [true|false] This allows the host application to direct OpenCL to acquire exclusive CU access, so that low-level AXI read/write (xclRegRead and xclRegWrite) can be used for regular kernels, as well as free-running kernels.
polling_throttle <value> Specifies the time interval in microseconds that the runtime library polls the device status when ert_polling is enabled. The default value is 0.
runtime_log [null | console | syslog | <filename>] Specifies where the runtime logs are printed
  • null: Do not print any logs. This is the default value.
  • console: Print logs to stdout
  • syslog: Print logs to Linux syslog.
  • <filename>: Print logs to the specified file. For example, runtime_log=my_run.log.
verbosity [0 | 1 | 2 | 3] Verbosity of the log messages. The default value is 0.
Table 2. Debug Group
Key Valid Values Description
aie_profile [true|false]

Enables or disables AI Engine graph application profiling.

aie_profile_interval_ms <int> Specifies the interval in milliseconds to read the AI Engine trace buffers. This is useful when you want to increase the rate of dumping data to the disk to avoid overflowing the buffers and losing data. The default interval is 20 ms.
aie_trace [true|false] Enables or disables AI Engine graph application event tracing.
Note: This option is disabled when specified with profile=true.
aie_trace_buffer_size <value{K|M|G}> Specifies the size of the memory allocated to capture AI Engine trace data. This helps to ensure you can capture enough trace data. The value is specified as the amount of memory to allocate, for example, 64K, 200M, 1G.
app_debug [true|false] For host applications using the OpenCL API this feature enables xprint and xstatus command during debugging with GDB.
  • true: Enable.
  • false: Disable. This is the default value.
continuous_trace [on|off] Enables the continuous offload of device trace data while the application is running. The trace file will be written to disk continuously, so in the event of a crash, some trace data is available to help debug the application.

The continuous trace feature writes to the memory type specified by the --trace_memory option described in Vitis Compiler General Options. Continuous trace provides better results when the trace memory is not specified as FIFO.

Note: For OpenCL API profiling this feature requires both profile=true and timeline_trace=true to be set. For XRT API profiling, this feature requires both xrt_profile=true and data_transfer_trace=fine|coarse
continuous_trace_interval_ms <int> Specifies the interval in milliseconds to read the trace buffers. This is useful when trace data is captured in FIFO and you want to increase the rate of dumping data to the disk to avoid overflowing the buffers and losing data. The default interval is 10 ms.
Note: This option requires the use of continuous_trace=true.
data_transfer_trace=<arg> [coarse|fine|off] Enables device-level AXI transfers trace.
  • coarse: Show CU transfer activity from beginning of first transfer to end of last transfer (before compute unit transfer ends).
  • fine: Show all AXI-level burst data transfers.
  • off: Turn off reading and reporting of device-level trace during runtime. This is the default value.
Note: For OpenCL API profiling this feature requires both profile=true and timeline_trace=true to be set.
debug [true|false] Enables kernel debug functionality for software emulation and hardware emulation. If debug=true, then a separate GDB process can attach to the emulation process via xrt_server for kernel debug.
  • true: Enable.
  • false: Disable. This is the default value.
lop_trace [true|false] Enables or disables low overhead profiling of OpenCL API calls in the host application.

Low overhead profiling produces a reduced timeline of events written to lop_trace.csv. This reports only host side events, eliminating the overhead of device side profiling and significantly reducing the impact on performance.

  • true: Enable.
  • false: Disable. This is the default value.
TIP: lop_trace=true should not be specified with profile=true, or the tool will perform standard profiling and trace.
power_profile [true|false] When this option is enabled, power data is captured from the accelerator card during the application runtime. The power profile reports the avg/min/max power for each rail on the card. The logged data is written to power_profile_<device>.csv, and can be viewed in Vitis analyzer.
power_profile_interval_ms <int> Specifies the interval in milliseconds to read the power information. The default interval is 20 ms.
profile [true|false] Enables or disables OpenCL host code profiling.
  • true: Enable.
  • false: Disable. This is the default value.

When true, the runtime generates the profile_summary.csv file for OpenCL API calls. This will summarize host code events and some device level information. When false, no profile monitoring is performed at all.

IMPORTANT: Because this feature accesses device information from the PL region, it will override and disable any other profiling options that access the PL region of the device, such as aie_trace and vitis_ai_profile.
profile_api [true|false] Enables users to call device offload directly from the host application using XRT API calls.
Note: This option is disabled when specified with profile=true.
stall_trace=<arg> [dataflow|memory|pipe|all|off] Specifies the type of device-side stalls to capture and report in the timeline trace. The default is off.
  • off: Turn off stall trace information.
  • all: Record all stall trace information.
  • dataflow: Intra-kernel streams (for example, writing to full FIFO between dataflow blocks).
  • memory: External memory stalls (for example, AXI4 read from the DDR memory.
  • pipe: Inter-kernel pipe for OpenCL kernels (for example, writing to full pipe between kernels).
Note: For OpenCL API profiling this feature requires both profile=true and timeline_trace=true to be set. For XRT API profiling, this feature requires both xrt_profile=true and data_transfer_trace=fine|coarse
timeline_trace [true|false] Enables or disables the generation of the timeline_trace.csv file.
  • true: Enable.
  • false: Disable. This is the default value.

This option will enable data gathering for the timeline trace report. However, without adding Acceleration Monitors and AXI Performance Monitor IP into the kernels, the timeline will only show host information. At a minimum, to get compute unit start and end times, the CU needs to be built with --profile.exec as described in --profile Options.

IMPORTANT: This also requires the use of profile=true or no timeline data is captured.
trace_buffer_size <value{K|M|G}> Used with timeline_trace=true, this option specifies the size of the memory allocated to capture trace data. This helps to ensure you can capture enough trace data. The value is specified as the amount of memory to allocate, for example, 64K, 200M, 1G.
Note: This requires the device binary (.xclbin) to be linked with the --trace_memory option as explained in Vitis Compiler General Options.
vitis_ai_profile [true|false] Enables DPU counter profiling for Vitis AI library.
Note: This option is disabled when specified with profile=true.
xrt_profile [true|false] Enables capturing trace data of host applications using the XRT Native API. This option can be used with profile=true.
Table 3. Emulation Group
Key Valid Values Description
aliveness_message_interval Any integer Specifies the interval in seconds that aliveness messages need to be printed. The default is 300.
debug_mode [off|batch|gui|gdb] Specifies how the waveform is saved and displayed during emulation.
  • off: Do not launch simulator waveform GUI, and do not save wdb file. This is the default value.
  • batch: Do not launch simulator waveform GUI, but save wdb file
  • gui: Launch simulator waveform GUI, and save wdb file
  • gdb: Launch simulator in gdb mode to debug the kernel using gdb. This mode does not have waveform support and does not save any wdb file either.
Note: The kernel needs to be compiled with debug enabled (v++ -g) for the waveform to be saved and displayed in the simulator GUI.
print_infos_in_console [true|false] Controls the printing of emulation info messages to user's console. Emulation info messages are always logged into a file called emulation_debug.log
  • true: Print in user's console. This is the default value.
  • false: Do not print in user console.
print_warnings_in_console [true|false] Controls the printing emulation warning messages to user's console. Emulation warning messages are always logged into a file called emulation_debug.log.
  • true: Print in user's console. This is the default value.
  • false: Do not print in user console.
print_errors_in_console [true|false] Controls printing emulation error messages in user's console. Emulation error messages are always logged into the emulation_debug.log file.
  • true: Print in user's console. This is the default value.
  • false: Do not print in user's console.
user_pre_sim_script Path to Tcl file For the first run, run simulation in GUI mode. Add signals that you want to add. Copy the commands from the Tcl console and save into a Tcl script.

For the next run, pass the Tcl script in batch mode.

user_post_sim_script Path to Tcl file Any post operations can be specified in the Tcl and pass to the switch. All the command provided in the Tcl will get executed after simulation is completed.
xtlm_aximm_log [true|false] Enables the XTLM AXI4 Memory Map transaction logging at runtime and you could see all the transactions in the xsc_report.log file.
xtlm_axis_log [true|false] Enables the XTLM AXI4-Stream transaction logging at runtime and you could see all the transactions in the xsc_report.log file.
timeout_scale na/ms/sec/min Timeout support for clPollStream API in emulation. Provides a scale for the timeout specified in clPollStream API. The timeout specified in the code is specified in ms, and might not work for emulation. Therefore use the timeout_scale to map ms to another scale if needed for emulation.
IMPORTANT: Timeout is not enabled in emulation by default. Use this option to enable clPollStream timeout.