Skip to content

Lab 2 - Toolchain & FPGA Bring-up

Goal

By the end of this lab, you should be able to: write a tiny SystemVerilog design, simulate it, synthesize it for the Tang Nano 9K, and see it run on real hardware (an LED blinking is enough).

1. Install the OSS CAD Suite

Download a release of the OSS CAD Suite for your platform. It bundles everything we need:

  • Yosys - synthesis.
  • nextpnr-himbaechel (Gowin backend) - place and route for the GW1NR-9 (Tang Nano 9K's FPGA).
  • Verilator - fast SystemVerilog simulation for testbenches.
  • GTKWave - waveform viewer.
  • openFPGALoader - bitstream upload over USB.

Add the suite's bin directory to your PATH:

1
export PATH="/path/to/oss-cad-suite/bin:$PATH"

The suite also ships an environment.sh/activate script that does this for you - but that script also reorders several other things (its own bundled Python among them), which can quietly break unrelated Python-based tools you install later in the course (e.g. the optional LiteX tutorials need litex, a Python package, importable from python3 - sourcing the full script can shadow that with the suite's own bundled Python instead). Prefer the plain PATH export above - it's all any command in this course actually needs from the suite.

2. Connect the board

Connect the Tang Nano 9K via USB. Verify openFPGALoader can detect it:

1
openFPGALoader --detect

Write a minimal SystemVerilog module that drives one of the board's LEDs from a counter fed by the on-board clock. Keep it simple: a free-running counter, with one LED tied to one of its high bits.

Synthesize and program the board:

1
2
3
4
5
yosys -p "read_verilog -sv blink.sv; synth_gowin -top blink -json blink.json"
nextpnr-himbaechel --json blink.json --write blink_routed.json \
    --device GW1NR-LV9QN88PC6/I5 --vopt family=GW1N-9C --vopt cst=tangnano9k.cst
gowin_pack -d GW1N-9C -o blink.fs blink_routed.json
openFPGALoader -b tangnano9k blink.fs

(Exact flags depend on the OSS CAD Suite version - check the suite's documentation and the Tang Nano 9K constraint file examples for the pin constraints file, tangnano9k.cst.)

4. Simulate with Verilator

Write a small testbench for your blink module (or, better, for a simple combinational/sequential circuit you design for this lab) and run it with Verilator. Confirm you can view the resulting waveform in GTKWave.

Checklist

  • OSS CAD Suite installed and on PATH.
  • Board detected by openFPGALoader.
  • A design synthesized, placed/routed, and running on the board (LED blinking).
  • A Verilator testbench running and producing a waveform you can view in GTKWave.