Build your own CPU and tools for it like Assembler, High level language compiler, simple OS, then write Pong game on it using only open source software and hardware. Check nand2tetris-13 project with iCE40HX8K-EVB + MOD-LCD2.8RTP + IceStorm


Michael Schröder sent us link to his project nand2tetris-13 yesterday.

He managed to build his own CPU, to write Assembler, Jack high level language, OS and then write Fibonacci demo and Pong game. All this done on Open Source Hardware FPGA  board iCE40HX8K-EVB with MOD-LCD2.8RTP as display and FOSS tools IceStorm project. Keyboard is done by UART but my guess is that it could be easily implemented by iCE40-IO .

This is perfect project to teach students about so many things: Combinatory Logic, Sequential Logic, Computer Achitecture, Machine code to Assembler, High level language Compilers, simple OS and so on.

And the best here is that you can see this working on hardware not just boring lectures. Student can experiment with their own CPU and write applications like small games etc.

Use Raspberry PI as Iceprog programmer for iCE40HX1K-EVB or iCE40HX8K-EVB


Andreas Seltenreich sent us message how he is using Raspberry PI to program his iCE40HX1K-EVB and we add to the wiki section.

Hello World! with Verilog on iCE40HX1K-EVB with open source tool IceStorm


One of the workshops at TuxCon 2016 included using Open Source Hardware FPGA board iCE40HX1K-EVB and there we went through the development process with FPGA and Verilog.

For those of you who were unable to attend, we will now show you what you’ve missed. First, see the previous post about how to setup FPGA FOSS IceStorm tools here.

Now that the tools are set, let’s learn some more about FPGA. This is a very brief introduction and it is far from comprehensive, but the Internet has tons of resources you can use to learn more.

We will go through most asked questions on the workshop only:

What is FPGA ?

FPGA stands for Field Programmable Gate Array. They are digital integrated circuits (ICs) that contain configurable (programmable) blocks of logic along with configurable interconnections between these blocks. Design engineers can configure, or program, such devices to perform a variety of tasks.

How many times can one FPGA be programmed?

Some FPGAs may only be programmed a single time (they are called OTP) while others may be reprogrammed over and over again. For development boards we need the latter because when we develop we often make mistakes and we need to be able to program FPGAs multiple times. The FPGAs which can be programmed many times usually have external non-volatile memory. It contains the configuration file which is read at power up to the local RAM inside FPGA, and is used to define the interconnections between the blocks inside FPGA. So when you apply power to these FPGA they need some small amount of time to read their program and then start working.

When are FPGA used in one design?

FPGAs allow many tasks to be performed in parallel at very high speed. They are also highly integrated (some FPGAs have millions of programmable blocks), so you can complete complex hardware designs in a very small space. The trade off is that FPGA are programmed differently than the micro controllers (as you will see later), so they require a little bit more studying in order to get used to them.
If you application requires high speed, and complex parallel tasks, you need FPGA. Typical applications are: digital signal processing as video and audio filtering, the FPGA outperform fastest DSPs in factor of 500. Another applications are developing new digital ICs like processors or microcontrollers  with new architectures and instructions. FPGA are used also for physical layer communications, decoding and encoding high speed communication lines like HDMI, SATA, USB.
There is no sense to use FPGA in slow processes which can be done by microcontrollers, but they can be used to add fast peripherals to them. For example if you need very fast SPI to capture some fast serial signal, most of microcontrollers have SPIs which work up to 20-30Mhz clock, with FPGA you can make SPI which work on 100 Mhz or 200Mhz or 300Mhz and to buffer the data then to re-transmit slowly to the microcontroller who to do something with this data.
You can synthesize almost any digital circuit with FPGA, to make your own microprocessor with custom number of registers and instruction set, most of the companies which design microprocessors / microcontrollers first test their ideas on FPGAs.

How FPGAs are programmed (configured)?

Back in 1984 when the first FPGAs were made, design flows used for CPLD was taken and they were programmed by drawing schematics of digital circuits, then the CAD tool synthesized the schematic to FPGA configuration files which you can load to the FPGAs. This approach works well, but when the FPGAs become with thousands of logic cells and the schematics become more than several pages long the process become prone to errors exponentially with the size of the schematic. (Just imagine to draw internal schematic on modern processor with digital logic and then to test it).
At the end 1980s move toward HDL (hardware description languages) was made. Visualizing, capturing, debugging, understanding, and maintaining a design at the gate level of abstraction became increasingly difficult and inefficient when juggling thousands gates.
The lowest level of abstraction for a digital HDL is switch level, which describe the circuit as a netlist of transistor switches.
A higher level of abstraction is the gate level,which describe the circuit as a netlist of primitive logic gates and functions.
The next level of HDL abstraction is the ability to support functional representations using Boolean equations.
The highest level of abstraction sported by traditional HDLs is known as behavioral, which describe the behavior of a circuit using abstract constructs like loops and processes similar to programming language.

Verilog and IceStorm

Verilog is one such HDL behavior language, another one very popular in Europe is VHDL, but as FOSS FPGA tool for iCE40 IceStorm has support for only Verilog we will make all next demos in Verilog :).

Let have look at the first Blink LED project we programmed on iCE40HX1K-EVB in the previous blog post. It’s available on GitHub.

The Makefile

This is configuration file for the project which tells how IceStorm to compile it:

    PROJ = example


this is project name, it could be any other name, IceStorm will search for example.v source file and the result at the end will be example.bin which you can program to iCE40HX1K-EVB

    PIN_DEF = ice40hx1k-evb.pcf


this is external file which assigns the signals we will use in the project to the physical chip pin numbers, if we open it will see:

    set_io CLK 15
    set_io BUT1 41
    set_io BUT2 42
    set_io LED1 40
    set_io LED2 51


which means the 100 Mhz Oscillator clock is connected to pin15, button1 to pin41, LED1 to pin40 and so on.

    DEVICE = hx1k


this tells IceStorm which device is used, in this case device from HX series with 1K logic blocks

    yosys -p 'synth_ice40 -top top -blif $@' $<


invokes yosys to syntheses example.v Verilog sources ‘top’ is the name of the top module you could assume it as something like main() in C language.

    arachne-pnr -d $(subst hx,,$(subst lp,,$(DEVICE))) -o $@ -p $^ -P vq100


after yosys has synthesized the sources ‘arachne-pnr’ try to place and route them physically inside the chip, you can imagine these logic cells are as matrix and this tool have to decide how to arrange them so to make smaller distances between the connected cells and physical pins, and design to work at maximal possible speed. Look at -P vq100 switch it tells arachne-pnr what package is used for the device in our case VQ100 chip package.

    icepack $< $@


packs the text file output generated by arachne-pnr to .bin file read to be programmed in FPGA external Flash memory

icetime -d $(DEVICE) -mtr $@ $<


The icetime program is an iCE40 timing analysis tool. It reads designs in IceStorm ASCII format and writes times timing netlists that can be used in external timing analysers. It also includes a simple topological timing analyser that can be used to create timing reports.

    sudo iceprogduino $<


small program which uses OLIMEXINO-32U4 (Arduino Leonardo) with custom firmware as programmer for the iCE40HX1K-EVB SPI Flash


    module top( //top module


this describes the ‘top’ module in the code which will be synthesised, it will use some physical signals defined in ice40hx1k-evb.pcf

then we define what are these signals inputs or outputs:

    input CLK;    //input 100Mhz clock
    input BUT1;   //input signal from button 1
    input BUT2;   //input signal from button 2
    output LED1;  //output signal to LED1
    output LED2;  //output signal to LED2


with the keyword ‘reg’ we define registers i.e. analog of variables in programming language, but here these are with default width of 1 bit, in the registers we can store and read signals

    reg BUT1_r;           //register to keep button 1 state
    reg BUT2_r;           //register to keep button 2 state
    reg LED1_m0_r;        //LED1 value in mode = 0
    reg LED2_m0_r;        //LED2 value in mode = 0
    reg LED1_m1_r;        //LED1 value in mode = 1
    reg LED2_m1_r;        //LED2 value in mode = 1
    reg [14:0] cntr;      // 15 bit counter for LED blink timing
    reg [14:0] rst_cnt=0; // 15 bit counter for button debounce
    reg mode=1;           //mode set to 1 initially
    reg [11:0] clk_div;   // 12 bit counter


you can see that cntr and rst_cntr are with [14:0] in front of them, this means they are 15 bit long registers, clk_div is 12 bit

with the keyword wire you define internal signals which are additional to these defined in the top module

    wire clk_24KHz; //signal with approx 24KHz clock
    wire reset;     //used for button debounce

the keyword assign makes connection between signals, so every time right side signal changes the same change occur at the left side signal

    assign reset = rst_cnt[14]; //reset signal is connected to bit15 of rst_cnt
    assign LED1 = mode ? LED1_m1_r : LED1_m0_r; //multiplexer controlled  
                      //by mode connects LED1_m1_r or LED1_m0_r to LED1
    assign LED2 = mode ? LED2_m1_r : LED2_m0_r; //multiplexer controlled  
                      //by mode connects LED2_m1_r or LED2_m0_r to LED2
    assign clk_24KHz = clk_div[11];      //100Mhz/4096= 24414 Hz


in this case 15th bit of rst_cnt register is connected to signal reset, signal clk_24KHz is connected to 12th bit of clk_div register
LED1 and LED2 are connected via multiplexers (made with ? keyword) with control signal mode to two registers with suffix ‘m1’ and ‘m0’
so when mode is 0 LED1 will be connected to LED1_m0_r register and when mode is 1 to LED1_m1_r

always block is executed every time when something in his sensitivity list changes:

    always @ (posedge CLK) begin      //on each positive edge of 100Mhz clock increment clk_div
       clk_div <= clk_div + 12'b1;


in this case every time positive edge of CLK is happen i.e. CLK change from 0 to 1 it’s executed and adds 1 to clk_div

next always block is a bit more complex:

  always @ (posedge clk_24KHz) begin //on each positive edge of 24414Hz clock
     BUT1_r <= BUT1;       //capture button 1 state to BUT1_r
     BUT2_r <= BUT2;       //capture button 2 state to BUT2_r
     cntr <= cntr + 15'd1; //increment cntr LED blink counter
  if(reset == 1'b0) begin //if bit15 of rst_cnt is not set yet
     rst_cnt <= rst_cnt + 15'd1; //increment the counter rst_cnt

  if(BUT1_r == 1'b0 && BUT2_r == 1'b0 && reset == 1'b1) begin 
       //if bit15 of rst_cnt is set and both buttons are pressed
    mode <= mode ^ 1'b1; //toggle the mode
    rst_cnt <= 15'd0; //clear debounce rst_cnt
  LED1_m0_r <= ~BUT1_r; //copy inv state of button 1 to LED1_m0_r
  LED2_m0_r <= ~BUT2_r; //copy inv state of button 2 to LED2_m0_r
  if(cntr == 15'd12207) begin //when 0.5s pass
    LED1_m1_r <= 1'b0; //reset LED1_m1_r
    LED2_m1_r <= 1'b1; //set LED2_m1_r

  if(cntr > 15'd24414) begin //when 1.0s pass
    cntr <= 15'd0; //clear cntr
    LED1_m1_r <= 1'b1; //set LED1_m1_r
    LED2_m1_r <= 1'b0; //reset LED2_m1_r

what happens here? every time at positive edge of clk_24KHz :
in BUT1_r and BUT2_r is loaded the current state of the buttons,
cntr is incremented with 1, this is our LED blink frequency counter
clk_24KHz is not actually exactly 24KHz but 100 000 000 Hz / 4096 = 24414 Hz or 24.414KHz 🙂

when this cntr reach value 12207 i.e. half second pass LED1_m1_r is loaded with 0 and LED2_m1_r is loaded with 1
when this cntr reach value 24414 i.e. one second pass LED1_m1_r is loaded with 1 and LED2_m1_r is loaded with 0
i.e. if mode is 1 the LED1 and LED2 will blink each half second.

when the mode is 0 LED1_m0_r and LED2_m0_r will follow button states i.e. in this mode when you press button 1LED1 will be on and when you release button 1 LED1 will be off
same will be for LED2 too

Now let pay some more attention to what this code describes:

   if(reset == 1'b0) begin //if bit15 of rst_cnt is not set yet
     rst_cnt <= rst_cnt + 15'd1; //increment the counter rst_cnt

   if(BUT1_r == 1'b0 && BUT2_r == 1'b0 && reset == 1'b1) begin 
           //if bit15 of rst_cnt is set and both buttons are pressed
     mode <= mode ^ 1'b1;  //toggle the mode
     rst_cnt <= 15'd0;    //clear debounce rst_cnt

reset is signal connected to rst_cnt 15th bit, so until this bit is set rst_cnt will be incremented on every positive edge of clk_24KHz,
when reset is set to 1 if BUT1 and BUT2 are pressed together the mode is toggled and res_cnt is set to 0 to ensure some debounce time

you can download the project and make and program with these two lines:


    make prog

You will see first LED1 and LED2 to blink as default mode is 1. If you want to toggle the mode press and hold BUT1 and BUT2 and release them quickly.

LED1 and LED2 will switch off, in this mode if you press BUT1 will switch on LED1 and if you press BUT2 will switch on LED2, if you press the both buttons together mode will change again to 1 and LED1 and LED2 will start blinking.

Your first program is done!

Now let see what will happen if we change line 48 from

   mode <= mode ^ 1'b1; //toggle the mode


   model <= mode ^ 1'b1; //toggle the mode

i.e. we made mistake and instead of mode wrote model what do you think will be there error message when synthesis is done?

You can try! Whaaaat? everything completes correctly and you get your example.bin ready for program. What happens when we run it? Right! The LED1 and LED2 blinks and you can’t change the mode by pressing BUT1 and BUT2 together anymore!

OMG how this happens? Welcome to the wonderful world of Verilog 🙂 If you do not define but use new signal Verilog silently creates it and just issue WARNING not error, in this case the warning is in the very beginning of the 1233 lines of messages you see printed while the source is synthesized:

    Parsing Verilog input from `example.v' to AST representation.
    Generating RTLIL representation for module `\top'.
    Warning: Identifier `\model' is implicitly declared at example.v:48.
    Successfully finished Verilog frontend.


This feature may make you bang your head to the wall searching for errors and can’t happen in VHDL, where everything have to be strictly defined before to be used.

VHDL vs Verilog is like old C vs Pascal choice. In C you can do lot of things to shoot yourself in the leg and the compiler will not stop you.


In the next FPGA blog post we will go deeper and will show you how to generate VGA video signals with iCE40HX1-EVB + iCE40-IO boards and how to move object on the screen with the arrow keys of PS2 keyboard.

And we will not stop here, we are preparing more tutorials with iCE40HX1-EVBiCE40-IO – video games Snake and Flappy bird. Then latter we will teach you how to build Digital Storage Oscilloscope with iCE40HX1-EVB + iCE40-IO+ iCE40-ADC , how to make Digital Logic Analyzer with  iCE40HX1-EVB +iCE40-DIO for sniffing protocols from devices operating from 1.65 to 5.5V levels and how to make DDS generator of signals with any forms using iCE40HX1-EVB + iCE40-DAC.


EDIT: As I wrote we learn this stuff too! Regarding the implicit declarations they may be disabled by adding on top of your code:

    `default_nettype none


I just try this and yosys stops with error when I mistype ‘mode’ with ‘model’:

Parsing Verilog input from `example.v' to AST representation.
Generating RTLIL representation for module `\top'.
ERROR: Identifier `\model' is implicitly declared at example.v:50 and `default_nettype is set to none.
Makefile:8: recipe for target 'example.blif' failed
make: *** [example.blif] Error 1

Getting started with FPGA with only Free and Open source software and hardware tools tutorial


iCE40 is the first FPGA family with completely Free and Open source software tools thanks to Clifford Wolf who put incredible amount of time to create tool which compiles Verilog code to iCE40 bitstream by reverse engineering the output of the closed source Lattice tools.

As soon as we saw his presentation at FOSDEM we decided that we should make iCE40 FPGA board to use with his IceStorm tools.

The result is iCE40HX1K-EVB completely open source hardware board with all CAD files on GitHub. Which could be programmed with IceStorm!

Clifford built his tool to work with the Lattice stick, there they use FTDI chip to program the board, something we do not like at all 🙂

In the next tutorials we will teach you how you can program iCE40HX1K-EVB with any other board or processor which have SPI, but we will start with Arduino-Leonardo or our equivalent OLIMEXINO-32U4.

OLIMEXINO-32U4 is also OSHW board and all CADs are available, Arduino IDE is also FOSS.

What you will need to follow this tutorial:

  • iCE40HX1K-EVB this is the core board with the FPGA, some buttons, LEDs, SRAM memory which will be very useful for the more advanced demos like VGA video generator, Oscilloscope with fast ADC etc which will follow
  • OLIMEXINO-32U4 which will act as programmer instead of FTDI, instead this board you can use any Arduino or other board just have to wire the SPI signals to the iCE40HX1K-EVB programming connector, in this caseOLIMEXINO-32U4 UEXT connector is used and we connect it with 10 pin ribbon cable to iCE40HX1K-EVB
  • CABLE-IDC10-15cm  to connect between boards 1. and 2.
  • USB-MINI-CABLE to connect OLIMEXINO-32U4 to your host computer where you will install Clifford’s IceStorm and will build your verilog code.
  • SY0605E  power supply 5V adapter for iCE40HX1K-EVB
  • optional but highly recommended USB-ISO – after burning several USB ports on laptops and desktops while playing with development boards now I’m very careful and do not connect anything directly, its very easy to drop tweezers or wire or drop of solder on top of the development board while it’s connected to your computer and the result is USB damage and expensive repair.USB-ISO saves all these troubles and isolate your precious computer from problems with shorts, over voltages etc.

Installing IceStorm

We will install IceStorm from sources so first we have to make sure we have all tools to build it:

    sudo apt-get install build-essential clang bison flex libreadline-dev \
     gawk tcl-dev libffi-dev git mercurial graphviz \
     xdot pkg-config python python3 libftdi-dev


Installing the IceStorm Tools (icepack, icebox, iceprog, icetime, chip databases):

    git clone icestorm
    cd icestorm
    make -j$(nproc)
    sudo make install


Installing Arachne-PNR (the place&route tool):

    git clone arachne-pnr
    cd arachne-pnr
    make -j$(nproc)
    sudo make install


Installing Yosys (Verilog synthesis):

    git clone yosys
    cd yosys
    make -j$(nproc)
    sudo make install

If everything completes with no errors – congratulations you successfully installed the IceStorm!

Preparing OLIMEXINO-32U4 as programmer

Now we have to prepare OLIMEXINO-32U4  as our FPGA programmer.

Download latest Arduino IDE . We recommend you to use the one from current revision is 1.6.9.

Copy iceprog.ino sketch from GitHub to examples folder.

Plug the USB cable to OLIMEXINO-32U4 and start the Arduino IDE

    cd arduino-1.6.9
    sudo ./arduino

From Tools menu select ‘Arduino Leonardo’ as board.

From the same menu select the PORT where the board is attached it will be something like: ‘/dev/ttyACM0 (Arduino Leonardo)’ or ‘/dev/ttyUSB0 (Arduino Leonardo)’

Open the iceprog.ino sketch.

From menu SketchInclude libraryManage libraries check if you have SPI and SPIFlash libraries installed if not install them.

Compile and Upload the sketch.

If everything complete without error now you have OLIMEXINO-32U4 set as iCE40HX1K-EVB programmer!

Add support for OLIMEXINO-32U4 in IceStorm

Copy iceprogduino folder from GitHub to icestorm folder and build it

    cd icestorm/iceprogduino
    make install

Make your first program for FPGA – blink LED

Copy demo code from GitHub to icestorm/examples

    cd icestorm/examples/ice40hx1k-evb
    make prog

If everything finish with no error you will see LED1 and LED2 blinking on iCE40HX1K-EVB.

Congratulations! You made blinking LED on FPGA!

Now check what is the content of example.v , ice40hx1k-evb.pcf and Makefile and learn why the LEDs blink and what happen when you press together BUT1 and BUT2?

Next tutorial will be how to use iCE40HX1K-EVB with A20-OLinuXino-MICRO as both host for the IceStorm tool and programmer via UEXT connector with just cable and what additional options it gives like loading the code directly to FPGA whthout using SPI flash and your can change FPGA code in milliseconds.