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 or Ubuntu 16.04.

1.1. Installation

1.1.1. Windows

Run the Windows installer program, LegUp-5.1-Win64-Setup.exe.

The first time you simulate with Modelsim, this will take a few minutes as we compile our hardware simulation libraries with Modelsim.

1.1.2. Linux

Download the Linux installer file and double-click on it. When the installer opens up, click Install.

You may also install it in command line:

sudo dpkg -i legup-5.1-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-5.1/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.

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.

_images/eclipse_workspace.png

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.

_images/new_project.png

Once the 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.

_images/fir_filter_project_creation_small.png

Click Next, and you will be asked to choose a target FPGA vendor and device, For this first example, we will use Intel’s Cyclone V device. Then click on Finish.

_images/fir_filter_choose_fpga_small.png

Take a look at the source file fir.c, which should automatically open up. It contains four functions, FIRFilterStreaming, test_input_injector, test_output_checker, and 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, input_fifo and output_fifo, with calls to fifo_malloc, which is part of the FIFO library that is provided with LegUp HLS. Then, test_input_injector, FIRFilterStreaming, and test_output_checker are called in a loop. The test_input_injector function creates input values and writes them to the input_fifo. FIRFilterStreaming reads from the input_fifo, computes the filter output and writes it to the output_fifo. Finally, test_output_checker reads from the output_fifo and verifies, at the end of the computation, that the final value is correct.

_images/fir_source_code.png

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.

_images/fir_software_compile.png

You should see in the Console window at the bottom of the screen that the software compiled successfully.

_images/fir_software_compile_console.png

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

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 Terminate icon.

_images/fir_software_debug.png

Switch back to the previous perspective by clicking on the C/C++ icon on the top-right corner of the toolbar.

_images/C_perspective.png

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 streaming_tb and streaming_tb.v. Click OK to exit the constraint window.

_images/fir_hls_constraints.png

Let’s perform the hardware synthesis now. Click on the Compile Software to Hardware icon (to the left of the HLS Constraints icon). In the 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!

_images/fir_hardware_compile.png

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. The 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 PASS.

_images/fir_hardware_sim.png

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 Cyclone V 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 Console window. 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 Cyclone V FPGA.

_images/fir_hardware_synthesis.png

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 LEGUP_INSTALLATION_DIRECTORY/legup/examples/user_guide_examples. For Linux, the LEGUP_INSTALLATION_DIRECTORY is /usr/lib/legup-5.1. 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 Next.

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
FIR_function_pipelining_wrapper fir.c
loop_pipelining_simple loop_pipelining_simple.c
multi_threading_simple multi_threading_simple.c, array_init.h
openmp_reduction openmp_reduction.c, array_init.h

Import the appropriate source files for each project and click Next.

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
FIR_function_pipelining_wrapper pipeline_wrapper streaming_tb streaming_tb.v

Specify the Top-Level Function and Test Bench Module and include the Test Bench File as shown in the table, then click Next. If your example project is not specified in the table above, you may simply just click Next.

Now you can choose the target FPGA vendor and FPGA device. For these examples, let’s choose Intel’s Cyclone V 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 Add.

FIR_function_pipelining_wrapper:

_images/FIR_function_pipelining_wrapper_constraints.png

openmp_reduction:

_images/openmp_reduction_constraints.png