Introduction to FPGA Part 2 - Toolchain Setup

By ShawnHymel

Many FPGA manufacturers have specific toolchains that you are required to use to work with their parts. Lucky for us, we can use a set of free and open-source tools to create, build, and upload designs for the Lattice iCE40 family of FPGAs.

In the previous tutorial, we examined how an FPGA works and why you might want to use one. This time, we install the toolchain necessary to build (e.g. synthesize) Verilog HDL and upload it to an iCE40 FPGA.

See here if you would like to view this part in video format:


Required Hardware

I recommend an iCEstick for this tutorial. However, any of the development boards listed as “supported” by the apio project should work. I also recommend a USB extension cable, but it is optional.

Install apio

Apio is a Python-based tool that controls other low-level tools, such as yosys, nextpnr, icepack, and iceprog. It’s designed to work with development boards (rather than individual FPGA chips). As such, it’s helpful to think of apio as the “Arduino IDE” of FPGAs (where yosys would be analogous to the avr-gcc compiler).

You will need to have Python 3.5+ installed on your system (if you do not have it already). Navigate to the Python website and follow the instructions for installing it.

Here is the apio guide for installing the tool on different operating systems.

Note: as of this writing, the current version of apio does not work. You will want to install version 0.6.7. Future updates to apio will hopefully fix any bugs.

Install apio with the following command:

Copy Code
python -m pip install apio==0.6.7

Linux Only:

You might need to update your path so that `apio` can be found as a command-line tool. Edit your profile:

Copy Code
nano ~/.profile

Add the following line to the end:

Copy Code

Save and exit (‘ctrl+x’ and ‘y’ if you are using nano). Re-run the profile configuration:

Copy Code
source ~/.profile

If you are using a Debian/Ubuntu flavor, you will also likely need to add your current username to the “dialout” group:

Copy Code
sudo usermod -a -G dialout $USER

Install Tool Suite

Run the following commands to install all of the required tools and drivers:

Copy Code
apio install --all
apio install drivers

Many of the FPGA dev boards contain an FTDI chip to translate USB communication to UART communication (e.g. so you can upload your synthesized/packaged FPGA design to the onboard flash memory). If your board has an FTDI chip (the iCEstick has one), enter the following command:

Copy Code
apio drivers --ftdi-enable

Windows Only:

On windows, you will need to call the above command in an administrator command prompt. In the Windows search bar, enter “cmd.” Right-click on the Command Prompt entry and select Run as administrator.

Run command prompt as administrator

In the new window, enter the `apio drivers --ftdi-enable` command. This will launch Zadig. Plug in your dev board. Select Options > List All Devices. Select your dev board from the drop-down menu (e.g. the iCEstick will show up as “Lattice FTUSB Interface Cable (Interface 0)”). Choose the libusbK driver and click Replace Driver.

Install FTDI driver using Zadig in Windows

Important! On Windows, make sure you have no other FTDI parts plugged into your USB ports. This will cause a conflict with the apio uploading process. If you run `apio upload` or `apio system --lsftdi` and get the following error, it means you have an extra FTDI device plugged into your computer:

Copy Code
ftdi_usb_get_strings failed: -4 (libusb_open() failed)

Remove the extra FTDI device before trying to upload or communicate with the dev board using apio again.

Upload Example

Apio comes with a number of pre-made examples. Create a folder on your system to hold your FPGA designs. For example, I will place my designs in C:\Users\sgmustadio\Documents\apio.

In a terminal window, navigate to your working directory (e.g. Documents\apio for me) and enter the following to list all of the available examples:

Copy Code
apio examples -l

Create the icestick/leds example (if you have the iCEstick):

Copy Code
apio examples -d icestick\leds

Navigate into the leds directory. Verify and simulate the design:

Copy Code
cd icestick/leds
apio verify
apio sim

This should open gtkwave. All five LED pins (D1-D5) should be logic HIGH.

gtkwave simulation

When you are satisfied with the simulation, build and upload the design to your FPGA:

Copy Code
apio build
apio upload

You should see the LEDs on your FPGA board turn on!

LEDs on iCEstick FPGA board


Your challenge for this episode is to turn off one of the LEDs by modifying leds.v. Use whichever text editing program you like.


Here is one possible solution to turn off one of the LEDs. Note that I turned off the 5th LED (the green LED on the iCEstick).

Copy Code
//-- Hello world example for the iCEstick board
//-- Turn on all the leds

module leds(output wire D1,
output wire D2,
output wire D3,
output wire D4,
output wire D5);

assign D1 = 1'b1;
assign D2 = 1'b1;
assign D3 = 1'b1;
assign D4 = 1'b1;
assign D5 = 1'b0;


There are a number of ways to represent numbers in Verilog. `1’b0` means that the constant value is a 1-bit number (given by the first ‘1’) and expressed in binary (given by the ‘b’). The final ‘0’ is the value of the number.

We set the value of the D5 pin to binary ‘0’, which tells the FPGA to set that pin to logic LOW.

I recommend reading this documentation page on data types in Verilog to learn about the different ways to express numbers.

Recommended Reading

All demonstrations and solutions for this series can be found in this GitHub repository.

You can learn more about the apio tool on their documentation site.

Matt Venn demonstrates how to use yosys, nextpnr, and icepack/iceprog in a 3-part video series (if you would like to see how to use the tools without apio).

Key Parts and Components

Add all Digi-Key Parts to Cart
  • 220-2656-ND