Creating HLS Components from the Command Line - Creating HLS Components from the Command Line - 2026.1 English - UG1399

Vitis High-Level Synthesis User Guide (UG1399)
Document ID
UG1399
Release Date
2026-06-23
Version
2026.1 English

This section focuses on building and running an HLS component using command line tools.

You can use the v++ -c --mode hls compiler command to build an HLS component. The command uses a configuration file command language. Running C simulation, C/RTL Co-simulation, implementation, and export all rely on the vitis-run command. See details for the different steps for the command-line flows below.

Tip: The following examples are based on the DCT design in the Getting Started With Vitis HLS . The example includes the HLS component, with source files and test bench.

Running C-Synthesis

To build the dct HLS component the v++ command-line is as follows: 

v++ -c --mode hls --config ./dct/hls_config.cfg --work_dir dct

Where:

  • --config specifies a config file with the compiler directives for the build, and to configure the simulator for the run
  • --work_dir provides a work directory to build the component
    Tip: When creating an HLS component from the command line, the --work_dir specifies the HLS component folder, and the parent folder of the --work_dir becomes the workspace for launching the Vitis IDE.

The contents of a configuration file can vary. For synthesis, the dct HLS component requires the following commands in the hls_config.cfg file. 

part=xczu9eg-ffvb1156-2-e

[hls]
syn.file=./src/dct.cpp
syn.top=dct
syn.interface.default.axi=1
clock=8ns
clock_uncertainty=12%
syn.output.format=rtl
syn.directive.pipeline=dct_2d II=4
Important: If your HLS configuration file uses platform= instead of part=, you must also specify freqhz= instead of clock=. Doing so changes the default clock frequency of the platform.

The success of the synthesis command largely depends on the contents of the configuration file. The required elements for synthesis are the part, syn.file, and syn.top. You only need the default_axi, clock, and clock_uncertainty to override the default values. Use the syn.directive.xxx commands to provide optimizations to function synthesis.

Running C Simulation

To run the HLS component in C simulation, use the vitis-run command. C simulation does not require C Synthesis to run as it does not require the code that RTL code synthesis generates. 

vitis-run --mode hls --csim --config ./dct/hls_config.cfg --work_dir dct

Where:

  • --csim specifies the target for the run.
  • --config specifies a config file for synthesis, but includes C simulation specific requirements as shown below.
  • --work_dir provides a work directory to build the component as indicated for synthesis.

The contents of a configuration file can vary. For C simulation, the config file requires the source files and top specified for synthesis. C simulation also require test bench and input files and csim configuration settings. See C-Simulation Configuration.

part=xczu9eg-ffvb1156-2-e

[hls]
clock=8ns
clock_uncertainty=12%
syn.interface.default.axi=1
syn.output.format=rtl
syn.file=./src/dct.cpp
syn.file=./src/dct.h
syn.top=dct
tb.file=./src/dct_coeff_table.txt
tb.file=./src/dct_test.cpp
tb.file=./src/in.dat
tb.file=./src/out.golden.dat
csim.clean=true
syn.directive.pipeline=dct_2d II=4

Running C/RTL Co-Simulation

To run C/RTL Co-simulation on the HLS component, use the vitis-run command as shown below: 

vitis-run --mode hls --cosim --config ./dct/hls_config.cfg --work_dir dct

The contents of the configuration file for C/RTL Co-Simulation include the following:

part=xczu9eg-ffvb1156-2-e

[hls]
clock=8ns
clock_uncertainty=12%
syn.interface.default_axi=1
syn.output.format=rtl
syn.file=./src/dct.cpp
syn.file=./src/dct.h
syn.top=dct
tb.file=./src/dct_coeff_table.txt
tb.file=./src/dct_test.cpp
tb.file=./src/in.dat
tb.file=./src/out.golden.dat
syn.directive.pipeline=dct_2d II=4
cosim.enable_dataflow_profiling=true
cosim.enable_fifo_sizing=true
cosim.trace_level=port
cosim.wave_debug=true
Note: The hls_config.cfg file above shows some of the settings for the C/RTL co-simulation tool. Refer to Co-Simulation Configuration for more information.

Running Implementation

To run Vivado synthesis or implementation on the HLS component, use the vitis-run command.

vitis-run --mode hls --impl --config ./dct/hls_config.cfg --work_dir dct

Exporting the IP/XO

To export a Vivado IP or Vitis kernel from the synthesized HLS component, use the vitis-run --package command.

vitis-run --mode hls --package --config ./dct/hls_config.cfg --work_dir dct

The contents of the configuration file required to export the package IP or XO include the following: 

part=xcvu9p-flga2104-2-i

[hls]
syn.file=/group/xcoswmktg/randyh/rigel-tests/03-Vitis_HLS/reference-files/src/dct.cpp
syn.top=dct
syn.output.format=xo
Note: The --package command exports an IP or an XO from the previously synthesized HLS component. You can export a Vitis kernel as an IP. However, you cannot export a Vivado flow IP as an XO unless it meets the specific requirements of the Vitis kernel.