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 Files page.

    The Add/Remove Files page lets you add C/C++ source files to your project, as shown in the following figure:

    Figure 2: Add/Remove Files Page
  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:

    Figure 3: Edit CFLAGS Dialog Box

    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 synthesis.

    Figure 4: Select Top Function Dialog Box
    TIP: You can just type the name of top-level function if you have not yet added any files to the project. However, with files added the tool lists the available functions for you to choose from.
  9. In the Add/Remove 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 testbench files and other required files to your project, as shown in the following figure.

    Figure 5: Add/Remove Testbench
  10. As with the C source files, click Add Files to add the testbench. Click Edit CFLAGS or Edit CSIMFLAGS to include any compiler options.
  11. In addition to the C source files, all files read by the testbench must be added to the project. In the example shown in the figure above, the testbench opens file in.dat to supply input stimuli to the design, and reads out.golden.dat to read the expected results. Because the testbench 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. There is no requirement to add a testbench to the project, so you can click Next to proceed.

    The Solution Configuration dialog box is displayed, letting you configure the initial solution for your project.

    Figure 6: Solution Configuration Page
  13. Specify the 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. Specify the clock 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 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 nanoseconds (ns), or as a percentage of the clock period. The default clock uncertainty is 12.5% of the clock period.
  16. Specify the target device (Part) for your project by clicking the Browse button (…) to display the Device Selection dialog box, as shown below.
    Figure 7: Device Selection Dialog Box

    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. For the Flow Target, select Vitis Kernel Flow Target from the drop-down menu to configure the project and enable the output of a compiled Xilinx object file (.xo) from the synthesized project as described in Enabling the Vitis Kernel Flow. This is a requirement for using Vitis HLS to develop kernels for the Vitis application acceleration development flow.
  18. Click Finish to create and open the new Vitis HLS project as shown in the following figure.
    Figure 8: New Project in the Vitis HLS GUI

The default perspective of the Vitis HLS GUI consists of four panes:

  • On the 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 pane displays files. Files can be opened by double-clicking on them in the Explorer Pane.
  • On the right, the Auxiliary pane shows information relevant to whatever file is open in the Information pane.
  • At the bottom, the Console view displays the output when Vitis HLS is running.

Enabling the Vitis Kernel Flow

When you select the Vitis Kernel Flow Target on the Solution Settings dialog box, as discussed in Creating a New Vitis HLS Project, you are configuring Vitis HLS to generate the compiled kernel object (.xo) for the Vitis application acceleration flow.

The flow selection is enabled with the -flow_target option of the open_solution command. When you open the solution it is configured for the specified flow target, in this case the Vitis application acceleration flow. This means that the RTL IP developed by high-level synthesis must meet the kernel requirements defined by the Vitis tool and Xilinx runtime (XRT), as described in Kernel Properties in the Vitis Unified Software Platform Documentation (UG1416).

After the initial simulation or synthesis run, the script.tcl file for the solution is updated to include two new configuration commands:
config_rtl -register_reset_num=3

and

config_interface -default_slave_interface=s_axilite -m_axi_latency=64 \
-m_axi_alignment_byte_size=64 -m_axi_max_widen_bitwidth=512

The config_rtl command defines characteristics of the RTL code generated by Vitis HLS, specifically defining characteristics of the reset required by the Vitis application acceleration development flow.

The config_interface command sets characteristics of the default interface protocols the tool assigns. If there are no existing Interface pragmas in the code, then the following interface protocols will be applied.

  • AXI4-Lite interfaces (s_axilite) are assigned to scalar arguments, global variables, control signals for arrays, and the return value of the software function.
  • AXI4 Master interfaces (m_axi) are assigned to pointer arguments of the C/C++ function.
  • Vitis HLS automatically tries to infer BURST transactions whenever possible to aggregate memory accesses to maximize the throughput bandwidth and/or minimize the latency.
  • Defining a software function argument using an hls::stream datatype implies an AXI4-Stream (axis) port.

You can manually assign the interface specification for your function argument, using the INTERFACE pragma or set_directive_interface command. You can use this technique to change the settings of the default interfaces, such as -bundle to group function arguments into AXI interfaces, and -max_read/write_burst_length to manage burst transactions.

Working with Sources

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

Figure 9: 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 following standards for C compilation/simulation:

  • ANSI-C (GCC 4.6)
  • C++ (G++ 4.6)

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.

In the lower left corner of the Vitis HLS GUI, you will see the Git Repositories view.

TIP: If this view is not open, you can enable it using the Window > Preference command, and navigating to the Run/Debug > View Management page of the Preferences dialog box.
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.
    Figure 10: Clone Git Repository
  2. In the Source Git Repository page of the wizards, enter the following in for URL: https://github.com/Xilinx/HLS-Tiny-Tutorials/tree/2020.1

    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. The libraries can be found to download and use at 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.

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 11: 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 button 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 to open the Project Settings dialog box. Click General, and make sure Disable Parsing All Header Files is deselected.

TIP: To manually force Vitis HLS to index all C files, click the Index C files toolbar button .

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 configuration setting commands, config_xxx. These commands are described in detail in Configuration Commands, but you can set these commands 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 on the solution and using the Solution Settings command.
Figure 12: Solution Settings Dialog Box
The Solutions Setting dialog box provides access to the following settings:
  • General: Displays configuration commands for the current solution that generally apply to the Vitis HLS tool overall. You can Add, Remove, and Edit configuration settings in the current solution.
  • 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.

When you click Add under the General settings, this opens the Add Command dialog box as shown below. This dialog box lets you specify a Command to select, and then configure the Parameters of that command to add to the current solution. The listed commands reflect the available Configuration Commands that are not already added to the solution. The displayed Parameters are options for the selected command.

Select Help to display some information related to the selected command.

Click OK to add the command to the current solution.

Figure 13: Add Command dialog box

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 14: 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.