Lab Workbook Vitis HLS Tool Flow

Vitis HLS Tool Flow

2020.2

2023/10/3 by NOVENDRA

Software Link:

Vitis HLS 2020.2 :

https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/v
itis/archive-vitis.html

Vitis HLS Patch: https://support.xilinx.com/s/article/76960?language=en_US

1.1 Abstract
This lab introduces how to perform basic actions using the Vitis™ High-Level Synthesis (HLS)
tool design flow.
This lab should take approximately 45 minutes.

1.2 Objectives
After completing this lab, you will be able to:
• Create a new project in the Vitis HLS tool GUI
• Simulate a C design by using a self-checking test bench
• Synthesize the design
• Perform design analysis using the Analysis Perspective view
• Perform co-simulation on a generated RTL design by using a provided C test bench
• Implement the design

1.3 Introduction
This lab provides a basic introduction to high-level synthesis using the Vitis HLS tool flow. You
will use Vitis HLS in GUI mode to create a project. You will simulate, synthesize, and implement
the provided design.
In this lab, you will be using a C design to implement a matrix multiplication (matmul). The
function implements a matmul algorithm by first processing each row and column using scalar
multiplication. And the final process is sum the result from each scalar multiplication. The
illustration of matrix multiplication is described bellow:

www.xilinx.com 1
© Copyright 2021 Xilinx
Vitis HLS Tool Flow Lab Workbook

𝑏1
𝑎 = [𝑎1 𝑎2 𝑎3]; 𝑏 = +𝑏2,
𝑏3
𝑏1
𝑟 = 𝑎𝑏 = [𝑎1 𝑎2 𝑎3] +𝑏2, = 𝑎1𝑏1 + 𝑎2𝑏2 + 𝑎3𝑏3
𝑏3

Understanding the Lab Environment

These environment variables are:

Environment Variable Description

Name

XILINX_PATH Points to the installation directory for the Xilinx tools. Tools such
as the Vivado® Design Suite and others can be found here.

VITIS_PATH Points to the installation directory for the Vitis™ tools.

PETALINUX_PATH Points to the installation directory for the Xilinx PetaLinux tools.
This is usually within XILINX_PATH, but may have been installed
elsewhere.

TRAINING_PATH Points to the space allocated for students to work through their
labs. This directory includes prebuilt images and starting points
for the labs and demos.

VERSION Contains the specific version of the Xilinx tools you are using.

hls_tool_flow Points to the specific name of the lab or demo within the
TRAINING_PATH directory. This lab uses $hls_tool_flow,
which is equivalent to $TRAINING_PATH/hls_tool_flow
when using the VM and is common on native Linux machines.

The environment variable notation used in this lab does not work in every tool and environment.
When to use which form is explained in the instructions.
Here is a brief overview: You can directly use $variableName whenever you are working in the
Linux terminal windows and in shell scripts. The Tcl environment (whether it is through a Tcl
shell, Tcl script, or tool GUI) requires users to use the form $::env(variableName). When
using the Vivado Design Suite or Vitis IDE, you must replace the $variableName with the
expanded value of the variable.

2 www.xilinx.com
© Copyright 2021 Xilinx
Lab Workbook Vitis HLS Tool Flow

You can find the value of a variable by opening a terminal window and entering: echo
$variableName. The value of variableName will be displayed.

1.4 General Flow

Step 1: Step 2: Step 3: Step 4: Step 5:
Creating a Create the Running Synthesizing Using
Vitis HLS Design C the Analysis
Tool Project using C Simulation Design Perspective

Step 6: Step 7:
Performing Exporting
Co- the RTL
simulation as IP

1.5 Creating a Vitis HLS Tool Project (Step 1)

In this step, you will launch the Vitis HLS tool GUI and create a new project for the
provided C-based discrete cosine transformation (DCT) design.
There are a number of ways to launch the Vitis HLS tool. The two most popular
mechanisms are shown here.

www.xilinx.com 3
© Copyright 2021 Xilinx
Vitis HLS Tool Flow Lab Workbook

1.5.1 Launch the Vitis HLS tool.

1.5.1.1 [Windows 10 users:] Select Start > Xilinx Design Tools > Vitis HLS 2020.2.

Figure 1-1: Launching the Vitis HLS Tool

You can also double-click the Vitis HLS shortcut icon ( ) from the Windows or Linux
desktop or taskbar.

[Linux users]: Click the Vitis HLS ( ) icon from the taskbar to launch the tool.
The Vitis HLS tool opens to the Welcome window. From the Welcome window, you can
create a new project, open examples, and access documentation and examples.

Figure 1-2: Vitis HLS Welcome Page

4 www.xilinx.com
© Copyright 2021 Xilinx
Lab Workbook Vitis HLS Tool Flow

Here you will create a new Vitis HLS tool project from scratch.

Create a Vitis HLS tool project named matmul.

1.5.1.2 Click Create Project from the Welcome Page.

Figure 1-3: Creating a New Vitis HLS Tool Project

The Project Configuration dialog box asks for a project name and location.
1.5.1.3 create project name with matmul in the Project name field.
1.5.1.4 create folder Lab1 to fill the Location field.
You can also browse to the desired path and click Open.

www.xilinx.com 5
© Copyright 2021 Xilinx
Vitis HLS Tool Flow Lab Workbook

6 www.xilinx.com
© Copyright 2021 Xilinx
Lab Workbook Vitis HLS Tool Flow

1.5.1.5 Click Next (3).

1.5.2 The Add/Remove Files dialog box opens. Here you will be invited to add existing
files or create new sources.
1.5.2.1 fill the Top Function field with matmul same as the project name.

1.5.2.2 Click Next (3).

1.5.2.3 Click Next (4).

www.xilinx.com 7
© Copyright 2021 Xilinx
Vitis HLS Tool Flow Lab Workbook

1.5.3 Finally, it is time to specify some of the physical parameters of the design.
By default, solution1 is populated in the Solution Name field. No changes
are required.
1.5.3.1 Set the clock period to 10.
You can leave the Uncertainty field blank.
1.5.3.2 Click the Browse (. . .) icon to select a part or board.

Figure 1-4: Locating the Board Browse Button

1.5.3.3 Click Boards as shown below.

1.5.3.4 Enter ZYNQ-7 in the Search field.

Figure 1-5: Filtering to Quickly Locate Target Platforms

8 www.xilinx.com
© Copyright 2021 Xilinx
Lab Workbook Vitis HLS Tool Flow

1.5.3.5 Select ZYNQ-7 ZC702 Evaluation Board from the search list.
1.5.3.6 Click OK to select the board.
1.5.3.7 Make sure that Vivado IP Flow Target is selected from the drop-down list under Flow
Target field.
1.5.3.8 Click Finish.
You will see the created project in the Explorer tab.

Figure 1-6: Vitis HLS with Newly Created Project

The Vitis HLS tool GUI consists of various panes to proceed with the development work.
You will see the created project in the Explorer view. Expand various sub-folders to see
the entries under each sub-folder. The Source folder consists of source files associated
with the project and the Test Bench folder consists of test bench files associated with the
project.

www.xilinx.com 9
© Copyright 2021 Xilinx
Vitis HLS Tool Flow Lab Workbook

1.6 Design the Device with C (Step 2)

1.6.1 Create device source code with C
1.6.1.1 From explorer right click the source

1.6.1.2 New File

10 www.xilinx.com
© Copyright 2021 Xilinx
Lab Workbook Vitis HLS Tool Flow

1.6.1.3 Name the source code with matmul.cpp

1.6.1.4 Save

1.6.2 Create C Header File

1.6.2.1 From menu File, click New File, give the C header file name with matmul.h such as the
figure bellow.

www.xilinx.com 11
© Copyright 2021 Xilinx
Vitis HLS Tool Flow Lab Workbook

1.6.2.2 Save
1.6.2.3 Create the C header file with the source code in the following figure:

12 www.xilinx.com
© Copyright 2021 Xilinx
Lab Workbook Vitis HLS Tool Flow

1.6.2.4 Save

1.6.3 Load Test Bench with C

1.6.3.1 From Test Bench, right click and Add File

1.6.3.2 Load the file name is matmul_test.cpp

1.6.3.3 Click open

www.xilinx.com 13
© Copyright 2021 Xilinx
Vitis HLS Tool Flow Lab Workbook

1.7 Running C Simulation Step 3

After creating the project, the next step is to validate that the C function is correct
before proceeding with synthesizing the design. In this step, you will validate the
design by using the provided self-checking C test bench.
1.7.1 Simulate the Vitis HLS tool design.
1.7.1.1 Select Project > Run C Simulation.

Figure 1-7: Launching the C Simulation

The Run C Simulation dialog box opens.

Figure 1-8: C Simulation Dialog Box

Each of the options controls how simulation is run:

o Launch Debugger: After compilation the debug perspective automatically opens for
you to step through the code.

14 www.xilinx.com
© Copyright 2021 Xilinx
Lab Workbook Vitis HLS Tool Flow

o Build Only: Compiles the source code and the test bench, but the simulation does
not run. This option can be used to test the compilation process and resolve any
issues with the build prior to running simulation.
o Clean Build: Removes any existing executable and object files before compiling the
code.
o Optimizing Compile: By default the design is compiled with debug information
enabled, allowing the compilation to be analyzed and debugged. The Optimizing
Compile option uses a higher level of optimization effort when compiling the design,
but does not add information required by the debugger. This increases the compile
time but should reduce the simulation runtime.
1-0-1. Select Default Options (i.e. select nothing to run a C simulation).
1-0-2. Click OK.

The simulation log will be displayed in the editor pane.

1-1. View the simulation report.

The information generated by the Vitis HLS tool can be found in two places,
both described here.
The first is the Console window, which reports not only the output produced
by the code being simulated, but all of the simulation engine messages as
well. The simulation log provides only a few simulation engine messages
and the simulated code output.
1-1-1. Select the Console tab in the lower portion of the tool's GUI.

You may need to scroll to view all the output produced by the simulation.

Figure 1-9: Example Output After Simulation

The other location, described below, provides only a few simulation engine messages
and the simulated code output. Typically this is opened after the simulation completes;
however, if you need to access it after closing the log pane, here's how to access the
simulation report.
1-1-2. Expand matmul > solution1 > csim > report in the Explorer pane.

www.xilinx.com 15
© Copyright 2021 Xilinx
Vitis HLS Tool Flow Lab Workbook

1-1-3. Double-click the log file name to open it in the editor pane.

Figure 1-10: Locating the Simulation Log File

You should see a "Results are good" message in the simulation log file and in the console
area. If you do not see this message, ask for help from your instructor.

Synthesizing the Design Step 2

In this step, you will synthesize the design by using Vitis HLS tool defaults and
analyze how many resources are utilized to implement the C design.

2-1. Synthesize the design.

2-1-1. Select Solution > Run C Synthesis > Active Solution or click the C Synthesis icon in
the menu bar.

Figure 1-11: Launching Synthesis

This option synthesizes the currently selected solution.

All solutions (or selected solutions) can be synthesized by using the drop-down menu
next to the synthesis icon. You can synthesize all solutions or synthesize selected
solutions in addition to the default.

16 www.xilinx.com
© Copyright 2021 Xilinx
Lab Workbook Vitis HLS Tool Flow

When the synthesis completes, the Synthesis report will be displayed in the Information
pane.

Figure 1-12: Synthesis Report [Example]

The Synthesis report shows the timing, performance, and area estimates as well as
estimated latency in the design.
2-1-2. Expand the matmul > solution1 > syn > report folder in the Explorer pane.
2-1-3. Double-click the matmul_csynth.rpt file to view the Synthesis report.
2-1-4. Scroll to Performance Estimates and Utilization Estimates in the Synthesis report to
answer the following question.

Question 1
Write down the following details from the Synthesis report:
• Estimated clock frequency:
• Worst case latency:
• Number of BRAM_18K:
• Number of DSP48E used:
• Number of FFs used:
• Number of LUTs used:

2-1-5. Select Interface > Summary in the Synthesis report.

www.xilinx.com 17
© Copyright 2021 Xilinx
Vitis HLS Tool Flow Lab Workbook

The report also shows the top-level interface signals generated by the tools.

Figure 1-13: Generated Interface Signals

You can see that ap_clk and ap_rst are automatically added. ap_start, ap_done, and
ap_idle are top-level signals used as handshaking signals to indicate when the design is
able to accept the next computation command (ap_idle), when the next computation is
started (ap_start), and when the computation is completed (ap_done). Other signals are
generated based on the design itself.
2-1-6. Select the Console tab.

The Synthesis log is available in the Vitis HLS Console.

Note that when the Solution1 > syn folder is expanded in the Explorer view, it will show
the report, verilog, and vhdl sub-folders under which the report files and generated
source files (VHDL, Verilog, header, and cpp) are available. Double-clicking any of these
entries will open the corresponding file in the Information pane.

18 www.xilinx.com
© Copyright 2021 Xilinx
Lab Workbook Vitis HLS Tool Flow

Also note that the target design has hierarchical functions, and reports corresponding to
lower-level functions are also created. By default, the report for the top-level function is
displayed in the Information pane once synthesis is completed.

Analyzing the Design Using the Analysis Perspective Step 3

The Analysis perspective is used after synthesis completes for analyzing the
design in detail. This perspective provides considerably more details than the
Synthesis report.
The Analysis perspective is provided as a place to view different elements of your
project to evaluate the results of synthesis and the performance of your current
solution. By default, it opens with the Schedule Viewer displayed. It provides both
a tabular and graphical view of the design performance and resources and
supports cross-referencing between both views.

3-1. Switch to the Analysis perspective and understand the design behavior.
3-1-1. Select Solution > Open Analysis Perspective or click the Open Analysis Viewer icon

( ) to open the analysis viewer.

The Analysis perspective consists of the following panes.
o Schedule Viewer: Shows each operation and control step of the function and the
clock cycle that it executes in.
o Module Hierarchy: Shows the function hierarchy and the performance characteristics
of the current hierarchy.
o Performance Profile: Shows the loops from the top-level function without any
performance information.
o Resource Profile: Shows the resource usage of different elements of the synthesized
function.
www.xilinx.com 19
© Copyright 2021 Xilinx
Vitis HLS Tool Flow Lab Workbook

o Properties view: Shows the properties of the currently selected control step or
operation in the Schedule Viewer.
The Module Hierarchy pane provides an overview of the entire RTL design. It shows the
resources and latency contribution for each block in the RTL hierarchy. This view directly
indicates any II or timing violations. In case of timing violations, the hierarchy window
will also show the total negative slack observed in a specific module.
Note that the module hierarchies are displayed unexpanded by default.
The Performance Profile pane is visible and shows the performance details for this level
of hierarchy. The information in these two panes is similar to the information reviewed
earlier in the Synthesis report.

The Schedule Viewer provides a detailed view of the synthesized RTL, showing each
operation and control step of the function, and the clock cycle that it executes in. It helps
you to identify any loop dependencies that are preventing parallelism, timing violations,
and data dependencies.
o The left vertical axis shows the names of operations and loops in the RTL hierarchy in
topological order, implying that an operation on line n can only be driven by
operations from a previous line and will only drive an operation in a later line.
o The top horizontal axis shows the clock cycles in consecutive order.
o The vertical dashed line in each clock cycle shows the reserved portion of the clock
period due to clock uncertainty. This time is left by the tool for Vivado Design Suite
back-end processes, like place and route.
o Each operation is shown as a gray box in the table. The box is horizontally sized
according to the delay of the operation as a percentage of the total clock cycle. In
case of function calls, the provided cycle information is equivalent to the operation
latency.

20 www.xilinx.com
© Copyright 2021 Xilinx
Lab Workbook Vitis HLS Tool Flow

o Multi-cycle operations are shown as gray boxes with a horizontal line through the
center of the box.
o General operator data dependencies are also displayed as solid blue lines. The green
dotted line indicates an inter-iteration data dependency. Memory dependencies are
displayed using golden lines.
o In addition, lines of source code are associated with each operation in the Schedule
Viewer report. Right-click the operation to use the Goto Source command to open
the input source code associated with the operation.

3-2. Analyze the performance of the dct module.

The dct module has three main resources:
• A loop called Row_Col.
Notice that all the loops in the design are pipelined by default.
3-2-1. Expand the loop ROW_COLin the Schedule viewer (solution1).
3-2-2. Select add_In5_3(+).
3-2-3. Right-click the highlighted box and select Goto Source.

Figure 1-14: Performance of the dct Loop Operation

www.xilinx.com 21
© Copyright 2021 Xilinx
Vitis HLS Tool Flow Lab Workbook

The information presented in the Schedule view is explained below by reviewing the first
set of resources to be executed:
o The design starts in the 0 state.
o It then starts to execute the logic in the loop RD_Loop_Row.
§ Note: In the first state of the loop, the exit condition is checked and there is an
add operation.
o The loop executes over two states: 0, 1 and 2.
3-2-4. Review the Performance Profile pane information.

Figure 1-15: Performance Profile Pane

The Performance Profile pane shows that this loop has a trip count of 4. It therefore
iterates around these 7 states twice.
3-2-5. Expand the Row_Col loop in the Schedule viewer (solution1).

22 www.xilinx.com
© Copyright 2021 Xilinx
Lab Workbook Vitis HLS Tool Flow

3-2-6. Select add_In5_3(+).

www.xilinx.com 23
© Copyright 2021 Xilinx
Vitis HLS Tool Flow Lab Workbook

3-2-7. Right-click the highlighted box and select Goto Source.

Figure 1-16: C Source Code Correlation

You can see that the write operation is implementing the writing of data into the buf
array from the input array variable.

24 www.xilinx.com
© Copyright 2021 Xilinx
Lab Workbook Vitis HLS Tool Flow

3-3. Analyze the resource usage for the design.

3-3-1. Select the Module Hierarchy and Resource Profile tabs as shown below.

Figure 1-17: Analysis Perspective – Resource Usage

The Resource Profile tab shows the resources used at this level of hierarchy. In this
design, you can see that most of the resources are due to the instances—blocks that are
instantiated inside this block. As per the function selected in the Module Hierarchy tab,
you are able to view the resources used by the function in the Resource Profile tab.

3-3-2. Click the Synthesis perspective icon ( ) to return to

the Synthesis view.

www.xilinx.com 25
© Copyright 2021 Xilinx
Vitis HLS Tool Flow Lab Workbook

Performing C/RTL Co-simulation Step 4

Now that you have performed high-level synthesis on the C design, you will
perform RTL co-simulation on the generated RTL using the C test bench.
Run C/RTL co-simulation, selecting Verilog and skipping VHDL. Verify that the
simulation passes.

4-1. Cosimulate the Vitis HLS tool design.

4-1-1. Select Solution > Run C/RTL Cosimulation.

Figure 1-18: Launching from the Menu

The Run C/RTL Co-simulation dialog box opens.

Figure 1-19: Co-simulation Dialog Box

The dialog box includes the following settings:

o Simulator: Choose from one of the supported HDL simulators in the Vivado Design
Suite. The Vivado simulator is the default simulator.
o Language: Specify the use of Verilog or VHDL as the output language for simulation.
o Setup Only: Create the required simulation files, but do not run the simulation. The
simulation executable can be run from a command shell at a later time.
o Optimizing Compile: Enable optimization to improve the runtime performance, if
possible, at the expense of compilation time.
26 www.xilinx.com
© Copyright 2021 Xilinx
Lab Workbook Vitis HLS Tool Flow

o Input Arguments: Specify any command-line arguments to the C test bench.

o Dump Trace: Specifies the level of trace file output written to the sim/Verilog or
sim/VHDL directory of the current solution when the simulation executes. Options
include:
§ all: Output all port and signal waveform data being saved to the trace file.
§ port: Output waveform trace data for the top-level ports only.
§ none: Do not output trace data.
o Random Stall: Applies a randomized stall for each data transmission.
4-1-2. Select the default options (i.e. select nothing).
4-1-3. Click OK.

The simulation log will be displayed in the editor pane.

4-2. View the Cosimulation report.

The information generated by the Vitis HLS tool can be found in two places,
both described here.
The first is the Console window, which reports not only the output produced
by the code being simulated, but all of the simulation engine messages as
well. The simulation log provides only a few simulation engine messages
and the simulated code output.
4-2-1. Select the Console tab in the lower portion of the Vitis HLS tool GUI.

You may need to scroll to view all the output produced by the cosimulation.

Figure 1-20: Example Output After a C/RTL Co-simulation

The other location, described below, provides only a few simulation engine messages
and the simulated code output. Typically this is opened after the simulation completes;
however, if you need to access it after closing the log pane, here is how to access the
simulation report.
4-2-2. Expand dct_prj > solution1 > sim > report in the Explorer pane.

www.xilinx.com 27
© Copyright 2021 Xilinx
Vitis HLS Tool Flow Lab Workbook

4-2-3. Double-click the log file name to open it in the editor pane.

Figure 1-21: Locating the Co-simulation Log File

The Cosimulation Report in HTML format will be displayed in the main viewing area.

Figure 1-22: Cosimulation Report – HTML

You can quickly verify the cosimulation status here.

This process will take a few minutes to complete. After C/RTL cosimulation has been
completed, the Cosimulation report will be accessible in the Information pane, including
the latency information.
Also, in the Console tab, notice the "Results are Good " message that is displayed.

28 www.xilinx.com
© Copyright 2021 Xilinx
Lab Workbook Vitis HLS Tool Flow

Exporting the RTL as an IP Core Step 5

In this step you will export the RTL as an IP core to be used with the top-level
design.

5-1. Export the RTL, selecting Verilog as the language.

5-1-1. Select Solution > Export RTL.

Note: If you see the Feedback Request dialog box, click Cancel.
5-1-2. Ensure that Vivado IP (.zip) is selected from the Format Selection drop-down list.

Figure 1-23: Export RTL Dialog Box

5-1-3. Click Configuration next to the Format Selection drop-down list.

Notice that you can provide information about the IP, such as the vendor, library,
version, and description in the IP Identification dialog box.

Figure 1-24: IP Identification Dialog Box

5-1-4. Click Cancel in the IP Identification dialog box.

5-1-5. Make sure that Verilog is selected as the RTL to be evaluated.

www.xilinx.com 29
© Copyright 2021 Xilinx
Vitis HLS Tool Flow Lab Workbook

5-1-6. Select the Vivado synthesis, place and route option.

5-1-7. Keep the rest of the settings at their defaults.

These options will enable Vivado RTL synthesis and implementation to be performed on
the generated IP. Implementation is run to evaluate and provide confidence that the RTL
will meet its estimated timing and area goals and that these results are not included as
part of the exported package.
5-1-8. Click OK in the Export RTL dialog box.

You can observe the progress in the Console tab. Once implementation completes, the
Implementation report will open in the Information pane.
Observe the "Timing met" message in the report in the Final Timing section. This shows
that the final timing of the implemented design has been achieved.

Figure 1-25: Export Report

5-1-9. Select File > Exit to close the Vitis HLS tool.

30 www.xilinx.com
© Copyright 2021 Xilinx
Lab Workbook Vitis HLS Tool Flow

Some systems (particularly VMs) may be memory constrained. Removing the

workspace frees a portion of the disk space, allowing other labs to be performed.
You can delete the directory containing the lab you just ran by using the
graphical interface or the command line interface. You can choose either
mechanism. Both processes will recursively delete all the files in the
$hls_tool_flow directory.

5-2. [Optional] Clean up the file system.

Using the GUI:
5-2-1. Using the graphical browser (Windows: press the <Windows> key + <E>; Linux: press
<Ctrl + N>), navigate to $hls_tool_flow.
5-2-2. Select hls_tool_flow.
5-2-3. Press <Delete>.

-- OR --
Using the command line:
5-2-4. Open a terminal window (Windows: press the <Windows> key + <R>, then enter cmd;
Linux: press <Ctrl + Alt + T>).
5-2-5. Enter the following command to delete the contents of the workspace:

[Windows users]: rd /s /q $hls_tool_flow

[Linux users]: rm -rf $hls_tool_flow

1.8 Summary
In this lab, you learned how to create a new Vitis HLS tool project in the GUI and execute major
steps such as simulating, synthesizing, co-simulating, and exporting the design as an IP.
In the following labs, you will examine some of the software reports, determine how the design
was implemented, and determine whether or not design goals for area and performance were
met.

www.xilinx.com 31
© Copyright 2021 Xilinx
 Lab Workbook

1.9 Answers
1. Write down the following details from the Synthesis report:
Estimated clock frequency: 6.508
Worst case latency: 412
Number of BRAM_18K: 17
Number of DSP used: 16
Number of FFs used: 1001
Number of LUTs used: 1627

32 www.xilinx.com
© Copyright 2021 Xilinx