Introduction to FPGA Part 2 - Toolchain Setup

2021-11-15 | By ShawnHymel

License: Attribution

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

PATH=$PATH:~/.local/bin

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!

Challenge

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

Solution

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;

endmodule

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).

Introduction to FPGA Part 1 - What is an FPGA?

Introduction to FPGA Part 3 - Getting Started with Verilog

Introduction to FPGA Part 4 - Clocks and Procedural Assignments

Introduction to FPGA Part 5 - Finite State Machine (FSM)

Introduction to FPGA Part 6 - Verilog Modules and Parameters

Introduction to FPGA Part 7 - Verilog Testbenches and Simulation

Introduction to FPGA Part 8 - Memory and Block RAM

Introduction to FPGA Part 9 - Phase-Locked Loop (PLL) and Glitches

Introduction to FPGA Part 10 - Metastability and FIFO

Introduction to FPGA Part 11 - RISC-V Softcore Processor

Introduction to FPGA Part 12 - RISC-V Custom Peripheral