vitis-run Command - vitis-run Command - 2026.1 English - UG1702

Vitis Reference Guide (UG1702)
Document ID
UG1702
Release Date
2026-06-23
Version
2026.1 English

The vitis-run command is enables C-simulation, C/RTL Co-simulation, and Vivado implementation of an HLS component that v++ -c --mode hls creates.

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) on the HLS component. Provides resource usage and timing estimates from the synthesized or implemented design.
--tcl
Run Vitis HLS using the Tcl scripting language. See Tcl commands in 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

Run C‑simulation on an existing work directory that contains a previously compiled HLS component. Specify a new work directory to run C‑simulation directly on source files. For existing components, the config file needs only C‑simulation commands, as described in C-Simulation Configuration. The existing HLS component defines source files, test benches, and the target part or platform. For new work directories, provide a complete config file that specifies source files, the part, and 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
syn.interface.default_axi=1
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.clean=true
csim.profile=true

Run C/RTL Co-Simulation

You can run Co-simulation on an existing work directory that contains a previously compiled HLS component. You can also 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. You need to specify the 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
syn.interface.default_axi=1
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. Commands in the configuration file as described in Implementation Configuration manage the synthesis and implementation processes.

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
syn.interface.default_axi=1
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 to build the project and then write a config file from the Tcl script. An example of such a script is the script.tcl from an existing project. 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: 
# Create a project
open_component -reset component_array_partition_complete

# Add design files
add_files matmul_partition.cpp
# Add test bench & files
add_files -tb matmul_partition_test.cpp 

# Set the top-level function
set_top matmul_partition

# ########################################################
# Define technology and clock rate
set_part  {xcvu9p-flga2104-2-i}
create_clock -period 10
csynth_design
write_ini ./hls_config 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.