iCE40 FPGA Toolchain on Linux

Published 11 Nov 2020 · Updated 01 Feb 2022

Since I tested FPGA development tools on Ubuntu 20.04, there have been requests for more posts on FPGA tooling. In this post, I provide a quick guide to building an open-source FPGA toolchain for iCE40 boards, such as iCEBreaker. I plan to cover ECP5 FPGAs in a future version.

This guide is designed for Ubuntu or Pop!_OS 20.04, but should be straightforward to adjust to your own distro. These instructions will work on Windows Subsystem for Linux (WSL), but there’s no USB support in WSL, so you can’t program boards under WSL.

If you prefer pre-built tools, then OSS CAD Suite has binaries for Linux, Mac, and Windows.

Checklist

We’ll be installing:

Build Prerequisites - what we need before we begin
IceStorm Tools - create bitstreams file and programs boards
nextpnr - portable place and route
iVerilog - Verilog simulation and synthesis tool (optional)
Yosys - Verilog RTL synthesis
Verilator - Verilog simulation and linting (optional)

We’ll also demonstrate a simple iCE40 makefile for building a Verilog project with the iCEBreaker board.

Build Prerequisites

Make sure we’ve got git and curl installed to retrieve source code:

apt install curl git

Install build prerequisites (covers all tools included in this guide):

apt install build-essential clang bison flex gperf libfl2 \
    libfl-dev libreadline-dev gawk tcl-dev libffi-dev \
    graphviz xdot pkg-config python python3 libftdi-dev \
    qt5-default python3-dev libboost-all-dev cmake libeigen3-dev

Create a directory for building in; I’m going to use ~/src/fpga-toolchain:

mkdir -p ~/src/fpga-toolchain

IceStorm Tools

IceStorm tools create and analyse bitstream files for iCE40 FPGAs as well as programming boards. Learn more from Project IceStorm.

Make sure you’ve installed prerequisites then run the following:

cd ~/src/fpga-toolchain

git clone https://github.com/YosysHQ/icestorm.git icestorm

cd icestorm
make -j$(nproc)
make install

If you want to allow non-root users to program boards with iceprog, then add the following entry to: /etc/udev/rules.d/53-lattice-ftdi.rules:

ACTION=="add", ATTR{idVendor}=="0403", ATTR{idProduct}=="6010", MODE:="666"

nproc
The nproc command returns the number of available processing units in the system. For modern x86 CPUs, this is usually twice the number of physical cores due to hyperthreading. Telling make to use all the processing units may make your system sluggish.

nextpnr

nextpnr is a portable FPGA place and route tool that supports iCE40 and ECP5 (with Xilinx support in the works). Learn more from nextpnr GitHub.

Make sure you’ve installed prerequisites then run the following:

cd ~/src/fpga-toolchain

git clone https://github.com/YosysHQ/nextpnr nextpnr

cd nextpnr
git submodule init && git submodule update
cmake . -DARCH=ice40 -DCMAKE_INSTALL_PREFIX=/usr/local
make -j$(nproc)
make install

If you get an error of the form files in icebox are missing: /usr/local/share/icebox/timings_lp384.txt then you need to install IceStorm Tools (see above), before building nextpnr.

If you get a cmake error, such as undefined reference to pthread_create, then you need to make sure you’ve updated the git submodules.

iVerilog

Icarus Verilog is a Verilog simulation and synthesis tool. The Yosys test suite requires iVerilog, so you need to install it to test Yosys, but it isn’t needed to build iCE40 designs. Learn more from the Icarus Verilog site.

For this tool, we build the latest stable release, rather than cloning from git. If you wish to use the git version, it’s available from git://github.com/steveicarus/iverilog.git.

Make sure you’ve installed prerequisites, then run the following:

cd ~/src/fpga-toolchain

curl -O ftp://ftp.icarus.com/pub/eda/verilog/v11/verilog-11.0.tar.gz
tar xvzf verilog-11.0.tar.gz

cd verilog-11.0
sh autoconf.sh
./configure
make -j$(nproc)
make install

For more options see the Icarus Verilog Installation Guide.

Yosys

Yosys does Verilog RTL synthesis. You can run the test suite if you install iVerilog. Learn more from the Yosys site.

Make sure you’ve installed prerequisites, then run the following:

cd ~/src/fpga-toolchain

git clone https://github.com/YosysHQ/yosys yosys

cd yosys
make -j$(nproc)
make test  # optional (requires iVerilog)
make install

Verilator

Verilator is a fast Verilog simulation tool that includes comprehensive linting. Verilator isn’t required to build iCE40 designs, but linting and graphics simulation are great ways to test your designs. Learn more at the official Verilator site.

Make sure you’ve installed prerequisites, then run the following:

cd ~/src/fpga-toolchain

git clone https://github.com/verilator/verilator

cd verilator
git checkout stable
autoconf
./configure
make -j$(nproc)
make test  # optional
make install

iCE40 Makefile

Building your designs using this toolchain is a multi-stage process; having a makefile makes it much more convienient. The following sample makefile should get you off to a good start.

If you’re not using the iCEBreaker with iCE40UP5K FPGA, you need to change the following:

FPGA_PKG - the FPGA IC package (sg48 for iCEBreaker)
FPGA_TYPE - the FPGA device type (up5k for iCEBreaker)

You should also update the following for your design:

icebreaker.pcf is the physical constraints file, which contains pin mappings
module_1.v and module_2.v are example modules required by top_foo.v and top_bar.v
If using SystemVerilog, change the .v extensions to .sv.

# Example iCEBreaker Makefile
# Learn more at https://projectf.io/posts/building-ice40-fpga-toolchain/

# configuration
SHELL = /bin/sh
FPGA_PKG = sg48
FPGA_TYPE = up5k
PCF = icebreaker.pcf

# included modules
ADD_SRC = module_1.v module_2.v

top_foo: top_foo.rpt top_foo.bin
top_bar: top_bar.rpt top_bar.bin

%.json: %.sv $(ADD_SRC)
	yosys -ql $(basename $@)-yosys.log -p \
	    'synth_ice40 -top $(basename $@) -json $@' $< $(ADD_SRC)

%.asc: %.json
	nextpnr-ice40 --${FPGA_TYPE} --package ${FPGA_PKG} --json $< --pcf ${PCF} --asc $@

%.rpt: %.asc
	icetime -d ${FPGA_TYPE} -mtr $@ $<

%.bin: %.asc
	icepack $< $(subst top_,,$@)

all: top_foo top_bar

clean:
	rm -f top*.json top*.asc top*.rpt *.bin top*yosys.log

.PHONY: all clean

You can find also find iCEBreaker makefiles in the Project F Exploring FPGAs repo.

What’s Next?

Check your Verilog designs with Verilator Lint. Or take a look at all our FPGA Tools posts.

Get in touch on Mastodon, Bluesky, or X. If you enjoy my work, please sponsor me. 🙏