Open-Source FPGA Toolchains: Yosys, nextpnr, APIO

FPGA work needs tools that convert HDL into a configuration bitstream. Vendor tools are common, but open-source flows are excellent for learning because each step is visible.

Learning Objectives

By the end of this lesson, you should be able to:

name the main stages from HDL to programmed FPGA;
explain what Yosys, nextpnr, IceStorm, and APIO do;
run basic build, lint, simulation, and upload commands;
know which commands are board-family-specific.

The Toolchain Stack

flowchart TD A["Verilog source"] --> B["Yosys synthesis"] B --> C["JSON / netlist"] C --> D["nextpnr place and route"] D --> E["ASCII routed design"] E --> F["Bitstream packer"] F --> G["FPGA board upload"]

Yosys reads synthesizable Verilog and maps it into FPGA resources. nextpnr places and routes that synthesized design for a specific FPGA family. A packer such as icepack converts the placed/routed result into a board-loadable bitstream for iCE40 devices.

Common Open-Source Tools

Tool	Job
Yosys	synthesis from Verilog/SystemVerilog subset to a netlist
nextpnr	place-and-route for supported FPGA families
Project IceStorm	iCE40 bitstream packing and programming tools
Project Trellis	ECP5 database/bitstream support
Verilator	fast Verilog/SystemVerilog simulation and linting
Icarus Verilog	lightweight Verilog simulation
GHDL	VHDL analysis, elaboration, and simulation
GTKWave	waveform viewing
APIO	beginner-friendly project wrapper around FPGA tools

Example Raw iCE40 Flow

This is a conceptual command sequence for a small iCE40 project. The exact device/package options depend on your board.

yosys -p "read_verilog blinky.v; synth_ice40 -top blinky -json blinky.json"
nextpnr-ice40 --up5k --package sg48 --json blinky.json --pcf blinky.pcf --asc blinky.asc
icepack blinky.asc blinky.bin
iceprog blinky.bin

Read it like this:

synthesize blinky.v into blinky.json;
place-and-route it for the selected FPGA and package;
pack the routed design into a bitstream;
upload the bitstream.

APIO: Easier for Beginners

APIO wraps many open-source commands into a project workflow. It is useful when the student goal is "learn FPGA design" rather than "debug every tool flag on day one."

Typical commands:

apio examples fetch alhambra-ii/getting-started
apio lint
apio build
apio sim
apio test
apio devices scan-usb
apio upload

apio lint checks the source. apio build builds the FPGA project. apio sim runs the testbench and opens GTKWave when configured. apio test runs testbenches in batch mode. apio upload builds if needed and programs the board.

Board Files Matter

The HDL does not know which physical pin drives LED1. That mapping comes from constraints:

set_io led 21
set_io clk 35

Constraint syntax differs by tool family. iCE40 projects commonly use PCF files. Xilinx projects commonly use XDC. Intel projects use SDC/QSF-style files.

Worked Example: Choosing a Toolchain

You have an iCE40 learning board and want to blink an LED.

Good beginner path:

use APIO to fetch a known-good example;
run apio lint;
run apio sim if a testbench is included;
run apio build;
run apio upload;
then modify one line and repeat.

The important habit is the repeatable loop: edit, lint, simulate, build, upload.

Exercise

Create a notebook table with these columns:

Stage	Command	Output file	What can go wrong?
Synthesis
Place-and-route
Pack bitstream
Upload

Fill it for your target board. If you do not have a board yet, fill it for an iCE40 board using the example commands above.

Common Mistakes

Copying commands without changing device/package options for the board.
Forgetting the constraint file.
Simulating a testbench successfully but never testing synthesis.
Treating warnings as decoration.
Uploading to hardware before checking pin voltage and board schematic.

Summary

The open-source FPGA flow is visible and teachable: Yosys synthesizes, nextpnr places and routes, family-specific tools pack/program, and APIO can wrap the workflow for beginners. Learn the raw stages, then use wrappers to move faster.

Next: Design Flow: Synthesis, Place-and-Route, and Bitstream.

Mind Map

mindmap root((Open Toolchains)) Core concept Yosys synthesis nextpnr place route Apio project flow Bitstream tools Applications Applications Learning boards CI builds Design checks Reproducible demos Checks Device family Pin file Common mistakes Timing report Common mistakes Wrong part Skipping warnings