Skip to content

Remove exercise leaks, draw waveforms in Module 5 - #22

Merged
jserv merged 4 commits into
devfrom
fix-notebook-leaks
Nov 15, 2026
Merged

jserv merged 4 commits into
devfrom
fix-notebook-leaks

Conversation

@jserv

@jserv jserv commented Nov 15, 2026 •

Copy link
Copy Markdown

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 PipelineFlush truth-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 x0 forwarding program from 5.7 and ForwardingSpec; the forwarding unit test still verifies x0 is 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 with Locale.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.
  • PipelinedSpec gains a "jump behind a halt" program; the PipelineFlush unit 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.

Written for commit 428cfac. Summary will update on new commits.

View guided diff Turn on auto-fix

The test of the PipelineFlush exercise, in 5.6 and in PipelinedSpec,
compared each output with an expression that was the answer. It now
runs three short programs on the pipelined core and compares them
with the golden model: stores on the wrong path of a jump, stores
behind a halt, and a jump behind a halt. Together they catch every
wrong value of any one flush output, checked by trying each one.
The hazard list of 5.7 and ForwardingSpec ran the very program the
5.9 ForwardsX0 exercise asks students to find. The forwarding unit
test still checks that x0 is never forwarded.
Synthesis does not report how fast a core's clock can run; place and
route does, as 5.10 explains, with nextpnr outside the image.
The two notebooks talked about waveforms but only printed tables.
riscv.Waves draws per-cycle samples as an SVG timing diagram: a clock,
one-bit lanes, and buses as bands with their values. 5.8 draws the
UART frame of 'H' once the transmitter passes its test, and 5.9 draws
the forwarding waveform with the cycle where the seeded bug forwards
the older result highlighted.
cubic-dev-ai[bot]

This comment was marked as resolved.

@jserv
jserv merged commit ba8c7f1 into dev Nov 15, 2026
36 checks passed
@jserv
jserv deleted the fix-notebook-leaks branch November 15, 2026 05:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant