Chisel Manual

Jonathan Bachrach, Huy Vo, Krste Asanovic

EECS Department, UC Berkeley
{jrb|huytbvo|krste}@eecs.berkeley.edu

August 29, 2014

Introduction

// return value of lit if litOf is non null

def litValue(default: BigInt = BigInt(-1)): BigInt
}

This document is a manual for Chisel (Constructing

Hardware In a Scala Embedded Language). Chisel
is a hardware construction language embedded in
the high-level programming language Scala. A separate Chisel tutorial document provides a gentle introduction to using Chisel, and should be read first.
This manual provides a comprehensive overview
and specification of the Chisel language, which is really only a set of special class definitions, predefined
objects, and usage conventions within Scala. When
you write a Chisel program you are actually writing a Scala program. In this manual, we presume
that you already understand the basics of Scala. If
you are unfamiliar with Scala, we recommend you
consult one of the excellent Scala books ([3], [2]).

The uppermost levels of the node class hierarchy

are shown in Figure 1. The basic categories are:
Lit constants or literals,
Op logical or arithmetic operations,
Updateable conditionally updated nodes,
Data typed wires or ports,
Reg positive-edge-triggered registers, and
Mem memories.

Node

Nodes

Any hardware design in Chisel is ultimately represented by a graph of node objects. User code in
Chisel generate this graph of nodes, which is then
passed to the Chisel backends to be translated into
Verilog or C++ code. Nodes are defined as follows:

Lit

class Node {
// name assigned by user or from introspection
var name: String = ""
// incoming graph edges
def inputs: ArrayBuffer[Node]
// outgoing graph edges
def consumers: ArrayBuffer[Node]
// node specific width inference
def inferWidth: Int
// get width immediately inferrable
def getWidth: Int
// get first raw node
def getRawNode: Node
// convert to raw bits
def toBits: Bits
// convert to raw bits
def fromBits(x: Bits): this.type
// return lit value if inferrable else null
def litOf: Lit

Op

Updateable

Data

Reg

Mem

Figure 1: Node hierarchy.

Lits

Raw literals are represented as Lit nodes defined as

follows:
class Lit extends Node {
// original value
val inputVal: BigInt
}

Raw literals contain a collection of bits. Users do

not create raw literals directly, but instead use type
constructors defined in Section 5.

abstract class Data extends Node {

override def clone(): this.type =
this.getClass.newInstance.
asInstanceOf[this.type]
// simple conversions
def toSInt: SInt
def toUInt: UInt
def toBool: Bool
def toBits: Bits
// flatten out to leaves of tree
def flatten: Array[(String, Data)]
// port direction if leaf
def dir: PortDir
// change dir to OUTPUT
def asOutput: this.type
// change dir to INPUT
def asInput: this.type
// change polarity of dir
def flip: this.type
// assign to input
def :=[T <: Data](t: T)
// bulk assign to input
def <>(t: Data)
}

Ops

Raw operations are represented as Op nodes defined

as follows:
class Op extends Node {
// op name used during emission
val op: String
}

Ops compute a combinational function of their inputs.

Types

A Chisel graph representing a hardware design contains raw and type nodes. The Chisel type system
is maintained separately from the underlying Scala
type system, and so type nodes are interspersed
between raw nodes to allow Chisel to check and respond to Chisel types. Chisel type nodes are erased
before the hardware design is translated into C++ or
Verilog. The getRawNode operator defined in the base
Node class, skips type nodes and returns the first
raw node found. Figure 2 shows the built-in Chisel
type hierarchy, with Data as the topmost node.

The Data class has methods for converting between

types and for delegating port methods to its single
input. We will discuss ports in Section 10. Finally,
users can override the clone method in their own
type nodes (e.g., bundles) in order to reflect construction parameters that are necessary for cloning.
Data nodes can be used for four purposes:
types UInt(width = 8) record intermediate
types in the graph specifying at minimum
bitwidth (described in this section),
wires UInt(width = 8) serve as forward declarations of data allowing future conditional
updates (described in Section 6),

Data

UInt

Bits

Aggregate

Num

Bundle

ports UInt(dir = OUTPUT, width = 8) are specialized wires defining module interfaces, and additionally specify direction (described in Section 10), and

Vec

literals UInt(1) or UInt(1, 8) can be constructed using type object constructors specifying their value and optional width.

SInt

5.1

Bool

Bits

In Chisel, a raw collection of bits is represented by

the Bits type defined as follows:

Figure 2: Chisel type hierarchy.

object Bits {
def apply(dir: PortDir = null,
width: Int = -1): Bits
// create literal from BigInt or Int
def apply(value: BigInt, width: Int = -1): Bits
// create literal from String using
// base_char digit+ string format

Built-in scalar types include Bool, SInt, and UInt and

built-in aggregate types Bundle and Vec allow the
user to expand the set of Chisel datatypes with collections of other types.
Data itself is a node:

producing a Lit as shown in the leftmost subfigure

of Figure 3.
Operations return an actual operator node with
a type node combining the input type nodes. See
Figure 3 for successively more complicated examples.

def apply(value: String, width: Int = -1): Bits

}
class Bits extends Data with Updateable {
// bitwise-not
def unary_~(): Bits
// bitwise-and
def & (b: Bits): Bits
// bitwise-or
def | (b: Bits): Bits
// bitwise-xor
def ^ (b: Bits): Bits
// and-reduction
def andR(): Bool
// or-reduction
def orR(): Bool
// xor-reduction
def xorR(): Bool
// logical NOT
def unary_!(): Bool
// logical AND
def && (b: Bool): Bool
// logical OR
def || (b: Bool): Bool
// equality
def ===(b: Bits): Bool
// inequality
def != (b: Bits): Bool
// logical left shift
def << (b: UInt): Bits
// logical right shift
def >> (b: UInt): Bits
// concatenate
def ## (b: Bits): Bits
// extract single bit, LSB is 0
def apply(x: Int): Bits
// extract bit field from end to start bit pos
def apply(hi: Int, lo: Int): Bits
}

5.2

Boolean values are represented as Bools:

object Bool {
def apply(dir: PortDir = null): Bool
// create literal
def apply(value: Boolean): Bool
}
class Bool extends UInt

Bool

5.3

= 1).

Nums

is a type node which defines arithmetic operations:

class Num extends Bits {

// Negation
def unary_-(): Bits
// Addition
def +(b: Num): Num
// Subtraction
def -(b: Num): Num
// Multiplication
def *(b: Num): Num
// Greater than
def >(b: Num): Bool
// Less than
def <(b: Num): Bool
// Less than or equal
def <=(b: Num): Bool
// Greater than or equal
def >=(b: Num): Bool
}

Bits has methods for simple bit operations. Note

that ## is binary concatenation, while Cat is an nary concatentation. To avoid colliding with Scalas
builtin ==, Chisels bitwise comparison is named ===.
A field of width n can be created from a single bit
using Fill:

Signed and unsigned integers are considered subsets of fixed-point numbers and are represented by
types SInt and UInt respectively:

def Fill(n: Int, field: Bits): Bits

object SInt {
def apply (dir: PortDir = null,
width: Int = -1): SInt
// create literal
def apply (value: BigInt, width: Int = -1): SInt
def apply (value: String, width: Int = -1): SInt
}

and two inputs can be selected using Mux:

def Mux[T <: Data](sel: Bits, cons: T, alt: T): T

Constant or literal values are expressed using

Scala integers or strings passed to constructors for
the types:
//
//
//
//

is equivalent to UInt(width

Num

def Cat[T <: Data](elt: T, elts: T*): Bits

UInt(1)
UInt("ha")
UInt("o12")
UInt("b1010")

Bools

class SInt extends Num

decimal 1-bit lit from Scala Int.

hex 4-bit lit from string.
octal 4-bit lit from string.
binary 4-bit lit from string.

object UInt {
def apply(dir: PortDir = null,
width: Int = -1): UInt
// create literal
def apply(value: BigInt, width: Int = -1): UInt

UInt

Op(|)

UInt

UInt

UInt

Op(&)

Op(&)

Lit(3)

UInt

UInt

UInt

UInt

UInt

Lit(1)

Lit(1)

Lit(2)

Lit(1)

Lit(2)

a = UInt(1)

b = a & UInt(2)

b | UInt(3)

Figure 3: Chisel Op/Lit graphs constructed with algebraic expressions showing the insertion of type nodes.
def apply(value: String, width: Int = -1): UInt

val x = new MyFloat()

val xs = x.sign

The names given to a bundles elements when

they are emitted by a C++ or Verilog backend are
obtained from their bundle field names, using Scala
introspection.

class UInt extends Num {

// arithmetic right shift
override def >> (b: UInt): SInt
}

Signed fixed-point numbers, including integers, are

represented using twos-complement format.

5.4

5.5

Vecs create an indexable vector of elements:

Bundles

object Vec {
def apply[T <: Data](elts: Seq[T]): Vec[T]
def apply[T <: Data](elt0: T, elts: T*): Vec[T]
def fill[T <: Data](n: Int)(type: => T): Vec[T]
def tabulate[T <: Data](n: Int)
(type: (Int) => T): Vec[T]
def tabulate[T <: Data](n1: Int, n2: Int)
(type: (Int, Int) => T): Vec[Vec[T]]
}

Bundles group together several named fields of potentially different types into a coherent unit, much
like a struct in C:
class Bundle extends Data {
// shallow named bundle elements
def elements: ArrayBuffer[(String, Data)]
}

class Vec[T <: Data](n: Int, val type: () => T)

extends Data {
def apply(idx: UInt): T
def apply(idx: Int): T
def forall(p: T => Bool): Bool
def exists(p: T => Bool): Bool
def contains[T <: Bits](x: T): Bool
def count(p: T => Bool): UInt
def indexWhere(p: T => Bool): UInt
def lastIndexWhere(p: T => Bool): UInt
}

The name and type of each element in a Bundle

can be obtained with the elements method, and the
flatten method returns the elements at the leaves
for nested aggregates. Users can define new bundles by subclassing Bundle as follows:
class
val
val
val
}

Vecs

MyFloat extends Bundle {

sign
= Bool()
exponent
= UInt(width = 8)
significand = UInt(width = 23)

with n elements of type defined with the gen thunk.

Users can access elements statically with an Int in-

Elements are accessed using Scala field access:

dex or dynamically using a UInt index, where dynamic access creates a virtual type node (representing a read port) that records the read using the
given address. In either case, users can wire to the
result of a read as follows:

a series of conditional updates to the output value

and to spread out these updates across several separate statements. For example, the output of a Data
node can be referenced immediately, but its input
can be set later. Updateable represents a conditionally updateable node, which accumulates accesses
to the node and which can later generate muxes to
combine these accesses in the circuit.

v(a) := d

Read-only memories can be expressed as Vecs of

literals:

abstract class Updateable extends Node {

// conditional reads
def reads: Queue[(Bool, UInt)]
// conditional writes
def writes: Queue[(Bool, UInt, Node)]
// gen mux integrating all conditional writes
def genMuxes(default: Node)
override def := (x: Node): this.type
}

val rom = Vec(UInt(3), UInt(7), UInt(4), UInt(0)) {

UInt(width=3) }
val dout = rom(addr)

5.6

Bit Width Inference

Users are required to set bit widths of ports and

registers, but otherwise, bit widths on nodes are
automatically inferred unless set manually by
the user (using Extract or Cat). The bit-width
inference engine starts from the graphs input
ports and calculates node output bit widths from
their respective input bit widths according to the
following set of rules:
operation

bit width

z
z
z
z
z
z
z
z
z

wz
wz
wz
wz
wz
wz
wz
wz
wz

=
=
=
=
=
=
=
=
=

x + y
x - y
x & y
Mux(c, x, y)
w * y
x << n
x >> n
Cat(x, y)
Fill(n, x)

=
=
=
=
=
=
=
=
=

Chisel provides conditional update rules in the

form of the when construct to support this style of
sequential logic description:
object when {
def apply(cond: Bool)(block: => Unit): when
}
class when (prevCond: Bool) {
def elsewhen (cond: Bool)(block: => Unit): when
def otherwise (block: => Unit): Unit
}

max(wx, wy)
max(wx, wy)
max(wx, wy)
max(wx, wy)
wx + wy
wx + maxNum(n)
wx - minNum(n)
wx + wy
wx * maxNum(n)

manipulates a global condition stack with dynamic scope. Therefore, when creates a new condition that is in force across function calls. For example:
when

def updateWhen (c: Bool, d: Data) =

when (c) { r := d }
when (a) {
updateWhen(b, x)
}

where for instance wz is the bit width of wire z, and

the & rule applies to all bitwise logical operations.
The bit-width inference process continues until no bit width changes. Except for right shifts
by known constant amounts, the bit-width inference rules specify output bit widths that are never
smaller than the input bit widths, and thus, output
bit widths either grow or stay the same. Furthermore, the width of a register must be specified by
the user either explicitly or from the bitwidth of
the reset value. From these two requirements, we
can show that the bit-width inference process will
converge to a fixpoint.

is the same as:

when (a) {
when (b) { r := x }
}

Chisel provides some syntactic sugar for other

common forms of conditional updates:
def unless(c: Bool)(block: => Unit) =
when (!c) { block )

and

Shouldnt & return bitwidth that is min() of inputs?

def otherwise(block: => Unit) =

when (Bool(true)) { block }

Updateables

We introduce the switch statement for conditional

updates involving a series of comparisons against a
common key:

When describing the operation of wire and state

nodes, it is often useful to give the specification as

def switch(c: UInt)(block: => Unit): Unit

class Reg extends Updateable

def is(v: Bool)(block: => Unit)

where it can be constructed as follows:

val
val
val
val

Forward Declarations

Purely combinational circuits are not allowed to

have cycles between nodes, and Chisel will report
an error if such a cycle is detected. Because they
do not have cycles, legal combinational circuits can
always be constructed in a feed-forward manner,
by adding new nodes whose inputs are derived
from nodes that have already been defined. Sequential circuits naturally have feedback between nodes,
and so it is sometimes necessary to reference an
output wire before the producing node has been defined. Because Scala evaluates program statements
sequentially, we have allowed data nodes to serve
as a wire providing a declaration of a node that can
be used immediately, but whose input will be set
later. For example, in a simple CPU, we need to
define the pcPlus4 and brTarget wires so they can
be referenced before definition:
val pcPlus4 =
val brTarget =
val pcNext
=
val pcReg
=
pcPlus4
:=
...
brTarget
:=

=
=
=
=

RegUpdate(io.in)
RegReset(UInt(1, 8))
RegUpdate(io.in, UInt(1))
Reg(UInt(width = 8))

where resetVal is the value a reg takes on when

implicit reset is Bool(true).

Mems

Chisel supports random-access memories via the

Mem construct. Writes to Mems are positive-edgetriggered and reads are either combinational or
positive-edge-triggered.
object Mem {
def apply[T <: Data](type: T, depth: Int,
seqRead: Boolean = false): Mem
}
class Mem[T <: Data](type: T, depth: Int,
seqRead: Boolean = false)
extends Updateable {
def apply(idx: UInt): T
}

UInt()
UInt()
Mux(pcSel, brTarget, pcPlus4)
RegUpdate(pcNext)
pcReg + UInt(4)

Ports into Mems are created by applying a UInt index. A 32-entry register file with one write port and
two combinational read ports might be expressed
as follows:

addOut

The wiring operator := is used to wire up the connection after pcReg and addOut are defined. After
all assignments are made and the circuit is being
elaborated, it is an error if a forward declaration is
unassigned.

r1
r2
r3
r4

val rf = Mem(UInt(width = 64), 32)

when (wen) { rf(waddr) := wdata }
val dout1 = rf(waddr1)
val dout2 = rf(waddr2)

If the optional parameter seqRead is set, Chisel

will attempt to infer sequential read ports when a
Reg is assigned the output of a Mem. A one-read,
one-write SRAM might be described as follows:

Regs

The simplest form of state element supported by

Chisel is a positive-edge-triggered register defined
as follows:

val ram1r1w =
Mem(UInt(width = 32), 1024, seqRead = true)
val dout = Reg(UInt())
when (wen) { ram1r1w(waddr) := wdata }
when (ren) { dout := ram1r1w(raddr) }

object Reg {
def apply[T <: Data]
(type: T, next: T = null, init: T = null): T
}

Single-ported SRAMs can be inferred when the

read and write conditions are mutually exclusive in
the same when chain:

object RegNext {
def apply[T <: Data] (next: T, init: T = null): T
}

val ram1p =
Mem(UInt(width = 32), 1024, seqRead = true)
val dout = Reg(UInt())
when (wen) { ram1p(waddr) := wdata }
.elsewhen (ren) { dout := ram1p(raddr) }

object RegInit {
def apply[T <: Data] (init: T): T
}

If the same Mem address is both written and

sequentially read on the same clock edge, or if a
sequential read enable is cleared, then the read data
is implementation-defined.
Mem also supports write masks for subword
writes. A given bit is written if the corresponding
mask bit is set.

val
val
val
val

Bool(INPUT)
Bool(INPUT)
Bool(INPUT)
Bool(OUTPUT)

The := assignment operator, used in the body of a

module definition, is a special operator in Chisel
that wires the input of left-hand side to the output
of the right-hand side. It is typically used to connect
an output port to its definition.
The <> operator bulk connects interfaces of opposite gender between sibling modules or interfaces of same gender between parent/child modules. Bulk connections connect leaf ports using pathname matching. Connections are only made if one
of the ports is non-null, allowing users to repeatedly bulk-connect partially filled interfaces. After
all connections are made and the circuit is being
elaborated, Chisel warns users if ports have other
than exactly one connection to them.
The names given to the nodes and submodules
stored in a module when they are emitted by a C++
or Verilog backend are obtained from their module
field names, using Scala introspection.

Ports

Ports are Data derived nodes used as interfaces to

hardware modules. A port is a directional version of
a primitive Data object. Port directions are defined
as follows:
trait PortDir
object INPUT extends PortDir
object OUTPUT extends PortDir

Aggregate ports can be recursively constructed using either a vec or bundle with instances of Ports as
leaves.

11

=
=
=
=

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

val ram = Mem(UInt(width = 32), 256)

when (wen) { ram.write(waddr, wdata, wmask) }

10

sel
in0
in1
out

Modules

12

In Chisel, modules are very similar to modules in

Verilog, defining a hierarchical structure in the generated circuit. The hierarchical module namespace
is accessible in downstream tools to aid in debugging and physical layout. A user-defined module is
defined as a class which:

BlackBox

Black boxes allow users to define interfaces to circuits defined outside of Chisel. The user defines:
a module as a subclass of BlackBox and
an io field with the interface.

inherits from Module,

For example, one could define a simple ROM blackbox as:

contains an interface Bundle stored in a field

named io, and

class
val
val
val
}

wires together subcircuits in its constructor.

Users write their own modules by subclassing
Module which is defined as follows:

RomIo
isVal
raddr
rdata

extends Bundle {
= Bool(INPUT)
= UInt(INPUT, 32)
= UInt(OUTPUT, 32)

class Rom extends BlackBox {

val io = new RomIo()
}

abstract class Module {

val io: Bundle
var name: String = ""
def compileV: Unit
def compileC: Unit
}

13

and defining their own io field. For example, to

define a two input mux, we would define a module
as follows:

Printf and Sprintf

Chisel provides the ability to format and print

strings for debugging purposes. The printf and
sprintf construct are similar to their C namesakes:
they take a format string and a variable number of

class Mux2 extends Module {

val io = new Bundle{

arguments, then print or return a string, respectively. During simulation, printf prints the formatted string to the console on rising clock edges.
sprintf, on the other hand, returns the formatted
string as a bit vector.
Supported format specifiers are %b (binary number), %d (decimal number), %x (hexadecimal number),
and %s (string consisting of a sequence of 8-bit extended ASCII characters). (%% specifies a literal %.)
Unlike in C, there are no width modifiers: the bit
width of the corresponding argument determines
the width in the string representation.
The following example prints the line "0x4142
16706 AB" on cycles when c is true:

inputs
Chisel
outputs

Figure 4: DUT run using a Tester object in Scala

with stdin and stdout connected
def
def
def
def
def
def
def
def
def
def
def
def

val x = Bits(0x4142)
val s1 = sprintf("%x %s", x, x);
when (c) { printf("%d %s\n", x, s1); }

14

Assert

int(x: Int): BigInt

int(x: Bits): BigInt
reset(n: Int = 1)
step(n: Int): Int
pokeAt(data: Mem[T], index: Int, x: BigInt)
poke(data: Bits, x: BigInt)
poke(data: Aggregate, x: Array[BigInt])
peekAt(data: Mem[T], index: Int)
peek(data: Bits): BigInt
peek(data: Aggregate): Array[BigInt]
expect (good: Boolean, msg: String): Boolean
expect (data: Bits, target: BigInt): Boolean

Runtime assertions are provided by the assert construct. During simulation, if an assertions argument is false on a rising clock edge, an error is
printed and simulation terminates. For example,
the following will terminate simulation after ten
clock cycles:

which binds a tester to a module and allows users

to write tests using the given debug protocol. In
particular, users utilize:

val x = Reg(init = UInt(0, 4))

x := x + UInt(1)
assert(x < UInt(10))

15

DUT

Main and Testing

poke

to set input port and state values,

step

to execute the circuit one time unit,

peek

to read port and state values, and

expect to compare peeked circuit values to expected arguments.

Users connect tester instances to modules using:

In order to construct a circuit, the user calls

chiselMain from their top level main function:

object chiselMainTest {
def apply[T <: Module]
(args: Array[String], comp: () => T)(
tester: T => Tester[T]): T
}

object chiselMain {
def apply[T <: Module]
(args: Array[String], comp: () => T): T
}

When --test is given as an argument to chiselMain, a

tester instance runs the Design Under Test (DUT) in
a separate process with stdin and stdout connected
so that debug commands can be sent to the DUT
and responses can be received from the DUT as
shown in Figure 4.
For example, in the following:

which when run creates C++ files named module_name.cpp and module_name.h in the directory specified with --targetDir dir_name argument.
Testing is a crucial part of circuit design, and
thus in Chisel we provide a mechanism for testing
circuits by providing test vectors within Scala using
subclasses of the Tester class:

class Mux2Tests(c: Mux2) extends Tester(c) {

val n = pow(2, 3).toInt
for (s <- 0 until 2) {
for (i0 <- 0 until 2) {
for (i1 <- 0 until 2) {
poke(c.io.sel, s)
poke(c.io.in1, i1)

class Tester[T <: Module]

(val c: T, val isTrace: Boolean = true) {
var t: Int
var ok: Boolean
val rnd: Random
def int(x: Boolean): BigInt

dat_t<w> (val_t val);

template <int sw>
dat_t<w> mask(dat_t<sw> fill, int n);
template <int dw>
dat_t<dw> mask(int n);
template <int n>
dat_t<n> mask(void);
dat_t<w> operator + ( dat_t<w> o );
dat_t<w> operator - ( dat_t<w> o );
dat_t<w> operator - ( );
dat_t<w+w> operator * ( dat_t<w> o );
dat_t<w+w> fix_times_fix( dat_t<w> o );
dat_t<w+w> ufix_times_fix( dat_t<w> o );
dat_t<w+w> fix_times_ufix( dat_t<w> o );
dat_t<1> operator < ( dat_t<w> o );
dat_t<1> operator > ( dat_t<w> o );
dat_t<1> operator >= ( dat_t<w> o );
dat_t<1> operator <= ( dat_t<w> o );
dat_t<1> gt ( dat_t<w> o );
dat_t<1> gte ( dat_t<w> o );
dat_t<1> lt ( dat_t<w> o );
dat_t<1> lte ( dat_t<w> o );
dat_t<w> operator ^ ( dat_t<w> o );
dat_t<w> operator & ( dat_t<w> o );
dat_t<w> operator | ( dat_t<w> o );
dat_t<w> operator ~ ( void );
dat_t<1> operator ! ( void );
dat_t<1> operator && ( dat_t<1> o );
dat_t<1> operator || ( dat_t<1> o );
dat_t<1> operator == ( dat_t<w> o );
dat_t<1> operator == ( datz_t<w> o );
dat_t<1> operator != ( dat_t<w> o );
dat_t<w> operator << ( int amount );
dat_t<w> operator << ( dat_t<w> o );
dat_t<w> operator >> ( int amount );
dat_t<w> operator >> ( dat_t<w> o );
dat_t<w> rsha ( dat_t<w> o);
dat_t<w>& operator = ( dat_t<w> o );
dat_t<w> fill_bit(val_t bit);
dat_t<w> fill_byte
(val_t byte, int nb, int n);
template <int dw, int n>
dat_t<dw> fill( void );
template <int dw, int nw>
dat_t<dw> fill( dat_t<nw> n );
template <int dw>
dat_t<dw> extract();
template <int dw>
dat_t<dw> extract(val_t e, val_t s);
template <int dw, int iwe, int iws>
dat_t<dw> extract
(dat_t<iwe> e, dat_t<iws> s);
template <int sw>
dat_t<w> inject
(dat_t<sw> src, val_t e, val_t s);
template <int sw, int iwe, int iws>
dat_t<w> inject
(dat_t<sw> src,
dat_t<iwe> e, dat_t<iws> s);
template <int dw>
dat_t<dw> log2();
dat_t<1> bit(val_t b);
val_t msb();
template <int iw>
dat_t<1> bit(dat_t<iw> b)
}

poke(c.io.in0, i0)
step(1)
expect(c.io.out, (if (s == 1) i1 else i0))
}
}
}
}

assignments for each input of Mux2 is set to the appropriate values using poke. For this particular example, we are testing the Mux2 by hardcoding the
inputs to some known values and checking if the
output corresponds to the known one. To do this,
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,
step the circuit, and test the expected value. Finally,
the following shows how the tester is invoked:
chiselMainTest(args + "--test", () => new Mux2()){
c => new Mux2Tests(c)
}

Finally, command arguments for chiselMain* are

as follows:
--targetDir
--genHarness
--debug
--compile
--test
--backend v
--backend c
--vcd

16

target pathname prefix

generate harness file for C++
put all wires in C++ class file
compiles generated C++
runs tests using C++ app
generate verilog
generate C++ (default)
enable vcd dumping

C++ Emulator

The C++ emulator is based on a fast multiword

library using C++ templates. A single word is defined by val_t as follows:
typedef uint64_t val_t;
typedef int64_t sval_t;
typedef uint32_t half_val_t;

and multiwords are defined by dat_t as follows:

template <int w>
class dat_t {
public:
const static int n_words;
inline int width ( void );
inline int n_words_of ( void );
inline bool to_bool ( void );
inline val_t lo_word ( void );
inline unsigned long to_ulong ( void );
std::string to_str ();
dat_t<w> ();
template <int sw>
dat_t<w> (const dat_t<sw>& src);
dat_t<w> (const dat_t<w>& src);

reused.

template <int w, int sw>

dat_t<w> DAT(dat_t<sw> dat);
template <int w>
dat_t<w> LIT(val_t value);
template <int w> dat_t<w>
mux ( dat_t<1> t, dat_t<w> c, dat_t<w> a )

18

Chisel 2.0 introduced support of multiple clock domains.

where w is the bit width parameter.

The Chisel compiler compiles top level modules
into a single flattened mod_t class that can be created
and executed:

18.1

Creating Clock domains

In order to use multiple clock domains, users must

create multiple clocks. In Chisel, clocks are first
class nodes created with a reset signal parameter
and defined as follows:

class mod_t {
public:
// initialize module
virtual void init (void) { };
// compute all combinational logic
virtual void clock_lo (dat_t<1> reset) { };
// commit state updates
virtual void clock_hi (dat_t<1> reset) { };
// print printer specd node values to stdout
virtual void print (FILE* f) { };
// scan scanner specd node values from stdin
virtual bool scan (FILE* f) { return true; };
// dump vcd file
virtual void dump (FILE* f, int t) { };
};

class Clock (reset: Bool) extends Node {

def reset: Bool // returns reset pin
}

In Chisel there is a builtin implicit clock that state

elements use by default:
var implicitClock = new Clock( implicitReset )

The clock for state elements and modules can

be defined using an additional named parameter
called clock:

Either the Chisel compiler can create a harness

or the user can write a harness themselves. The
following is an example of a harness for a CPU
module:

Reg(... clock: Clock = implicitClock)

Mem(... clock: Clock = implicitClock)
Module(... clock: Clock = implicitClock)

#include "cpu.h"
int main (int argc, char* argv[]) {
cpu_t* c = new cpu_t();
int lim = (argc > 1) ? atoi(argv[1]) : -1;
c->init();
for (int t = 0; lim < 0 || t < lim; t++) {
dat_t<1> reset = LIT<1>(t == 0);
if (!c->scan(stdin)) break;
c->clock_lo(reset);
c->clock_hi(reset);
c->print(stdout);
}
}

17

Multiple Clock Domains

18.2

Crossing Clock Domains

There are two ways that circuits can be defined to

send data between clock domains. The first and
most primitive way is by using a synchronizer circuit comprised of two registers as follows:
// signalA is in clock domain clockA,
// want a version in clockB as signalB
val s1 = Reg(init = UInt(0), clock = clockB)
val s2 = Reg(init = UInt(0), clock = clockB)
s1
:= signalA
s2
:= s1;
signalB := s2

Verilog

Due to metastability issues, this technique is limited

to communicating one bit data between domains.
The second and more general way to send data
between domains is by using an asynchronous
queue:

Chisel generates Verilog when the -v argument is

passed into chiselMain. For example, from SBT, the
following
run --v

class AsyncQueue[T<:Data](gen: T, depth: Int, enq_clk:

Clock, deq_clock: Clock)
extends Module

would produce a single Verilog file named modulename.v in the target directory. The file will contain
one module per module defined as submodules of
the top level module created in chiselMain. Modules
with the same interface and body are cached and

We can then get a version of signalA from clock

domains clockA to clockB by specifying the stan-

10

dard queue parameters and the two clocks and then

using the standard decoupled ready/valid signals:

dut.fastClock_cnt = 0;
dut.slowClock = 6;
dut.slowClock_cnt = 0;
for (int i = 0; i < 12; i ++)
dut.reset();
for (int i = 0; i < 96; i ++)
dut.clock(LIT<1>(0));

val queue = new AsyncQueue(Uint(width = 32), 2, clockA,

clockB)
fifo.enq.bits := signalA
signalB
:= fifo.deq.bits
fifo.valid
:= condA
fifo.ready
:= condB
...

18.3.2

18.3

In Verilog,

Backend Specific Multiple Clock

Domains

Chisel creates a new port for each clock / reset,

Clock domains can be mapped to both the C++

and Verilog backends in a domain-specific manner. For the purposes of showing how to drive a
multi clock design, consider the example of hardware with two modules communicating using an
AsyncQueue with each module on separate clocks:
fastClock and slowClock.
18.3.1

Verilog

Chisel wires all the clocks to the top module,

and
the user must create an always block clock
driver for every clock i.
The following is a Verilog example of a top level
harness to drive the slowClock / fastClock example
circuit:

C++

In the C++ backend, for every clock i there is a

module emulator;
reg fastClock = 0, slowClock = 0,
resetFast = 1, resetSlow = 1;
wire [31:0] add, mul, test;
always #2 fastClock = ~fastClock;
always #4 slowClock = ~slowClock;
initial begin
#8
resetFast = 0;
resetSlow = 0;
#400
$finish;
end
ClkDomainTest dut (
.fastClock(fastClock),
.slowClock(slowClock),
.io_resetFast(resetFast),
.io_resetSlow(resetSlow),
.io_add(add), .io_mul(mul), .io_test(test));
endmodule

uint64_t clk_i field representing the clock is

period,
uint63_t clk_i_cnt field representing the
clock is current count,
clock_lo_i and clock_hi_i,
int reset() function which ensures that all
clock_lo and clock_hi functions are called at
least once, and
int clock(reset) function which computes
min delta, invokes appropriate clock_lo and
clock_his and returns min delta used.
In order to set up a C++ simulation, the user
initializes all period fields to desired period

See
http://www.asic-world.com/verilog/
verifaq2.html for more information about

initializes all count fields to desired phase,

simulating clocks in Verilog.

calls reset and then

19

repeated calls clock to step the simulation.

The following is a C++ example of a main function
for the slowClock / fastClock example:

Extra Stuff

def ListLookup[T <: Bits]

(addr: UInt, default: List[T],
mapping: Array[(UInt, List[T])]): List[T]

int main(int argc, char** argv) {

ClkDomainTest_t dut;
dut.init(1);
dut.clk = 2;
dut.clk_cnt = 1;
dut.fastClock = 4;

def Lookup[T <: Data]

(addr: UInt, default: T,
mapping: Seq[(UInt, T)]): T
// n-way multiplexor

11

def MuxCase[T <: Data]

(default: T, mapping: Seq[(Bool, T)]): T

// Returns the reverse the input signal

def Reverse(in: UInt): UInt

// n-way indexed multiplexer:

def MuxLookup[S <: UInt, T <: Data]
(key: S, default: T, mapping: Seq[(S, T)]): T

// returns the one hot encoding of

// the input UInt
def UIntToOH(in: UInt, width: Int): UInt
// does the inverse of UIntToOH
def OHToUInt(in: UInt): UInt
def OHToUInt(in: Seq[Bool]): UInt

// create n enum values of given type

def Enum[T <: UInt]
(n: Int)(type: => T): List[T]

// Builds a Mux tree out of the input

// signal vector using a one hot encoded
// select signal. Returns the output of
// the Mux tree
def Mux1H[T <: Data]
(sel: UInt, in: Vec[T]): T
def Mux1H[T <: Data]
(sel: Vec[Bool], in: Vec[T]): T

// create enum values of given type and names

def Enum[T <: UInt]
(l: Symbol *)(type: => T): Map[Symbol, T]
// create enum values of given type and names
def Enum[T <: UInt]
(l: List[Symbol])(type: => T): Map[Symbol, T]

20
20.1

// Builds a Mux tree under the

// assumption that multiple
// select signals can be enabled.
// Priority is given to the first
// select signal. Returns the output
// of the Mux tree.
def PriorityMux[T <: Data]
(sel: UInt, in: Seq[T]): T
def PriorityMux[T <: Data]
(sel: Seq[UInt], in: Seq[T]): T

Standard Library
Math

// Returns the log base 2 of the input

// Scala Integer rounded up
def log2Up(in: Int): Int
// Returns the log base 2 of the input
// Scala Integer rounded down
def log2Down(in: Int): Int

// Returns the bit position of the

// trailing 1 in the input vector with
// the assumption that multiple bits of
// the input bit vector can be set
def PriorityEncoder(in: UInt): UInt
def PriorityEncoder(in: Seq[Bool]): UInt

// Returns true if the input Scala Integer

// is a power of 2
def isPow2(in: Int): Boolean

// Returns the bit position of the

// trailing 1 in the input vector with
// the assumption that only one bit in
// the input vector can be set
def PriorityEncoderOH(in: UInt): UInt
def PriorityEncoderOH(in: Seq[Boo]): UInt

// linear feedback shift register

def LFSR16(increment: Bool = Bool(true)): UInt

20.2

Sequential

// Returns the n-cycle delayed version

// of the input signal
// Has an optional enable signal defaulting to true
def ShiftRegister[T <: Data](in: T, n: Int, en =
Bool(true)): T

20.4

// Adds a ready-valid handshaking

// protocol to any interface. The
// standard used is that the
// consumer uses the flipped
// interface.
class DecoupledIO[+T <: Data](type: T)
extends Bundle {
val ready = Bool(INPUT)
val valid = Bool(OUTPUT)
val bits = data.asOutput
}

def Counter(cond: Bool, n: Int) = {

val c = RegReset(UInt(0, log2Up(n)))
val wrap = c === UInt(n-1)
when (cond) {
c := Mux(Bool(!isPow2(n)) && wrap, UInt(0),
c + UInt(1))
}
(c, wrap && cond)
}

20.3

Decoupled

UInt

// Adds a valid protocol to any

// interface. The standard used is
// that the consumer uses the
// fliped interface.
class ValidIO[+T <: Data](type: T)
extends Bundle {
val valid = Bool(OUTPUT)
val bits = data.asOutput

// Returns the number of bits set in the

// input signal. Causes an exception if
// the input is wider than 32 bits.
def PopCount(in: UInt): UInt

12

[3] Payne, A., Wampler, D. Programming Scala by

OReilly books.

}
// Hardware module that is used to
// sequence n producers into 1 consumer.
// Priority is given to lower
// producer
// Example usage:
//
val arb = new Arbiter(UInt(), 2)
//
arb.io.in(0) <> producer0.io.out
//
arb.io.in(1) <> producer1.io.out
//
consumer.io.in <> arb.io.out
class Arbiter[T <: Data](type: T, n: Int)
extends Module
// Hardware module that is used to
// sequence n producers into 1 consumer.
// Producers are chosen in round robin
// order
// Example usage:
//
val arb = new RRArbiter(UInt(), 2)
//
arb.io.in(0) <> producer0.io.out
//
arb.io.in(1) <> producer1.io.out
//
consumer.io.in <> arb.io.out
class RRArbiter[T <: Data](type: T, n: Int)
extends Module
// Generic hardware queue. Required
// parameter entries controls the
// depth of the queues. The width of
// the queue is determined from the
// inputs.
// Example usage:
//
val q = new Queue(UInt(), 16)
//
q.io.enq <> producer.io.out
//
consumer.io.in <> q.io.deq
class Queue[T <: Data]
(type: T, entries: Int,
pipe: Boolean = false,
flow: Boolean = false
flushable: Boolean = false)
extends Module
// A hardware module that delays data
// coming down the pipeline by the
// number of cycles set by the
// latency parameter. Functionality
// is similar to ShiftRegister but
// this exposes a Pipe interface.
// Example usage:
//
val pipe = new Pipe(UInt())
//
pipe.io.enq <> produce.io.out
//
consumer.io.in <> pipe.io.deq
class Pipe[T <: Data]
(type: T, latency: Int = 1) extends Module

References
[1] Bachrach, J., Vo, H., Richards, B., Lee, Y., Waterman, A., Aviienis, Wawrzynek, J., Asanovic
Chisel: Constructing Hardware in a Scala Embedded Language in DAC 12.
[2] Odersky, M., Spoon, L., Venners, B. Programming in Scala by Artima.

13