Skip to content

Add Module 5: build an RV32I core in Chisel - #21

Merged
jserv merged 17 commits into
devfrom
todo-plan
Nov 14, 2026
Merged

jserv merged 17 commits into
devfrom
todo-plan

Conversation

@jserv

@jserv jserv commented Nov 14, 2026 •

Copy link
Copy Markdown

This adds Module 5, ten notebooks that build an RV32I core in Chisel 7 (no CSRs): the ISA and an assembler, the ALU and register file, a table-driven decoder, a single-cycle core checked against a golden model and the official riscv-tests, a five-stage pipeline with forwarding and stalls, a bus with a UART, debugging with traces and a formal check, and lint, synthesis and an FPGA board. The exercises live in the riscv/ sbt project, with reference solutions under riscv/solutions/ that the image leaves out. Module 2 gains notebooks on enums, bundles and memories, and teaches reset kinds, assertions, waveforms and tests in files.

Around it: CI gates that run every notebook and fail on deprecated calls, one code style for Scala, Python and shell, a troubleshooting page, an instructor guide with a JupyterHub setup, a tested install script for use outside Docker, checksum-checked downloads, firtool on Arm64, and a visualizer that draws from exact FIRRTL references and colors nodes for color-blind readers. The Docker image shrinks from 1.21 GB to 0.65 GB on amd64: a jlink'd Java runtime, Graphviz and GCC pruned to what the course uses, Verilator without Perl, shared jar caches stored once, and UPX on the largest binaries.

Verified locally on amd64: tools/check-solutions.sh (70 tests pass, the scaffold compiles), runtest.py over all 31 notebooks (exit 0), tests/test_visualizer.py, the chiseltest compatibility and riscv import tests, pre-commit run --all-files, and the JupyterHub image build. The Arm64 base stage was cross-built and checked (g++, Verilator, dot -Tsvg, the JVM's class-data archive); the full Arm64 image is left to CI.

Closes #18, closes #19


Summary by cubic

Adds Module 5, ten notebooks that build a CSR-free RV32I core in Chisel 7, and the tooling to run the whole course: CI now executes every notebook on both architectures, and the Docker image shrinks from 1.21 GB to 0.65 GB.

Course content

  • Module 5 covers the ISA and a self-written assembler (no GNU toolchain), the ALU and register file, a table-driven decoder, a single-cycle core checked against a golden model and the official riscv-tests, a five-stage pipeline with forwarding and stalls, a bus with a UART, debugging with traces and a formal check, and lint, synthesis, and an FPGA board.
  • Exercises live in the riscv/ sbt project; reference solutions are committed but left out of the image; regression programs that once exposed bugs are kept in riscv/programs/regress.
  • Module 2 gains notebooks on enums, bundles, and memories, and teaches reset kinds, assertions, waveforms, and tests in files; Module 1's sections are tagged by what each learning path needs.
  • The docs record a firtool bug that drops write masks on memories with an unmasked port, plus troubleshooting, an instructor guide with a JupyterHub setup, and the processor's design decisions.

Tooling and CI

  • CI runs every notebook, one per job, on amd64 and natively on Arm64, and gates the codebase on deprecation warnings, pinned-version agreement, and one code style for Scala, Python, and shell; pull requests run a smoke subset.
  • The Docker image drops from 1.21 GB to 0.65 GB via a jlink'd Java runtime, pruned Graphviz, GCC, Verilator, and Yosys, no Perl, one shared jar cache, and UPX; a tested install script covers a non-Docker Ubuntu setup with checksum-checked downloads and firtool on Arm64.
  • The visualizer draws from exact FIRRTL references and uses a color-blind-safe palette, closing Keep distinct FIRRTL references apart in the visualizer graph #18 and Use exact declared names to color nodes in the visualizer #19.

Written for commit de8612b. Summary will update on new commits.

View guided diff Turn on auto-fix

cubic-dev-ai[bot]

This comment was marked as resolved.

cubic-dev-ai[bot]

This comment was marked as resolved.

@jserv
jserv force-pushed the todo-plan branch 2 times, most recently from a554e9c to 952ae07 Compare November 14, 2026 19:03
jserv added 17 commits November 15, 2026 03:30
CI ran four notebooks on amd64 only, and deprecation warnings went
unread. It now runs every notebook registered in runtest.py, one per
job, on amd64 and natively on Arm64; a pull request runs a smoke
subset plus what it changes. runtest.py reports any deprecation as an
error, and the deprecated calls in load-ivy.sc and 1_intro_to_scala
are gone (docs/chisel7-audit.md records the audit).

A Checks workflow runs without a kernel: the pinned versions agree
(tools/check-versions.py), notebooks carry no outputs (nbstripout),
and tests/test_notebooks.py checks links, images, alt text, removed
Chisel 3 APIs and the runtest.py registry, each rule proven against a
seeded violation. Images are also tagged chisel-<version> and
sha-<commit>.
2.7 covers ChiselEnum, switch and is, BitPat with decoders, MixedVec
and the connection operators. 2.8 covers Mem, SyncReadMem, write
masks, SRAM and memory files, and records what this toolchain really
does with them. 2.4 gains synchronous and asynchronous reset, and 2.6
gains failing expects, seeded random tests, bounded waits and
waveforms: simulate takes waves = "name" and prints the VCD's path.
Format Python with black (line length 120, in pyproject.toml), the
Binder postBuild script with shfmt (4-space indentation), and Scala
with scalafmt (.scalafmt.conf, close to Chisel's own settings): both
source/load-ivy.sc and the code cells of every notebook. The change is
whitespace only, apart from one comment in 2.3_control_flow moved to
its own line, and every notebook still passes runtest.py.

tools/format-scala.py formats source/*.sc and the notebook cells (all
cells in one scalafmt run), leaves alone the cells scalafmt cannot
parse, and fails when their number differs from the expected one (one
cell in 3.6_types shows a syntax error on purpose). Pre-commit runs
black and shfmt; the Checks workflow runs every pre-commit hook and
tools/format-scala.py --check with a scalafmt binary whose checksum is
pinned. binder/postBuild becomes executable, which Binder does anyway,
so that pre-commit recognises it as a shell script.
Module 5 builds an RV32I processor (no CSRs, no extensions; see
riscv/DESIGN.md) in an sbt project under riscv/, pinned to the
notebooks' Scala and Chisel, starting with the RV32I encodings. The
image gets a checked sbt with a preloaded cache, so sbt test runs
with --network none, and CI runs the project's tests on both
architectures.

Exercises in riscv/src/ leave the student's part as ???, with
reference solutions in riscv/solutions/ that the image leaves out;
tools/check-solutions.sh checks both. source/load-riscv.sc lets a
notebook import riscv._ and recompiles the project only when it
changed. The first exercise is the ALU.
The course brings its own assembler instead of a GNU toolchain:
riscv.Asm reads GNU syntax, every RV32I instruction and the
pseudo-instructions, and is checked against GNU as 2.44. riscv.IsaSim
interprets RV32I and reports each instruction as a Retire record, the
fields of the retire port the cores will have, so co-simulation
compares streams rather than final states. riscv.RandomProgram writes
programs that halt by construction.

5.1 covers the registers, the formats and their immediates, decoding
and the assembler; its exercise is a disassembler.
5.2 builds the ALU (the exercise, tested against the golden model),
the immediate generator and the register file. 5.3 adds a
table-driven decoder, one row per instruction minimized by
decoder.qmc, checked against a second description derived from the
opcodes, on random instructions and on near misses; three rows are
the exercise.
5.4 connects the blocks into SingleCycleCore, which retires one
instruction per cycle on an RVFI-style port, and CoSim compares it
with the golden model instruction by instruction. The RAM has one
write port: with Chisel 7.16's firtool, a Mem with a masked and an
unmasked write port ignores the mask.

5.5 runs the rv32ui tests of riscv-tests, at a pinned revision, on
both. They are assembly with C macros, so tools/import-riscv-tests.py
expands them once against a CSR-free environment, and CI checks the
committed files against a fresh import. riscv.Asm now reads the GNU
as syntax they use and assembles all 40 into the images GNU produces.
The outline is a table of every notebook with a rough time, and a
section suggests paths for Scala newcomers, Verilog and VHDL
designers and RISC-V students; every section of 1_intro_to_scala is
tagged Required, Recommended or Optional for them. The notebook lint
checks that every notebook has a row.
firtool (1.160.0, which Chisel 7.16.0 uses, and still 1.163.0, the
latest release) drops the write masks of a memory that also has a
write port without a mask: the lowered memory has no mask inputs, and
a masked write writes every byte. The FIRRTL still has the mask. A
constant all-ones mask counts as no mask; write ports masked with
signals keep their masks; Mem and SyncReadMem are alike. 2.8 now
states this after the store-unit exercise, links the upstream report
(llvm/circt#11591), and has a cell whose unused, unmasked second port
is enough to lose the mask (the cell asserts that, so a firtool that
fixes it makes the notebook fail and the section get updated). It
recommends one write port fed by Muxes, as riscv.Ram does. 5.4,
DESIGN.md and Ram's comment state the same rule.
A RiscvSystem declares what a testbench needs of a core, so CoSim
drives any core, and riscv/programs/regress keeps the programs that
once exposed a bug. 5.6 builds a five-stage pipeline that resolves
branches in EX and flushes on a halt, with programs padded by nops;
CoSim also fails if anything retires after the halt. 5.7 adds
forwarding, a load-use stall and waiting for a slow data memory, so
programs need no nops, and passes every program and rv32ui test.
5.8 puts the forwarding core's data port on a bus with the RAM and a
UART that holds a write until it can send it, so a program needs no
status loop; the golden model takes memory-mapped devices, and
hello.S prints from both. 5.9 plants a bug in the forwarding unit and
finds it three ways: disassembled retire traces, waveforms read back
from the VCD, and a proof with Yosys's SAT solver, which the image
gets from YoWASP.
Yosys synthesizes the designs of Module 5 for iCE40 and ECP5 and
Verilator lints them, and 5.10 compares the numbers. Ulx3sTop puts
the system of 5.8 on a ULX3S board, and fpga/ulx3s.sh builds a
bitstream that meets the board's 25 MHz in nextpnr (about 48 MHz); it
has not yet run on a board.

The specs and the notebooks now take their programs from one place,
riscv.Programs, found from riscv/ or the repository root, instead of
lists kept by hand.
2.6 gains assertions written in the design (an assert, and a
chisel3.ltl property), with the layer setting they need and what
assume and cover mean, and ends with a ScalaTest class run by sbt from
riscv/ (MemorySpec). getVerilog stops printing the empty
verification-layer files of designs without assertions.
docs/troubleshooting.md gives, for each failure seen so far, what it
prints and the fix, and every notebook links it under its Setup
heading. The notebooks name only libraries that work with Chisel 7:
the chiseltest compatibility package is checked in the kernel, and
dsptools is no longer named.

The lint catches an image with an empty source, accepts a
troubleshooting link with an anchor, and checks each self-test seed on
its own. The pull-request selector runs every notebook when it changes
itself, and fails on a SMOKE entry that runtest.py does not register.
tools/install.sh sets the course up on Ubuntu 24.04 or newer,
building a Verilator new enough for ChiselSim and registering the
Scala kernel in its own environment; a workflow runs it in a bare
container weekly and when it changes. On Arm64 it runs firtool under
qemu, as the image does. The coursier launcher and the firtool jar
are now checked against their sha256 everywhere, as sbt and Verilator
were.

docs/instructors.md is for running the bootcamp as a course: a
schedule, how exercises are checked, and what a class needs, with a
JupyterHub setup on the image in docs/jupyterhub/. No instructor has
reviewed it yet.
firrtlToDot named nodes by replacing dots and brackets with
underscores, so different references became one node and the graph
showed connections that do not exist, and it could not read the
nested selections Chisel 7 emits. Nodes are now named by their
reference, scoped by instance, and a selection's base and index are
references of their own. The fills come from the Okabe-Ito palette,
which color-blind readers can tell apart. test_visualizer.py has the
issues' reproducers.

Closes #18, closes #19
The image carried more than the course runs. It now has a Java 17
runtime cut down with jlink to the modules that the Scala compiler,
Almond, coursier and sbt use (92 MB instead of 172, with a class-data
sharing archive and the system's CA certificates); JupyterLab without
the Python kernel it pulls in, so Scala is the only and default
kernel; of the host GCC only what Verilator uses to compile C++; of
Graphviz only what dot needs for SVG; and of Yosys's libraries only
those for iCE40 and ECP5. Perl goes: a shell script takes the place
of Verilator's Perl wrapper, doing what that does for a normal run.
The jars that coursier and sbt both hold are stored once, as hard
links in one directory, and on amd64 the C++ compiler, Verilator and
firtool are compressed with UPX. There was already no RISC-V
toolchain: riscv.Asm assembles programs.

An image built on this one restores the packages that lost files
before adding others; /etc/bootcamp-pruned lists them, and the
instructor guide says how.

Verified in the image: the riscv tests with the solutions, every
notebook through runtest.py, the Python tests, a clean JupyterLab
start, and the JupyterHub image built on it, which now opens /lab.
An Arm64 cross-build of the base stage compiles and links C++ and
opens the class-data archive under qemu.
@jserv
jserv merged commit 1fdc4d1 into dev Nov 14, 2026
71 checks passed
@jserv
jserv deleted the todo-plan branch November 14, 2026 19:58
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.

Use exact declared names to color nodes in the visualizer Keep distinct FIRRTL references apart in the visualizer graph

1 participant