Tutorial: FPGA Programming

This tutorial shows how to do basic FPGA programming with Cloud V.

Currently, the following FPGA boards are supported:

• Lattice iCEStick Evaluation Kit
• Lattice iCE40-HX8K Breakout Board
• NANDLand GoBoard (Untested)
• Olimex iCE40HX1K-EVB (Untested)

Cloud V runs the open source icestorm toolchain under the hood.

Setting up your project

To synthesize an FPGA bitstream on Cloud V, you need:

• A valid Verilog top module
• A pin constraints file

Creating the Verilog top module

In the Workspace, create a new Verilog module and set it as a top module by right clicking your module from the drop down list in the Verilog file:

Here is the code for the example top module shown here:

module LightUp (clk, ledArray);
    input clk;
    output [7:0] ledArray;
    reg [31:0] counter = 32'b0;

    assign ledArray[7:0] = counter[25:18];
    
    always @ (posedge clk) begin
        counter <= counter + 1;
    end
endmodule

Luckily, icestorm supports initialization in the manner shown above, so there is no need for a reset signal. You can also use an initial begin block if that's your cup of tea.

Next, you need to create a pin constraints file. You need a pinout of the board for this:

• For the iCEStick, the lovely people over at pighixxx.com have already mapped a pinout here. DO NOT USE ANY PINS MARKED WITH "FTDI" UNLESS YOU ARE ABSOLUTELY SURE OF WHAT YOU ARE DOING OR YOU MAY RENDER THE DEVICE INOPERABLE.
• For the Breakout Board, conveniently, the names on the board are the names you want! The LEDs, however, do share pins with the GPIO (from left to right): B5, B4, A2, A1, C5, C4, B3, C3. Oh, and the clock is at J3.

Creating the file is straightforward. First you pick your board...

...then you specify the pins.

And voila. Your project is ready.

Generating a Bitstream

From the top menu, Project > Generate Bitstream.

From here, you can pick a constraints file (you could have multiple per project for multiple boards or whatever the case may be) and just press generate.

In the "build (read-only)" folder of your repository, a file called <TopModule>.bin should have been generated. Right click it and download it.

Programming

There are a couple ways you could go about programming the FPGA. Programming is not integrated into Cloud V as that would require a native browser extension of some kind that may introduce security issues, but there are a lot of offline tools.

The first is Lattice iCECube 2 but apparently it is not the most well-documented piece of software and it is still a pain to install, which rules it out as the favourable option for Cloud V.

The second is iceprog. A part of icestorm, iceprog is the metaphorical last piece of the puzzle in the toolchain. You will need iceprog installed locally on your machine, which is a terminal-based tool.

To program with iceprog, in the terminal, connect your FPGA board and:

   #For SPI Flash Programming
   iceprog <TopModule>.bin
   #For SRAM Programming (Not available on all boards)
   iceprog -S <TopModule>.bin

The last is Malice. This is a GUI frontend for iceprog that was developed by one of the Cloud V researchers that makes things a little more friendly and puts up appropriate warnings/configuration instructions for the FPGA boards. Currently, it's available for Linux and is in alpha for macOS. Windows should be coming soon enough.

1, 2 - Device Status

Shows whether the device is detected or not. If it is detected, you may proceed to pick a board. If not, you user may have to re-plug in your FPGA and use ② to refresh the status.

3 - Board Picker

Allows you to pick your board. This does not affect any settings, but rather, limits your options to what is possible with the board and displays info for said board that you may need to know.

4 - Bitstream Picker

This is where you pick the bitstream you downloaded earlier.

5 - SPI Flash Program Option

On some boards, like the Breakout Board you may be able to pick between direct SRAM-based FPGA programming and SPI Flash programming. Some, like the iCEStick Evaluation Kit, only support one option (in this case, SPI Flash only). Generally, it is recommended to use direct SRAM-based FPGA programming whenever possible as a faulty flash program may render a device inoperable.

6 - Program Button

When every other option is set, just press this button and the program will be downloaded onto the FPGA.

7 - Notes

This shows you some notes of intrigue on the board you have picked: warnings, jumper configurations, the like.

Just connect your board, pick it from the drop down menu, pick the bitstream file, press program and you should be good to go.