The v++
command supports many options for the compilation,
linking, and packaging processes as described below.
v++
command-line options can be specified in a configuration file for use with the
--config
option, as discussed in the Vitis Compiler Configuration File. For example, the --platform
option can be specified in a configuration
file using the following
syntax:platform=xilinx_u50_gen3x16_xdma_5_202210_1
--advanced
- Applies to:
- Compile, Link, Package
Specify parameters and properties for use by the v++
command. See --advanced Options for more information.
--board_connection
- Applies to:
- Link
--board_connection
Specifies a dual in-line memory module (DIMM) board file for each DIMM connector slot. The board is specified using the Vendor:Board:Name:Version (vbnv) attribute of the DIMM card as it appears in the board repository.
For example:
<DIMM_connector>:<vbnv_of_DIMM_board>
-c | --compile
- Applies to:
- Compile
--compile
Required for compilation, but mutually exclusive with --link
and --package
. Run v++ -c
to generate XO
files from kernel source files.
--clock
- Applies to:
- Link
Provide a method for assigning clocks to kernels during the linking process. See --clock Options for more information.
--config
- Applies to:
- Compile, Link, Package
--config <config_file> ...
Specifies a configuration file containing v++
command options. The configuration file can be used to capture
compilation, linking, or packaging strategies, that can be easily reused by
referring to the config file on the v++
command
line. In addition, the config file allows the v++
command line to be shortened to include only the options that are not specified in
the config file. Refer to the Vitis Compiler Configuration File
for more information.
v++
command line. A separate --config
switch is
required for each file used. For example:v++ -l --config system.cfg --config vivado.cfg ...
--connectivity
- Applies to:
- Link
Used to specify important architectural details of the device binary during the linking process. See --connectivity Options for more information.
--custom_script
- Applies to:
- Compile, Link
--custom_script <kernel_name>:<file_name>
This option lets you specify custom Tcl scripts to be used in the
build process during compilation or linking. Use with the --export_script
option to create, edit, and run the scripts to
customize the build process.
When used with the v++ --compile
command, this option lets you specify a custom HLS script to be used when compiling
the specified kernel. The script lets you modify or customize the Vitis HLS tool. Use the --export_script
option to extract a Tcl script Vitis HLS uses to compile the kernel, modify the
script as needed, and resubmit using the --custom_script
option to better manage the kernel build process.
v++ -c -k kernel1 -export_script ...
*** Modify the exported script to customize in some way, then resubmit. ****
v++ -c --custom_script kernel1:./kernel1.tcl ...
When used with the v++ --link
command for the hardware build target (-t hw
),
this option lets you specify the absolute path to an edited run_script_map.dat file. This file contains a list
of steps in the build process, and Tcl scripts that are run by the Vitis and Vivado tools during those steps. You can edit run_script_map.dat to specify custom Tcl scripts to
run at those steps in the build process. You must use the following steps to
customize the Tcl scripts:
- Run the build process specifying the
--export_script
option as follows:v++ -t hw -l -k kernel1 -export_script ...
- Copy the Tcl scripts referenced in the run_script_map.dat file for any of the steps you want to customize. For example, copy the Tcl file specified for the synthesis run, or the implementation run. You must copy the file to a separate location, outside of the project build structure.
- Edit the Tcl script to add or modify any of the existing commands to create a new custom Tcl script.
- Edit the run_script_map.dat file to point a specific implementation step to the new custom script.
- Relaunch the build process using the
--custom_script
option, specifying the absolute path to the run_script_map.dat file as shown below: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]
The synthesis run returns an error related to a missing dont_touch.xdc file if this is not done.
--debug
- Applies to:
- Link
Specify the addition of debug IP core insertion into the hardware design. See --debug Options for more information.
-D | --define
- Applies to:
- Compile, Link
--define <arg>
Valid macro name and definition pair: <name>=<definition>
.
Predefine name as a macro with definition. This option is passed to the
v++
preprocessor.
--export_script
- Applies to:
- Compile, Link, Package
--export_script
This option runs the build process up to the point of exporting a
script file, or list of script files, and then stops execution. The build process
must be completed using the --custom_script
option. This lets you edit the exported script, or list of scripts, and then rerun
the build using your custom scripts.
When used with the v++ --compile
command, this option exports a Tcl script for the specified kernel, <kernel_name>.tcl, that can be used to execute
Vitis HLS, but stops the build process
before actually launching the HLS tool. This lets you interrupt the build process to
edit the generated Tcl script, and then restart the build process using the --custom_script
option, as shown in the following
example:
v++ -c -k kernel1 -export_script ...
–t sw_emu
)
of OpenCL kernels.When used with the v++ --link
command for the hardware build target (-t hw
),
this option exports a run_script_map.dat file
in the current directory. This file contains a list of steps in the build process,
and Tcl scripts that are run by the Vitis and
Vivado tools during those steps. You can
edit the specified Tcl scripts, customizing the build process in those scripts, and
relaunch the build using the --custom_script
option. Export the run_script_map.dat file
using the following command:
v++ -l -t hw -export_script ...
--from_step
- Applies to:
- Compile, Link, Package
--from_step <arg>
Specifies a step name for the Vitis compiler build process, to start the build process from that
step. If intermediate results are available, the link process fast forwards and
begins execution at the named step if possible. This allows you to run the build
through a --to_step
, and then resume the build
process at the --from_step
, after interacting
with your project in some method. You can use the --list_step
option to determine the list of valid steps.
--to_step
/--from_step
are sequential build options that require you to use
--from_step
to resume the build in the same
project directory that you used when starting the build with --to_step
.For example:
v++ --link --from_step vpl.update_bd
-g
- Applies to:
- Compile, Link
-g
Generates code for debugging the kernel during software emulation. Using this option adds features to facilitate debugging the kernel as it is compiled.
For example:
v++ -g ...
-h | --help
- Applies to:
- Compile, Link, Package
-h
Prints the help contents for the v++
command. For example:
v++ -h
--hls
- Applies to:
- Compile
Specify options for the Vitis HLS synthesis process during kernel compilation. See --hls Options for more information.
-I | --include
- Applies to:
- Compile, Link
--include <arg>
Add the specified directory to the list of directories to be searched for header files. This option is passed to the Vitis compiler pre-processor.
--input_files <input_file>
- Applies to:
- Compile, Link, Package
--input_files <input_file1> <input_file2> ...
Specifies an OpenCL or C/C++
kernel source file for v++
compilation, or
Xilinx object (XO) files for v++
linking.
For example:
v++ -l --input_files kernel1.xo kernelRTL.xo ...
--input_files
option. For example:
v++ -l kernel1.xo kernelRTL.xo ...
--interactive
- Applies to:
- Link
--interactive [ impl ]
v++
configures the needed
environment and launches the Vivado tool with
the implementation project.
Because you are interactively launching the Vivado tool, the linking process is stopped after
the vpl
step, which is the equivalent of using
the --to_step vpl
option in your v++
command.
When you are done interactively working with the Vivado tool, and you save the design checkpoint
(DCP), you can resume the Vitis compiler
linking process using the v++ --from_step rtdgen
,
or use the --reuse_impl or --reuse_bit
options to read in the implemented DCP
file or bitstream.
For example:
v++ --interactive impl
## Interactively use the Vivado tool
v++ --from_step rtdgen
-k | --kernel
- Applies to:
- Compile
--kernel <arg>
Compile only the specified kernel from the input file. Only one
-k
option is allowed per v++
command. Valid values include the name of the
kernel to be compiled from the input .cl or
.c/.cpp kernel source code.
This is required for C/C++ kernels, but is optional for OpenCL kernels. OpenCL uses the kernel
keyword to
identify a kernel. For C/C++ kernels, you must identify the kernel by -k
or --kernel
.
When an OpenCL source file is
compiled without the -k
option, all the kernels in
the file are compiled. Use -k
to target a
specific kernel.
For example:
v++ -c --kernel vadd
--kernel_frequency
- Applies to:
- Link
--kernel_frequency <freq> | <clockID>:<freq>[<clockID>:<freq>]
Specifies a user-defined clock frequency (in MHz) for the kernel,
overriding the default clock frequency defined on the hardware platform. The <freq>
specifies a single frequency for kernels
with only a single clock, or can be used to specify the <clockID> and the
<freq> for kernels that support two clocks.
The syntax for overriding the clock on a platform with only one kernel clock, is to simply specify the frequency in MHz:
v++ --kernel_frequency 300
To override a specific clock on a platform with two clocks, specify the clock ID and frequency:
v++ --kernel_frequency 0:300
To override both clocks on a multi-clock platform, specify each clock ID and the corresponding frequency. For example:
v++ --kernel_frequency 0:300|1:500
-l | --link
- Applies to:
- Link
--link
This is a required option for the linking process, which follows
compilation, but is mutually exclusive with --compile
or --package
. Run v++
in link mode to link XO input files and generate
an xclbin or and .xsa output file.
--link
option generates an .xclbin file for most platforms, but generates an .xsa file for Versal platforms. --linkhook
- Applies to:
- Link
Lets you customize the build process for the device binary by specifying Tcl scripts to be run at specific steps in the implementation flow. See --linkhook Options for more information.
--list_steps
- Applies to:
- Compile, Link, Package
--list_steps
List valid run steps for a given target. This option returns a list
of steps that can be used in the --from_step
or
--to_step
options. The command must be
specified with the following options:
-
-t | --target [sw_emu | hw_emu | hw ]
: -
[ --compile | --link ]
: Specifies the list of steps from either the compile or link process for the specified build target.
For example:
v++ -t hw_emu --link --list_steps
--log_dir
- Applies to:
- Compile, Link, Package
--log_dir <dir_name>
Specifies a directory to store log files into. If --log_dir
is not specified, the tool saves the log
files to ./_x/logs. Refer to Output Directories of the v++ Command for more information.
For example:
v++ --log_dir /tmp/myProj_logs ...
--message_rules
- Applies to:
- Compile, Link, Package
--message-rules <file_name>
Specifies a message rule file with rules for controlling messages. Refer to Using the Message Rule File for more information.
For example:
v++ --message_rules ./minimum_out.mrf ...
--no_ip_cache
- Applies to:
- Link
--no_ip_cache
Disables the IP cache for out-of-context (OOC) synthesis for Vivado Synthesis. Disabling the IP cache repository requires the tool to regenerate the IP synthesis results for every build, and can increase the build time. However, it also results in a clean build, eliminating earlier results for IP in the design.
For example:
v++ --no_ip_cache ...
-O | --optimize
- Applies to:
- Link
--optimize <arg>
This option specifies the optimization level of the Vivado implementation results. Valid optimization values include the following:
-
0
: Default optimization. Reduces compilation time. -
1
: Optimizes to reduce power consumption by running Vivado implementation strategyPower_DefaultOpt
. This takes more time to build the design. -
2
: Optimizes to increase kernel speed. This option increases build time, but also improves the performance of the generated kernel by adding thePHYS_OPT_DESIGN
step to implementation. -
3
: This optimization provides the highest level performance in the generated code, but compilation time can increase considerably. This option specifies retiming during synthesis, and enables bothPHYS_OPT_DESIGN
andPOST_ROUTE_PHYS_OPT_DESIGN
during implementation. -
s
: Optimizes the design for size. This reduces the logic resources of the device used by the kernel by running theArea_Explore
implementation strategy. -
quick
: Reduces Vivado implementation time, but can reduce kernel performance, and increases the resources used by the kernel. This enables theFlow_RuntimeOptimized
strategy for both synthesis and implementation.
For example:
v++ --link --optimize 2
-o | --output
- Applies to:
- Compile, Link, Package
-o <output_name>
Specifies the name of the output file generated by the v++
command. The compilation (-c
) process output name must end with the XO file
suffix, for Xilinx object file. The linking
(-l
) process output file must end with the
xclbin file suffix, for Xilinx executable binary.
For example:
v++ -o krnl_vadd.xo
If --o
or --output
are not specified, the output file names
default to the following:
- Compilation
- a.o
- Linking
- a.xclbin (a.xsa for Versal platforms)
- Packaging
- a.xclbin
-p | --package
- Applies to:
- Package
Specify options for the Vitis compiler to package your design for either running emulation or running on hardware. See --package Options for more information.
-f | --platform
- Applies to:
- Compile, Link, Package
--platform <platform_name>
Specifies the name of a supported acceleration platform as
specified by the $PLATFORM_REPO_PATHS
environment
variable, or the full path to the platform .xpfm file. For a list of supported platforms for the release, see
the Vitis Software Platform Release Notes.
This is a required option for both compilation and linking, to
define the target Xilinx platform of the build
process. The --platform
option accepts either a
platform name, or the path to a platform file xpfm, using the full or relative path.
--platform
and -t
options specified when the XO file is generated by
compilation, must be the --platform
and -t
used during linking, and packaging. For more
information, see platforminfo Utility.For example:
v++ --platform xilinx_u50_gen3x16_xdma_5_202210_1 ...
--config
option. For example, the platform
option can be
specified in a configuration file without a section head using the following
syntax:platform=xilinx_u50_gen3x16_xdma_5_202210_1
--profile
- Applies to:
- Compile, Link
Specify options to configure the Xilinx runtime environment to capture application performance information. See --profile Options for more information.
--remote_ip_cache
- Applies to:
- Link
--remote_ip_cache <dir_name>
Specifies the location of the remote IP cache directory for Vivado Synthesis to use during out-of-context (OOC) synthesis of IP. OOC synthesis lets the Vivado synthesis tool reuse synthesis results for IP that have not been changed in iterations of a design. This can reduce the time required to build your .xclbin files, due to reusing synthesis results.
When the --remote_ip_cache
option is not specified the IP cache is written to the current working directory
from which v++
was launched. You can use this
option to provide a different cache location, used across multiple projects for
instance.
For example:
v++ --remote_ip_cache /tmp/IP_cache_dir ...
--report_dir
- Applies to:
- Compile, Link, Package
--report_dir <dir_name>
Specifies a directory to store report files into. If --report_dir
is not specified, the tool saves the
report files to ./_x/reports. Refer to Output Directories of the v++ Command for more information.
For example:
v++ --report_dir /tmp/myProj_reports ...
-R | --report_level
- Applies to:
- Compile, Link, Package
--report_level <arg>
Valid report levels: 0
, 1
, 2
, estimate
.
These report levels have mappings kept in the optMap.xml file. You can override the installed optMap.xml to define custom report levels.
-
-R0
specification turns off all intermediate design checkpoint (DCP) generation during Vivado implementation. Turns on post-route timing report generation. - The
-R1
specification includes everything from-R0
, plusreport_failfast pre-opt_design
,report_failfast post-opt_design
, and enables all intermediate DCP generation. - The
-R2
specification includes everything from-R1
, plusreport_failfast post-route_design
. - The
-Restimate
specification forces Vitis HLS to generate a design.xml file if it does not exist and then generates a System Estimate report, as described in System Estimate Report.Tip: This option is useful for the software emulation build (-t sw_emu
), when design.xml is not generated by default.
For example:
v++ -R2 ...
--reuse_bit
--reuse_bit <arg>
- Applies to:
- Link
Specifies the path and file name of generated bitstream file
(.bit) to use when generating the device
binary (xclbin) file. As described in Using -to_step and Launching Vivado Interactively, you can specify the --to_step
option to interrupt the Vitis build process and manually place and route a
synthesized design to generate the bitstream.
--reuse_bit
option is a sequential build
option that requires you to use the same project directory when resuming the
Vitis compiler with --reuse_bit
that you specified when using --to_step
to start the build.For example:
v++ --link --reuse_bit ./project.bit
--reuse_impl
--reuse_impl <arg>
- Applies to:
- Link
Specifies the path and file name of an implemented design
checkpoint (DCP) file to use when generating the device binary (xclbin) file. The link process uses the specified
implemented DCP to extract the FPGA bitstream and generates the xclbin. You can manually edit theVivado project created by a previously completed
Vitis build, or specify the --to_step
option to interrupt the Vitis build process and manually place and route a
synthesized design, for instance. This allows you to work interactively with
Vivado Design Suite to change the design and
use DCP in the build process.
--reuse_impl
option is an incremental build
option that requires you to use the same project directory when resuming the
Vitis compiler with --reuse_impl
that you specified when using --to_step
to start the build.For example:
v++ --link --reuse_impl ./manual_design.dcp
-s | --save-temps
- Applies to:
- Compile, Link, Package
--save-temps
Directs the v++
command to save
intermediate files/directories created during the compilation and link process. Use
the --temp_dir
option to specify a location to
write the intermediate files to.
For example:
v++ --save-temps ...
-t | --target
- Applies to:
- Compile, Link, Package
-t [ sw_emu | hw_emu | hw ]
Specifies the build target, as described in Build Targets. The build target determines the results of the
compilation and linking processes. You can choose to build an emulation model for
debug and test, or build the actual system to run in hardware. The build target
defaults to hw
if -t
is not specified.
--platform
and -t
options specified when the XO file is generated by compilation must
be the --platform
and -t
used during linking.The valid values are:
-
sw_emu
: Software emulation -
hw_emu
: Hardware emulation -
hw
: Hardware
For example:
v++ --link -t hw_emu
--temp_dir
- Applies to:
- Compile, Link, Package
--temp_dir <dir_name>
This allows you to manage the location where the tool writes
temporary files created during the build process. The temporary results are written
by the v++
compiler, and then removed, unless the
--save-temps
option is also specified.
If --temp_dir
is not specified,
the tool saves the temporary files to ./_x/temp. Refer to Output Directories of the v++ Command for more information.
For example:
v++ --temp_dir /tmp/myProj_temp ...
--to_step
- Applies to:
- Compile, Link, Package
--to_step <arg>
Specifies a step name, for either the compile or link process, to
run the build process through that step. You can use the --list_step
option to determine the list of valid compile or link
steps.
The build process terminates after completing the named step. At
this time, you can interact with the build results. For example, manually accessing
the HLS project or the Vivado Design Suite
project to perform specific tasks before returning to the build flow, launch the
v++
command with the --from_step
option.
--to_step
/--from_step
are
sequential build options that require you to use --from_step
to resume the build in the same project directory that you
used when starting the build with --to_step
.You must also specify --save-temps
when using --to_step
to
preserve the temporary files required by the Vivado tools. For example:
v++ --link --save-temps --to_step vpl.update_bd
--user_board_repo_paths
- Applies to:
- Link
--user_board_repo_paths
Specifies an existing user board repository for DIMM board files.
This value is pre-pended to the board_part_repo_paths
property of the Vivado project.
--user_ip_repo_paths
- Applies to:
- Link
--user_ip_repo_paths <repo_dir>
Specifies the directory location of one or more user IP repository
paths to be searched first for IP used in the kernel design. This value is appended
to the start of the ip_repo_paths
used by the
Vivado tool to locate IP cores. IP
definitions from these specified paths are used ahead of IP repositories from the
hardware platform (.xsa) or from the Xilinx IP catalog.
--user_ip_repo_paths
can be specified on the v++
command line.The following lists show the priority order in which IP definitions are found during the build process, from high to low.
- For the system hardware build (
-t hw
):- IP definitions from
--user_ip_repo_paths
. - Kernel IP definitions (
vpl --iprepo
switch value). - IP definitions from the IP repository associated with the platform.
- IP cache from the installation area (for example, <Install_Dir>/Vitis/2019.2/data/cache/).
- Xilinx IP catalog from the installation area (for example, <Install_Dir>/Vitis/2019.2/data/ip/)
- IP definitions from
- For the hardware emulation build (
-t hw_emu
):- IP definitions and User emulation IP repository from
--user_ip_repo_paths
. - Kernel IP definitions (
vpl --iprepo
switch value). - IP definitions from the IP repository associated with the platform.
- IP cache from the installation area (for example, <Install_Dir>/Vitis/2019.2/data/cache/).
-
$::env(XILINX_VITIS)/data/emulation/hw_em/ip_repo
-
$::env(XILINX_VIVADO)/data/emulation/hw_em/ip_repo
- Xilinx IP catalog from the installation area (for example, <Install_Dir>/Vitis/2019.2/data/ip/)
- IP definitions and User emulation IP repository from
For example:
v++ --user_ip_repo_paths ./myIP_repo ...
-v | --version
-v
Prints the version and build information for the v++
command. For example:
v++ -v
--vivado
- Applies to:
- Link
Specify properties and parameters to configure the Vivado synthesis and implementation environment prior to building the device binary. See --vivado Options for more information.