FPGA Brook Compiler

Table of Contents

Introduction

FPGA Brook Compiler is a compilation system for implementation of streaming programs written in the FPGA Brook streaming language in Field Programmable Gate Arrays.
FPGA Brook is a streaming language based on the Brook and GPU Brook languages developed at Stanford University.

At the heart of the FPGA Brook compilation system is a source-to-source compiler that converts FPGA Brook code into C code suitable for behavioral compilation. The output C code typically consists of multiple C functions suitable for parallel hardware implementation. The compiler also produces Verilog code for modules interconnecting hardware units implementing C functions, and full description of the SOPC (System On Programmable Chip).

FPGA Brook streaming language allows the programmer to expose data and task level parallelism in the application. This is achieved in an abstract fashion from the programmer's point of view, but is at the same time sufficiently explicit for the compiler to be able to take advantage of this parallelism when targeting FPGA hardware.
Currently, the system supports Altera C2H back-end. That is, the output of the FPGA Brook source-to-source compiler is compiled using C2H compiler, and then synthesized using Quartus II to produce programming file that can be downloaded to an FPGA. The compiler comes pre-configured with a system that targets Altera's DE2 FPGA board Design flow could also be adapted to use other behavioral synthesis compilers and target other FPGA boards.
Typical compilation flow is shown in Figure 1.



Figure 1. FPGA Brook Compilation Flow

To learn more about FPGA Brook, please consult the following publications:
  1. F. Plavec, Z. Vranesic, S. Brown, "Enhancements to FPGA Design Methodology Using Streaming", In Proceedings of the International Conference on Field Programmable Logic and Applications (FPL '09), Prague, Czech Republic, 2009.
  2. F. Plavec, "Stream Computing on FPGAs", Ph.D. thesis, University of Toronto, 2010.

Legal Disclaimers

IMPORTANT!
FPGA Brook Compiler packages include some files that are normally distributed with free versions of Altera's Quartus II version 7.2 and Nios II EDS version 7.2.
These files are provided courtesy of Altera Corporation, with an understanding that the files are provided "as is", without any warranty or support from Altera.
By downloading these files, you agree to abide by all the licensing and other agreements with Altera Corporation, in the same manner you would if you downloaded the files directly from Altera.
FPGA Brook compiler is neither associated with, nor supported by Altera Corporation!

Other files in the packages are distributed under the terms of the GNU General Public License Version 1 or later, as specified inside the packages.
Since FPGA Brook builds on GPU Brook, which was in turn built using CTool Library, Copyrights for some parts of the package are retained by their respective owners, as specified by the Copyright notices inside the appropriate files.


FPGA Brook Compiler Installation Instructions

FPGA Brook Compiler can be downloaded as source code or Windows executable binary.
In addition, a collection of FPGA Brook programs that were used for development and testing of the compiler, known as the FPGA Brook benchmark set, is available for download as well.

Each application is provided in its base version (e.g. autocor.br) and one or more versions that use kernel replication (e.g. autocor_2.br, autocor_4.br, autocor_8.br, autocor_16.br).
The only difference between different versions is use of the br2c_speed_up pragma statement that specifies desired speedup of kernels comprising the application.

Prerequisites

Several tools have to be present on the computer system to compile the output of the FPGA Brook compiler and implement programs in an FPGA.
It is highly recommended to install all the tools into default folders, to reduce a chance of conflicts.
Altera's tools (version 7.2) should be installed into a folder whose full path does NOT contain any spaces, otherwise the C2H compiler will not work correctly!

Install the following tools:
  1. Quartus II 7.2, which can be downloaded from Altera here.
  2. MegaCore IP Library 7.2, which can be downloaded from Altera here.
  3. Nios II EDS 7.2 (includes the C2H compiler), which can be downloaded from Altera here.
  4. BR2C Compiler (see download section below).
  5. Microsoft Visual C++ 2010 Express (Optional), which can be downloaded from Microsoft here. This package is free, but requires you to register to use it beyond the trial period. Registration is also free.
    Only required if you want to modify and compile the FPGA Brook compiler source-code.
  6. Latest version of Cygwin for your platform, which can be downloaded from Cygwin project here.
    Only required if you are installing the tools on 64-bit version of Windows.
    Also required if you want to modify and compile the FPGA Brook compiler source-code. In such a case, make sure to select Development packages to be installed (they are not selected by default).
Once all the tools are installed, configure them as follows:
  1. Go to the folder C:\altera\72\ip\sopc_builder_ip\ (assuming all the tools were installed into their default folders) and create a folder with the name "brcc_components".
  2. Next, update the environment variable called "SOPC_BUILDER_PATH" (In Windows, go to Control Panel->System->Advanced->Environment Variables).
    This variable defines path to various folders that contain IP components. Individual entries are delimited using the "+" character.
    Add path to the "brcc_components" folder that was created in the previous step to this environment variable. To do this, add the following to the beginning of the "Variable value" field:
    "C:\altera\72\ip\sopc_builder_ip\brcc_components+" (omit quotations, but make sure to include the "+" character. The variable value should now look something like this:
    C:\altera\72\ip\sopc_builder_ip\brcc_components+C:\altera\72...

Licensing Altera Software

For licensing options, please consult Altera's licensing center.

Additional Instructions for 64-bit Windows

Quartus II 7.2 comes with Cygwin version that does not operate correctly on 64-bit Windows versions. The following steps can be used to circumvent most problems related to this:
  1. Download and install the latest version of Cygwin for your version of Windows (see point 6. under prerequisites above)
  2. Go to C:\altera\72\quartus\bin (assuming you installed Quartus into the default folder) and rename folder cygwin into cygwin.backup.
  3. Copy complete cygwin folder that you installed in step 1 into C:\altera\72\quartus\bin.
  4. Latest Cygwin release requires that all shell scripts use Unix-style newlines (\n), but various Nios scripts use Windows-style newlines (\n\r). To compensate for this, edit the file C:\altera\72\nios2eds\Nios II Command Shell.bat and replace the line:
    @ "%QUARTUS_ROOTDIR%\bin\cygwin\bin\bash.exe" --rcfile "%SOPC_KIT_NIOS2%\nios2_sdk_shell_bashrc"
    with 
    @ "%QUARTUS_ROOTDIR%\bin\cygwin\bin\bash.exe" --rcfile "%SOPC_KIT_NIOS2%\nios2_sdk_shell_bashrc" -o igncr
    The -o igncr switch tells the shell to ignore the Windows-style newlines.
  5. Unfortunately, because of the way various shell scripts are called from within other shell scripts, it may also be necessary to convert all such scripts from using Windows-style newlines to using Unix-style newlines.
    This can be achieved using d2u utility that ships with Cygwin. The following shell script performs this operation in batch mode on all the shell scripts in the Nios installation folder: d2u_batch.sh
    The script needs to be run from a Cygwin shell. Please note that depending on how this file is downloaded, you may first have to run d2u on the d2u_batch script itself. Also, the script needs to be customized in case Altera tools were not installed into default folders.


FPGA Brook Compiler Download

To install FPGA Brook compiler, simply download and unzip one of the following packages (while preserving the folder structure) into a folder on your disk, whose path does not contain any spaces.


Using the FPGA Brook Design Flow

FPGA Brook compiler package is preconfigured to be used with Altera's DE2 FPGA board. After writing a program in FPGA Brook, follow these steps to implement it on the DE2 FPGA board:
  1. Save your FPGA Brook source file into the folder where you unzipped the BR2C compiler. If you want to compile one of the FPGA Brook benchmarks instead, you will find them in this folder already.
  2. Open the Nios II Command Shell (Start->Programs->Altera->Nios II EDS 7.2->Nios II 7.2 Command Shell). Nios II command shell is based on the Cygwin program, which is a Unix-like shell environment for Windows.
  3. Enter the folder where you unzipped the BR2C compiler (e.g. cd C:\br2c)
  4. Review the file CONFIGURATION.cfg to see if any parameters require customization. If you installed all tools into their default folders, no customization should be needed.
  5. Compile your code using the BR2C source-to-source compiler. The compiler takes only one argument, which is the name of the FPGA Brook source file (e.g. ./br2c.exe autocor.br The compiler may produce some warnings about division operator. for details, see below .
    The compiler produces a folder named <sourcename>_sopc_system (e.g. autocor_sopc_system). This folder contains all the files needed for Quartus II to generate the complete system implementing your application.
    This includes a basic Quartus project, which contains the basic computer system with Nios II, and a few peripherals used to interact with the system.
    The compiler also produces two .dot files: <sourcename>.dot and <sourcename>_replicated.dot. The two files contain streaming dataflow graphs before and after replication.
    The graphs are expressed in the dot language, suitable for graphing using Graphviz, which is an open source graph visualization software.
  6. Enter the folder <sourcename>_sopc_system (e.g. cd autocor_sopc_system/software/app/)
    This folder contains a C file, which is the C representation of the original Brook program, suitable for C2H compilation.
    The folder also contains a script called create-this-app, which runs all other tools necessary to build the project.
  7. Run the script, by simply issuing the command: ./create-this-app
    This step may take some time (10-20 minutes), depending on your computer speed and available memory. If everything went smoothly, you should reach a stage where you will see the following message in the terminal window: 
            To download and run the application:
        1. Make sure the board is connected to the system.
    As the message indicates, you will need a DE2 board powered-up and connected to the USB port of your computer to proceed.
  8. Configure the FPGA with the hardware configuration (i.e. processor and hardware units implementing the original Brook application). To do this, you can use the following command:
    nios2-configure-sof ../../NiosII_cycloneII_2c35_standard.sof
  9. Next, open another Nios II command shell by repeating step 2 of these instructions
    This shell will serve as a terminal window, where we can see the output that the program prints. In the new window, issue the following command: nios2-terminal
    This establishes a serial connection with the board, so that output of the program can be observed.
    ATTENTION: This terminal uses the same USB cable that was used to download hardware configuration in the previous step. Before configuring the FPGA with a new system (for example after compiling a new application, or after recompiling an existing application), you have to quit this terminal window (by pressing CTRL-C), otherwise the nios2-configure-sof command will fail (it will produce an error message if this happens, but the error message is not very obvious).
  10. Now that the hardware system is in place, we have to download software that will be running on the Nios II processor. Switch back to the original Nios II command shell (the one where all the previous compilation steps were performed) and use the following command to download software:
    make download-elf
    After a few seconds, the program should be downloaded and you should see its output in the terminal window.
    If you compiled the autocor.br benchmark, the output should indicate that The two implementation produce results that are equivalent, and the running times of the software version (autocorrelation running on the Nios II soft-core processor), and the hardware version (Brook application implemented in hardware) should be approximately the same for this implementation.


Compiling FPGA Brook source code

If you wish to modify and compile FPGA Brook source code, you will have to have the latest version of Cygwin (see point 6. under prerequisites above) installed, including the Development packages.
Also, you will require Microsoft Visual C++ (see point 5. under prerequisites above).
To compile the source code, open the Visual Studio Command Prompt, and issue the following commands:
  1. Type SET PATH=%PATH%;C:\cygwin\bin\; (assuming you installed Cygwin into its default location (C:\cygwin)
  2. Enter the folder where you unzipped the BR2C compiler (e.g. cd C:\br2c)
  3. Type make
This should compile all necessary files and produce binary br2c.exe. In case you add new files to be compiled, you may have to update the Makefile to include the new files in compilation.

Compiler Limitations

FPGA Brook compiler was developed as part of a research project in high-level compilation flows for FPGAs. As such it implements features that were required to support the research project. As a result, the compiler has a number of limitations, some of which are outlined here:

FPGA Brook compiler is distributed under the terms of the GNU General Public License.
This means that the code comes WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Bug reports are welcome, but there is NO SUPPORT GUARANTEED.
Comments and bug reports should be sent to: plavec@eecg.toronto.edu,
with subject line "FPGA Brook Comment/Bug Report".
Back to my homepage.