Remove exercise leaks, draw waveforms in Module 5
Module 5 gave away two exercise answers, made one wrong claim about timing, and talked about waveforms in 5.8 and 5.9 without showing any. This removes the leaks, corrects the claim, and adds a small SVG waveform drawer that the two notebooks use.
The 5.6 PipelineFlush test (notebook and PipelinedSpec) used to state the answer as expected values. It now runs three short programs on the pipelined core against the golden model: stores on the wrong path, stores behind a halt, and a jump behind a halt. I checked it by mutation: each of the 45 wrong truth tables for a single flush output fails at least one program, and the correct one passes. The program that 5.9 asks students to find for ForwardsX0 was listed verbatim in 5.7 and ForwardingSpec; it is gone, and the Forward unit test still checks x0. 5.7 credited synthesis with reporting clock speed; it is place and route.
riscv.Waves draws per-cycle samples (from a Vcd or a test log) as an SVG timing diagram: a clock lane, one-bit lanes, and buses as bands with their values. It formats numbers with Locale.ROOT and draws x/z as a grey band. 5.8 draws the UART frame of 'H' once the transmitter passes, with bit names taken from the logged busy and txd. 5.9 draws the forwarding waveform and highlights the cycle where the seeded bug forwards the older result. A notebook shows the drawing only when its outputs are trusted, which is always the case for cells the student runs.
Verified in the Docker image:
- tools/check-solutions.sh: 72 tests pass. One fewer than before, because the PipelineFlush unit test became program checks.
- 5.6, 5.8 and 5.9 executed with the solutions applied: only the expected 5.9 exercise cell errors.
- runtest.py on 5.6 to 5.9 without solutions: the expected NotImplementedError counts.
- tests/test_notebooks.py, scalafmt and pre-commit (nbstripout): clean.
Codex, agy and Claude each reviewed the changes in two rounds, and their findings are addressed.
Summary by cubic
Module 5 no longer gives away two exercise answers, corrects a wrong claim about clock speed, and adds a small SVG waveform drawer (riscv.Waves) that notebooks 5.8 and 5.9 use to show what they previously only described.
- Replaces the 5.6
PipelineFlushtruth-table test with three short programs run against the golden model, so the expected flush values are no longer stated as the answer. - Removes the
x0forwarding program from 5.7 andForwardingSpec; the forwarding unit test still verifiesx0is never forwarded. The 5.9 exercise previously gave away this answer verbatim. - Corrects 5.7 to attribute reported clock speed to place and route, not synthesis.
- Adds
riscv.Waves, which draws per-cycle samples (from a VCD or a test log) as an SVG timing diagram with a clock lane, one-bit lanes, and buses as value bands; x/z draw as grey bands and numbers format withLocale.ROOT. - 5.8 draws the UART frame of
'H'once the transmitter test passes; 5.9 draws the forwarding waveform and highlights the cycle where the seeded bug forwards the older result. PipelinedSpecgains a "jump behind a halt" program; thePipelineFlushunit test is replaced by program checks.- Verified with
tools/check-solutions.sh(72 tests pass), notebook runs with and without solutions,tests/test_notebooks.py, scalafmt, and pre-commit.