xrt.ini 文件 - 2022.1 简体中文

赛灵思的 Xilinx Runtime (XRT) 库在运行主机应用和内核执行时，使用各种控制参数来指定调试、剖析和消息记录。这些控制参数在运行时初始化文件 xrt.ini 中指定，并用于在启动时配置 XRT 的功能。

如果您是命令行用户，则需手动创建 xrt.ini 文件并将其保存至主机可执行文件所在的目录。

该运行时库会检查主机可执行文件中是否存在 xrt.ini 并自动读取该文件来配置运行时。您还可以通过将 XRT_INI_PATH 环境变量设置为指向文件，以在运行时指定 xrt.ini 文件的位置，例如：

export XRT_INI_PATH=/path/to/xrt.ini

提示： Vitis IDE 会根据运行配置自动创建 xrt.ini 文件，并将其与主机可执行文件保存在一起。

运行时初始化文件格式

xrt.ini 文件是简单的文本文件，其中包含多组键和键值。以分号 (;) 或井号 (#) 开头的任何行都是注释。组名、键和键值都区分大小写。

以下是 xrt.ini 文件示例，此文件支持时间线轨迹功能，并且指示在Console（控制台）视图上显示运行时 log 日志消息。

#Start of Debug group 
[Debug] 
native_xrt_trace = true
device_trace = fine

#Start of Runtime group 
[Runtime] 
runtime_log = console

其中有 3 组初始化键：

运行时
调试
仿真

下表列出了每个组的所有受支持的键、每个键支持的值以及键用途的简短描述。

运行时组

开关的运行时组允许您配置运行时操作的元素，如下所述。

键	有效值	描述
`api_checks`	`[true\|false]`	启用或禁用 OpenCL API 检查。 `true`：启用。这是默认值。 `false`：禁用。
`cpu_affinity`	`{N,N,...}`	将所有运行时线程固定到指定的 CPU。示例： `cpu_affinity = {4,5,6}`
`exclusive_cu_context`	`[true\|false]`	这样即可允许主机应用指示 OpenCL 获取专属 CU 访问，以便低层次 AXI 读写（xclRegRead 和 xclRegWrite）可供常规内核使用。
`runtime_log`	`[null \| console \| syslog \| <filename>]`	指定运行时 log 日志的打印位置 `null`：不打印任何 log 日志。这是默认值。 `console`：将 log 日志打印至 `stdout` `syslog`：将 log 日志打印至 Linux syslog。 `<filename>`：将 log 日志打印至指定文件。例如，runtime_log=my_run.log。
`verbosity`	`[0 \| 1 \| 2 \| 3]`	log 日志文件的详细程度。默认值为 0。

调试组

开关的调试组用于定义键的选项，以便在运行时期间启用应用剖析，或者追踪数据传输与执行。这些开关适用于 Vitis 加速流程中的 AI 引擎和 PL 内核，并且允许您配置运行时的方方面面，以便控制数据捕获频率、要捕获的事件以及要保留或用于记录追踪和剖析数据的存储器量。

表 1. AI 引擎剖析和追踪选项
键	有效值	描述
`aie_profile`	`[true\|false]`	启用 AI 引擎硬件性能计数器的运行时配置和轮询。仅在运行 VCK190 硬件时才可用。 `true`：启用。 `false`：禁用。这是默认值。
`aie_profile_core_metrics`	`[heat_map\|stalls\|execution\|floating_point\|write_bandwidths\|read_bandwidths\|aie_trace]`	控制从 AI 引擎核性能计数器读取的统计数据的配置。 `heat_map`：剖析活动/停滞的周期和矢量指令使用情况 `stalls`：剖析不同类型的停滞（例如，存储器、串流、锁定和级联） `execution`：剖析 AI 引擎指令 `floating_point`：剖析浮点异常 `write_bandwidths`：剖析串流和级联的写入带宽 `read_bandwidths`：剖析串流和级联的读取带宽 `aie_trace`：剖析来自核与存储器模块的事件追踪的量和停滞注释：仅当 `aie_profile = true` 时，此开关才有效。
`aie_profile_interface_metrics`	`[bandwidths\|stalls_idle]`	控制从 AI 引擎接口拼块性能计数器读取的统计数据的配置 `bandwidths`：剖析 PLIO 主/从接口的带宽 `stalls_idle`：剖析 PLIO 主/从接口的停滞和空闲周期
`aie_profile_interval_us`	`<int>`	控制读取 AI 引擎计数器值的时间间隔（以微秒 (µs) 为单位）。默认时间间隔为 1000 µs。注释：仅当 `aie_profile = true` 时，此开关才有效。
`aie_profile_memory_metrics`	`[conflicts\|dma_locks\|dma_stalls_s2mm\|dma_stalls_mm2s\|write_bandwidths\|read_bandwidths]`	控制从 AI 引擎存储器性能计数器读取的统计数据的配置 `conflicts`：剖析 DMA 存储器冲突 `dma_locks`：剖析获取锁定时其中的 DMA 锁定和停滞 `dma_stalls_s2mm`：剖析 DMA S2MM 通道上的停滞 `dma_stalls_mm2s`：剖析 DMA MM2S 通道上的停滞 `write_bandwidths`：剖析 DMA S2MM 通道的带宽 `read_bandwidths`：剖析 DMA MM2S 通道的带宽 . 注释：仅当 `aie_profile = true` 时，此开关才有效。
`aie_status`	`[true\|false]`	启用 AI 引擎状态信息的轮询。仅在运行 VCK190 硬件时才可用。
`aie_status_interval_us`	整数（默认值 = 1000us）	控制捕获 AI 引擎状态信息的时间间隔。以微秒为单位来指定。
`aie_trace`	`[true\|false]`	启用 AI 引擎事件追踪的运行时配置和收集。仅在运行 VCK190 硬件时才可用。 `true`：启用。 `false`：禁用。这是默认值。
`aie_trace_buffer_offload_interval_ms`	整数（默认值 = 10ms）	读取从器件到主机存储器的 PLIO 模式 AI 引擎追踪的时间间隔（以毫秒为单位）。
`aie_trace_buffer_size`	`<string> (default=8M)`	控制为 AI 引擎事件追踪分配的缓冲器的总大小。此大小最终将根据 AI 引擎输出的不同追踪串流的数量进行分区。默认值为 8M。注释：仅当 `aie_trace = true` 时，此开关才有效。
`aie_trace_file_dump_interval_s`	整数（默认值 = 5s）	原始 AI 引擎追踪数据写入（追加到）输出文件的时间间隔（以秒为单位）。
`aie_trace_metrics`	`[functions\|functions_partial_stalls\| function_all_stalls]`	控制 AI 引擎寄存器的配置，以生成指定级别的事件追踪。注释：仅当 `aie_trace = true` 时，此开关才有效。
`aie_trace_periodic_offload`	true/false（默认值 = true）	启用 PLIO 模式 AI 引擎追踪的连续卸载。在生成的 AI 引擎追踪输出文件（每条串流一个文件）中追加新追踪数据。
`aie_trace_start_time`	字符串（例如，<N>[ns\|us\|ms\|s]，默认值 = 0）	按 AI 引擎时钟周期或时间（s、ms、us 或 ns）指定启动追踪的延迟，例如，100、20.3ms 或 16.1us

表 2. 主机与 PL 内核选项
键	有效值	描述
`app_debug`	`[true\|false]`	使用 GDB 进行调试时，针对主机代码启用 OpenCL 应用调试。 `true`：启用。 `false`：禁用。这是默认值。
`continuous_trace`	`[true\|false]`	启用将器件数据的追踪和连续读取对应的文件连续转储到主机中。 `true`：启用。 `false`：禁用。这是默认值。注释：仅当启用 `device_trace` 时，此开关才有效。
`device_counters`	`[true\|false]`	仅启用器件计数器卸载，不启用追踪功能。
`device_trace`	`[off\|fine\|coarse\|accel]`	启用从 PL 上插入的监控器收集数据，以添加至汇总数据和轨迹。 `accel`：追踪计算单元启动/停止。 `coarse`：在计算单元的每次执行下归并所有读写。 `fine`：追踪发生的一切。 `off`：关闭运行时期间器件级别追踪的读取和报告。这是默认值。
`host_trace`	`[true\|false]`	基于遇到的第一条协议，启用主机代码追踪。提示：如果您的主机应用使用 OpenCL 和 XRT 本机 API，则应手动指定 `opencl_trace` 和 `native_xrt_trace` 来捕获所有事件。
`lop_trace`	`[true\|false]`	启用低开销 OpenCL API 主机追踪的生成。不应配合其它 OpenCL 选项一起使用。 `true`：启用。 `false`：禁用。这是默认值。
`native_xrt_trace`	`[true\|false]`	启用原生 C/C++ API 追踪的生成。这也会在“Profile Summary”（剖析汇总）中生成“Host Data Transfer from/to Global memory”（出入全局存储器的主机数据传输）表。 `true`：启用。 `false`：禁用。这是默认值。
`opencl_trace`	`[true\|false]`	启用 OpenCL API 主机追踪的生成。 `true`：启用。 `false`：禁用。这是默认值。
`pl_deadlock_detection`	`[true\|false]`	为 PL 内核启用死锁检测。
`power_profile`	`[true\|false]`	在应用执行期间，启用功耗数据的轮询。 `true`：启用。 `false`：禁用。这是默认值。注释：在某些平台（包括 AWS）上不支持此功能。
`power_profile_interval_ms`	`<int>(default=20)`	控制读取功耗计数器的时间间隔（以毫秒为单位）。默认时间间隔为 20 ms。注释：仅当 `power_profile = true` 时，此开关才有效。
`profile_api`	`[true\|false]`	支持直接从主机应用访问 HAL API，以在执行期间读取器件剖析监控器上的计数器。 `true`：启用。 `false`：禁用。这是默认值。
`stall_trace`	`[off\|all\|dataflow\|memory\|pipe]`	指定时间线轨迹内要捕获和报告的器件侧停滞类型。默认设置为关 (off)。 `off`：关闭停滞追踪信息。 `all`：记录所有停滞追踪信息。 `dataflow`：内核内串流（例如，向数据流块之间的完整 FIFO 写入）。 `memory`：外部存储器停滞（例如，从 DDR 存储器中进行 AXI4 读取）。 `pipe`：OpenCL 内核的内核间管道（例如，向内核之间的完整管道写入）。注释：仅当启用 `device_trace` 时，此开关才有效。
`trace_buffer_offload_interval_ms`	`<int>`	控制从器件到主机的器件数据读取（以毫秒 (ms) 为单位）。默认值为 10 ms。注释：仅当启用 `device_trace` 时，此开关才有效。
`trace_buffer_size`	`<string>`	如果创建的 .xclbin 中已指定追踪的存储器卸载方案（如 --profile 选项中所述），则此开关可确定在存储器中要分配用于捕获追踪数据的缓冲器大小。默认值为 1M。注释：仅当启用 `device_trace` 时，此开关才有效。
`trace_file_dump_interval_s`	`<int>`	控制追踪文件转储的时间间隔（以秒 (s) 为单位）。默认值为 5s。注释：仅当启用 `device_trace` 时，此开关才有效。
`vitis_ai_profile`	`[true\|false]`	剖析汇总和其它文件来自 Vitis AI 应用层。 `true`：启用。 `false`：禁用。这是默认值。
`xocl_debug`	`[true\|false]`	启用时，生成 xocl.log 文件。同时启用任意追踪选项时，调试 log 日志已添加到 xrt.run_summary 中，以供在 Vitis 分析器内查看。
`xrt_trace`	`[true\|false]`	支持在硬件运行期间生成低级硬件 shim 函数追踪。这将在搭配 `native_xrt_trace` 一起使用时禁用。 `true`：启用。 `false`：禁用。这是默认值。

仿真组

开关的仿真组适用于仿真环境和 Vivado 仿真器。

键	有效值	描述
`aliveness_message_interval`	任何整数	指定需要打印活动消息的时间间隔（以秒为单位）。默认值为 300。
`debug_mode`	`[off\|batch\|gui]`	指定在仿真 (emulation) 期间如何保存和显示波形。 `off`：不启动仿真器波形 GUI，且不保存 wdb 文件。这是默认值。 `batch`：不启动仿真器波形 GUI，但保存 wdb 文件 `gui`：启动仿真器波形 GUI，并保存 wdb 文件注释：内核需要在调试启用 (`v++ -g`) 的情况下进行编译，以便保存波形并在仿真器 GUI 中显示。
`kernel-dbg`	`[true\|false]`	在软件仿真期间启用内核调试功能，如命令行调试流程中所述。 `true`：启用。 `false`：禁用。这是默认值。
`print_infos_in_console`	`[true\|false]`	控制将仿真 (emulation) 参考消息打印到用户控制台的行为。仿真参考消息始终记录到名为 emulation_debug.log 的文件中 `true`：在用户控制台中打印。这是默认值。 `false`：不在用户控制台中打印。
`print_warnings_in_console`	`[true\|false]`	控制将仿真 (emulation) 警告消息打印到用户控制台的行为。仿真警告消息始终记录到名为 emulation_debug.log 的文件中。 `true`：在用户控制台中打印。这是默认值。 `false`：不在用户控制台中打印。
`print_errors_in_console`	`[true\|false]`	控制在用户控制台中打印仿真错误消息的行为。仿真错误消息始终记录到 emulation_debug.log 文件中。 `true`：在用户控制台中打印。这是默认值。 `false`：不在用户控制台中打印。
`user_pre_sim_script`	Tcl 文件路径	首次运行时，以 GUI 模式运行仿真 (simulation)。添加要添加的信号。将命令从 Tcl 控制台复制并保存到 Tcl 脚本中。对于下一次运行，以批处理模式传递此 Tcl 脚本。
`user_post_sim_script`	Tcl 文件路径	任何转发操作均可在 Tcl 中指定并传递给开关。Tcl 中提供的所有命令都在仿真 (simulation) 完成后执行。
`xtlm_aximm_log`	`[true\|false]`	在运行时启用 XTLM AXI4 存储器映射传输事务 log 日志记录，您可在 xsc_report.log 文件中看到所有传输事务。
`xtlm_axis_log`	`[true\|false]`	在运行时启用 XTLM AXI4-Stream 传输事务 log 日志记录，您可在 xsc_report.log 文件中看到所有传输事务。
`timeout_scale`	`na/ms/sec/min`	针对仿真 (emulation) 中的 `clPollStream` API 的超时支持。为 `clPollStream` API 中指定的超时提供刻度。代码中指定的超时是以毫秒 (ms) 为单位来指定的，可能对于仿真 (emulation) 无效。因此，请使用 `timeout_scale` 将 ms 映射到其它刻度，以满足仿真 (emulation) 所需。重要：默认情况下，在仿真 (emulation) 中不启用超时。该选项可用于启用 `clPollStream` 超时。