vitis-run Command - 2024.1 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)

Document ID

UG1393

Release Date

2024-07-03

Version

2024.1 English

The vitis-run command is provided to enable C-simulation, C/RTL Co-simulation, and Vivado implementation of an HLS component created with the v++ -c --mode hls command.

The options of the vitis-run command include:

--mode hls: Specifies the use of vitis-run for HLS components. This is the only mode currently supported.
--csim: Run C-simulation on an HLS component.
--cosim: Run C/RTL Co-simulation on an HLS component.
--package: Run the package process to generate the IP or XO files from the RTL design of the HLS component. This generates the required export files to use the RTL design in the Vivado Design Suite, or Vitis development flow.
--impl: Run Vivado implementation out-of-context (OOC) run on the HLS component. This is used to provide resource usage and timing estimates from the synthesized or implemented design.
--tcl: Run Vitis HLS using the Tcl scripting language. Tcl commands are described in the Vitis High-Level Synthesis User Guide (UG1399) under the heading of Vitis HLS Command Reference.
--work_dir: Specify the working directory. For -cosim and -impl, the specified working directory must contain a previously compiled HLS component.
--config arg: Specify a config file for use with the tool. Refer to v++ Mode HLS for specific commands to use in the config file.
-h [ --help ]: Display command help for the tool.

Tip: The list of options above is not complete list. You can use the --help command to display the complete list of vitis-run commands.

You can use the vitis-run command to run C-simulation without an existing design, or run C/RTL Co-simulation or Vivado implementation on an existing HLS component. Some examples follow.

Run C-Simulation

You can run C-simulation on an existing work directory containing a previously compiled HLS component, or specify a new work directory to run C-simulation on the source files directly. The config file for an existing HLS component only needs to specify commands for C-Simulation as described in C-Simulation Configuration. The previously built HLS component provides the foundation for simulation, defining the source files, test bench files, and part or platform for the design. Running C-simulation on a new work directory requires a complete config file, specifying the required source files and part, in addition to any C-simulation options.

An example command line:

vitis-run --mode hls --csim --config ./hls_csim.cfg --work_dir newTest

The example config file:

part=xcvu11p-flga2577-1-e

[hls]
clock=8
flow_target=vitis
syn.file=../../src/dct.cpp
syn.top=dct
tb.file=../../src/out.golden.dat
tb.file=../../src/in.dat
tb.file=../../src/dct_test.cpp
tb.file=../../src/dct_coeff_table.txt
syn.output.format=xo
clock_uncertainty=15%
csim.O=true
csim.code_analyzer=0
csim.clean=true
csim.profile=true

Run C/RTL Co-Simulation

You can run Co-simulation on an existing work directory containing a previously compiled HLS component, or specify a new work directory to run C-simulation on the source files directly. The config file for an existing HLS component only needs to specify commands for C-Simulation as described in Co-Simulation Configuration. The previously built HLS component provides the foundation for simulation, defining the source files, test bench files, and part or platform for the design. Running C-simulation on a new work directory requires a complete config file, specifying the required source files and part, in addition to any C-simulation options.

An example command line:

vitis-run --mode hls --cosim --config ./cosim.cfg --work_dir myHLS

The example config file:

part=xcvu11p-flga2577-1-e

[HLS]
clock=8
flow_target=vitis
syn.file=/group/xcoswmktg/randyh/rigel-tests/03-Vitis_HLS/reference-files/src/dct.cpp
syn.top=dct
tb.file=/group/xcoswmktg/randyh/rigel-tests/03-Vitis_HLS/reference-files/src/out.golden.dat
tb.file=/group/xcoswmktg/randyh/rigel-tests/03-Vitis_HLS/reference-files/src/in.dat
tb.file=/group/xcoswmktg/randyh/rigel-tests/03-Vitis_HLS/reference-files/src/dct_test.cpp
tb.file=/group/xcoswmktg/randyh/rigel-tests/03-Vitis_HLS/reference-files/src/dct_coeff_table.txt
syn.output.format=xo
clock_uncertainty=15%
cosim.trace_level=port
#cosim.wave_debug=true
cosim.random_stall=true
cosim.enable_dataflow_profiling=true

Run Vivado Implementation

You can run the Vivado Design Suite to synthesize and run place and route on the RTL generated by the HLS synthesis process. The synthesis and implementation processes are managed by commands specified in the configuration file as described in Implementation Configuration.

An example command line:

vitis-run --mode hls --impl --config ./impl.cfg --work_dir myHLS

The example config file:

part=xcvu11p-flga2577-1-e

[HLS]
clock=8
flow_target=vitis
syn.file=/group/xcoswmktg/randyh/rigel-tests/03-Vitis_HLS/reference-files/src/dct.cpp
syn.top=dct
tb.file=/group/xcoswmktg/randyh/rigel-tests/03-Vitis_HLS/reference-files/src/out.golden.dat
tb.file=/group/xcoswmktg/randyh/rigel-tests/03-Vitis_HLS/reference-files/src/in.dat
tb.file=/group/xcoswmktg/randyh/rigel-tests/03-Vitis_HLS/reference-files/src/dct_test.cpp
tb.file=/group/xcoswmktg/randyh/rigel-tests/03-Vitis_HLS/reference-files/src/dct_coeff_table.txt
syn.output.format=xo
clock_uncertainty=15%
cosim.trace_level=port
#cosim.wave_debug=true
cosim.random_stall=true
cosim.enable_dataflow_profiling=true

Run Tcl Script

You can also use vitis-run to run an existing Tcl script, such as the script.tcl from an existing project, to build the project and then write a config file from the Tcl script. The example below shows the vitis-run command to perform these actions.

An example command line:

vitis-run --mode hls --tcl dct-build.tcl

An example Tcl script:

open_project dctProj
set_top dct
add_files ../03-Vitis_HLS/reference-files/src/dct.cpp
add_files -tb ../03-Vitis_HLS/reference-files/src/dct_coeff_table.txt
add_files -tb ../03-Vitis_HLS/reference-files/src/dct_test.cpp
add_files -tb ../03-Vitis_HLS/reference-files/src/in.dat
add_files -tb ../03-Vitis_HLS/reference-files/src/out.golden.dat
open_solution "solution1" -flow_target vivado
set_part {xcvu11p-flga2577-1-e}
create_clock -period 10 -name default
csynth_design
write_ini ./dct-build.cfg
exit

Tip: The addition of the write_ini command at the end of the script creates a config file from the Tcl script, thus providing you with a config file to use with v++ -c --mode hls.