Repository navigation
Conversation
jserv
force-pushed
the
todo-plan
branch
2 times, most recently
from
November 14, 2026 19:03
a554e9c to
952ae07
Compare
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
riscv/sbt project; reference solutions are committed but left out of the image; regression programs that once exposed bugs are kept inriscv/programs/regress.Tooling and CI
Written for commit de8612b. Summary will update on new commits.