Part 0 answers: What is debugging, and why does guessing fail?
Debugging is a search, and searches have methods. This part sets out the debug loop the whole course uses, the difference between a symptom and its cause, why a bug costs more at every stage, and the running design, dbglab, that you will debug throughout.
Name the nine steps of the debug loop and the cost of skipping each.
Tell a symptom from a fault from a cause on a real waveform.
Write a bug report someone else can reproduce.
6 lessons, about 67 min
The part on one page, taken from each lesson's Remember box.
The Debug Loop
Each step ends with something you can show: a failing line, a repro command, a first wrong value, a prediction, a clean seed sweep, a new check.
Reproduce and Prove use the same command. Without a repro, a passing run tells you nothing.
A hypothesis is useful only if it predicts a result you have not seen yet. Run that experiment before you edit the RTL.
Rule of thumb: do not touch the design until you can make it fail on demand, and do not close the bug until that same command passes.
Symptom, Fault and Cause
Symptom: where a check or a user first sees something wrong. Fault: the first wrong value inside the design. Cause: the code or decision that made it.
Walk back from the symptom to the first wrong value. Here that is 7,944 cycles, from the scoreboard at cycle 7949 to an X in the FILL register at reset.
A fix at the symptom can pass every test you have and still fail in silicon. Fix the cause, then check the fix in a run that could tell the two apart.
Rule of thumb: the line you change must be the line that made the first wrong value, not the line that reported it.
The Cost of a Bug by Stage
Each stage multiplies the cost of one run, the people involved and the size of the fix. The numbers vary by project; the shape does not.
Visibility falls as cost rises: every signal in RTL, pins and scan dumps in silicon. Fewer things seen means more experiments per bug.
On dbglab's seed 17, one dump and one script found the first X in under a second; pass or fail only took 11 runs and still named no signal.
Rule of thumb: find it in the cheapest stage that can show it, and move any later failure back there before you debug it.
Guessing vs Searching
Before an experiment, predict its result. If you are almost sure of it, it buys almost nothing; the most a yes-or-no run can buy is one bit.
Halving N suspects takes about log2 N runs: 1,500 operations took 11 here. Random pokes over the same knob took 670.
Halving needs a monotone question, like "is the state already wrong after n operations?". Check both ends before you start.
Rule of thumb: before you run anything, say what each possible result would rule out.
Meet dbglab
dbglab: two masters (CPU port, DMA) share one valid/ready bus to RAM, CSRs, a default slave and a stream peripheral that crosses into pclk.
tb/run.sh <test> [seed] [icarus|verilator] prints one PASS or FAIL line; exit 0, 1, or 125 if it does not build. A seed fixes the stimulus.
The history has bugs in it on purpose. v0.1 is clean; later commits are not. The course finds the bugs one at a time.
Rule of thumb: learn the map before you debug: which block, which address, which test checks it.
A Bug Report Others Can Act On
Title the symptom, not your theory: test, what was wrong, where it was seen. A guessed cause in the title steers everyone who reads it.
The repro is a command anyone can paste: commit, test, seed, tool and version. Run it from a clean checkout before you file.
Say what you ruled out and how (other seeds, the other simulator, the last good commit). It saves the next person repeating it.
Rule of thumb: if the reader has to ask you a question before they can reproduce it, the report is not finished.
Practice question: Counter with wrap and saturate modes
Practice question: Waveform debug: a write transaction timeout
Code lab: DMA control FSM
Practice question: Reset strategies in RTL
Code lab: D flip-flop with asynchronous reset
Interview: run a mock interview on this topic