Add Module 5: build an RV32I core in Chisel

Merged
JS
2d ago
+16291-1620

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 #18 and #19.