11 November 2020

Building iCE40 FPGA Toolchain on Linux

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 Open Tool Forge has binaries for Linux, Mac, and Windows.

Updated 2020-11-12. Feedback to @WillFlux is most welcome.

Checklist

We’ll be installing:

  1. Build Pre-requisites - what we need before we begin
  2. IceStorm Tools - create bitstreams file and programs boards
  3. nextpnr - portable place and route
  4. iVerilog - Verilog simulation and synthesis tool (optional)
  5. Yosys - Verilog RTL synthesis
  6. Verilator - Verilog simulation and linting (optional)

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

Build Pre-requisites

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

apt install curl git

Install build depedencies (covers all six tools):

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.

cd ~/src/fpga-toolchain

git clone https://github.com/cliffordwolf/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"

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.

cd ~/src/fpga-toolchain

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

cd nextpnr
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.

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.

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.

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 Verilog linting. This tool isn’t required to build iCE40 designs, but the linting is a great way to check your Verilog designs before building. Learn more at the Verilator site.

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
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: %.v
	yosys -ql $(subst .json,,$@)-yosys.log -p 'synth_ice40 -top $(subst .json,,$@) -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 $< $@

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

all: top_foo top_bar

.PHONY: all clean

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

©2020 Will Green, Project F