Project Commands

Project commands are Vitis HLS commands that let you create and manage projects and solutions. The commands must be run in the interactive mode, vitis_hls -i, or can be run as a script using the -f option as described in vitis_hls Command.

The features of these commands are also available through the Vitis HLS GUI when performing specific functions as described in sections like Creating a New Vitis HLS Project and C/RTL Co-Simulation in Vitis HLS.

TIP: When running the commands through the GUI, the Tcl commands are added to a script of your project written to solution/constraints/script.tcl.

add_files

Description

Adds design source files to the current project.

The tool searches the current directory for any header files included in the design source. To use header files stored in other directories, use the -cflags option to include those directories to the search path.

Syntax

add_files [OPTIONS] <src_files>
  • <src_files> lists one or more supported source files.

Options

-blackbox <file_name.json>
Specify the JSON file to be used for RTL blackbox. The information in this file is used by the HLS compiler during synthesizing and running C/C++ and co-simulation. See Adding RTL Blackbox Functions for more information.
-cflags <string>
A string with any GCC compilation options.
-csimflags <string>
A string with any desired simulation compilation options. Flags specified with this option are only applied to simulation compilation, which includes C/C++ simulation and RTL co-simulation, not synthesis compilation. This option does not impact the -cflags option.
-tb
Specifies any files used as part of the design test bench. These files are not synthesized. They are used when simulation is run by the csim_design or cosim_design commands.

Do not use the -tb option when adding source files for the design. Use separate add_files commands to add design files and simulation files.

Examples

Add three design files to the project.

add_files a.cpp
add_files b.cpp
add_files c.cpp

Add multiple files with a single command line.

add_files "a.cpp b.cpp c.cpp"

Use the-tb option to add test bench files to the project. This example adds multiple files with a single command, including:

  • The test bench a_test.cpp
  • All data files read by the test bench:
    • input_stimuli.dat
    • out.gold.dat
      add_files -tb "a_test.cpp input_stimuli.dat out.gold.dat"

    If the test bench data files in the previous example are stored in a separate directory (for example test_data), the directory can be added to the project in place of the individual data files.

    add_files -tb a_test.cpp
add_files -tb test_data

close_project

Description

Closes the current project. The project is no longer active in the Vitis HLS session.

The close_project command:

  • Prevents you from entering any project-specific or solution-specific commands.
  • Is not required. Opening or creating a new project closes the current project.

Syntax

close_project

Options

This command has no options.

Examples

close_project
  • Closes the current project.
  • Saves all results.

close_solution

Description

Closes the current solution. The current solution is no longer active in the Vitis HLS session.

The close_solution command does the following:

  • Prevents you from entering any solution-specific commands.
  • Is not required. Opening or creating a new solution closes the current solution.

Syntax

close_solution

Options

This command has no options.

Examples

close_solution
  • Closes the current solution.
  • Saves all results.

cosim_design

Description

Executes post-synthesis co-simulation of the synthesized RTL with the original C/C++-based test bench.

TIP: To specify the files for the test bench run the following command:
add_files -tb

The simulation results are written to the sim/Verilog or sim/VHDL folder of the active solution, depending on the setting of the -rtl option.

Syntax

cosim_design [OPTIONS]

Options

-O
Enables optimized compilation of the C/C++ test bench and RTL wrapper. This increases compilation time, but results in better runtime performance.
-argv <string>
The <string> is passed onto the main C/C++ function.

Specifies an argument list for the behavioral test bench.

-compiled_library_dir <string>
Specifies the compiled library directory during simulation with third-party simulators. The <string> is the path name to the compiled library directory. The library must be compiled ahead of time using the compile_simlib command as explained in the Vivado Design Suite Tcl Command Reference Guide (UG835).
-coverage
Enables the coverage feature during simulation with the VCS simulator.
-disable_deadlock_detection
Disables the deadlock detection feature in co-simulation.
-disable_dependency_check
Disables dependency checks when running co-simulation.
-enable_dataflow_profiling
This option turns on the dataflow channel profiling to track channel sizes during co-simulation.
-enable_fifo_sizing
This option turns on automatic FIFO channel size tuning for dataflow profiling during co-simulation.
-ldflags <string>
Specifies the options passed to the linker for co-simulation.

This option is typically used to pass include path information or library information for the C/C++ test bench.

-mflags <string>
Specifies options required for simulation.
-random_stall
Enable random stalling of top-level interfaces during co-simulation.
-rtl [verilog | vhdl]
Specifies which RTL language to use for C/RTL co-simulation. The default is Verilog.
-setup
Creates all simulation files created in the sim/<HDL> directory of the active solution. The simulation is not executed, but can be run later from a command shell.
-stable_axilite_update
Enable s_axilite to configure registers which are stable compared with the prior transaction.
-tool [auto | vcs | modelsim | riviera | isim | xsim | ncsim | xceilum]
Specifies the simulator to use to co-simulate the RTL with the C/C++ test bench. The Vivado simulator (xsim) is the default, unless otherwise specified.
-trace_level [*none* | all | port | port_hier]
Determines the level of waveform trace data to save during C/RTL co-simulation.
  • none does not save trace data. This is the default.
  • all results in all port and signal waveforms being saved to the trace file.
  • port only saves waveform traces for the top-level ports.
  • port_hier save the trace information for all ports in the design hierarchy.

The trace file is saved in the sim/Verilog or sim/VHDL folder of the current solution when the simulation executes, depending on the selection used with the -rtl option.

-user_stall <string>
Specifies the JSON stall file to be used during co-simulation. The stall file can be generated using the cosim_stall command.
-wave_debug
Opens the Vivado simulator GUI to view waveforms and simulation results. Enables waveform viewing of all processes in the generated RTL, as in the dataflow and sequential processes. This option is only supported when using Vivado simulator for co-simulation by setting -tool xsim. See Viewing Simulation Waveforms for more information.

Examples

Performs verification using the Vivado simulator:

cosim_design

Uses the VCS simulator to verify the Verilog RTL and enable saving of the waveform trace file:

cosim_design -tool VCS -rtl verilog -coverage -trace_level all

Verifies the VHDL RTL using ModelSim. Values 5 and 1 are passed to the test bench function and used in the RTL verification:

cosim_design -tool modelsim -rtl vhdl -argv "5 1"

cosim_stall

Description

Command for development of the co-simulation stall file in JSON format.

Syntax

cosim_stall [OPTIONS]

Options

-check <string>
Specify the JSON format stall file to use when running co-simulation.
-generate <string>
Generate a JSON stall file to be used during co-simulation.
-list
List all ports which can apply stall during co-simulation. This option returns a list of ports based on the current design.

Examples

The following example generates the specified stall file, and then specifies the file for use during co-simulation:

cosim_stall -generate my_cosim_stall.json
cosim_stall -check my_cosim_stall.json

create_clock

Description

Creates a virtual clock for the current solution.

The command can be executed only in the context of an active solution. The clock period is a constraint that drives optimization (chaining as many operations as feasible in the given clock period).

C and C++ designs support only a single clock.

Syntax

create_clock -period <number> [OPTIONS]

Options

-name <string>
Specifies the clock name. If no name is given, a default name is used.
-period <number>
Specifies the clock period in ns or MHz.
  • If no units are specified, ns is assumed.
  • If no period is specified, a default period of 10 ns is used.

Examples

Species a clock period of 50 ns:
create_clock -period 50
Uses the default name and period of 10 ns to specify the clock:
create_clock
Specifies clock frequency in MHz:
create_clock -period 100MHz

csim_design

Description

Compiles and runs pre-synthesis C/C++ simulation using the provided C/C++ test bench.

TIP: To specify the files for the test bench run the following command:
add_files -tb

The simulation results are written to the csim folder inside the active solution.

Syntax

csim_design [OPTIONS]

Options

-O
Enables optimized compilation of the C/C++ test bench. This increases compilation time, but results in better runtime performance.
-argv <string>
Specifies the argument list for the behavioral test bench. The <string> is passed onto the main() C/C++ function of the test bench.
-clean
Enables a clean build. Without this option, csim_design compiles incrementally.
-ldflags <string>
Specifies the options passed to the linker for simulation. This option is typically used to pass include path information or library information for the C/C++ test bench.
-mflags <string>
Specifies options required for simulation.
-profile
Enable the creation of the Pre-Synthesis Control Flow.
-setup
When this option is specified, the simulation binary will be created in the csim directory of the active solution, but simulation will not be executed. Simulation can be launched later from the compiled executable.

Examples

Compiles and runs C/C++ simulation:

csim_design

Compiles source design and test bench to generate the simulation binary. Does not execute the simulation binary:

csim_design -O -setup
TIP: To run the simulation, execute run.sh in a command terminal, from the csim/build directory of the active solution.

csynth_design

Description

Synthesizes the Vitis HLS project for the active solution.

The command can be executed only in the context of an active solution. The elaborated design in the database is scheduled and mapped onto RTL, based on any constraints that are set.

Syntax

csynth_design [OPTIONS]

Options

-dump_cfg
Write a pre-synthesis control flow graph (CFG).
-dump_post_cfg
Write a post-synthesis control flow graph (CFG).
-synthesis_check
Runs a pre-synthesis design rule check, but does not generate RTL.

Examples

Runs Vitis HLS synthesis on the top-level design.

csynth_design

delete_project

Description

Deletes the directory associated with the project.

The delete_project command checks the corresponding project directory <project> to ensure that it is a valid Vitis HLS project before deleting it. If the specified project directory does not exist in the current work directory, the command has no effect.

Syntax

delete_project <project>
  • <project> is the project name.

Options

This command has no options.

Examples

Deletes the Project_1 by removing the directory and all its contents.

delete_project Project_1

delete_solution

Description

Removes a solution from an active project, and deletes the <solution> sub-directory from the project directory.

If the solution does not exist in the project directory, the command has no effect.

Syntax

delete_solution <solution>
  • <solution> is the solution to be deleted.

Options

This command has no options.

Examples

Deletes solution solution1 from the active project by deleting the sub-directory.

delete_solution solution1

enable_beta_device

Description

Enables specified beta access devices in the Vitis HLS tool set.

Syntax 

enable_beta_device <pattern>
  • <pattern> Specifies a pattern matching the beta devices to enable.

Options

This command has no options.

Examples

The following example enables all beta devices in the release: 

 enable_beta_device *

export_design

Description

Exports and packages the generated RTL code as a packaged IP for use in the Vivado Design Suite, or as a compiled Vitis kernel object (.xo) for the Vitis application acceleration development flow.

Supported formats include:

  • Vivado IP for inclusion in the IP catalog.
  • Vitis application acceleration kernel (.xo).
  • Synthesized or implemented design checkpoint (DCP) format.
  • Vivado IP and ZIP archive for use in the System Generator for DSP tool.

The packaged project is written to the solution/impl folder of the active solution.

Syntax

export_design [OPTIONS]

Options

-description <string>
Provides a description for the catalog entry for the generated IP, used when packaging the IP.
-display_name <string>
Provides a display name for the catalog entry for the generated IP, used when packaging the IP.
-flow (syn | impl)
Obtains more accurate timing and resource usage data for the generated RTL using Vivado synthesis and implementation. The option syn performs RTL synthesis. The option impl performs both RTL synthesis and implementation, including a detailed place and route of the RTL netlist. In the Vitis HLS IDE, these options appear as check boxes labeled Vivado Synthesis and Vivado Synthesis, place and route stage.
-format (ip_catalog | xo | syn_dcp | sysgen)
Specifies the format to package the IP. The supported formats are:
ip_catalog
A format suitable for adding to the Xilinx IP catalog.
ip_catalog
A format suitable for adding to the Xilinx IP catalog.
xo
A format accepted by the v++ compiler for linking in the Vitis application acceleration flow.
syn_dcp
Synthesized checkpoint file for Vivado Design Suite. If this option is used, RTL synthesis is automatically executed. Vivado implementation can be optionally added.
sysgen
Generate a Vivado IP and .zip archive for use in System Generator.
-ipname <string>
Provides the name component of the Vendor:Library:Name:Version (VLNV) identifier for generated IP.
-library <string>
Provides the library component of the Vendor:Library:Name:Version (VLNV) identifier for generated IP.
-output <string>
Specifies the output location of the generated IP, XO, or DCP files. The file is written to the solution/impl folder of the current project if no output path is specified.
-rtl (verilog | VHDL)
Specifies which HDL is used when the -flow option is executed. If not specified, Verilog is the default language for the Vivado synthesized netlist.
-taxonomy <string>
Specifies the taxonomy for the catalog entry for the generated IP, used when packaging the IP.
-vendor <string>
Provides the vendor component of the Vendor:Library:Name:Version (VLNV) identifier for generated IP.
-version <string>
Provides the version component of the Vendor:Library:Name:Version (VLNV) identifier for generated IP.

Examples

Exports RTL for the Vitis application acceleration flow:

export_design -format xo

Exports the RTL as VHDL code in the Vivado IP catalog format. The VHDL is synthesized in Vivado synthesis tool to obtain better timing and usage data:

export_design -rtl vhdl -format ip_catalog -flow syn

get_clock_period

Description

This command returns the clock period for specified clock objects, or returns the default clock period for the active solution.

Syntax

get_clock_period [OPTIONS]

Options

-default
Return the default period if the clock period is not specified.
-name <string>
Get the clock period for the specified clock.
-ns
Return the clock period in nanoseconds (ns). By default Vitis HLS returns the clock period in the same units as it was specified.

Examples

The following example creates a clock, ap_clk, and specifies the clock period in MHz. Then it gets the clock period for the clock as ns:

create_clock -name ap_clk -period 200MHz
get_clock_period -name ap_clk -ns

get_clock_uncertainty

Description

This command returns the clock uncertainty for specified clock, or returns the default clock uncertainty for the active solution.

Syntax

get_clock_uncertainty [clock_name]
  • <clock_name> indicates the clock to get the uncertainty for.

Options

This command has no options.

Examples

The following example gets the clock uncertainty for the specified clock:

get_clock_uncertainty clk1

get_files

Description

This command gets the files that have been added to the active solution.

Syntax 

get_files [OPTIONS]

Options

-cflags
Return any compiler flags specified with the files.
-fullpath
Return the full path of the files.
-tb
Return only the files that were added as part of the test bench (added with the -tb option).

Examples

The following example gets the added test bench files from the current solution, and returns the full path for the files:

get_files -tb -fullpath

get_part

Description

This command returns the Xilinx device used in the active solution.

Syntax 

get_part

Options

There are no options for this command.

Examples

The following example returns the part used in the active solution: 

get_part

get_project

Description

This command gets information for the currently opened project.

Syntax 

get_project [OPTIONS]

Options

-directory
Return the full path to the project directory.
-name
Return the project name.
-solutions
Return a list of all the solution names in the project.

Examples

The following example gets the full path for the current project:

get_project -directory

get_solution

Description

This command returns information related to the active solution.

Syntax 

get_solution [OPTIONS]

Options

-directory
Returns the full path to the active solution.
-flow_target
Returns the flow target for the active solution.
-json
Return the absolute path to the solution meta-data JSON file
-name
Returns the solution name.

Examples

The following example returns the flow target for the active solution: 

get_solution -flow_target

get_top

Description

This command returns the name of the top-level function for the open Vitis HLS project.

Syntax 

get_top

Options

There are no options for this command.

Examples

The following example returns the top-level function for the open project:

get_top

help

Description

  • When specified without a command name, the help command lists all Vitis HLS Tcl commands.
  • When used with a Vitis HLS Tcl command as an argument, the help command returns details of the specified command.
TIP: For recognized Vitis HLS commands, auto-completion using the tab key is available when entering the command name.

Syntax

help <cmd>
  • <cmd> specifies a command name to return the help for. If no command is specified, a list of all Vitis HLS commands will be returned.

Options

This command has no options.

Examples

Displays help for all commands and directives:
help
Displays help for the add_files command:
help add_files

list_part

Description

This command returns names of supported device families, parts, or boards.

If no argument is provided, the command will return all supported part families. To return specific parts of a family, provide the family name as an argument.

Syntax

list_part [name] [OPTIONS]
  • <family> specifies a device family to return the specific devices of. If no <family> is specified, the list_part command returns a list of available device families.

Options

-name <string>
Family, part, board name, or glob pattern.
-board[=false|true]
Returns list of board names instead of part names.
-clock_regions
Return a list of clock regions for the specified part. Must be specified with the -name command.
-slr_pblocks
Return the SLR pblock dictionary for the specified part. Must be specified with the -name command.

Examples

Returns all supported device families.

list_part

Returns the clock regions of the current part in the active solution.

list_part -name [get_part] -clock_regions

open_project

Description

Opens an existing project, or creates a new one if the specified project does not exist.

IMPORTANT: In Vitis HLS, the open_project command returns an error when opening a Vivado HLS project, unless the -upgrade or -reset option is used.

There can only be one active project in a Vitis HLS session. To close a project:

  • Use the close_project command, or
  • Open or create another project with the open_project or open_tcl_project commands.

Use the delete_project command to completely delete the project directory (removing it from the disk) and any solutions associated it.

Syntax

open_project [OPTIONS] <name>
  • <name> specifies the project name.

Options

-reset
  • Resets the project by removing any data that already exists in the project.
  • Removes any previous project information on design source files, header file search paths, and the top-level function. The associated solution directories and files are kept, but might now have invalid results.
Note: Use the -reset option when executing Vitis HLS with Tcl scripts. Otherwise, each new add_files command adds additional files to the existing data.
-upgrade
Upgrade a Vivado HLS project to Vitis HLS.

Examples

Opens an existing project named Project_1, or creates a new one if it does not exist:

open_project Project_1

Opens a project and removes any existing data:

open_project -reset Project_2

open_solution

Description

Opens an existing solution or creates a new one in the currently active project. There can only be one active solution at any given time in a Vitis HLS session. As described in Vitis HLS Process Overview, the solution targets either the Vivado IP flow, or the Vitis Kernel flow. The default flow is the Vivado IP flow if no flow target is specified.

IMPORTANT: Attempting to open or create a solution when there is no open project results in an error.

Each solution is managed in a sub-directory of the current project. A new solution is created if the specified solution does not exist in the open project. To close a solution:

  • Run the close_solution command, or
  • Open another solution with the open_solution command.

Use the delete_solution command to remove a solution from the project and delete the corresponding sub-directory.

Syntax

open_solution [OPTIONS] <name>
  • <name> specifies the solution name.

Options

-flow_target [vitis | vivado]
vivado
Configures the solution to run in support of the Vivado IP generation flow, requiring strict use of pragmas and directives, and exporting the results as Vivado IP. This is the default flow when -flow_target is not specified.
vitis
Configures the solution for use in the Vitis application acceleration development flow. This configures the Vitis HLS tool to properly infer interfaces for the function arguments without the need to specify the INTERFACE pragma or directive, and to output the synthesized RTL code as a Vitis kernel object file (.xo).
-reset
  • Resets the solution data if the solution already exists. Any previous solution information on libraries, constraints, and directives is removed.
  • Also removes synthesis, verification, and implementation results.

Examples

Opens an existing solution named Solution_1 in the open project, or creates a new solution if one with the specified name does not exist. The solution is configured for creating kernel objects (.xo) for use in the Vitis tool flow.

open_solution -flow_target vitis Solution_1

Opens and resets the specified solution in the open project. Removes any existing data from the solution.

open_solution -reset Solution_2

open_tcl_project

Description

Create a project by sourcing a Tcl file, but skipping all design commands in the Tcl script: cosim_design, csynth_design, and csim_design. This command only creates and configures the project from a Tcl script. This lets you create a project using Tcl scripts from existing projects without running simulation or synthesis.

There can only be one active project in a Vitis HLS session. To close a project:

  • Use the close_project command, or
  • Open or create another project with the open_tcl_project or open_project commands.

Use the delete_project command to completely delete the project directory (removing it from the disk) and any solutions associated it.

Syntax

open_tcl_project <tclfile>
  • <tclfile> specifies the path and name of a Tcl script to use when creating a project.

Options

This command has no options.

Examples

Creates and opens a project from the specified Tcl script:

open_tcl_project run_hls.tcl

set_clock_uncertainty

Description

Sets a margin on the clock period defined by create_clock.

The margin of uncertainty is subtracted from the clock period to create an effective clock period. The clock uncertainty is defined in ns, or as a percentage of the clock period. The clock uncertainty defaults to 27% of the clock period.

Vitis HLS optimizes the design based on the effective clock period, providing a margin for downstream tools to account for logic synthesis and routing. The command can be executed only in the context of an active solution. Vitis HLS still uses the specified clock period in all output files for verification and implementation.

Syntax

set_clock_uncertainty <uncertainty> <clock_list>
  • <uncertainty>: A value, specified in ns, representing how much of the clock period is used as a margin. The uncertainty can also be specified as a percentage of the clock period. The default uncertainty is 27% of the clock period.
  • <clock_list>: A list of clocks to which the uncertainty is applied. If none is provided, it is applied to all clocks.

Options

This command has no options.

Examples

Specifies an uncertainty or margin of 0.5 ns on the clock. This effectively reduces the clock period that Vitis HLS can use by 0.5 ns.

set_clock_uncertainty 0.5

set_part

Description

Sets a target device, device family, or board for the current solution. The command can be executed only in the context of an active solution.

TIP: Each solution in a project can target a separate device or device family.

Syntax

set_part <device_specification>
  • <device_specification> is a device specification that sets the target device for Vitis HLS synthesis and implementation.
  • The device specification includes <device>, <package>, and <speed_grade> information.
  • Specifying the <device_family> uses the default device for the device family.

Options

-board
Specify the part as defined on a board.

Examples

The FPGA libraries provided with Vitis HLS can be added to the current solution by providing the device family name as shown below. In this case, the default device, package, and speed grade specified in the Vitis HLS FPGA library for the Virtex-7 device family are used.
set_part virtex7

The FPGA libraries provided with Vitis HLS can optionally specify the specific device with package and speed grade information.

set_part xc6vlx240tff1156-1

Specifies the part through the definition of a board.

set_part -board u200

set_top

Description

Defines the top-level function to be synthesized.

IMPORTANT: Any functions called from the top-level function will also become part of the HLS design.

Syntax

set_top <name>
  • <name> is the function to be synthesized by HLS.

Options

This command has no options.

Examples

Sets the top-level function as foo.

set_top foo