Creating a New Vitis HLS Project

To create a new project, click the Create New Project link on the Welcome page, or select the File > New Project menu command. This opens the New Vitis HLS Project wizard, as shown in the following figure.

Figure 1: New Vitis HLS Project Wizard

Create a new Vitis HLS project using the following steps:

  1. Specify the project name, which is also the name of the directory in which the project files and folders are written.
  2. Specify the location where the project is written.
    IMPORTANT: The Windows operating system has a 255-character limit for path lengths, which can affect the Vitis tools. To avoid this issue, use the shortest possible names and directory locations when creating projects, or adding new files.
  3. Click Next to proceed to the Add/Remove Design Files page.
    The Add/Remove Design Files page lets you add C/C++ source files to your project, as shown in the following figure:

  4. Click Add Files, and navigate to the location of the source code files to add to your project.

    Do not add header files (with the .h suffix) to the project using the Add Files button, or the add_files Tcl command. Vitis HLS automatically adds the following directories to the compilation search path:

    • Working directory, which contains the Vitis HLS project directory.
    • Any directory that contains C/C++ files that have been added to the project.

    Header files that reside in these directories are automatically included in the project during compilation. However, you can specify other include paths using the Edit CFLAGS function.

  5. Optionally, click New File to create a new source file to add to your project. The File Browser dialog box opens to let you specify the file name and location to store the new file.
    TIP: If you want to write the new file to the directory that will be created for your new project, you must wait to create the new file until after the project has been created.
  6. You can select a file, and click Edit CFLAGS or Edit CSIMFLAGS to open a dialog box letting you add one or more compiler or simulation flags for the selected file.
    The following figure shows example CFLAGS:

    Compiler flags are standard compiler options for gcc or g++. For a complete list of options, refer to http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html on the GNU Compiler Collection (GCC) website. The following are some example CFLAGS:

    -I/source/header_files
    Provides the search path to associated header files. You can specify absolute or relative paths to files.
    IMPORTANT: You must specify relative paths in relation to the working directory, not the project directory.
    -DMACRO_1
    Defines macro MACRO_1 during compilation.
    -fnested-functions
    Defines directives required for any design that contains nested functions.
    TIP: You can use $::env(MY_ENV_VAR) to specify environment variables in CFLAGS. For example, to include the directory $MY_ENV_VAR/include for compilation, you can specify the CFLAG as -I$::env(MY_ENV_VAR)/include.
  7. Click Remove to delete any files from your project that are not needed or were added by mistake.
  8. Next to the Top Function field, click Browse to list the functions and sub-functions found in the added files.
    The Select Top Function dialog box is opened as shown below. This dialog box lists the functions found in the added files, and lets you specify which of these is the top function for the purposes of HLS.

    TIP: You can simply type the name of top-level function in the available field. However, after source files have been added to the project, the tool lists the available functions for you to choose from.
  9. In the Add/Remove Design Files page, with files added and the top function specified, click Next to proceed.
    In the Add/Remove Testbench Files dialog box, you can add test bench files and other required files to your project, as shown in the following figure.
    TIP: There is no requirement to add a test bench to the project. You can simply click Next to skip this step if you prefer.


  10. As with the C source files, click Add Files to add the test bench. Click Edit CFLAGS or Edit CSIMFLAGS to include any compiler options.
  11. In addition to the C source files, all files read by the test bench must be added to the project. In the example shown in the figure above, the test bench opens file in.dat to supply input stimuli to the design, and reads out.golden.dat to read the expected results. Because the test bench accesses these files, both files must be included in the project.
    TIP: If the test bench files exist in a directory, you can add the entire directory to the project, rather than the individual files, by clicking Add Folder.
  12. Click Next to proceed and the Solution Configuration dialog box is displayed, letting you configure the initial solution for your project.

  13. Specify a Solution Name to collect the directives, the results, and the reports for a specific configuration of the project. Multiple solutions let you create different project configurations to quickly find the best solution.
  14. Under Clock, specify the Period in units of ns, or as a frequency value specified with the MHz suffix (for example, 150 MHz). Refer to Specifying the Clock Frequency for more information.
  15. Specify the Uncertainty used for synthesis as the clock period minus the clock uncertainty. Vitis HLS uses internal models to estimate the delay of the operations for each device. The clock uncertainty value provides a controllable margin to account for any increases in net delays due to RTL logic synthesis, place, and route. Specify as a value in nanoseconds (ns), or as a percentage of the clock period. The default clock uncertainty is 12.5% of the clock period.
  16. Complete Part Selection for your project by clicking the browse button () to display the Device Selection Dialog box, as shown below.

    The Device Selection Dialog box lets you select the device for your project as a part, or as a board, such as an Alveo™ Data Center accelerator card. You can click the Search filter to reduce the number of devices in the device list.

  17. Select the appropriate Flow Target from the drop-down menu to configure the project and enable the output of the synthesized project as described in Vitis HLS Process Overview. By specifying the Flow Target, you can configure the HLS tool to develop kernels for the Vitis application acceleration development flow, or RTL IP for use in the Vivado Design Suite.
  18. Click Finish to create and open the new Vitis HLS project as shown in the following figure.

By default the Vitis HLS IDE initially displays four panes:

  • In the upper left-hand side, the Explorer view lets you navigate through the project hierarchy. A similar hierarchy exists in the project directory on the disk.
  • In the center, the Information area displays report summaries and open files. Files can be opened by double-clicking them in the Explorer view.
  • At the bottom, the Console view displays the output when Vitis HLS is running synthesis or simulation.
  • In the lower left-hand side, the Flow Navigator view which provides access to commands and processes as described in Using the Flow Navigator to take your source code through simulation, synthesis, and exported output.
  • Though not displayed by default, when source code is opened in the Information area the Outline and Directive views are displayed on the right-side, and show information related to the hierarchy of the code.

In addition to the views displayed by default, there are additional views that are opened by launching specific processes such as C/RTL co-simulation, or opening source files or reports. Additional views can be opened using the Window > Show View command from the main menu.

Working with Sources

The following figure illustrates the Vitis HLS design flow, showing the inputs and output files.

Figure 2: Vitis HLS Design Flow

Vitis HLS inputs include:

  • C functions written in C and C++11/C++14. This is the primary input to Vitis HLS. The function can contain a hierarchy of sub-functions.
  • C functions with RTL blackbox content as described in Adding RTL Blackbox Functions.
  • Design Constraints that specify the clock period, clock uncertainty, and the device target.
  • Directives are optional and direct the synthesis process to implement a specific behavior or optimization.
  • C test bench and any associated files needed to simulate the C function prior to synthesis, and to verify the RTL output using C/RTL Co-simulation.

You can add the C input files, directives, and constraints to a project using the Vitis HLS graphical user interface (GUI), or using Tcl commands from the command prompt, as described in Running Vitis HLS from the Command Line. You can also create a Tcl script, and execute the commands in batch mode.

The following are Vitis HLS outputs:

  • Compiled object files (.xo).

    This output lets you create compiled hardware functions for use in the Vitis application acceleration development flow. Vitis HLS produces this output when called as part of the compilation process from the Vitis tool flow, or when invoked as a stand-alone tool in the bottom up flow.

  • RTL implementation files in hardware description language (HDL) formats.

    This is a primary output from Vitis HLS. This flow lets you use C/C++ code as a source for hardware design in the Vitis tool flow. RTL IP produced by Vitis HLS is available in both Verilog (IEEE 1364-2001), and VHDL (IEEE 1076-2000) standards, and can be synthesized and implemented into Xilinx devices using the Vivado Design Suite.

  • Report files.

    Reports generated as a result of simulation, synthesis, C/RTL co-simulation, and generating output.

Coding C/C++ Functions

Coding Style

In any C program, the top-level function is called main(). In the Vitis HLS design flow, you can specify any sub-function below main() as the top-level function for synthesis. You cannot synthesize the top-level function main(). Following are additional rules:

  • Only one function is allowed as the top-level function for synthesis.
  • Any sub-functions in the hierarchy under the top-level function for synthesis are also synthesized.
  • If you want to synthesize functions that are not in the hierarchy under the top-level function for synthesis, you must merge the functions into a single top-level function for synthesis.

C/C++ Language Support

Vitis HLS supports the C/C++ 11/14 for compilation/simulation. Vitis HLS supports many C and C++ language constructs, and all native data types for each language, including float and double types. However, synthesis is not supported for some constructs, including:

  • Dynamic memory allocation: An FPGA has a fixed set of resources, and the dynamic creation and freeing of memory resources is not supported.
  • Operating system (OS) operations: All data to and from the FPGA must be read from the input ports or written to output ports. OS operations, such as file read/write or OS queries like time and date, are not supported. Instead, the host application or test bench can perform these operations and pass the data into the function as function arguments.

For details on the supported and unsupported C constructs and examples of each of the main constructs, see Vitis HLS Coding Styles.

Accessing Source Files in Git Repositories

When adding source files to your project,Vitis HLS offers an integrated view of GitHub repositories integrated into the tool. You can use this feature to work with your own repositories for managing source code for the project, or for linking to external repositories to download files for your design.

At the bottom of the Vitis HLS GUI, where the Console view is located, you will see the Git Repositories view.

TIP: If this view is not open, you can enable it using the Window > Show View > Git Repository menu command.

Clone a repository using the following steps.

  1. Select the Clone a Git Repository command. This opens the Clone Git Repository wizard as shown in the following figure.

  2. In the Source Git Repository page of the wizards, enter the following in for URL: https://github.com/Xilinx/HLS-Tiny-Tutorials/tree/master

    This sets up the Tiny Tutorials repository as described in Tutorials and Examples. Click Next to proceed.

  3. In the Branch Selection page, select the master branch of the repository, or another branch as appropriate. Click Next to proceed.
  4. In the Local Destination page, specify the Destination Directory where the repository will be cloned. Click Next to proceed.

At this time you should see the list of examples from the Tiny Tutorials repository. You can now use these files as source files for your own projects. You can also add an existing local repository to the Vitis HLS GUI, or create a new repository to help you manage projects.

Using Libraries in Vitis HLS

Vitis HLS Libraries

Vitis HLS provides foundational C libraries allowing common hardware design constructs and functions to be easily modeled in C and synthesized to RTL. The following C libraries are provided with Vitis HLS:

  • Arbitrary Precision Data Types Library: Arbitrary precision data types let your C code use variables with smaller bit-widths than standard C or C++ data types, to enable improved performance and reduced area in hardware.
  • Vitis HLS Math Library: Used to specify standard math operations for synthesis into RTL and implementation on Xilinx devices.
  • HLS Stream Library: For modeling and compiling streaming data structures.

You can use each of the C libraries in your design by including the library header file in your code. These header files are located in the include directory in the Vitis HLS installation area.

IMPORTANT: The header files for the Vitis HLS C libraries do not have to be in the include path if the design is used in Vitis HLS. The paths to the library header files are automatically added.
Vitis Libraries

In addition, the Vitis accelerated libraries are available for use with Vitis HLS, including common functions of math, statistics, linear algebra and DSP; and also supporting domain specific applications, like vision and image processing, quantitative finance, database, data analytics, and data compression. Documentation for the libraries can be found at https://xilinx.github.io/Vitis_Libraries/. The libraries can be downloaded from https://github.com/Xilinx/Vitis_Libraries.

The Vitis libraries contain functions and constructs that are optimized for implementation on Xilinx devices. Using these libraries helps to ensure high quality of results (QoR); that the results of synthesis are a high-performance design that optimizes resource usage. Because the libraries are provided in C and C++, you can incorporate the libraries into your top-level function and simulate them to verify the functional correctness before synthesis.

TIP: The Vitis application acceleration libraries are not available for use on the Windows operating system.

Resolving Header File Problems

By default, the Vitis HLS GUI continually parses all header files to resolve coding references. The GUI highlights unresolved references, as shown in the following figure:

Figure 3: Index C Files
  • Left sidebar: Highlights unresolved references at the line number of the source code.
  • Right sidebar: Displays unresolved references relative to the whole file.

Unresolved references occur when code defined in a header file (.h or .hpp extension) cannot be resolved. The primary causes of unresolved references are:

  • The code was recently added to the file.

    If the code is new, ensure the header file is saved. After saving the header file, Vitis HLS automatically indexes the header files and updates the code references.

  • The header file is not in the search path.

    Ensure the header file is included in the C code using an #include statement, and the header file is found in the same directory as the source C file, or the location to the header file is in the search path.

    TIP: To explicitly add the search path for a source file, select Project > Project Settings, click Synthesis or Simulation, and use the Edit CFLAGs or Edit CFLAGs commands for the source file as discussed in Creating a New Vitis HLS Project.
  • Automatic indexing has been disabled.

    Ensure that Vitis HLS is parsing all header files automatically. Select Project > Project Settings, click General, and make sure Disable Parsing All Header Files is deselected.

TIP: To manually force Vitis HLS to index all C files, select the Project > Index C Source command from the main menu.

Resolving Comments in the Source Code

In some localizations, non-English comments in the source file appears as strange characters. This can be corrected using the following steps:

  1. Right-click the project in the Explorer view and select the Properties menu command.
  2. Select the Resource section in the left side of the dialog box.
  3. Under Text file encoding, select the Other radio button, and choose appropriate encoding from the drop-down menu.
  4. Select Apply and Close to accept the change.

Setting Configuration Options

After the project and solution have been created, you can configure default settings of the Vitis HLS tool using the Solution > Solution Settings menu command. This command opens the Solution Settings dialog box for the currently active solution.

TIP: If you have created multiple solutions for your project, as described in Creating Additional Solutions, you can make a solution active by right clicking on a solution in the Explorer view and using the Set Active Solution command. You can also open the Solution Settings dialog box for a specific solution by right-clicking the solution and using the Solution Settings command.
Figure 4: Solution Settings Dialog Box

The Solutions Setting dialog box provides access to the following settings:

General
Displays the Configuration Settings page for the current solution, listing settings that generally apply to the Vitis HLS tool overall.
Synthesis
Synthesis settings are initially defined when the project is created as described in Creating a New Vitis HLS Project.
Cosimulation
These settings control the C/RTL Co-simulation feature as described in C/RTL Co-Simulation in Vitis HLS.
Export
These settings affect the output generated by Vitis HLS as described in Exporting the RTL Design.
RTL Synthesis
These settings affect the results and reports generated by Vivado synthesis as described in Exporting the RTL Design.
Place and Route
These settings affect the results and reports generated by Vivado implementation as described in Exporting the RTL Design.

Configuration Settings

On the Configuration Settings page, as displayed in the figure above, you have access to the various configuration commands like config_compile and config_interface. These commands are described in detail in Configuration Commands.

Select one of the listed configuration commands, and click the Expand All (+) command to expand the selected configuration command to view the available options. You can edit the options for the selected command, or use the Reset all (X) command to restore the selected configuration to its default setting.

Use the Collapse All (-) command to collapse any selected configuration command.

Use the Help (?) command to open a window that provides a text description of the selected configuration command and all its options.

Enable the Show only non-defaults check box to only display the configuration commands that have been modified from their default values.

Click OK to confirm the settings of the various configuration commands and close the Solution Settings dialog box. Click Cancel to cancel any changes and close the dialog box.

Synthesis Settings

On the Synthesis Settings page, as shown in the following figure, you have access to the various settings to drive the synthesis process, such as the target Xilinx device, the clock period and uncertainty, and the target flow for the solution.

Figure 5: Synthesis Settings Page
  • Specify the clock period in units of nanoseconds (ns), or as a frequency value specified with the MHz suffix (for example, 150 MHz). Refer to Specifying the Clock Frequency for more information.
  • Specify the clock uncertainty used for synthesis as the clock period minus the clock uncertainty. Vitis HLS uses internal models to estimate the delay of the operations for each device. The clock uncertainty value provides a controllable margin to account for any increases in net delays due to RTL logic synthesis, place, and route. Specify as a value in ns, or as a percentage of the clock period. The default clock uncertainty is 12.5% of the clock period.
  • Specify the target device (Part) for your project by clicking the Browse button () to open the Device Selection Dialog box to select a device or board for the solution. You can click the Search filter to reduce the number of devices listed.
  • Select the Flow Target as explained in Vitis HLS Process Overview.

Specifying the Clock Frequency

For C and C++ designs only a single clock is supported. The same clock is applied to all functions in the design.

The clock period, in ns, is set in the Solutions > Solutions Setting. The default clock period is 10 ns. Vitis HLS uses the concept of a clock uncertainty to provide a user defined timing margin. You can define the clock uncertainty for your design using the Solutions Setting dialog box as well. The default clock uncertainty, when it is not specified, is 27% of the clock period.

TIP: You can also set the clock period using the create_clock Tcl command, and the clock uncertainty using the set_clock_uncertainty Tcl command.

Using the clock frequency and device target information Vitis HLS estimates the timing of operations in the design but it cannot know the final component placement and net routing: these operations are performed by logic synthesis of the output RTL. As such, Vitis HLS cannot know the exact delays.

To calculate the clock period used for synthesis, Vitis HLS subtracts the clock uncertainty from the clock period, as shown in the following figure.

Figure 6: Clock Period and Margin

This provides a user specified margin to ensure downstream processes, such as logic synthesis and place & route, have enough timing margin to complete their operations. If the FPGA is mostly used the placement of cells and routing of nets to connect the cells might not be ideal and might result in a design with larger than expected timing delays. For a situation such as this, an increased timing margin ensures Vitis HLS does not create a design with too much logic packed into each clock cycle and allows RTL synthesis to satisfy timing in cases with less than ideal placement and routing options.

Vitis HLS aims to satisfy all constraints: timing, throughput, latency. However, if a constraints cannot be satisfied, Vitis HLS always outputs an RTL design.

If the timing constraints inferred by the clock period cannot be met Vitis HLS issues message SCHED-644, as shown below, and creates a design with the best achievable performance.

@W [SCHED-644] Max operation delay (<operation_name> 2.39ns) exceeds the effective 
cycle time

Even if Vitis HLS cannot satisfy the timing requirements for a particular path, it still achieves timing on all other paths. This behavior allows you to evaluate if higher optimization levels or special handling of those failing paths by downstream logic syntheses can pull-in and ultimately satisfy the timing.

IMPORTANT: It is important to review the constraint report after synthesis to determine if all constraints is met: the fact that Vitis HLS produces an output design does not guarantee the design meets all performance constraints. Review the Performance Estimates section of the design report.

A design report is generated for each function in the hierarchy when synthesis completes and can be viewed in the solution reports folder. The worse case timing for the entire design is reported as the worst case in each function report. There is no need to review every report in the hierarchy.

If the timing violations are too severe to be further optimized and corrected by downstream processes, review the techniques for specifying an exact latency and specifying exact implementation cores before considering a faster target technology.

Clock and Reset Ports

If the design takes more than 1 cycle to complete operation, a clock-enable port (ap_ce) can optionally be added to the entire block using the config_interface command, or in the Vitis HLS GUI using the Solution > Solution Settings > General command.

The operation of the reset is described in Controlling the Reset Behavior, and can be modified using the config_rtl command, also available in the Solutions Settings dialog box.

Using the Flow Navigator

The Flow Navigator is a process flow representation of the Vitis HLS design flow. Each step in the process is represented by actions that you can launch to work through the flow. All viewers and reports are also available through the Flow Navigator as each step is completed.

Figure 7: Flow Navigator
The different steps represented in the Flow Navigator include:
  • C SIMULATION: opens the C Simulation dialog box, and lists the available reports after simulation has been run, as described in Verifying Code with C Simulation.
  • C SYNTHESIS: opens the C Synthesis dialog box, and lists the available reports after synthesis has been run, as discussed in Synthesizing the Code.
  • C/RTL COSIMULATION: opens the C/RTL Cosimulation dialog box, and lists the available reports after simulation has been run, as described in C/RTL Co-Simulation in Vitis HLS.
  • IMPLEMENTATION: lets you specify the format and location of the exported RTL file from Vitis HLS as discussed in Exporting the RTL Design, and also run Vivado synthesis and implementation to generate more detailed utilization and timing reports.
TIP: You can cancel Simulation, Synthesis, C/RTL Cosimulation, or Implementation using the Stop command from the Flow Navigator.