Chisel 3.

0 Tutorial (Beta)
Jonathan Bachrach, Krste Asanović, John Wawrzynek
EECS Department, UC Berkeley
{jrb|krste|johnw}@eecs.berkeley.edu

January 12, 2017

1 Introduction developed as hardware simulation languages, and

only later did they become a basis for hardware syn-
This document is a tutorial introduction to Chisel thesis. Much of the semantics of these languages are
(Constructing Hardware In a Scala Embedded Lan- not appropriate for hardware synthesis and, in fact,
guage). Chisel is a hardware construction language many constructs are simply not synthesizable. Other
constructs are non-intuitive in how they map to hard-
embedded in the high-level programming language
ware implementations, or their use can accidently lead
Scala. At some point we will provide a proper refer- to highly inefficient hardware structures. While it is
ence manual, in addition to more tutorial examples. possible to use a subset of these languages and yield
In the meantime, this document along with a lot of acceptable results, they nonetheless present a cluttered
trial and error should set you on your way to using and confusing specification model, particularly in an
Chisel. Chisel is really only a set of special class def- instructional setting.
initions, predefined objects, and usage conventions
within Scala, so when you write a Chisel program you
are actually writing a Scala program. However, for
However, our strongest motivation for developing
the tutorial we don’t presume that you understand a new hardware language is our desire to change the
how to program in Scala. We will point out necessary way that electronic system design takes place. We
Scala features through the Chisel examples we give, believe that it is important to not only teach students
and significant hardware designs can be completed how to design circuits, but also to teach them how
using only the material contained herein. But as you to design circuit generators—programs that auto-
gain experience and want to make your code simpler matically generate designs from a high-level set of
or more reusable, you will find it important to lever- design parameters and constraints. Through circuit
age the underlying power of the Scala language. We generators, we hope to leverage the hard work of de-
recommend you consult one of the excellent Scala sign experts and raise the level of design abstraction
books to become more expert in Scala programming. for everyone. To express flexible and scalable circuit
construction, circuit generators must employ sophis-
Chisel is still in its infancy and you are likely to
ticated programming techniques to make decisions
encounter some implementation bugs, and perhaps concerning how to best customize their output cir-
even a few conceptual design problems. However, cuits according to high-level parameter values and
we are actively fixing and improving the language, constraints. While Verilog and VHDL include some
and are open to bug reports and suggestions. Even primitive constructs for programmatic circuit genera-
in its early state, we hope Chisel will help designers tion, they lack the powerful facilities present in mod-
be more productive in building designs that are easy ern programming languages, such as object-oriented
to reuse and maintain. programming, type inference, support for functional
programming, and reflection.

Through the tutorial, we format commentary on our

design choices as in this paragraph. You should be
able to skip the commentary sections and still fully Instead of building a new hardware design lan-
understand how to use Chisel, but we hope you’ll find guage from scratch, we chose to embed hardware con-
them interesting. struction primitives within an existing language. We
We were motivated to develop a new hardware picked Scala not only because it includes the program-
language by years of struggle with existing hardware ming features we feel are important for building cir-
description languages in our research projects and cuit generators, but because it was specifically devel-
hardware design courses. Verilog and VHDL were oped as a base for domain-specific languages.

1
2 Hardware expressible in Chisel 5.S(7.W) // signed decimal 7-bit lit of type SInt
5.U(8.W) // unsigned decimal 8-bit lit of type UInt

This version of Chisel only supports binary logic, and

does not support tri-state signals. For literals of type UInt, the value is zero-extended
to the desired bit width. For literals of type SInt, the
We focus on binary logic designs as they constitute the value is sign-extended to fill the desired bit width. If
vast majority of designs in practice. We omit support the given bit width is too small to hold the argument
for tri-state logic in the current Chisel language as value, then a Chisel error is generated.
this is in any case poorly supported by industry flows,
and difficult to use reliably outside of controlled hard We are working on a more concise literal syntax
macros. for Chisel using symbolic prefix operators, but are
stymied by the limitations of Scala operator overload-
ing and have not yet settled on a syntax that is actu-
3 Datatypes in Chisel ally more readable than constructors taking strings.
We have also considered allowing Scala literals to
Chisel datatypes are used to specify the type of val- be automatically converted to Chisel types, but this
ues held in state elements or flowing on wires. While can cause type ambiguity and requires an additional
hardware designs ultimately operate on vectors of import.
binary digits, other more abstract representations The SInt and UInt types will also later support
for values allow clearer specifications and help the an optional exponent field to allow Chisel to auto-
tools generate more optimal circuits. In Chisel, a matically produce optimized fixed-point arithmetic
circuits.
raw collection of bits is represented by the Bits type.
Signed and unsigned integers are considered sub-
sets of fixed-point numbers and are represented by
types SInt and UInt respectively. Signed fixed-point 4 Combinational Circuits
numbers, including integers, are represented using
two’s-complement format. Boolean values are repre- A circuit is represented as a graph of nodes in Chisel.
sented as type Bool. Note that these types are distinct Each node is a hardware operator that has zero or
from Scala’s builtin types such as Int or Boolean. Ad- more inputs and that drives one output. A literal,
ditionally, Chisel defines Bundles for making collec- introduced above, is a degenerate kind of node that
tions of values with named fields (similar to structs in has no inputs and drives a constant value on its out-
other languages), and Vecs for indexable collections put. One way to create and wire together nodes is
of values. Bundles and Vecs will be covered later. using textual expressions. For example, we can ex-
Constant or literal values are expressed using Scala press a simple combinational logic circuit using the
integers or strings passed to constructors for the following expression:
types: (a & b) | (~c & d)

1.U // decimal 1-bit lit from Scala Int.

"ha".U // hexadecimal 4-bit lit from string.
The syntax should look familiar, with & and | rep-
"o12".U // octal 4-bit lit from string. resenting bitwise-AND and -OR respectively, and ˜
"b1010".U // binary 4-bit lit from string. representing bitwise-NOT. The names a through d
represent named wires of some (unspecified) width.
5.S // signed decimal 4-bit lit from Scala Int.
-8.S // negative decimal 4-bit lit from Scala Int.
Any simple expression can be converted directly
5.U // unsigned decimal 3-bit lit from Scala Int. into a circuit tree, with named wires at the leaves and
operators forming the internal nodes. The final circuit
true.B // Bool lits from Scala lits.
output of the expression is taken from the operator at
false.B
the root of the tree, in this example, the bitwise-OR.
By default, the Chisel compiler will size each con- Simple expressions can build circuits in the shape
stant to the minimum number of bits required to hold of trees, but to construct circuits in the shape of ar-
the constant, including a sign bit for signed types. Bit bitrary directed acyclic graphs (DAGs), we need to
widths can also be specified explicitly on literals, as describe fan-out. In Chisel, we do this by naming
shown below: a wire that holds a subexpression that we can then
reference multiple times in subsequent expressions.
"ha".U(8.W) // hexadecimal 8-bit lit of type UInt
"o12".U(6.W) // octal 6-bit lit of type UInt
We name a wire in Chisel by declaring a variable.
"b1010".U(12.W) // binary 12-bit lit of type UInt For example, consider the select expression, which is
used twice in the following multiplexer description:

2
val sel = a | b 6 Functional Abstraction
val out = (sel & in1) | (~sel & in0)

We can define functions to factor out a repeated piece

The keyword val is part of Scala, and is used to name of logic that we later reuse multiple times in a design.
variables that have values that won’t change. It is For example, we can wrap up our earlier example of
used here to name the Chisel wire, sel, holding the a simple combinational logic block as follows:
output of the first bitwise-OR operator so that the
output can be used multiple times in the second ex- def clb(a: UInt, b: UInt, c: UInt, d: UInt): UInt =
(a & b) | (~c & d)
pression.
where clb is the function which takes a, b, c, d as
arguments and returns a wire to the output of a
5 Builtin Operators boolean circuit. The def keyword is part of Scala
and introduces a function definition, with each ar-
Chisel defines a set of hardware operators for the
gument followed by a colon then its type, and the
builtin types shown in Table 1.
function return type given after the colon following
the argument list. The equals (=) sign separates the
5.1 Bitwidth Inference function argument list from the function definition.
We can then use the block in another circuit as
Users are required to set bitwidths of ports and regis- follows:
ters, but otherwise, bit widths on wires are automat-
ically inferred unless set manually by the user. The val out = clb(a,b,c,d)
bit-width inference engine starts from the graph’s
input ports and calculates node output bit widths We will later describe many powerful ways to use
from their respective input bit widths according to functions to construct hardware using Scala’s func-
the following set of rules: tional programming support.
operation bit width
z = x + y wz = max(wx, wy)
z = x - y wz = max(wx, wy)
7 Bundles and Vecs
z = x & y wz = min(wx, wy) Bundle and Vec are classes that allow the user to ex-
z = Mux(c, x, y) wz = max(wx, wy) pand the set of Chisel datatypes with aggregates of
z = w * y wz = wx + wy other types.
z = x << n wz = wx + maxNum(n) Bundles group together several named fields of
z = x >> n wz = wx - minNum(n) potentially different types into a coherent unit, much
z = Cat(x, y) wz = wx + wy like a struct in C. Users define their own bundles by
z = Fill(n, x) wz = wx * maxNum(n) defining a class as a subclass of Bundle:
where for instance wz is the bit width of wire z, and
the & rule applies to all bitwise logical operations. class MyFloat extends Bundle {
val sign = Bool()
The bit-width inference process continues until no val exponent = UInt(8.W)
bit width changes. Except for right shifts by known val significand = UInt(23.W)
constant amounts, the bit-width inference rules spec- }
ify output bit widths that are never smaller than the
val x = new MyFloat()
input bit widths, and thus, output bit widths either val xs = x.sign
grow or stay the same. Furthermore, the width of a
register must be specified by the user either explicitly A Scala convention is to capitalize the name of new
or from the bitwidth of the reset value or the next pa- classes and we suggest you follow that convention
rameter. From these two requirements, we can show in Chisel too. The W method converts a Scala Int to
that the bit-width inference process will converge to a Chisel Width, specifying the number of bits in the
a fixpoint. type.
Vecs create an indexable vector of elements, and
Our choice of operator names was constrained by the are constructed as follows:
Scala language. We have to use triple equals === for
// Vector of 5 23-bit signed integers.
equality and =/= for inequality to allow the native
val myVec = Vec(5, SInt(23.W))
Scala equals operator to remain usable.
We are also planning to add further operators that // Connect to one element of vector.
constrain bitwidth to the larger of the two inputs. val reg3 = myVec(3)

3
Example Explanation
Bitwise operators. Valid on SInt, UInt, Bool.
val invertedX = ~x Bitwise NOT
val hiBits = x & "h_ffff_0000".U Bitwise AND
val flagsOut = flagsIn | overflow Bitwise OR
val flagsOut = flagsIn ^ toggle Bitwise XOR
Bitwise reductions. Valid on SInt and UInt. Returns Bool.
val allSet = andR(x) AND reduction
val anySet = orR(x) OR reduction
val parity = xorR(x) XOR reduction
Equality comparison. Valid on SInt, UInt, and Bool. Returns Bool.
val equ = x === y Equality
val neq = x =/= y Inequality
Shifts. Valid on SInt and UInt.
val twoToTheX = 1.S << x Logical left shift.
val hiBits = x >> 16.U Right shift (logical on UInt and& arithmetic on SInt).
Bitfield manipulation. Valid on SInt, UInt, and Bool.
val xLSB = x(0) Extract single bit, LSB has index 0.
val xTopNibble = x(15,12) Extract bit field from end to start bit position.
val usDebt = Fill(3, "hA".U) Replicate a bit string multiple times.
val float = Cat(sign,exponent,mantissa) Concatenates bit fields, with first argument on left.
Logical operations. Valid on Bools.
val sleep = !busy Logical NOT
val hit = tagMatch && valid Logical AND
val stall = src1busy || src2busy Logical OR
val out = Mux(sel, inTrue, inFalse) Two-input mux where sel is a Bool
Arithmetic operations. Valid on Nums: SInt and UInt.
val sum = a + b Addition
val diff = a - b Subtraction
val prod = a * b Multiplication
val div = a / b Division
val mod = a % b Modulus
Arithmetic comparisons. Valid on Nums: SInt and UInt. Returns Bool.
val gt = a > b Greater than
val gte = a >= b Greater than or equal
val lt = a < b Less than
val lte = a <= b Less than or equal

Table 1: Chisel operators on builtin data types.

4
(Note that we have to specify the type of the Vec ele- By folding directions into the object declarations,
ments inside the trailing curly brackets, as we have Chisel is able to provide powerful wiring constructs
to pass the bitwidth parameter into the SInt construc- described later.
tor.)
The set of primitive classes (SInt, UInt, and Bool)
plus the aggregate classes (Bundles and Vecs) all in- 9 Modules
herit from a common superclass, Data. Every object
that ultimately inherits from Data can be represented Chisel modules are very similar to Verilog modules in
as a bit vector in a hardware design. defining a hierarchical structure in the generated cir-
Bundles and Vecs can be arbitrarily nested to build cuit. The hierarchical module namespace is accessible
complex data structures: in downstream tools to aid in debugging and phys-
ical layout. A user-defined module is defined as a
class BigBundle extends Bundle { class which:
// Vector of 5 23-bit signed integers.
val myVec = Vec(5, SInt(23.W))
• inherits from Module,
val flag = Bool()
// Previously defined bundle.
val f = new MyFloat()
• contains an interface wrapped in an IO() func-
} tion and stored in a port field named io, and

Note that the builtin Chisel primitive and aggre- • wires together subcircuits in its constructor.
gate classes do not require the new when creating
As an example, consider defining your own two-
an instance, whereas new user datatypes will. A
input multiplexer as a module:
Scala apply constructor can be defined so that a user
datatype also does not require new, as described in class Mux2 extends Module {
Section 14. val io = IO(new Bundle{
val sel = Input(UInt(1.W))
val in0 = Input(UInt(1.W))
val in1 = Input(UInt(1.W))
8 Ports })
val out = Output(UInt(1.W))

io.out := (io.sel & io.in1) | (~io.sel & io.in0)

Ports are used as interfaces to hardware components. }
A port is simply any Data object that has directions
assigned to its members. The wiring interface to a module is a collection of
Chisel provides port constructors to allow a di- ports in the form of a Bundle. The interface to the
rection to be added (input or output) to an object module is defined through a field named io. For
at construction time. Simply wrap the object in an Mux2, io is defined as a bundle with four fields, one
Input() or Output() function. for each multiplexer port.
An example port declaration is as follows: The := assignment operator, used here in the body
of the definition, is a special operator in Chisel that
class Decoupled extends Bundle {
wires the input of left-hand side to the output of the
val ready = Output(Bool())
val data = Input(UInt(32.W))
right-hand side.
val valid = Input(Bool())
}
9.1 Module Hierarchy
After defining Decoupled, it becomes a new type that
We can now construct circuit hierarchies, where we
can be used as needed for module interfaces or for
build larger modules out of smaller sub-modules. For
named collections of wires.
example, we can build a 4-input multiplexer module
The direction of an object can also be assigned at in terms of the Mux2 module by wiring together three
instantation time: 2-input multiplexers:
class ScaleIO extends Bundle {
class Mux4 extends Module {
val in = new MyFloat().asInput
val io = IO(new Bundle {
val scale = new MyFloat().asInput
val in0 = Input(UInt(1.W))
val out = new MyFloat().asOutput
val in1 = Input(UInt(1.W))
}
val in2 = Input(UInt(1.W))
val in3 = Input(UInt(1.W))
The methods asInput and asOutput force all modules val sel = Input(UInt(2.W))
of the data object to the requested direction. val out = Output(UInt(1.W))

5
 }) expect(c.io.out, (if (s == 1) i1 else i0))
val m0 = Module(new Mux2()) }
m0.io.sel := io.sel(0) }
m0.io.in0 := io.in0; m0.io.in1 := io.in1 }
}
val m1 = Module(new Mux2())
m1.io.sel := io.sel(0) assignments for each input of Mux2 are set to the ap-
m1.io.in0 := io.in2; m1.io.in1 := io.in3
propriate values using poke. For this particular ex-
val m3 = Module(new Mux2()) ample, we are testing the Mux2 by hardcoding the
m3.io.sel := io.sel(1) inputs to some known values and checking if the
m3.io.in0 := m0.io.out; m3.io.in1 := m1.io.out output corresponds to the known one. To do this,
io.out := m3.io.out
on each iteration we generate appropriate inputs to
} the module and tell the simulation to assign these
values to the inputs of the device we are testing c,
We again define the module interface as io and wire step the circuit 1 clock cycle, and test the expected
up the inputs and outputs. In this case, we create value. Steps are necessary to update registers and
three Mux2 children modules, using the Module con- the combinational logic driven by registers. For pure
structor function and the Scala new keyword to create combinational paths, poke alone is sufficient to up-
a new object. We then wire them up to one another date all combinational paths connected to the poked
and to the ports of the Mux4 interface. input wire.
Finally, the following the tester is invoked by call-
ing runPeekPokeTester:
10 Running Examples
def main(args: Array[String]): Unit = {
runPeekPokeTester(() => new GCD()){
Now that we have defined modules, we will discuss (c,b) => new GCDTests(c,b)}
how we actually run and test a circuit. }
Testing is a crucial part of circuit design, and thus
in Chisel we provide a mechanism for testing circuits This will run the tests defined in GCDTests with the
by providing test vectors within Scala using tester GCD module being simulated but the Firrtl inter-
method calls which binds a tester to a module and preter. We can instead have the GCD module be
allows users to write tests using the given debug simulated by a C++ simulator generated by Verilator
protocol. In particular, users utilize: by calling the following:

• poke to set input port and state values, def main(args: Array[String]): Unit = {
runPeekPokeTester(() => new GCD(), "verilator"){
(c,b) => new GCDTests(c,b)}
• step to execute the circuit one time unit,
}

• peek to read port and state values, and

• expect to compare peeked circuit values to ex-

pected arguments. 11 State Elements
The simplest form of state element supported by
Chisel produces Firrtl intermediate representation Chisel is a positive edge-triggered register, which
(IR). Firrtl can be interpreted directly or can be can be instantiated as:
translated into Verilog, which can then be used to
val reg = Reg(next = in)
generate a C++ simulator through verilator.

For example, in the following: This circuit has an output that is a copy of the input
signal in delayed by one clock cycle. Note that we do
class Mux2Tests(c: Mux2, b: Option[TesterBackend] = None) not have to specify the type of Reg as it will be auto-
extends PeekPokeTester(c, _backend=b) {
matically inferred from its input when instantiated in
val n = pow(2, 3).toInt
for (s <- 0 until 2) {
this way. In the current version of Chisel, clock and
for (i0 <- 0 until 2) { reset are global signals that are implicity included
for (i1 <- 0 until 2) { where needed.
poke(c.io.sel, s)
poke(c.io.in1, i1)
Using registers, we can quickly define a number of
poke(c.io.in0, i0) useful circuit constructs. For example, a rising-edge
step(1) detector that takes a boolean signal in and outputs

6
true when the current value is true and the previous has been defined. Because Scala evaluates program
value is false is given by: statements sequentially, we allow data nodes to serve
as a wire providing a declaration of a node that can
def risingedge(x: Bool) = x && !Reg(next = x)
be used immediately, but whose input will be set later.
Counters are an important sequential circuit. To For example, in a simple CPU, we need to define the
construct an up-counter that counts up to a maxi- pcPlus4 and brTarget wires so they can be referenced
mum value, max, then wraps around back to zero (i.e., before defined:
modulo max+1), we write: val pcPlus4 = UInt()
val brTarget = UInt()
def counter(max: UInt) = {
val pcNext = Mux(io.ctrl.pcSel, brTarget, pcPlus4)
val x = Reg(init = 0.U(max.getWidth.W))
val pcReg = Reg(next = pcNext, init = 0.U(32.W))
x := Mux(x === max, 0.U, x + 1.U)
pcPlus4 := pcReg + 4.U
x
...
}
brTarget := addOut

The counter register is created in the counter func-

The wiring operator := is used to wire up the connec-
tion with a reset value of 0 (with width large enough
tion after pcReg and addOut are defined.
to hold max), to which the register will be initialized
when the global reset for the circuit is asserted. The
:= assignment to x in counter wires an update combi-
11.2 Conditional Updates
national circuit which increments the counter value
unless it hits the max at which point it wraps back to In our previous examples using registers, we simply
zero. Note that when x appears on the right-hand wired the combinational logic blocks to the inputs of
side of an assigment, its output is referenced, whereas the registers. When describing the operation of state
when on the left-hand side, its input is referenced. elements, it is often useful to instead specify when up-
Counters can be used to build a number of useful dates to the registers will occur and to specify these
sequential circuits. For example, we can build a pulse updates spread across several separate statements.
generator by outputting true when a counter reaches Chisel provides conditional update rules in the form
zero: of the when construct to support this style of sequen-
tial logic description. For example,
// Produce pulse every n cycles.
def pulse(n: UInt) = counter(n - 1.U) === 0.U
val r = Reg(init = 0.U(16.W))
when (cond) {
A square-wave generator can then be toggled by the r := r + 1.U
pulse train, toggling between true and false on each }
pulse:
where register r is updated at the end of the current
// Flip internal state when input true. clock cycle only if cond is true. The argument to when
def toggle(p: Bool) = {
val x = Reg(init = false.B)
is a predicate circuit expression that returns a Bool.
x := Mux(p, !x, x) The update block following when can only contain
x update statements using the assignment operator :=,
} simple expressions, and named wires defined with
// Square wave of a given period.
val.
def squareWave(period: UInt) = toggle(pulse(period/2)) In a sequence of conditional updates, the last con-
ditional update whose condition is true takes priority.
For example,
11.1 Forward Declarations when (c1) { r := 1.U }
when (c2) { r := 2.U }
Purely combinational circuits cannot have cycles be-
tween nodes, and Chisel will report an error if such leads to r being updated according to the following
a cycle is detected. Because they do not have cycles, truth table:
combinational circuits can always be constructed in a
feed-forward manner, by adding new nodes whose c1 c2 r
inputs are derived from nodes that have already been 0 0 r r unchanged
defined. Sequential circuits naturally have feedback 0 1 2
between nodes, and so it is sometimes necessary to 1 0 1
reference an output wire before the producing node 1 1 2 c2 takes precedence over c1

7
 Initial values leads to r and s being updated according to the fol-
0 0 e1 lowing truth table:
c1 c2 r s
c1 f t 0 0 3 3
0 1 2 3 // r updated in c2 block, s at top level.
when (c1) 1 0 1 1
{ r := e1 } 1 1 2 1
e2

c2 f t We are considering adding a different form of condi-

when (c2) tional update, where only a single update block will
{ r := e2 } take effect. These atomic updates are similar to Blue-
spec guarded atomic actions.
enable in

clock r Conditional update constructs can be nested and

any given block is executed under the conjunction of
out
all outer nesting conditions. For example,
when (a) { when (b) { body } }
Figure 1: Equivalent hardware constructed for con-
ditional updates. Each when statement adds another is the same as:
level of data mux and ORs the predicate into the
enable chain. The compiler effectively adds the termi- when (a && b) { body }
nation values to the end of the chain automatically. Conditionals can be chained together using when,
.elsewhen, .otherwise corresponding to if, else if
and else in Scala. For example,
Figure 1 shows how each conditional update can
be viewed as inserting a mux before the input of when (c1) { u1 }
a register to select either the update expression or .elsewhen (c2) { u2 }
the previous input according to the when predicate. .otherwise { ud }
In addition, the predicate is OR-ed into an enable is the same as:
signal that drives the load enable of the register. The
compiler places initialization values at the beginning when (c1) { u1 }
of the chain so that if no conditional updates fire in when (!c1 && c2) { u2 }
when (!(c1 || c2)) { ud }
a clock cycle, the load enable of the register will be
deasserted and the register value will not change. We introduce the switch statement for conditional
Chisel provides some syntactic sugar for other updates involving a series of comparisons against a
common forms of conditional update. The unless common key. For example,
construct is the same as when but negates its condi-
switch(idx) {
tion. In other words, is(v1) { u1 }
is(v2) { u2 }
unless (c) { body }
}

is the same as
is equivalent to:
when (!c) { body }
when (idx === v1) { u1 }
.elsewhen (idx === v2) { u2 }
The update block can target multiple registers, and
there can be different overlapping subsets of registers Chisel also allows a Wire, i.e., the output of some
present in different update blocks. Each register is combinational logic, to be the target of conditional up-
only affected by conditions in which it appears. The date statements to allow complex combinational logic
same is possible for combinational circuits (update expressions to be built incrementally. Chisel does
of a Wire). Note that all combinational circuits need a not allow a combinational output to be incompletely
default value. For example: specified and will report an error if an unconditional
r := 3.S; s := 3.S
update is not encountered for a combinational output.
when (c1) { r := 1.S; s := 1.S }
when (c2) { r := 2.S }
In Verilog, if a procedural specification of a combina-

8
 tional logic block is incomplete, a latch will silently be Here is the vending machine FSM defined with
inferred causing many frustrating bugs. switch statement:
It could be possible to add more analysis to the
Chisel compiler, to determine if a set of predicates class VendingMachine extends Module {
val io = IO(new Bundle {
covers all possibilities. But for now, we require a
val nickel = Input(Bool())
single predicate that is always true in the chain of val dime = Input(Bool())
conditional updates to a Wire. val valid = Output(Bool())
})
val s_idle :: s_5 :: s_10 :: s_15 :: s_ok :: Nil =
11.3 Finite State Machines Enum(5)
val state = Reg(init = s_idle)
A common type of sequential circuit used in digital
switch (state) {
design is a Finite State Machine (FSM). An example
is (s_idle) {
of a simple FSM is a parity generator: when (io.nickel) { state := s_5 }
when (io.dime) { state := s_10 }
class Parity extends Module {
}
val io = IO(new Bundle {
is (s_5) {
val in = Input(Bool())
when (io.nickel) { state := s_10 }
val out = Output(Bool()) })
when (io.dime) { state := s_15 }
val s_even :: s_odd :: Nil = Enum(2)
}
val state = Reg(init = s_even)
is (s_10) {
when (io.in) {
when (io.nickel) { state := s_15 }
when (state === s_even) { state := s_odd }
when (io.dime) { state := s_ok }
when (state === s_odd) { state := s_even }
}
}
is (s_15) {
io.out := (state === s_odd)
when (io.nickel) { state := s_ok }
}
when (io.dime) { state := s_ok }
}
where Enum(2) generates two UInt literals. States are is (s_ok) {
updated when in is true. It is worth noting that all state := s_idle
of the mechanisms for FSMs are built upon registers, }
}
wires, and conditional updates. io.valid := (state === s_ok)
Below is a more complicated FSM example which }
is a circuit for accepting money for a vending ma-
chine:
class VendingMachine extends Module {
val io = IO(new Bundle {
12 Memories
val nickel = Input(Bool())
val dime = Input(Bool()) Chisel provides facilities for creating both read only
val valid = Output(Bool()) }) and read/write memories.
val s_idle :: s_5 :: s_10 :: s_15 :: s_ok :: Nil =
Enum(5)
val state = Reg(init = s_idle)
when (state === s_idle) {
12.1 ROM
when (io.nickel) { state := s_5 }
when (io.dime) { state := s_10 }
Users can define read only memories with a Vec:
}
Vec(inits: Seq[T])
when (state === s_5) {
Vec(elt0: T, elts: T*)
when (io.nickel) { state := s_10 }
when (io.dime) { state := s_15 }
} where inits is a sequence of initial Data literals
when (state === s_10) { that initialize the ROM. For example, users can cre-
when (io.nickel) { state := s_15 } ate a small ROM initialized to 1, 2, 4, 8 and loop
when (io.dime) { state := s_ok }
}
through all values using a counter as an address gen-
when (state === s_15) { erator as follows:
when (io.nickel) { state := s_ok }
val m = Vec(Array(1.U, 2.U, 4.U, 8.U))
when (io.dime) { state := s_ok }
val r = m(counter(UInt(m.length.W)))
}
when (state === s_ok) {
state := s_idle We can create an n value sine lookup table using a
} ROM initialized as follows:
io.valid := (state === s_ok)
} def sinTable (amp: Double, n: Int) = {

9
 val times = val rdata = ram1p(reg_raddr)
Range(0, n, 1).map(i => (i*2*Pi)/(n.toDouble-1) - Pi)
val inits = If the same Mem address is both written and sequen-
times.map(t => SInt(round(amp * sin(t)), width = 32))
Vec(inits)
tially read on the same clock edge, or if a sequential
} read enable is cleared, then the read data is unde-
def sinWave (amp: Double, n: Int) = fined.
sinTable(amp, n)(counter(UInt(n.W))
Mem also supports write masks for subword writes.

where amp is used to scale the fixpoint values stored A given bit is written if the corresponding mask bit
in the ROM. is set.
val ram = Mem(256, UInt(32.W))
when (wen) { ram.write(waddr, wdata, wmask) }
12.2 Mem
Memories are given special treatment in Chisel since
hardware implementations of memory have many
variations, e.g., FPGA memories are instantiated 13 Interfaces & Bulk Connections
quite differently from ASIC memories. Chisel defines
a memory abstraction that can map to either sim- For more sophisticated modules it is often useful to
ple Verilog behavioral descriptions, or to instances define and instantiate interface classes while defin-
of memory modules that are available from exter- ing the IO for a module. First and foremost, inter-
nal memory generators provided by foundry or IP face classes promote reuse allowing users to capture
vendors. once and for all common interfaces in a useful form.
Chisel supports random-access memories via the Secondly, interfaces allow users to dramatically re-
Mem construct. Writes to Mems are positive-edge- duce wiring by supporting bulk connections between
triggered and reads are either combinational or producer and consumer modules. Finally, users can
positive-edge-triggered.1 make changes in large interfaces in one place reduc-
Ports into Mems are created by applying a UInt ing the number of updates required when adding or
index. A 32-entry register file with one write port and removing pieces of the interface.
two combinational read ports might be expressed as
follows:
13.1 Ports: Subclasses & Nesting
val rf = Mem(32, UInt(64.W))
when (wen) { rf(waddr) := wdata } As we saw earlier, users can define their own inter-
val dout1 = rf(waddr1)
faces by defining a class that subclasses Bundle. For
val dout2 = rf(waddr2)
example, a user could define a simple link for hand-
If the optional parameter seqRead is set, Chisel will shaking data as follows:
attempt to infer sequential read ports when the read class SimpleLink extends Bundle {
address is a Reg. A one-read port, one-write port val data = Output(UInt(16.W))
SRAM might be described as follows: val valid = Output(Bool())
}
val ram1r1w =
Mem(1024, UInt(32.W)) We can then extend SimpleLink by adding parity bits
val reg_raddr = Reg(UInt())
when (wen) { ram1r1w(waddr) := wdata }
using bundle inheritance:
when (ren) { reg_raddr := raddr }
class PLink extends SimpleLink {
val rdata = ram1r1w(reg_raddr)
val parity = Output(UInt(5.W))
}
Single-ported SRAMs can be inferred when the
read and write conditions are mutually exclusive in In general, users can organize their interfaces into
the same when chain: hierarchies using inheritance.
val ram1p = Mem(1024, UInt(32.W)) From there we can define a filter interface by nest-
val reg_raddr = Reg(UInt()) ing two PLinks into a new FilterIO bundle:
when (wen) { ram1p(waddr) := wdata }
.elsewhen (ren) { reg_raddr := raddr } class FilterIO extends Bundle {
val x = new PLink().flip
1 Current FPGA technology does not support combinational val y = new PLink()
(asynchronous) reads (anymore). The read address needs to be }
registered.

10
where flip recursively changes the “gender” of a
bundle, changing input to output and output to in-
put.
We can now define a filter by defining a filter class
extending module:
class Filter extends Module {
val io = IO(new FilterIO())
...
}

where the io field contains FilterIO.

13.2 Bundle Vectors

Beyond single elements, vectors of elements form
richer hierarchical interfaces. For example, in order
to create a crossbar with a vector of inputs, producing
a vector of outputs, and selected by a UInt input, we
utilize the Vec constructor:
Figure 2: Simple CPU involving control and data
class CrossbarIo(n: Int) extends Bundle {
val in = Vec(n, new PLink().flip()) path submodules and host and memory interfaces.
val sel = Input(UInt(sizeof(n).W))
val out = Vec(n, new PLink())
}
only to a part of the instruction and data memory
interfaces. Chisel allows users to do this with par-
where Vec takes a size as the first argument and a
tial fulfillment of interfaces. A user first defines the
block returning a port as the second argument.
complete interface to a ROM and Mem as follows:
class RomIo extends Bundle {
13.3 Bulk Connections val isVal = Input(Bool())
val raddr = Input(UInt(32.W))
We can now compose two filters into a filter block as val rdata = Output(UInt(32.W))
follows: }

class Block extends Module { class RamIo extends RomIo {

val io = IO(new FilterIO()) val isWr = Input(Bool())
val f1 = Module(new Filter()) val wdata = Input(UInt(32.W))
val f2 = Module(new Filter()) }

f1.io.x <> io.x Now the control path can build an interface in terms
f1.io.y <> f2.io.x
f2.io.y <> io.y
of these interfaces:
}
class CpathIo extends Bundle {
val imem = RomIo().flip()
where <> bulk connects interfaces of opposite gender val dmem = RamIo().flip()
between sibling modules or interfaces of same gender ...
between parent/child modules. Bulk connections }

connect leaf ports of the same name to each other.

After all connections are made and the circuit is being and the control and data path modules can be built
elaborated, Chisel warns users if ports have other by partially assigning to this interfaces as follows:
than exactly one connection to them. class Cpath extends Module {
val io = IO(new CpathIo())
...
13.4 Interface Views io.imem.isVal := ...
io.dmem.isVal := ...
Consider a simple CPU consisting of control path io.dmem.isWr := ...
...
and data path submodules and host and memory }
interfaces shown in Figure 2. In this CPU we can
see that the control path and data path each connect class Dpath extends Module {

11
 val io = IO(new DpathIo()) }
...
io.imem.raddr := ... Selecting inputs is so useful that Chisel builds it in
io.dmem.raddr := ...
and calls it Mux. However, unlike Mux2 defined above,
io.dmem.wdata := ...
... the builtin version allows any datatype on in0 and
} in1 as long as they are the same subclass of Data. In
Section 15 we will see how to define this ourselves.
We can now wire up the CPU using bulk connects as Chisel provides MuxCase which is an n-way Mux
we would with other bundles:
MuxCase(default, Array(c1 -> a, c2 -> b, ...))
class Cpu extends Module {
val io = IO(new CpuIo()) where each condition / value is represented as a tuple
val c = Module(new CtlPath())
in a Scala array and where MuxCase can be translated
val d = Module(new DatPath())
c.io.ctl <> d.io.ctl into the following Mux expression:
c.io.dat <> d.io.dat
Mux(c1, a, Mux(c2, b, Mux(..., default)))
c.io.imem <> io.imem
d.io.imem <> io.imem
c.io.dmem <> io.dmem Chisel also provides MuxLookup which is an n-way
d.io.dmem <> io.dmem indexed multiplexer:
d.io.host <> io.host
} MuxLookup(idx, default,
Array(0.U -> a, 1.U -> b, ...))
Repeated bulk connections of partially assigned con-
trol and data path interfaces completely connect up which can be rewritten in terms of:MuxCase as follows:
the CPU interface. MuxCase(default,
Array((idx === 0.U) -> a,
(idx === 1.U) -> b, ...))

14 Functional Module Creation Note that the cases (eg. c1, c2) must be in parentheses.
It is also useful to be able to make a functional inter-
face for module construction. For instance, we could 15 Polymorphism and
build a constructor that takes multiplexer inputs as
parameters and returns the multiplexer output: Parameterization
object Mux2 { Scala is a strongly typed language and uses parame-
def apply (sel: UInt, in0: UInt, in1: UInt) = {
val m = new Mux2()
terized types to specify generic functions and classes.
m.io.in0 := in0 In this section, we show how Chisel users can de-
m.io.in1 := in1 fine their own reusable functions and classes using
m.io.sel := sel parameterized classes.
m.io.out
}
} This section is advanced and can be skipped at first
reading.
where object Mux2 creates a Scala singleton object on
the Mux2 module class, and apply defines a method 15.1 Parameterized Functions
for creation of a Mux2 instance. With this Mux2 creation
function, the specification of Mux4 now is significantly Earlier we defined Mux2 on Bool, but now we show
simpler. how we can define a generic multiplexer function.
We define this function as taking a boolean condition
class Mux4 extends Module {
val io = IO(new Bundle {
and con and alt arguments (corresponding to then
val in0 = Input(UInt(1.W)) and else expressions) of type T:
val in1 = Input(UInt(1.W))
val in2 = Input(UInt(1.W)) def Mux[T <: Bits](c: Bool, con: T, alt: T): T { ... }
val in3 = Input(UInt(1.W))
val sel = Input(UInt(2.W)) where T is required to be a subclass of Bits. Scala
val out = Output(UInt(1.W)) ensures that in each usage of Mux, it can find a com-
})
io.out := Mux2(io.sel(1),
mon superclass of the actual con and alt argument
Mux2(io.sel(0), io.in0, io.in1), types, otherwise it causes a Scala compilation type
Mux2(io.sel(0), io.in2, io.in3)) error. For example,

12
Mux(c, 10.U, 11.U) class DataBundle extends Bundle {
val A = UInt(32.W)
yields a UInt wire because the con and alt arguments val B = UInt(32.W)
}
are each of type UInt.
We now present a more advanced example of pa- object FifoDemo {
rameterized functions for defining an inner product def apply () = new Fifo(new DataBundle, 32)
FIR digital filter generically over Chisel Num’s. The in- }

ner product FIR filter can be mathematically defined

as: X
y[t] = wj ∗ xj [t − j] (1) class Fifo[T <: Data] (type: T, n: Int)
j extends Module {
val io = IO(new Bundle {
where x is the input and w is a vector of weights. In val enq_val = Input(Bool())
val enq_rdy = Output(Bool())
Chisel this can be defined as:
val deq_val = Output(Bool())
def delays[T <: Data](x: T, n: Int): List[T] = val deq_rdy = Input(Bool())
if (n <= 1) List(x) else x :: Delays(RegNext(x), n-1) val enq_dat = type.asInput
val deq_dat = type.asOutput
def FIR[T <: Data with Num[T]](ws: Seq[T], x: T): T = })
(ws, Delays(x, ws.length)).zipped. val enq_ptr = Reg(init = 0.U(sizeof(n).W))
map( _ * _ ).reduce( _ + _ ) val deq_ptr = Reg(init = 0.U(sizeof(n).W))
val is_full = Reg(init = false.B)
val do_enq = io.enq_rdy && io.enq_val
where delays creates a list of incrementally increas-
val do_deq = io.deq_rdy && io.deq_val
ing delays of its input and reduce constructs a reduc- val is_empty = !is_full && (enq_ptr === deq_ptr)
tion circuit given a binary combiner function f. In val deq_ptr_inc = deq_ptr + 1.U
this case, reduce creates a summation circuit. Finally, val enq_ptr_inc = enq_ptr + 1.U
val is_full_next =
the FIR function is constrained to work on inputs of Mux(do_enq && ~do_deq && (enq_ptr_inc === deq_ptr),
type Num where Chisel multiplication and addition true.B,
are defined. Mux(do_deq && is_full, false.B, is_full))
enq_ptr := Mux(do_enq, enq_ptr_inc, enq_ptr)
deq_ptr := Mux(do_deq, deq_ptr_inc, deq_ptr)
is_full := is_full_next
15.2 Parameterized Classes
val ram = Mem(n)
when (do_enq) {
Like parameterized functions, we can also parameter-
ram(enq_ptr) := io.enq_dat
ize classes to make them more reusable. For instance, }
we can generalize the Filter class to use any kind of io.enq_rdy := !is_full
link. We do so by parameterizing the FilterIO class io.deq_val := !is_empty
ram(deq_ptr) <> io.deq_dat
and defining the constructor to take a zero argument }
type constructor function as follow:
class FilterIO[T <: Data](type: T) extends Bundle {
val x = type.asInput.flip
Figure 3: Parameterized FIFO example.
val y = type.asOutput
} It is also possible to define a generic decoupled
interface:
We can now define Filter by defining a module class
that also takes a link type constructor argument and class DecoupledIO[T <: Data](data: T)
passes it through to the FilterIO interface construc- extends Bundle {
val ready = Input(Bool())
tor: val valid = Output(Bool())
val bits = data.cloneType.asOutput
class Filter[T <: Data](type: T) extends Module {
}
val io = IO(new FilterIO(type))
...
} This template can then be used to add a handshaking
protocol to any set of signals:
We can now define a PLink based Filter as follows:
class DecoupledDemo
val f = Module(new Filter(new PLink())) extends DecoupledIO()( new DataBundle )

A generic FIFO could be defined as shown in Figure 3 The FIFO interface in Figure 3 can be now be simpli-
and used as follows: fied as follows:

13
class Fifo[T <: Data] (data: T, n: Int) Chisel: Constructing Hardware in a Scala Em-
extends Module { bedded Language. in DAC ’12.
val io = IO(new Bundle {
val enq = new DecoupledIO( data ).flip()
[2] Bachrach, J., Qumsiyeh, D., Tobenkin, M. Hard-
val deq = new DecoupledIO( data )
})
ware Scripting in Gel. in Field-Programmable
... Custom Computing Machines, 2008. FCCM ’08.
} 16th.

16 Multiple Clock Domains

Chisel 3.0 does not yet support of multiple clock do-
mains. That support will be coming shortly.

17 Acknowlegements
Many people have helped out in the design of Chisel,
and we thank them for their patience, bravery, and
belief in a better way. Many Berkeley EECS students
in the Isis group gave weekly feedback as the de-
sign evolved including but not limited to Yunsup
Lee, Andrew Waterman, Scott Beamer, Chris Celio,
etc. Yunsup Lee gave us feedback in response to
the first RISC-V implementation, called TrainWreck,
translated from Verilog to Chisel. Andrew Waterman
and Yunsup Lee helped us get our Verilog backend
up and running and Chisel TrainWreck running on
an FPGA. Brian Richards was the first actual Chisel
user, first translating (with Huy Vo) John Hauser’s
FPU Verilog code to Chisel, and later implementing
generic memory blocks. Brian gave many invaluable
comments on the design and brought a vast expe-
rience in hardware design and design tools. Chris
Batten shared his fast multiword C++ template li-
brary that inspired our fast emulation library. Huy
Vo became our undergraduate research assistant and
was the first to actually assist in the Chisel imple-
mentation. We appreciate all the EECS students who
participated in the Chisel bootcamp and proposed
and worked on hardware design projects all of which
pushed the Chisel envelope. We appreciate the work
that James Martin and Alex Williams did in writ-
ing and translating network and memory controllers
and non-blocking caches. Finally, Chisel’s functional
programming and bit-width inference ideas were in-
spired by earlier work on a hardware description lan-
guage called Gel [2] designed in collaboration with
Dany Qumsiyeh and Mark Tobenkin.

References
[1] Bachrach, J., Vo, H., Richards, B., Lee, Y., Wa-
terman, A., Avižienis, Wawrzynek, J., Asanović

14