Part 2: Getting Started with Yosys, IceStorm, and Apio

What this lecture covers

This lecture follows the series introduction by getting the open-source iCE40 toolchain installed and working end to end. It answers a practical question: what tools turn a Verilog file into a bitstream running on real hardware, and how do you install and drive them?

You'll come away with apio, Yosys, nextpnr, and Project IceStorm installed, the iCEstick's FTDI drivers configured, and a working understanding of how a project folder is structured - the Verilog source, the physical constraints file (PCF), a test bench, and the apio.ini file. By the end you'll have built and uploaded the "leds" example so all onboard LEDs light up, and you'll know where to find the datasheet and pinout documents you'll keep referring back to.

Key ideas

• apio: a Python-based command-line tool that wraps Yosys, nextpnr, and Project IceStorm so you don't have to call each tool manually; it also ships example projects for supported dev boards.
• Toolchain roles: Yosys performs synthesis (Verilog to gate-level netlist), nextpnr performs place-and-route (netlist to chip-specific layout), icepack converts that into a binary bitstream, and iceprog uploads it to the board.
• Physical constraints file (.pcf): maps names used in your Verilog (like an LED signal) to physical pin numbers on the FPGA package; it is not Verilog code.
• Version pinning: the lecture recommends apio 0.6.7 rather than the newest release, since 0.7.6 had installation issues at the time of recording.
• FTDI drivers: boards like the iCEstick need a driver (installed via Zadig on Windows) so apio can talk to the board's USB interface.
• apio workflow: apio verify checks syntax, apio sim runs a test bench in GTKWave, apio build synthesizes and place-and-routes the design, and apio upload sends the resulting binary to the board's flash memory.
• Configuration memory: the iCE40 loses its configuration whenever power is removed and re-reads it from an external SPI flash chip on every boot; a separate one-time-write internal memory exists for permanent deployment.

Walkthrough

Setting up the toolchain (0:08)

The lecture reviews what Yosys, nextpnr, and the IceStorm tools (icepack, iceprog) each do, then introduces apio as the tool that manages all of them together, plus a brief mention of the graphical, block-based icestudio environment (not used in this series).

Installing Python and apio (3:26)

Python 3.5 or later is required. apio is installed with pip, pinned to version 0.6.7 due to known issues in the newer release. The lecture demonstrates the install on Windows and flags that the process differs slightly by operating system.

Installing the tool suite and drivers (4:26)

With apio installed, the underlying tool suite (Yosys, IceStorm, etc.) is installed separately, followed by the board's FTDI drivers. On Windows this requires using Zadig to install the libusbK driver for the board while it's plugged in. The lecture also shows a known conflict where having more than one FTDI device connected (such as an Analog Discovery 2 alongside the iCEstick) causes a "lib usb open failed" error, resolved by disconnecting the extra device.

Running the LEDs example (7:07)

Using apio examples, the lecture creates the iCEstick "leds" example and walks through its files: leds.v (ties all LEDs high), the .pcf file mapping signal names to physical pins, a test bench, a GTKWave save-state file, and apio.ini (declares the target board, regenerated with apio init --board icestick).

FPGA pin mapping and schematic (10:28)

The lecture shows how to cross-reference the iCE40HX1K pinout spreadsheet and the iCEstick user manual to find which physical pin (for example, pin 99) connects to which onboard LED, which is the information you need to write a .pcf file for your own design.

Building and uploading (12:08)

The lecture runs through apio verify, apio sim (GTKWave), apio build (synthesis and place-and-route), and apio upload (writes the binary to the board via iceprog), confirming that all LEDs turn on once uploaded.

FPGA internals and configuration memory (16:26)

Using the iCE40HX datasheet, the lecture points out programmable logic blocks (each containing eight logic cells), I/O banks with configurable pull-up/pull-down resistors, dedicated SPI logic, and a phase-locked loop. It explains that the chip's configuration lives in external SPI flash and is reloaded on every power-up, unlike the one-time-write internal configuration memory.

Before you watch

• Watch Part 1 ("What is an FPGA?") first for context on FPGA fabric and the design flow.
• Have an iCE40-based dev board (the lecture uses the Lattice iCEstick) and a computer with Python 3.5+ available if you want to follow along.

Check your understanding

1. What does each of Yosys, nextpnr, icepack, and iceprog do in the build pipeline?
2. Why does a .pcf file matter, and what information does it contain?
3. What problem can occur on Windows if multiple FTDI devices are connected, and how is it fixed?
4. Why does the iCE40 need to reload its configuration from external SPI flash every time it powers on?
5. What do apio verify, apio sim, apio build, and apio upload each do?