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 startup.

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:

Debug
Runtime
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	Descriptions
`api_checks`	`[true\|false]`	Enable or disable OpenCL API checks. `true`: Enable. This is the default value. `false`: Disable.
`cpu_affinity`	`{N,N,...}`	Pin all runtime threads to specified CPUs. Example: `cpu_affinity = {4,5,6}`
`ert_polling`	`[true\|false]`	Specify 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.
`polling_throttle`	`<value>`	Specify 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>]`	Specify 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	Descriptions
`app_debug`	`[true\|false]`	Enable `xprint` and `xstatus` command during debugging with GDB. `true`: Enable. `false`: Disable. This is the default value.
`data_transfer_trace=<arg>`	`[coarse\|fine\|off]`	Enable 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.
`device_profile`	`[true\|false]`	Enable or disable device profiling. `true`: Enable. `false`: Disable. This is the default value.
`profile`	`[true\|false]`	Enable or disable OpenCL code profiling. `true`: Enable. `false`: Disable. This is the default value. When this option is specified as `true`, the runtime enables basic profile monitoring. Without any additional options, this enables the host runtime logging profile summary. However, when `false`, no profile monitoring is performed at all.
`stall_trace=<arg>`	`[dataflow\|memory\|pipe\|all\|off]`	Specify what types of stalls to capture and report in the timeline trace. The default is `off`. Note: Enabling stall tracing can often fill the trace buffer, which results in incomplete and potentially corrupt timeline traces. This can be avoided by setting `stall_trace=off`. `off`: Turn off any stall trace information gathering. `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. `pipe`: Inter-kernel pipe for OpenCL kernels (for example, writing to full pipe between kernels).
`timeline_trace`	`[true\|false]`	Enable or disable profile timeline trace `true`: Enable. `false`: Disable. This is the default value. This option will enable data gathering for the timeline trace. 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 in the timeline, the CU needs to be built with `--profile_kernel exec` as described in Vitis Compiler Command.
`trace_buffer_size`	`<value{K\|M\|G}>`	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.

Table 3. Emulation Group
Key	Valid Values	Descriptions
`aliveness_message_interval`	Any integer	Specify the interval in seconds that aliveness messages need to be printed. The default is 300.
`launch_waveform`	`[off\|batch\|gui]`	Specify 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 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 users console. Emulation info messages are always logged into a file called emulation_debug.log `true`: Print in users 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 users console. Emulation warning messages are always logged into a file called emulation_debug.log. `true`: Print in users 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 users console. Emulation error messages are always logged into the emulation_debug.log file. `true`: Print in users console. This is the default value. `false`: Do not print in user console.