## FPGA Brook Compiler

### Table of Contents

- Introduction
- Legal Disclaimers
- FPGA Brook Compiler Installation Instructions

- Prerequisites
- Licensing Altera Software
- Additional Instructions for 64-bit Windows

- FPGA Brook Compiler Download
- Using the FPGA Brook Design Flow
- Compiling FPGA Brook source code
- Compiler Limitations

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

- FPGA Brook Compiler binary package can be downloaded here. By downloading this file, you confirm that you have read and agreed with Legal Disclaimers above.
- FGPA Brook compiler source-code can be downloaded here. By downloading this file, you confirm that you have read and agreed with Legal Disclaimers above
- FGPA Brook Benchmark Set (which is already included in both packages above) can be downloaded separately here.

### 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:

- Only integer streams are supported. This is a hard limitation, because the downstream C2H compiler does not support floating-point data. If you need to represent non-integers, you will have to use fixed-point representation.
- Only 1-D and 2-D streams are supported.
- Stream operators are not supported. streamRead and streamWrite are also considered operators and have not been implemented implicitly. If you need them, it is easy to implement them using "streamRead type" and "streamWrite type" kernels (see FPGA Brook benchmarks for examples).
- Division and modulo operations are not efficiently implemented in hardware, so the BR2C compiler produces a warning if either of these two operators are used. This is only a problem if one of these operators is used inside of a kernel, because only kernels get implemented in hardware. However, the compiler produces a warning if either of these operators is found anywhere in the code.
  You can ignore the warning if the modulo or division operation is only used outside kernels.
  Important exception: It is acceptable to use modulo and division operators on the result of the indexof operator. Compiler handles these operators as special cases and implements division and modulo operations on them efficiently.
- Stream sizes have to be static, i.e. constant at run-time.
- When using #define directives, only simple directives are supported. For instance:

            #define SIZE 100

  is OK, but

            #define DOUBLE_SIZE 2*SIZE

  is not OK. Instead, you should write

            #define DOUBLE_SIZE 200

- Any kernels defined in the application can only be called from one place in the code. If you need to call the same kernel from two different places, please copy the kernel code, and give it a new name (e.g. if you have a kernel my_kernel that needs to be called at two different spots in the main program, you should copy its code, rename it in the copy to my_kernel_2 and call my_kernel from one place, and my_kernel_2 from the other place).
- All code should be placed into one file with .br extension.
- Kernel code should not contain calls to other kernels or functions.

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.