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

Vitis High-Level Synthesis User Guide (UG1399)
Document ID
UG1399
Release Date
2023-12-18
Version
2023.2 English

While the prior content described building and running an HLS component using the Vitis unified IDE, this section focues on doing that using the command line tools that are available.

The v++ -c --mode hls compiler command is used to build an HLS component. The command uses a configuration file command language as described in HLS Config File Commands. Running C simulation, Code Analyzer, C/RTL Co-simulation, implementation, and export all rely on the vitis-run command. The different steps for the command-line flows are described 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 will look 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, but 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
flow_target=vitis
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= then you must also specify freqhz= instead of clock= as shown here to change the default clock frequency of the platform.

The success of the synthesis command largely depends on the contents of the configuration file. There are a few key required elements, and then there are a number of options that you can specify. From the config file provided above, the required elements for synthesis are the part, syn.file, and syn.top. The flow_target, clock, and clock_uncertainty are not required except to override the default values. The syn.directive.xxx commands are used to provide specific optimization to the synthesis of the function.

Running C Simulation or Code Analyzer

To run the HLS component in C simulation or in Code Analyzer, use the vitis-run command as described in vitis, v++, and vitis-run Commands. C simulation does not require C Synthesis to have been run as it does not require the RTL code generated by synthesis. 

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 as indicated 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, but for C simulation the config file requires the source files and top specified for synthesis, but also require test bench and input files, as well as csim configuration settings as explained in C-Simulation Configuration: 

part=xczu9eg-ffvb1156-2-e

[hls]
clock=8ns
clock_uncertainty=12%
flow_target=vitis
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
csim.code_analyzer=false
syn.directive.pipeline=dct_2d II=4
Tip: Change csim.code_analyzer to true to enable the Code Analyzer as well as simulation.

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 required for C/RTL Co-Simulation include the following:

part=xczu9eg-ffvb1156-2-e

[hls]
clock=8ns
clock_uncertainty=12%
flow_target=vitis
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 as shown below: 

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

The contents of the configuration file required for implementation include the following:

Exporting the IP/XO

To export a Vivado IP or Vitis kernel from the synthesized HLS component, you can use the Vitis-run --package command as shown below: 

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.