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
`app_debug`	`[true\|false]`	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. Note: 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.
`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 1 ms.
`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.
`device_profile`	`[true\|false]`	Enables or disables device profiling. `true`: Enable. `false`: Disable. This is the default value.
`lop_trace`	`[true\|false]`	Enables or disables low overhead profiling. Low overhead profiling produces a reduced timeline_trace, with only host side data, but eliminates the overhead of device side profiling, significantly reducing the impact on performance. `true`: Enable. `false`: Disable. This is the default value. Note: `lop_trace=true` should not be specified with `profile=true`, or you will not get low overhead profiling. Also, the `lop_trace` does not require compilation or linking with the `--profile_kernel` option as defined in Vitis Compiler General Options.
`power_profile`	`[true\|false]`	Enables or disables power profiling for the device. `true`: Enable. `false`: Disable. This is the default value. 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 available to view in Vitis analyzer.
`profile`	`[true\|false]`	Enables or disables 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]`	Specifies 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]`	Enables or disables 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. Note: This buffer size relates to the `--trace_memory` option as explained in Vitis Compiler General Options.

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