Add Module 5: build an RV32I core in Chisel
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.
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 inriscv/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.