xrt.ini 文件 - 2023.2 简体中文

Vitis 统一软件平台文档 应用加速开发 (UG1393)
Document ID
UG1393
Release Date
2023-12-13
Version
2023.2 简体中文
Xilinx Runtime (XRT) 库在运行主机应用和内核执行时，使用各种控制参数来指定调试、剖析和消息记录。这些控制参数在运行时初始化文件 xrt.ini 中指定，并用于在启动时配置 XRT 的功能。

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

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

export XRT_INI_PATH=/path/to/xrt.ini
提示： AMD 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 组初始化键：

  • 运行时
  • 调试
    • AIE_profile_settings
    • AIE_trace_settings
  • 仿真

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

运行时组

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

表 1. 运行时组键值
键 有效值 描述
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）可供常规内核使用。
force_program_xclbin [true|false] 强制将可重配置模块 (RM) .xclbin 文件重新加载到器件中，即使此文件已加载也是如此。这用于在含有 .xclbin 的平台中根据请求强制重新加载 DFX 区域。
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 | 4 | 5 | 6 | 7 ] log 日志文件的详细程度。默认值为 4。

调试组

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

表 2. 调试选项
键 有效值 描述
aie_profile [true|false] 启用 AI 引擎硬件性能计数器的运行时配置和轮询。在 VCK190 硬件上以及硬件仿真运行时可用。
  • true：启用。
  • false：禁用。这是默认值。
aie_trace [true|false] 启用 AI 引擎事件追踪的运行时配置和收集。仅在运行 VCK190 硬件时才可用。
  • true：启用。
  • false：禁用。这是默认值。
aie_status [true|false] 启用 AI 引擎状态信息的轮询。在 VCK190 硬件上以及硬件仿真运行时可用。
aie_status_interval_us 整数（默认值 = 1000 us） 控制捕获 AI 引擎状态信息的时间间隔。以微秒为单位来指定。
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 选项 中所述），则此开关可确定在存储器中要分配用于捕获追踪数据的缓冲器大小。默认值为 1 M。
注释： 仅当启用 device_trace 时，此开关才有效。
trace_file_dump_interval_s <int> 控制追踪文件转储的时间间隔（以秒 (s) 为单位）。默认值为 5 s。
注释： 仅当启用 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：禁用。这是默认值。

AIE_profile_settings 组

仅当 [Debug] 下的 aie_profile=true 时，该组中指定的选项才适用。

表 3. AI 引擎剖析选项
键 有效值 描述
graph_based_aie_metrics <graph name|all>:<kernel name|all>:<off|heat_map|stalls|execution|floating_point|write_bandwidths|read_bandwidths|aie_trace>

基于每个计算图，指定由 AI 引擎拼块的 AI 引擎模块所报告的指标集。

重要： 当前，指定内核时仅支持 all。

控制从整个 AI 引擎计算图应用的 AIE 核性能计数器读取的统计数据的配置。

heat_map：剖析活动/停滞的周期和矢量指令使用情况

stalls：剖析不同类型的停滞（例如，存储器、串流、锁定和级联）

execution：剖析 AI 引擎指令

floating_point：：剖析浮点异常

write_bandwidths：剖析串流和级联的写入带宽

read_bandwidths：剖析串流和级联的读取带宽

aie_trace：剖析来自核与存储器模块的事件追踪的量和停滞
graph_based_aie_memory_metrics <graph name|all>:<kernel name|all>:<off|conflicts|dma_locks|dma_stalls_s2mm|dma_stalls_mm2s|write_bandwidths|read_bandwidths>

基于每个计算图，指定由 AI 引擎拼块的存储器模块所报告的指标集。

重要： 当前，指定内核时仅支持 all。

控制从整个 AI 引擎计算图应用的 AI 引擎存储器性能计数器读取的统计配置。

conflicts：剖析 DMA 存储器冲突

dma_locks：剖析获取锁定时其中的 DMA 锁定和停滞

dma_stalls_s2mm：剖析 DMA S2MM 通道上的停滞

dma_stalls_mm2s：剖析 DMA MM2S 通道上的停滞

write_bandwidths：剖析 DMA S2MM 通道的带宽

read_bandwidths：剖析 DMA MM2S 通道的带宽
tile_based_aie_metrics

<{<column>,<row>}|all>:<off|heat_map|stalls|execution|floating_point|write_bandwidths|read_bandwidths|aie_trace>

;

{<mincolumn,<minrow>}:{<maxcolumn>,<maxrow>}:<off|heat_map|stalls|execution|floating_point|write_bandwidths|read_bandwidths|aie_trace>

基于每个 tile（拼块），指定由 AI 引擎拼块的 AI 引擎模块所报告的指标集。可搭配基于每个计算图的选项一起使用，并取指定拼块的优先级进行报告。

请参阅 graph_based_aie_metrics 中的描述
tile_based_aie_memory_metrics

<{<column>,<row>}|all>:<off|conflicts|dma_locks|dma_stalls_s2mm|dma_stalls_mm2s|write_bandwidths|read_bandwidths>

;

{<mincolumn,<minrow>}:{<maxcolumn>,<maxrow>}:<off|conflicts|dma_locks|dma_stalls_s2mm|dma_stalls_mm2s|write_bandwidths|read_bandwidths>

基于每个 tile（拼块），指定由 AI 引擎拼块的存储器模块所报告的指标集。可搭配基于每个计算图的选项一起使用，并取指定拼块的优先级进行报告。

请参阅 graph_based_aie_memory_metrics 中的描述
tile_based_interface_tile_metrics

<column|all>:<off|input_bandwidths|output_bandwidths|packets>[:<channel>]

;

<mincolumn>:<maxcolumn>:<off|input_bandwidths|output_bandwidths|packets>[:<channel>]

基于每个 tile（拼块），指定由 AI 引擎接口拼块所报告的指标集。

注释： 接口拼块与 AI 引擎拼块分离，并具有不同的指标集。
interval_us <int> 控制读取 AI 引擎计数器值的时间间隔（以微秒 (µs) 为单位）。默认时间间隔为 1000 µs。
注释： 仅当 aie_profile = true 时，此开关才有效。

AIE_trace_settings 组

仅当 [Debug] 下的 aie_trace=true 时，该组中指定的选项才适用。

表 4. AI 引擎追踪选项
键 有效值 描述
buffer_size <string> (default=8M) 控制为 AI 引擎事件追踪分配的缓冲器的总大小。此大小最终将根据 AI 引擎输出的不同追踪串流的数量进行分区。默认值为 8 M。
注释： 仅当 aie_trace = true 时，此开关才有效。
buffer_offload_interval_us 整数（默认值 = 10 ms） 读取从器件到主机存储器的 PLIO 模式 AI 引擎追踪的时间间隔（以毫秒为单位）。
periodic_offload true/false（默认值 = true） 启用 PLIO 模式 AI 引擎追踪的连续卸载。在生成的 AI 引擎追踪输出文件（每条串流一个文件）中追加新追踪数据。
file_dump_interval_s 整数（默认值 = 5 s） 原始 AI 引擎追踪数据写入（追加到）输出文件的时间间隔（以秒为单位）。
graph_based_aie_tile_metrics

string("")

<graph name|all>:<kernel name|all>:<off|functions|functions_partial_stalls|functions_all_stalls>

基于每个计算图，指定由 AI 引擎拼块的 AI 引擎模块所报告的指标集。

重要： 当前，指定内核时仅支持 all。
tile_based_aie_tile_metrics

string("")

<{<column>,<row>}|all>:<off|functions|functions_partial_stalls|functions_all_stalls>[:<memory_stalls|stream_stalls|cascasde_stalls|lock_stalls>]

{<mincolumn,<minrow>}:{<maxcolumn>,<maxrow>}:<off|functions|functions_partial_stalls|functions_all_stalls>

基于每个 tile（拼块），指定由 AI 引擎拼块的 AI 引擎模块所报告的指标集。

重要： 当前，指定内核时仅支持 all。
reuse_buffer true/false (false)  

仿真组

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

表 5. 仿真组键值
键 有效值 描述
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 超时。