1. Getting Started¶
First, download the LegUp installer from our website. We support both Windows (64-bit) and Linux (64-bit). We recommend Windows 10, CentOS 6/7, or Ubuntu 16.04.
Run the Windows installer program,
The first time you simulate with Modelsim, this will take a few minutes as we compile our hardware simulation libraries with Modelsim.
The CentOS installer is packaged as a self-extracting shell script that can be installed to a local directory. To run the installer:
cd $(INSTALLATION_DIRECTORY) sh /path/to/legup-8.0-centos-installer.run
This will install LegUp into the INSTALLATION_DIRECTORY. After the installation is completed, please add the LegUp bin directory to your path:
If you need to extend your license on CentOS, please also set the following environment variable:
Download the Linux installer file and double-click on it. When the installer opens up, click
You may also install it in command line:
sudo dpkg -i legup-8.0-LINUX_DISTRIBUTION_VERSION.deb sudo apt-get install -f
If you receive an error about missing the package libc6-dev:i386 you should run the following to enable 32-bit packages:
sudo dpkg --add-architecture i386 sudo apt-get update
These 32-bit packages can be installed without issue on a 64-bit system.
Once LegUp is installed, to enable simulation with Modelsim you will need to compile our hardware libraries:
cd /usr/lib/legup-8.0/legup/ip/libs sudo make LEGUP_TOOL_PATH=$(PATH_TO_MODELSIM)/
Please note that a slash is required at the end of the path to ModelSim binary directory.
1.1.3. ModelSim and Vendor CAD tools¶
You will need ModelSim to simulate the Verilog and vendor CAD tools to synthesize the generated hardware for their FPGA. For Intel, you can download Quartus Web Edition and Modelsim for free from Altera. LegUp HLS has been tested on Quartus 16.0. For Xilinx, you will need Vivado. For Microsemi, you can download Libero SoC. For Lattice, you will need Diamond. For Achronix, you will need to contact them to download their ACE Software.
Note: On some versions of Linux you need to edit line ~210 of /opt/altera/16.0/modelsim_ase/vco and change “linux_rh60” to “linux”.
1.2. Quick Start Tutorial¶
To get started with LegUp HLS, we will create a pipelined FIR filter from C.
First launch LegUp from the start menu in Windows or by running
legup_hls from a terminal in Linux.
Once the IDE opens, select a workspace. The workspace is where your projects and related preferences will be saved. You may click on
Use this as the default and do not ask again, if you do not want to see the workspace prompt every time you start LegUp HLS.
Now to create a project, click
File -> New -> LegUp C project in the top menu. You may also click on the drop-down menu icon next to the
New icon on the top-left corner, then click on
LegUp C Project.
New Project window opens up, select the project name, and under
Select Project Type:, choose the second option,
Example LegUp Project: Filter (Function Pipelining). You may leave the
Location as default if you would like to save this project in your default workspace.
Next, and you will be asked to choose a target FPGA vendor and device, For this first example, we will use Intel’s
Arria 10 device. Then click on
Take a look at the source file
fir.cpp, which should automatically open up. It contains four functions,
main. These functions are also shown in the
Outline pane on the right-hand side.
Looking at the
main function, it first creates two FIFOs,
test_output_checker are called in a loop. The
test_input_injector function creates input values and writes them to the
FIRFilterStreaming reads from the
input_fifo, computes the filter output and writes it to the
test_output_checker reads from the
output_fifo and verifies, at the end of the computation, that the final value is correct.
Let’s first run this code in software. Click on the
Compile Software icon in the middle of the toolbar at the top. You may also click
File -> Compile Software in the top menu.
You should see in the
Console window at the bottom of the screen that the software compiled successfully.
Now, click on the
Run Software icon next to the compile icon. You should see in the
Console window that the total is the expected value of
913040 and hence, the result is a
You may also want to debug your software, and LegUp HLS has an integrated debugger, (
gdb), so that you can debug your code directly within the IDE. Click on the
Debug Software icon (next to the
Run Software icon). A prompt will appear, asking if you would like to switch to
Debug perspective. Click on
Yes and you should see that the view changes. Try clicking on the
Step Over icon on the top-left of the toolbar. As you step over the function calls of the loop in the
main function, you should see the outputs produced by the software execution appear in the
Console window. You may click on the
Resume icon to the left to let the debugger finish, or stop the debugger by clicking on the
Switch back to the previous perspective by clicking on the
C/C++ icon on the top-right corner of the toolbar.
The steps above have illustrated how to compile, debug and run software using LegUp HLS. We now turn our attention to synthesis of hardware from software. That is, we can now synthesize the same
C code into hardware.
Before we execute the hardware synthesis, we can apply some constraints to LegUp HLS that influence the synthesis process and the hardware modules that will be generated.
Click on the
HLS Constraints icon (to the right of
Debug Software icon). You may also click
LegUp HLS -> HLS Constraints on the top menu. You should see that there are some pre-set constraints for the FIR filter example project already. The constraints specify the
FIRFilterStreaming function to be pipelined and to be set as the top-level function. When a function is designated to be pipelined, it implies that the function’s hardware implementation will be able to receive new inputs at regular intervals, ideally every clock cycle. The target clock period is set to 10 ns, and the test bench module and file are set to
OK to exit the constraint window.
Let’s perform the hardware synthesis now.
Click on the
Compile Software to Hardware icon (to the left of the
HLS Constraints icon).
Console window, you should see that the hardware has been generated properly, and a
summary.legup.rpt file should automatically open up in the right panel of the IDE. You have just compiled your first C program into hardware with LegUp HLS!
Let’s examine the report file, which provides an overview of several aspects of the generated hardware. Looking at the
Scheduling Result, it shows that the
Cycle Latency is 4, meaning that it takes 4 cycles for an output to be produced from start to finish.
Looking at the
Pipeline Result, it also shows that the
Initiation Interval (II) is 1, meaning that the hardware is completely pipelined, so that new inputs can be injected into the hardware every clock cycle, and that a new output is produced every cycle. This implies that computations are overlapped (parallelized): as each new input is received, previous inputs are still being processed.
An II of 1 produces the highest throughput for a pipelined circuit.
Memory Usage section shows that there are a number of registers (which form a shift register), as well as the input/output FIFO queues.
Let’s now simulate this circuit’s Verilog RTL implementation. First, make sure you set the path to ModelSim by going to
LegUp HLS -> Tool Path Settings in the top menu.
While you are there, also set the path to Intel Quartus, which is needed to synthesize the hardware later.
Once they are set, click on the
Simulate Hardware icon (to the right of
Compile Software to Hardware icon).
You should see that ModelSim is running in the
Console window, and that it prints out a
Having simulated the Verilog and demonstrated functional correctness, let’s synthesize the circuit to get its maximum clock frequency (Fmax) and area when implemented on the Intel Arria 10 FPGA. Click on the
Synthesize Hardware to FPGA icon (to the right of
Simulate Hardware icon).
This launches Intel Quartus in the background and you can see the output in the
When it finishes running, you will see that the
summary.results.rpt file is automatically updated with new information which is extracted from the Intel synthesis reports.
The Fmax of this circuit is 125.58 MHz, and it consumes 393 ALMs and 682 registers on the Arria 10 FPGA.
You have learned how to compile, debug, and execute your software, then compile the software to hardware, simulate the hardware, and synthesize the hardware to an FPGA. Great work!
1.3. Using Example Projects¶
We provide a number of other examples to demonstrate LegUp’s features and optimization techniques.
Later sections in the user guide reference these examples, and we describe here how you can use them.
The examples are contained in
For Linux, the
/usr/lib/legup-8.0. For Windows, it is where you
specified in the installer during installation.
For each example, you will need to create a new LegUp project.
As described above, click on
File -> New -> LegUp C project to create a LegUp project.
Input a project name and choose
New LegUp Project as the project type, then click on
Now you can import our example source files into the project. The table below lists the sources files for each example.
|Example Name||C source file|
Import the appropriate source files for each project and click
Some examples may also come with a custom test bench file. When there is a custom test bench, you also need to specify the name of the test bench module as well as the top-level function of the C program. The table below lists the information about test benches and top-level functions for our example projects.
|Example Name||Top-Level Function||Test Bench Module||Test Bench Files|
Top-Level Function and
Test Bench Module and include the
Test Bench File as shown in the table, then click
If your example project is not specified in the table above, you may simply just click
Now you can choose the target
FPGA vendor and
FPGA device. For these examples, let’s choose Intel’s Arria 10 FPGA as the target.
When you click
Finish, your new example project will be created.
For some examples, you will need to set some constraints.
To set new constraints, click on
LegUp HLS -> HLS Constraints on the top menu to open the constraints window.
For the examples shown below, please make sure that you have the same constraints set.
If your example is not shown below, you do not have to set any constraints at the moment.
To set a new constraint, select the appropriate constraint from the
Constraint Type dropdown menu, enter its corresponding
Constraint Value, then click