Each lesson answers one question. It starts with a concrete problem, builds the idea, and shows it running. Whenever a lesson says something you can check, you check it: by running code, reading a waveform, or following a real transcript.
Block | What it is for |
|---|---|
Header | The level badge, the question the lesson answers, and what to read first |
Hook | The question, asked before any explanation |
Concept | The idea in plain words; the jargon comes after the idea |
Picture | A figure or a simulated waveform, with a caption that says what to look at |
Run it | A listing from the example project and its real output |
Predict then reveal | You guess the outcome first, then see the answer and the reason |
Break it on purpose | One deliberate failure, the message it prints, and the fix |
Pitfalls | The mistakes beginners actually make, each with its fix |
Rule | One sentence to keep |
Check yourself and an interview question | Questions with reasoned answers, and one question as an interviewer would ask it |
Go deeper and Next | The course that owns the detail, and the lesson that follows |
A lesson drops a block only when it does not fit: a concept lesson with nothing to run carries a worked trace instead of a Run it block.
Badges F and W mark the lowest level a lesson serves: Foundation (Parts 1–3, 8, 9) assumes nothing; Working (Parts 4–7) assumes you can run the design loop alone. See reading paths for routes by background.
Download start-here-examples.zip and unpack it anywhere you like. It holds three folders: mini-controller/, the running example from Parts 1 to 8, pulse-counter-starter/, the Part 9 project, and primer/, the small program from the Syntax Primer. Each folder is self-contained.
In a terminal, cd into the unpacked mini-controller/ folder before you run any make command. Lesson 2.2 shows how to unpack the zip and what every folder is for.
After you finish the Part 9 project, start-here-pulse-counter-solution.zip holds the reference solution and the mutants to compare against. Look only when you are done: the project teaches you most when you build it first.
The example project is a folder with a Makefile. make all runs lint, the simulation with its self-checking testbench, and the synthesis check. make check-tools prints the versions of the tools it needs.
The simulation step passes only when the testbench prints exactly one line that starts with PASS:. Lesson 6.2 explains why.
Icarus Verilog (iverilog -g2012) simulates, Verilator (--lint-only, and --assert for assertions) lints and checks assertions, Yosys checks synthesis, GTKWave views waveforms, and python3 runs the golden models.
Listings that start with // snippet are fragments, and // bad-example marks code shown as a mistake. Neither is meant to run.
Python models use only the standard library. They check their own results and end with one PASS: line.
The example project was run on macOS with Homebrew packages and on Ubuntu 24.04 with that distribution's own, older packages, and make all passed on both. Windows is meant to work through WSL, a Linux environment inside Windows, but that has not been tested. The tool versions page lists exactly which versions were used. If a command behaves differently on your machine, compare your versions with that page first.
One column is one rising clock edge, and the values shown are the ones after that edge.
A single-bit signal is high or low. A bus signal shows its value in a box, and a new box starts only when the value changes.
Every waveform is followed by a how-to-read-it list that names the edges and the values. Read the two side by side, and say each edge out loud before you check the list.
The waveforms come from simulating the lesson's own testbench, so they match the code on the page.
Terminal output appears in plain text blocks whose first line is # captured terminal output. They come from real runs, with the home folder shown as /home/you/projects. Your tool versions, timestamps and commit hashes will differ, and each transcript names the versions it came from.
Read the hook and stop. Try to answer the question before reading on.
Before every run, predict what the output will be, or where it will fail, and write the prediction down.
Run it, then read the waveform or transcript slot by slot against your prediction.
Answer the check-yourself questions out loud before opening them.