Vitis 编译器常规选项 - 2022.1 简体中文

Vitis 编译器支持许多同时适用于编译进程和链接进程的选项。这些选项可提供诸多功能特性，覆盖范围广泛，部分选项专用于编译或链接，也有部分选项则可同时用于或者必须同时应用于编译和链接。

platform=xilinx_u200_gen3x16_xdma_2_202110_1

--advanced

适用于

编译和链接

指定参数和属性，以供 v++ 命令使用。如需了解更多信息，请参阅 --advanced 选项。

--board_connection

适用于

编译和链接

--board_connection

为每个 DIMM 连接器插槽指定一个双列直插式存储器模块 (DIMM) 开发板文件。此开发板是使用该 DIMM 卡的 Vendor:Board:Name:Version (vbnv) 属性（显示在开发板存储库中）指定的。

例如：

<DIMM_connector>:<vbnv_of_DIMM_board>

-c | --compile

适用于

编译

--compile

编译的必需选项，但与 --link 和 --package 互斥。运行 v++ -c 以从内核源文件生成 XO 文件。

--clock

适用于

链接

提供一种方法，用于在链接进程中向内核分配时钟。如需了解更多信息，请参阅 --clock 选项。

--config

适用于

编译、链接和封装

--config <config_file> ...

指定包含 v++ 命令选项的配置文件。此配置文件可用于捕获编译、链接或封装策略，通过查看 v++ 命令行上的配置文件即可轻松复用这些策略。此外，该配置文件允许将 v++ 命令行缩短为仅包含配置文件中未指定的选项。如需了解更多信息，请参阅 Vitis 编译器配置文件。

v++ -l --config system.cfg --config vivado.cfg ...

--connectivity

适用于

链接

用于在链接进程中指定重要的器件二进制文件架构详细信息。如需了解更多信息，请参阅 --connectivity 选项。

--custom_script

适用于

编译和链接

--custom_script <kernel_name>:<file_name>

该选项支持您指定在编译或链接期间，构建 (build) 进程中将使用的定制 Tcl 脚本。搭配 --export_script 选项一起使用，用于创建、编辑和运行脚本以自定义构建进程。

搭配 v++ --compile 命令一起使用时，该选项允许您指定定制 HLS 脚本，以供在编译指定内核时使用。此脚本支持您修改或自定义 Vitis HLS 工具。--export_script 选项可用于提取 Vitis HLS 用于编译内核的 Tcl 脚本、按需修改此脚本并使用 --custom_script 选项重新提交，以便更好地管理内核构建进程。

v++ -c -k kernel1 -export_script ...
*** Modify the exported script to customize in some way, then resubmit. ****
v++ -c --custom_script kernel1:./kernel1.tcl ...

搭配 v++ --link 命令一起用于硬件构建目标 (-t hw) 时，该选项允许您指定指向已编辑的 run_script_map.dat 文件的绝对路径。该文件包含构建进程中的步骤列表以及 Vitis 和 Vivado 工具在执行这些步骤期间运行的 Tcl 脚本。您可编辑 run_script_map.dat 以指定在构建进程中执行这些步骤时要运行的定制 Tcl 脚本。要自定义 Tcl 脚本，必须使用以下步骤：

1. 运行构建进程并指定 --export_script 选项，如下所示：

   v++ -t hw -l -k kernel1 -export_script ...

2. 针对要自定义的任意步骤，复制 run_script_map.dat 文件中引用的 Tcl 脚本。例如，复制针对综合运行或实现运行所指定的 Tcl 文件。您必须将此文件复制到位于工程构建结构外部的独立位置。
3. 编译此 Tcl 脚本，添加或修改任意现有命令以创建新的定制 Tcl 脚本。
4. 编译 run_script_map.dat 文件，将特定实现步骤指向新的定制脚本。
5. 使用 --custom_script 选项重新启动构建进程，指定指向 run_script_map.dat 文件的绝对路径，如下所示：

   v++ -t hw -l -k kernel1 -custom_script /path/to/run_script_map.dat

read_xdc dont_touch.xdc
set_property used_in_implementation false [get_files dont_touch.xdc]

--debug

适用于

链接

指定在器件二进制文件 (.xclbin) 中插入的调试 IP 核。如需了解更多信息，请参阅 --debug 选项。

-D | --define

适用于

编译和链接

--define <arg>

有效的宏名称和定义对：<name>=<definition>。

将名称预定义为含定义的宏。该选项将传递给 v++ 预处理器。

--export_script

适用于

编译和链接

--export_script

该选项可运行构建进程，直至导出脚本文件或者脚本文件列表为止，然后停止执行。构建进程必须使用 --custom_script 选项来完成。这样您即可编辑导出的脚本或脚本列表，然后使用您的定制脚本来重新运行构建。

该选项搭配 v++ --compile 命令一起使用即可为指定内核导出 Tcl 脚本 <kernel_name>.tcl（可用于执行 Vitis HLS），但会在实际启动 HLS 工具前停止构建进程。这样您即可中断构建进程以编辑生成的 Tcl 脚本，然后使用 --custom_script 选项重新启动构建进程，如以下示例所示：

v++ -c -k kernel1 -export_script ...

该选项搭配 v++ --link 命令一起用于硬件构建目标 (-t hw) 时，即可在当前目录中导出 run_script_map.dat 文件。该文件包含构建进程中的步骤列表以及 Vitis 和 Vivado 工具在执行这些步骤期间运行的 Tcl 脚本。您可编辑指定的 Tcl 脚本、自定义这些脚本中的构建进程，然后使用 --custom_script 选项重新启动构建。使用以下命令导出 run_script_map.dat 文件：

v++ -t hw -l -k kernel1 -export_script ...

--from_step

适用于

编译和链接

--from_step <arg>

为 Vitis 编译器构建进程指定步骤名称，以从该步骤开始启动构建进程。如有中间结果可用，那么链接进程会快进至该指定步骤开始执行（如可能）。这样您即可通过 --to_step 运行构建，然后在通过某种方式与工程进行交互之后，于 --from_step 处恢复构建进程。您可使用 --list_step 选项来判定有效步骤的列表。

例如：

v++ --link --from_step vpl.update_bd

-g

适用于

编译和链接

-g

生成代码用于在软件仿真期间进行内核调试。该选项可用于添加相应的功能特性，以促进内核编辑时的调试。

例如：

v++ -g ...

-h | --help

-h

打印 v++ 命令的帮助内容。例如：

v++ -h

--hls

适用于

编译

指定内核编译期间 Vitis HLS 综合进程的选项。如需了解更多信息，请参阅 --hls 选项。

-I | --include

适用于

编译和链接

--include <arg>

在目录列表中添加指定目录，此列表可供搜索头文件。该选项将传递给 Vitis 编译器预处理器。

--input_files <input_file>

适用于

编译和链接

--input_files <input_file1> <input_file2> ...

指定 OpenCL 或 C/C++ 内核源文件用于执行 v++ 编译，或者指定赛灵思对象 (XO) 文件用于执行 v++ 链接。

例如：

v++ -l --input_files kernel1.xo kernelRTL.xo ...

v++ -l kernel1.xo kernelRTL.xo ...

--interactive

适用于

编译和链接

--interactive [ impl ]

v++ 能以实现工程来配置所需环境并启动 Vivado 工具。

由于您采用交互式方式来启动 Vivado 工具，因此在完成 vpl 步骤后链接进程即停止，这等同于在 v++ 命令中使用 --to_step vpl 选项。

以交互方式处理完 Vivado 工具并保存设计检查点 (DCP) 后，您可使用 v++ --from_step rtdgen 或者使用 --reuse_impl 或 --reuse_bit 选项来恢复 Vitis 编译器链接进程，以便读入已实现的 DCP 文件或比特流。

例如：

v++ --interactive impl
## Interactively use the Vivado tool
v++ --from_step rtdgen

-k | --kernel

适用于

编译

--kernel <arg>

仅编译来自输入文件的指定内核。每条 v++ 命令仅允许一个 -k 选项。有效值包括要编译的内核名称（来自输入 .cl 或 .c/.cpp 内核源代码）。

该选项对于 C/C++ 内核而言是必需的，但对于 OpenCL 内核而言则是可选选项。OpenCL 使用 kernel 关键字来识别内核。对于 C/C++ 内核，您必须通过 -k 或 --kernel 来识别内核。

如果编译 OpenCL 源文件时不使用 -k 选项，则会编译文件中的所有内核。使用 -k 可指定特定内核作为目标。

例如：

v++ -c --kernel vadd

--kernel_frequency

适用于

链接

--kernel_frequency <freq> | <clockID>:<freq>[<clockID>:<freq>]

为内核指定用户定义的时钟频率（以 MHz 为单位），覆盖硬件平台上定义的默认时钟频率。<freq> 可为仅有单个时钟的内核指定单一频率，或者也可用于为支持 2 个时钟的内核指定 <clockID> 和 <freq>。

在仅含单个内核时钟的平台上覆盖时钟的语法是只需指定以 MHz 为单位的频率即可：

v++ --kernel_frequency 300

要在含 2 个时钟的平台上覆盖特定时钟，请指定时钟 ID 和频率：

v++ --kernel_frequency 0:300

要在多时钟平台上覆盖 2 个时钟，请指定每个时钟 ID 和对应的频率。例如：

v++ --kernel_frequency 0:300|1:500

-l | --link

--link

这是编译后的链接进程的必需选项，但该选项与 --compile 或 --package 互斥。在链接模式下运行 v++ 即可链接 XO 输入文件并生成 xclbin 或 .xsa 输出文件。

--linkhook

适用于

链接

支持您通过指定将在实现进程的特定步骤中运行的 Tcl 脚本，为器件二进制文件自定义构建进程。如需了解更多信息，请参阅 --linkhook 选项。

--list_steps

适用于

编译和链接

--list_steps

列出给定目标的有效运行步骤。该选项会返回可在 --from_step 或 --to_step 选项中使用的步骤列表。此命令指定时，必须包含以下选项：

• -t | --target [sw_emu | hw_emu | hw ]：
• [ --compile | --link ]：指定来自指定构建目标的编译进程或链接进程的步骤列表。

例如：

v++ -t hw_emu --link --list_steps

--log_dir

适用于

编译和链接

--log_dir <dir_name>

指定用于存储 log 日志文件的目录。如不指定 --log_dir，则该工具会将 log 日志文件保存到 ./_x/logs 中。如需了解更多信息，请参阅 v++ 命令的输出目录。

例如：

v++ --log_dir /tmp/myProj_logs ...

--message_rules

适用于

编译和链接

--message-rules <file_name>

指定消息规则文件，其中包含用于控制消息的规则。如需了解更多信息，请参阅 使用消息规则文件。

例如：

v++ --message_rules ./minimum_out.mrf ...

--no_ip_cache

适用于

编译和链接

--no_ip_cache

为 Vivado 综合的非关联 (OOC) 综合禁用 IP 高速缓存。禁用 IP 高速缓存存储库要求该工具为每次构建重新生成 IP 综合结果，可能导致增加构建时间。但它也能生成清洁无错的构建，删除设计中先前的 IP 结果。

例如：

v++ --no_ip_cache ...

-O | --optimize

适用于

编译和链接

--optimize <arg>

该选项可指定 Vivado 实现结果的最优化级别。有效的最优化值包括：

• 0：默认最优化。缩短编译时间。
• 1：通过运行 Vivado 实现策略 Power_DefaultOpt 进行最优化，以减少功耗。这会导致设计构建时间增加。
• 2：通过最优化来提升内核速度。该选项会增加构建时间，但也能通过在实现中添加 PHYS_OPT_DESIGN 步骤来改善生成的内核的性能。
• 3：此最优化可在生成的代码中提供最高级别的性能，但是编译时间会显著增加。该选项可指定综合期间的重定时，并在实现期间启用 PHYS_OPT_DESIGN 和 POST_ROUTE_PHYS_OPT_DESIGN。
• s：对设计大小进行最优化。它可通过运行 Area_Explore 实现策略来减少内核所使用的器件逻辑资源。
• quick：缩短 Vivado 实现时间，但是会降低内核性能，并增加内核所使用的资源。它能为综合和实现启用 Flow_RuntimeOptimized 策略。

例如：

v++ --link --optimize 2

-o | --output

适用于

编译、链接和封装

-o <output_name>

指定 v++ 命令所生成的输出文件的名称。编译 (-c) 进程输出名称必须以赛灵思对象文件的 XO 文件后缀结尾。链接 (-l) 进程输出文件必须以赛灵思可执行二进制文件的 xclbin 文件后缀结尾。

例如：

v++ -o krnl_vadd.xo

如不指定 --o 或 --output，则输出文件名默认设置为：

编译

a.o

链接

a.xclbin（对于 Versal 平台则为 a.xsa）

封装

a.xclbin

-p | --package

适用于

封装

指定选项，供 Vitis 编译器用于对设计进行封装，以运行仿真或在硬件上运行。如需了解更多信息，请参阅 --package 选项。

-f | --platform

适用于

编译和链接

--platform <platform_name>

指定受支持的加速平台（由 $PLATFORM_REPO_PATHS 环境变量指定）的名称，或者指定指向平台 .xpfm 文件的完整路径。要获取该版本支持的平台列表，请参阅 Vitis 软件平台版本说明。

该选项对于编译和链接都属于必需选项，用于定义构建进程的目标赛灵思平台。--platform 选项可接受平台名称或者指向平台文件 xpfm（使用完整路径或相对路径）的路径。

例如：

v++ --platform xilinx_u200_gen3x16_xdma_2_202110_1 ...

platform=xilinx_u200_gen3x16_xdma_2_202110_1

--profile

适用于

编译和链接

指定选项用于配置赛灵思运行时环境以便捕获应用性能信息。如需了解更多信息，请参阅 --profile 选项。

--remote_ip_cache

适用于

编译和链接

--remote_ip_cache <dir_name>

指定远程 IP 高速缓存目录的位置，以供 Vivado 综合在 IP 的非关联 (OOC) 综合期间使用。OOC 综合允许 Vivado 综合工具复用 IP 的综合结果，这些综合结果在设计迭代过程中未进行更改。由于复用综合结果，因此可缩短 .xclbin 文件所需的构建时间。

不指定 --remote_ip_cache 选项时，IP 高速缓存会写入原先从中启动 v++ 的当前工作目录。您可使用该选项来指定其它高速缓存位置，此位置可供多个工程使用。

例如：

v++ --remote_ip_cache /tmp/IP_cache_dir ...

--report_dir

适用于

编译和链接

--report_dir <dir_name>

指定用于存储报告文件的目录。如不指定 --report_dir，则该工具会将报告文件保存到 ./_x/reports 中。如需了解更多信息，请参阅 v++ 命令的输出目录。

例如：

v++ --report_dir /tmp/myProj_reports ...

-R | --report_level

适用于

编译和链接

--report_level <arg>

有效的报告级别：0、1、2 和 estimate。

这些报告级别的映射保存在 optMap.xml 文件中。您可改写已安装的 optMap.xml 以定义定制报告级别。

• -R0 规格会在 Vivado 实现期间关闭所有中间设计检查点 (DCP) 生成操作。开启布线后时序报告生成。
• -R1 规格包含来自 -R0 的一切以及 report_failfast pre-opt_design 和 report_failfast post-opt_design，还会启用所有中间 DCP 生成操作。
• -R2 规格包含来自 -R1 的一切以及 report_failfast post-route_design。
• -Restimate 规格会强制 Vitis HLS 生成 design.xml 文件（如果此文件不存在），然后生成“System Estimate”（系统估算）报告，如 系统估算报告 中所述。
  提示： 如果默认不生成 design.xml，该选项可用于软件仿真构建 (-t sw_emu)。

例如：

v++ -R2 ... 

--reuse_bit

--reuse_bit <arg>

适用于

链接

指定生成的比特流文件 (.bit) 的路径和文件名，生成器件二进制文件 (xclbin) 时将使用此比特流文件。如 使用 -to_step 并以交互方式启动 Vivado 中所述，您可指定 --to_step 选项以中断 Vitis 构建进程并对已综合的设计进行手动布局布线以生成比特流。

例如：

v++ --link --reuse_bit ./project.bit

--reuse_impl

--reuse_impl <arg>

适用于

链接

指定已实现的设计检查点 (DCP) 文件的路径和文件名，生成器件二进制文件 (xclbin) 时将使用此 DCP 文件。链接进程使用已实现的指定 DCP 来提取 FPGA 比特流并生成 xclbin。您可手动编辑由先前已完成的 Vitis 构建所创建的 Vivado 工程，或者也可指定 --to_step 选项以中断 Vitis 构建进程，并对已综合的设计进行手动布局布线。这样您即可以交互方式来使用 Vivado Design Suite，在构建进程中更改设计和使用 DCP。

例如：

v++ --link --reuse_impl ./manual_design.dcp

-s | --save-temps

适用于

编译和链接

--save-temps

指示 v++ 命令保存在编译进程和链接进程期间所创建的中间文件/目录。--temp_dir 选项可用于指定中间文件的写入位置。

例如：

v++ --save-temps ...

-t | --target

适用于

编译和链接

-t [ sw_emu | hw_emu | hw ]

指定构建目标，如 构建目标 中所述。构建目标会判定编译进程和链接进程的结果。您可以选择构建仿真模型用于调试和测试，或者构建真实系统以供在硬件中运行。如不指定 -t，那么构建目标默认设置为 hw。

有效值包括：

• sw_emu：软件仿真
• hw_emu：硬件仿真
• hw：硬件

例如：

v++ --link -t hw_emu

--temp_dir

适用于

编译和链接

--temp_dir <dir_name>

该选项允许您管理在构建进程中所创建的临时文件的写入位置。临时结果由 v++ 编译器写入，然后被移除，除非同时指定 --save-temps 选项。

如不指定 --temp_dir，那么该工具会将临时文件保存到 ./_x/temp 中。如需了解更多信息，请参阅 v++ 命令的输出目录。

例如：

v++ --temp_dir /tmp/myProj_temp ...

--to_step

适用于

编译和链接

--to_step <arg>

为编译进程或链接进程指定步骤名称，以便通过该步骤来运行构建进程。您可使用 --list_step 选项来判定有效的编译步骤或链接步骤的列表。

构建进程会在完成指定步骤后终止。此时，您即可与构建结果进行交互。例如，手动访问 HLS 工程或者 Vivado Design Suite 工程以执行特定任务，然后再返回构建流程并以 --from_step 选项启动 v++ 命令。

使用 --to_step 时，必须同时指定 --save-temps 以保存 Vivado 工具所需的临时文件。例如：

v++ --link --save-temps --to_step vpl.update_bd

--user_board_repo_paths

适用于

编译和链接

--user_board_repo_paths

为 DIMM 开发板文件指定现有用户开发板存储库。该值将追加到 Vivado 工程的 board_part_repo_paths 属性之前。

--user_ip_repo_paths

适用于

编译和链接

--user_ip_repo_paths <repo_dir>

指定一个或多个用户 IP 存储库路径的目录位置，以供首先在其中搜索内核设计中所使用的 IP。该值将附加到 Vivado 工具所用的 ip_repo_paths 开头位置之后，用于定位 IP 核。优先使用来自这些指定路径的 IP 定义，然后再使用来自硬件平台 (.xsa) 或来自赛灵思 IP 目录的 IP 存储库的 IP 定义。

以下列表显示了构建进程中查找 IP 定义的优先顺序（从高到低）。

• 对于系统硬件构建 (-t hw)：
  1. 来自 --user_ip_repo_paths 的 IP 定义。
  2. 内核 IP 定义（vpl --iprepo 开关值）。
  3. 来自与平台关联的 IP 存储库的 IP 定义。
  4. 来自安装区域的 IP 高速缓存（例如，<Install_Dir>/Vitis/2019.2/data/cache/）。
  5. 来自安装区域的赛灵思 IP 目录（例如，<Install_Dir>/Vitis/2019.2/data/ip/）
• 对于硬件仿真构建 (-t hw_emu)：
  1. 来自 --user_ip_repo_paths 的 IP 定义和用户仿真 IP 存储库。
  2. 内核 IP 定义（vpl --iprepo 开关值）。
  3. 来自与平台关联的 IP 存储库的 IP 定义。
  4. 来自安装区域的 IP 高速缓存（例如，<Install_Dir>/Vitis/2019.2/data/cache/）。
  5. $::env(XILINX_VITIS)/data/emulation/hw_em/ip_repo
  6. $::env(XILINX_VIVADO)/data/emulation/hw_em/ip_repo
  7. 来自安装区域的赛灵思 IP 目录（例如，<Install_Dir>/Vitis/2019.2/data/ip/）

例如：

v++ --user_ip_repo_paths ./myIP_repo ...

-v | --version

-v

打印 v++ 命令的版本和构建信息。例如：

v++ -v

--vivado

适用于

链接

指定属性和参数，以在构建器件二进制文件之前配置 Vivado 综合和实现环境。如需了解更多信息，请参阅 --vivado 选项。