Chisel Bootcamp

Elevate the level of your hardware design from instances to generators! This bootcamp teaches you Chisel, a Berkeley hardware construction DSL written in Scala. It teaches you Scala along the way, and it frames the learning of Chisel on the idea of hardware generators.

What you'll learn

• Why hardware designs are better expressed as generators, not instances
• Basics and some advanced features of Scala, a modern programming language
• Basics and some advanced features of Chisel 7, a hardware description language embedded in Scala
• How to write unit tests for Chisel designs with ChiselSim and Verilator
• How Chisel designs are compiled to SystemVerilog with CIRCT's firtool, and how to read the FIRRTL in between

Prerequisites

• Familiarity with Verilog, VHDL, or at least some digital hardware design
• Programming experience in with a "high-level" language, be it in Python, Java, C++, etc.
• An earnest desire to learn

Getting Started

Quick Start with Docker

The fastest way to get started is using the prebuilt Docker image that supports both x86-64 and Arm64 (there is no native Linux/Arm64 build of CIRCT's firtool, so on Arm64 it runs under qemu-user emulation; everything else is native):

Using Docker:

docker run -it --rm -p 8888:8888 sysprog21/chisel-bootcamp

Using nerdctl:

nerdctl run -it --rm -p 8888:8888 sysprog21/chisel-bootcamp

Then open the provided URL (starting with http://127.0.0.1:8888) in your browser.

Image tags: latest follows the dev branch, chisel-<version> (for example chisel-7.16.0) is the newest image built for that Chisel release, and sha-<commit> (the first 7 hex digits of a dev commit; a commit superseded by a newer push while its build was queued has none) pins one exact build.

Alternative Options

• Try it online HERE! No local installation required! Binder covers Modules 1-4 only: it lacks sbt and Yosys (Module 5), and its memory may be too small for a JVM beside a Verilator build. Use the Docker image for the whole course.
• For local installation without Docker, look at installation instructions here.
• Teaching a course? See the instructor guide.

Outline

The bootcamp is divided into modules, which are further subdivided. This README serves as Module 0, an introduction and motivation. The times are rough estimates for a first pass, exercises included, from the length of each notebook; they vary a lot with your background.

Notebook	Topic	Time
0_demo	A preview of what you will learn (not part of the course)	15 min
Module 1: Scala
1_intro_to_scala	Enough Scala to start writing Chisel; more comes along the way	45 min
Module 2: Chisel
2.1_first_module	A hardware example, broken down	35 min
2.2_comb_logic	Combinational logic	55 min
2.3_control_flow	Software and hardware control flow	75 min
2.4_sequential_logic	Registers, and the kinds of reset	55 min
2.5_exercise	Putting it together: an FIR filter	25 min
2.6_chiselsim	Testing with ChiselSim and Verilator, waveforms	50 min
2.7_enums_and_bundles	Enums, bit-pattern decoders, bundles and vectors	65 min
2.8_memories	Memories, write masks, a register file	45 min
Module 3: generators
3.1_parameters	Parameters	45 min
3.2_collections	Collections	40 min
3.2_interlude	The Chisel standard library	20 min
3.3_higher-order_functions	Higher-order functions	35 min
3.4_functional_programming	Functional programming	75 min
3.5_object_oriented_programming	Object-oriented programming	25 min
3.6_types	Types	90 min
Module 4: under the hood
4.1_firrtl_ast	FIRRTL, and how firtool turns it into SystemVerilog	40 min
4.2_firrtl_ast_traversal	Walking a FIRRTL circuit	45 min
4.3_firrtl_common_idioms	Common idioms of passes: collecting, adding, deleting	40 min
4.4_firrtl_add_ops_per_module	A worked example: counting adders per module	35 min
Module 5: a RISC-V processor
5.1_riscv_isa	The RV32I instruction set, a decoder and an assembler in Scala	55 min
5.2_alu_and_regfile	The ALU, the immediate generator and the register file	45 min
5.3_decoder	A table-driven decoder	45 min
5.4_single_cycle	A single-cycle RV32I processor, checked against a golden model	70 min
5.5_compliance	The official RISC-V tests on the processor	15 min
5.6_pipeline	A five-stage pipeline: stages, flushes, data hazards	45 min
5.7_hazards	Hazards: forwarding, stalls, the official tests on the pipeline	40 min
5.8_bus_and_mmio	A bus, memory-mapped I/O and a UART: Hello, world	45 min
5.9_debug_and_verify	Debugging a core: retire traces, waveforms, a formal check	40 min
5.10_to_silicon	From Chisel to an FPGA: lint, synthesis, a board	30 min

Module 5 builds the processor in an sbt project under riscv/ (see Install.md): you write parts of it in Scala files there, and the notebooks load the project.

By the end, you will be able to read and understand most of the Chisel code base, begin using Rocket Chip, and build and test a processor of your own, and synthesize it for an FPGA board (Module 5.10). It does not cover ASIC flows or analog circuits.

Which path should I take?

• New to Scala: take Module 1 in full, then Modules 2 and 3 in order. Module 4 is optional.
• Verilog or VHDL designer: read the sections of Module 1 tagged Required (enough to read Scala), take Module 2 (2.6 on testing and 2.7-2.8 differ most from what you know), then Module 3 for what Verilog cannot do: generators.
• Here for the RISC-V processor: Module 1 (at least its Required sections), what Module 5 assumes (below), then Module 5 in order. Module 4 and the rest of Module 3 are optional for it.

Module 5 assumes Module 2 (2.6-2.8 especially: testing, decoders and enums, memories), 3.1 (match, Option, case classes), 3.2_interlude (Decoupled) and 3.3 (the collection methods), and knowing what a processor's datapath is (a computer architecture course, or a book such as Patterson and Hennessy's Computer Organization and Design); it explains RV32I itself.

Motivation

All hardware description languages support writing single instances. However, writing instances is tedious. Why make the same mistakes writing a slightly modified version of something somebody else has likely already designed? Verilog supports limited parameterization, such as bitwidths and generate statements, but this only gets you so far. If we can't write a Verilog generator, we need to write a new instance, thus doubling our code size. As a better option, we should write one program that generates both hardware instances, which would reduce our code size and make tedious things easier. These programs are called generators.

Ideally, we want our generators to be (1) composable, (2) powerful, and (3) enable fine-grained control over the generated design. Error checking is necessary to make sure a composition is legal; without it, debugging is difficult. This requires a generator language to understand the semantics of the design (to know what’s legal and what’s not). Also, the generator should not be overly verbose! We want the generator program to concisely express many different designs, without rewriting it in if statements for each instance. Finally, it should be a zero-cost abstraction. Hardware design performance is very sensitive to small changes, and because of that, you need to be able to exactly specify the microarchitecture. Generators are very different than high-level-synthesis (HLS).

The benefits of Chisel are in how you use it, not in the language itself. If you decide to write instances instead of generators, you will see fewer advantages of Chisel over Verilog. But if you take the time to learn how to write generators, then the power of Chisel will become apparent and you will realize you can never go back to writing Verilog. Learning to write generators is difficult, but we hope this tutorial will pave the way for you to become a better hardware designer, programmer, and thinker!

Contributors

The bootcamp was written at UC Berkeley by the people below. This fork, sysprog21/chisel-bootcamp, moved it to Chisel 7, ChiselSim and CIRCT's firtool, rewrote the testing notebook for ChiselSim, added the notebooks on enums, decoders and memories, and Module 5 with its RISC-V project.

• Stevo Bailey (stevo@berkeley.edu)
• Adam Izraelevitz (adamiz@berkeley.edu)
• Richard Lin (richard.lin@berkeley.edu)
• Chick Markley (chick@berkeley.edu)
• Paul Rigge (rigge@berkeley.edu)
• Edward Wang (edwardw@berkeley.edu)