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.
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.
Key | Valid Values | Description |
---|---|---|
api_checks
|
[true|false]
|
Enables or disables OpenCL
API checks.
|
cpu_affinity
|
{N,N,...}
|
Pins all runtime threads to specified CPUs. Example:
|
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
|
verbosity
|
[0 | 1 | 2 | 3]
|
Verbosity of the log messages. The default value is 0. |
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.
|
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 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.
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.
|
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.
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.
When 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 .
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.
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
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 . |
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.
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
|
print_warnings_in_console
|
|
Controls the printing emulation warning messages to user's
console. Emulation warning messages are always logged into a file called emulation_debug.log.
|
print_errors_in_console
|
|
Controls printing emulation error messages in user's console.
Emulation error messages are always logged into the emulation_debug.log file.
|
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
|
|
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
|
|
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. |