xrt.ini File - 2020.2 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)

Document ID

UG1393

Release Date

2021-03-22

Version

2020.2 English

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.