xrt.ini File - 2021.2 English

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

Document ID

UG1393

Release Date

2022-03-29

Version

2021.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. You can also specify the location of an xrt.ini file at runtime by setting the XRT_INI_PATH environment variable to point to the file, for example:

export XRT_INI_PATH=/path/to/xrt.ini

Tip: The Vitis IDE creates an 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] 
opencl_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}`
`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.
`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 the runtime configuration and polling of AI Engine hardware performance counters. Available on VCK190 hardware runs only. `true`: Enable. `false`: Disable. This is the default value.
`aie_profile_core_metrics`	`[heat_map\|stalls\|execution]`	Controls the configuration of the statistics read from AI Engine core performance counters. The default is `heat_map`. Note: This switch only has an effect if `aie_profile = true`.
`aie_profile_interval_us`	`<int>`	Controls the interval of reading the AI Engine counter values in microseconds (µs). The default interval is 1000 µs. Note: This switch only has an effect if `aie_profile = true`.
`aie_profile_memory_metrics`	`[dma_locks\|conflicts]`	Controls the configuration of the statistics read from the AI Engine memory performance counters. The default is `dma_locks`. Note: This switch only has an effect if `aie_profile = true`.
`aie_trace`	`[true\|false]`	Enables the runtime configuration and collection of AI Engine event trace. Available on VCK190 hardware runs only. `true`: Enable. `false`: Disable. This is the default value.
`aie_trace_buffer_size`	`<string>`	Controls the total size of the buffers allocated for AI Engine event trace. This size is partitioned evenly into the number of different trace streams coming out of the AI Engine. The default is 8M. Note: This switch only has an effect if `aie_trace = true`.
`aie_trace_metrics`	`[functions\|functions_partial_stalls\| function_all_stalls\|all]`	Controls the configuration of the AI Engine registers to generate a specified level of event trace. Note: This switch only has an effect if `aie_trace = true`.
`app_debug`	`[true\|false]`	Enables the OpenCL application debug for the host code when debugging with GDB. `true`: Enable. `false`: Disable. This is the default value.
`continuous_trace`	`[true\|false]`	Enables the continuous dumping of files for trace and the continuous reading of device data into the host. `true`: Enable. `false`: Disable. This is the default value. Note: This switch only has an effect if `data_transfer_trace` is enabled.
`data_transfer_trace`	`[off\|fine\|coarse\|accel]`	Enables the collection of data from monitors inserted on the PL to add to summary and trace. `accel`: Traces compute unit starts/stops. `coarse`: Lumps all reads/writes together under each execution of a compute unit. `fine`: Tracks everything as it happens. `off`: Turns off reading and reporting of device-level trace during runtime. This is the default value.
`debug`	`[true\|false]`	Enables kernel debug functionality for software emulation. `true`: Enable. `false`: Disable. This is the default value.
`lop_trace`	`[true\|false]`	Enables generation of lower overhead OpenCL API host trace. Should not be used in conjunction with other OpenCL options. `true`: Enable. `false`: Disable. This is the default value.
`native_xrt_trace`	`[true\|false]`	Enables generation of the Native C/C++ API trace. This also generates the tables for "Host Data Transfer from/to Global memory" in the Profile Summary. `true`: Enable. `false`: Disable. This is the default value.
`xocl_debug`	`[true\|false]`	When enabled, the xrt.run_summary is generated to open in Vitis Analyzer and visualize OpenCL events and device profile.
`opencl_device_counter`	`[true\|false]`	Adds hardware counter information to the generated OpenCL summary file. This is not necessary if `data_transfer_trace` is specified. `true`: Enable. `false`: Disable. This is the default value.
`opencl_summary`	`[true\|false]`	Enables generation of OpenCL API summary report. If this is the only flag specified, then only host information is included. `true`: Enable. `false`: Disable. This is the default value.
`opencl_trace`	`[true\|false]`	Enables generation of OpenCL API host trace. `true`: Enable. `false`: Disable. This is the default value.
`power_profile`	`[true\|false]`	Enables the polling of power data during the execution of the application. `true`: Enable. `false`: Disable. This is the default value. Note: This feature is not supported on certain platforms including AWS.
`power_profile_interval_ms`	`<int>`	Controls the interval of reading the power counters in milliseconds. The default interval is 20 ms. Note: This switch only has an effect if `power_profile = true`.
`profile_api`	`[true\|false]`	Enables access to HAL API directly from the host application to read counters on device profiling monitors during execution. `true`: Enable. `false`: Disable. This is the default value.
`stall_trace`	`[off\|all\|dataflow\|memory\|pipe]`	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: This switch only has an effect if `data_transfer_trace` is enabled.
`trace_buffer_offload_interval_ms`	`<int>`	Controls the reading of device data from the device to the host in milliseconds (ms). The default is 10 ms. Note: This switch only has an effect if `data_transfer_trace` is enabled.
`trace_buffer_size`	`<string>`	If the .xclbin was created with memory offload of trace specified, this switch determines the size of the buffer to allocate in memory for trace. The default is 1M. Note: This switch only has an effect if `data_transfer_trace` is enabled.
`trace_file_dump_interval_s`	`<int>`	Controls the time between dumping of trace files in seconds (s). The default is 5s. Note: This switch only has an effect if `data_transfer_trace` is enabled.
`vitis_ai_profile`	`[true\|false]`	Profile summary and other files come from Vitis AI application layer. `true`: Enable. `false`: Disable. This is the default value.
`xrt_trace`	`[true\|false]`	Enables generation of HW shim function trace during HW runs. Will be disabled when used with `native_xrt_trace`. `true`: Enable. `false`: Disable. This is the default value.

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]`	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 Note: The kernel needs to be compiled with debug enabled (`v++ -g`) for the waveform to be saved and displayed in the simulator GUI.
`kernel-dbg`	`[true\|false]`	Enables kernel debug functionality during software emulation as described in Command Line Debug Flow. `true`: Enable. `false`: Disable. This is the default value.
`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 gets 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.