Using Configuration files to Control Vitis Compilation
Introduction
The Vitis™ unified software platform adopts the configuration file manner to control the compiler and linker behavior which is going to substitute the previous command line switches style in the Xilinx® OpenCL Compiler (XOCC). The major advantages of using configuration files include the following:
- Less error-prone: The old command line switches style results in long commands, which are hard to read and modify. Below is an example:
v++ -t hw --log_dir /f1/f2/log_dir --report_dir /f1/f2/report_dir --xp vivado_prop:run.impl_1.STEPS.ROUTE_DESIGN.TCL.POST=/f1/f2/f3/mypostroute.tcl --xp
param:compiler.userPostSysLinkTcl=/f1/f2/f3/f4/user_port_sys_link.tcl --nk
my_krnl:1:krnl_1 --sp krnl_1.m00_axi:bank0 --sp krnl_1.m01_axi:bank1 --sp
krnl_1.m02_axi:bank2 --sp krnl_1.m03_axi:bank3 --sp krnl_1.m04_axi:bank1 --sp
krnl_1.m05_axi:bank2 --sp krnl_1.m06_axi:bank0 --sp krnl_1.m07_axi:bank0 --sp
krnl_1.m08_axi:bank1 --sp krnl_1.m09_axi:bank2 --sp krnl_1.m10_axi:bank3
--profile_kernel data:my_krnl:all:m01_axi –debug --platform ./f1/f2/xilinx_u200_xdma_201920_1/xilinx_u200_xdma_201920_1.xpfm --kernel_frequency 0:300|1:350 -o my_design.xclbin ./my_krnl.xo
- Different types of options can be grouped into different sections/files: There are a lot of different options for the Vitis tool, and they are under different categories. For example, some of them are used to control Vitis compiler/linker behavior and some are used to control the Vivado® tools flow. To enhance ease of use, configuration files support grouping like types of options into one section or even one file. The format is:
[section name]
Option1=A
...
Option1=B
In one configuration file, we can have multiple sections as shown above.
- Using multiple configuration files can take advantage of the makefile dependency rule. Modifying the options within one configuration file will not cause the recompilation of everything.
- Switches are read in the order they are encountered. If the same switch is repeated with conflicting information, the first switch read is used. The order of precedence for switches is as follows, where item one takes highest precedence:
- Command line switches.
- Configuration files (on command line) from left to right.
- Within a configuration file, precedence is from top to bottom.
Although there is a precedence rule for switches specified more than once, it is recommended that you avoid doing this, because it will cause more work to identify which option wins. Also, there is no benefit for specifying the same option more than once.
Migrating Current Command Line Switches to Configuration Files
If you already have an existing design that uses command line style options, you might want to know how to convert into the new configuration style. For information about this, refer to Vitis Compiler Configuration File in the Vitis Unified Software Development Platform Documentation (UG1393).
The following summarizes some commonly used options and highlights the comparison between new and old command line styles.
Boolean Switches (Out of Any Sections)
Options that are set to True or False. Usually these are for enabling certain flow.
Purpose of Option |
Old |
New |
Select stage |
--link(or –l) |
link=1 |
Enable debug mode |
-g |
debug=1 |
General Switches (Out of Any Sections)
Usually used to specify project configurations.
Purpose of Option |
Old |
New |
Select target platform |
--platform xxx |
platform=xxx |
Directory for logs |
--log_dir |
log_dir=<dir_path> |
Directory for reports |
--report_dir |
report_dir=<dir_path> |
Select compile target |
--target hw |
target=hw |
Connectivity Switches (section name: [connectivity])
Options for system topology, such as memory connection, compute unit settings, etc.
Purpose of Option |
Old |
New |
Number of CUs |
--nk foo:2:foo_1.foo_2 |
nk=foo:2:foo_1.foo_2 |
Specify memory connection |
--sp vadd_cu1.m_axi_gmem:HBM[0:3] |
sp=vadd_cu1.m_axi_gmem:HBM[0:3] |
Specify streaming connection between CUs |
--sc vadd_1.stream_out:vadd_2.stream_in |
stream_connect=vadd_1.stream_out:vadd_2.stream_in |
Assign CU to SLR |
--slr vadd_1:SLR0 |
slr=vadd_1:SLR0 |
HLS Parameters (section name: [hls])
Options that are used to configure the HLS tool.
Purpose of Option |
Old |
New |
Specify kernel frequency |
--kernel_frequency:250 |
clock=<frequency>:<CU_name> |
Generate separate AXI interface for each argument(only for OpenCL kernel) |
--max_memory_ports <all|kernel_name> |
max_memory_ports=all|kernel_name |
Vivado Properties and Parameters (section name: [vivado])
Options that are used to configure Vivado tool.
Purpose of Option |
Old |
New |
Vivado Properties |
--xp vivado_prop run.synth.STEPS.SYNTH_DESIGN.TCL.PRE=pre.tcl |
prop=run.synth.STEPS.SYNTH_DESIGN.TCL.PRE=pre.tcl |
Vivado Parameters |
--xp vivado_param:project.writeIntermediateCheckpoints=1 |
param=project.writeIntermediateCheckpoints=1 |
Advanced Switches (section name: [advanced])
Advanced options to control the flow.
Purpose of Option |
Old |
New |
Misc |
--xp vivado_prop run.synth.STEPS.SYNTH_DESIGN.TCL.PRE=pre.tcl |
prop=run.synth.STEPS.SYNTH_DESIGN.TCL.PRE=pre.tcl |
Non-Vivado Properties |
--xp prop:kernel.krnl_vadd.kernel_flags=<prop_value> |
prop=kernel.krnl_vadd.kernel_flags=<prop_value> |
Non-Vivado Parameters |
--xp param:compiler.acceleratorBinaryContent=dcp |
param=compiler.acceleratorBinaryContent=dcp |
Use Case Examples
In following sections, we will provide a few common uses cases to show how to achieve it using configuration files.
Control Vitis Compile and Link
The most often use of the v++ option may relate to controlling Vitis compiler and linker. For example, you might need to create multiple compute units (CU) for your kernel design and assign the memory connections as well. To achieve that, you can create a connectivity.ini file and add the following lines into the file:
[connectivity]
nk=foo:3
sp=foo_1.m_axi_p0:DDR[0]
sp=foo_2.m_axi_p0:DDR[1]
sp=foo_3.m_axi_p0:DDR[2]
The connectivity.ini file needs to be sourced in v++ script as shown below.
v++ -l … --config connectivity.ini …
Control HLS and Vivado Compilation
Sometimes, we need to control HLS parameter and Vivado strategy to improve performance. In this situation, we can create either one configuration file to control both of them at the same time or use two separate files. Here we will use two files as an example: hls_config.ini and vivado_config.ini.
In hls_config.ini, we want to over constrain the HLS tool for better timing margin. For example, the kernel target frequency is 300MHz; we can increase HLS target frequency as 320MHz as follows:
[hls]
clock=320000000:foo
In vivado_config.ini, we can fine tune the implementation strategy in Vivado to get a better implementation result but it requires solid hardware design experience. Xilinx does not recommend manual modifications if you are not confident about the consequence of these options. For example, we can add following lines in vivado_config.ini:
[vivado]
prop=run.impl_1.STEPS.OPT_DESIGN.ARGS.DIRECTIVE=Explore
prop=run.impl_1.STEPS.PLACE_DESIGN.ARGS.DIRECTIVE=Explore
prop=run.impl_1.STEPS.PHYS_OPT_DESIGN.IS_ENABLED=true
prop=run.impl_1.STEPS.PHYS_OPT_DESIGN.ARGS.DIRECTIVE=AggressiveExplore
prop=run.impl_1.STEPS.ROUTE_DESIGN.ARGS.DIRECTIVE=Explore
prop=run.impl_1.STEPS.OPT_DESIGN.TCL.PRE=<absolute path>/preopt.tcl
You might notice that this file sources a Tcl file before opt_design stage. In this Tcl file, you can add a few timing or floorplan constraints, which benefit the performance.
After that, these two configuration files can be sourced together in v++ script:
v++ -l … --config vivado_config.ini –config hls_config.ini …
Summary
The Vitis tool provides the new configuration file method to substitute the traditional command line switches style. Using configuration files is more effective and less error-prone. If you are about to create a new design, Xilinx recommends that you start migrating to the configuration files because the old style will be deprecated in future releases.
About Joyce Li
Joyce Li is a Technical Marketing Engineer working in AMD AI and Software team and has more than 15 years of experience in ACAP/FPGA design and applications. Since joining AMD in 2004, she has held different roles in technical sales, application engineering and technical marketing. During these years, she has worked extensively on Vivado, SDx and Vitis areas. She holds an doctor degree on E.E. from Beijing Institute of Technology.