Welcome to Waterloo Reality Labs! We're a student design team at Waterloo working on XR (extended reality) and spatial computing. This is your onboarding for FPGA work across our different projects.
You'll start with an LED blinker in SystemVerilog, test its timing, inspect the waveforms, and synthesize it for an ECP5 FPGA. The goal is to get comfortable with the team's FPGA tools and workflow.
The whole lab runs on your computer, no hardware required. The LED shows up as a signal in GTKWave; ULX3S is the eventual board target. Keep notes as you go, and post questions in the #onboarding-posts channel in our Discord.
This onboarding might appear easy, but it does touch on some very applicative concepts. We recommend you use plenty of AI for better understanding.
We will be using the OSS CAD Suite, which bundles the open-source tools below. To manually install, you can reference the official setup instructions. If not, proceed to the steps below.
| Tool | What it's for |
|---|---|
Icarus Verilog (iverilog and vvp) |
Compile and run the design with your testbench |
| GTKWave | Inspect the signals recorded during simulation |
| Yosys | Map your design into ECP5 logic and report resource use |
Activate the suite in each new Bash terminal and check that the tools are available:
source "$HOME/oss-cad-suite/environment"
iverilog -V
vvp -V
yosys -V
You’ll need a GitHub account for this onboarding (sign up here). Follow GitHub’s Git setup guide to install Git, set your name/email, and setup auth (to push to your own repo). On Windows, set up Git inside Ubuntu/WSL. We highly recommend a CLI Git setup.
Make a repository under your GitHub account named uwrl-ecp5-fpga-onboarding and initialize it with a README. Clone it to your computer. Replace YOUR-USERNAME below with your GitHub username:
git --version
cd "$HOME"
git clone <https://github.com/YOUR-USERNAME/uwrl-ecp5-fpga-onboarding.git>
cd uwrl-ecp5-fpga-onboarding
mkdir -p rtl sim build
Use this repository as your project folder for the rest of the onboarding. Keep all the code you write here, including the RTL, testbench, or extra scripts that helps, and commit/push your progress to GitHub. If you already started locally, move those source files into this clone.
If a tool is missing, check the suite path and repeat thesourcecommand to reload the environment. For a WSL display error, check WSLg setup. Ping a team lead with your release date and versions in #onboarding-posts so we can help you fix this.
Put your design in rtl/top.sv, your testbench in sim/tb_top.sv, and add build/ to a .gitignore file in the project root.