Configuration File xrt.ini

XRT uses various parameters to control execution flow, debug, profiling, and message logging during host application and kernel execution in software emulation, hardware emulation, and system run on the acceleration board. These control parameters are optionally specified in a runtime initialization file xrt.ini

XRT looks for xrt.ini in host executable path and current directory in that order. It stops search when an xrt.ini is found. If xrt.ini is not found, XRT built-in defaults are used as described in the table below.

Runtime Initialization File Format

The runtime initialization file is a 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 in-sensitive.

There are three group of keys as below

  • Runtime: The keys in this group impact general XRT flow
  • Debug: The keys in this group are used to generate and configure the debug related files such as profile report and timeline trace
  • Emulation: The keys in this group are related to the Emulation flow only

The following is a simple example that turns on profile timeline trace and sends the runtime log messages to the console.

#Start of Runtime group
[Runtime]
runtime_log = console

#Start of Debug group
[Debug]
timeline_trace = true

The following table lists all supported groups, keys, valid key values, and short descriptions on the function of the keys.

Runtime Group

Key Valid Values Description
api_checks [true|false]

Enable or disable OpenCL API checks:

  • true: enable
  • false: disable

Default: true
runtime_log [null|console|syslog|filename]

Specify where the runtime logs are printed:

  • null: Do not print any logs.
  • console: Print logs to stdout
  • syslog: Print logs to Linux syslog
  • filename: Print logs to the specified file. Example, runtime_log=my_run.log

Default: console
cpu_affinity [{N,N,…}]

Pin all runtime threads to specified CPUs.

Example: cpu_affinity = {4,5,6}
polling_throttle [N]

Specify the time interval in microseconds that the runtime library polls the device.

Default: 0
verbosity [0|1|2|3]

verbosity level of log messages. Higher number implies more verbosity

Default: 0

Debug Group

Key Valid Values Description
profile [true|false]

Enable or disable OpenCL host code profile. Set true to generate profile_summary report

Default: false
timeline_trace [true|false]

Enable or disable profile timeline trace. Set true to generate timeline_trace report

Default: false
data_transfer_trace [coarse|fine|off]

Enable device-level AXI transfers trace:

  • coarse: Shows CU transfer activity
  • fine: Shows all AXI level burst data transfer
  • off: Does not show device-level AXI transfer

Default: off
stall_trace [dataflow|memory|pipe|all|off]

Specifies type of stalls to be captured in timeline trace report:

  • dataflow: Stall related to intra-kernel streams
  • memory: Stall related to memory transfer
  • pipe: Inter-kernel pipes, applicable to OpenCL kernel
  • all: All type of stalls
  • off: Does not show stalls

Default: off
app_debug [true|false]

If true, enable xprint and xstatus command during debugging with xgdb

Default: false
trace_buffer_size [N {K|M|G}]

Specifies the size of DDR/HBM memory for storing trace data:

  • N: Integer
  • K|M|G: Units Kilobyte or Megabyte or Gigabyte

Note:

  • This option only applicable in hardware flow
  • If no unit is given byte is assumed

Example: trace_buffer_size=100M

Default: 1M

Emulation Group

Key Valid Values Description
aliveness_message_interval [N]

Specify the interval in seconds that aliveness messages need to be printed.

Default:300
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
  • false = do not print in user console

Default: true
print_warning_in_console [true|false]

Controls the printing of emulation warning messages to users console.

Emulation warning messages are always logged into a file called emulation_debug.log

  • true = print in users console
  • false = do not print in user console

Default: true
print_errors_in_console [true|false]

Controls the printing of emulation error messages to users console.

Emulation error messages are always logged into a file called emulation_debug.log

  • true = print in users console
  • false = do not print in user console

Default: true
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
  • batch: Do not launch simulator waveform GUI, but save wdb file
  • gui: Launch simulator waveform GUI, and save wdb file

Default: off

Note: The kernel needs to be compiled with debug enabled for the waveform to be saved and displayed in the simulator GUI.