Tutorial page 1

Chapter 2

The Basics

2.0.1 The Chisel Directory Structure

Once you have acquired the tutorial files you should see the following Chisel tutorial directory structure under $TUT_DIR:

** APAJ: ADAPT DIRECTORY STRUCTURE **

chisel-tutorial/ 
  Makefile 
  examples/   # chisel examples 
    Makefile  # for running examples 
    build.sbt # project description 
    Accumulator.scala ... 
  problems/   # skeletal files for tutorial problems 
    Makefile  # for running / testing problems 
    build.sbt # project description 
    Counter.scala ... 
  solutions/  # solutions to problems 
    Makefile  # for running solutions 
    build.sbt # project description 
    Counter.scala ...`

Chisel source files are distributed between examples, problems, and solutions directories. The tutorial contains the files that you will be modifying under problems/ while the solutions/ folder contains the reference implementations for each of the problems. Finally, examples/ contains source to the complete examples given in this tutorial.

Finally, the build.sbt files contain the build configuration information used to specify what version of Chisel to make your project with.

2.1.1 The Chisel Source Code

Now that you are more familiar with what your Chisel directory structure contains, let’s start by exploring one of the Chisel files. Change directory into the examples/ directory and open up the GCD.scala file with your favorite text editor.

You will notice that file is already filled out for you to perform the well known GCD algorithm and should look like:

package TutorialExamples
 
import Chisel._ 
 
class GCD extends Module { 
  val io = new Bundle { 
    val a  = UInt(INPUT,  16) 
    val b  = UInt(INPUT,  16) 
    val e  = Bool(INPUT) 
    val z  = UInt(OUTPUT, 16) 
    val v  = Bool(OUTPUT) 
  } 
  val x  = Reg(UInt()) 
  val y  = Reg(UInt()) 
  when   (x > y) { x := x - y } 
  unless (x > y) { y := y - x } 
  when (io.e) { x := io.a; y := io.b } 
  io.z := x 
  io.v := y === UInt(0) 
}

The first thing you will notice is the import Chisel._ declaration; this imports the Chisel library files that allow us to leverage Scala as a hardware construction language. After the import declarations you will see the Scala class definition for the Chisel component you are implementing. You can think of this as almost the same thing as a module declaration in Verilog.

Next we see the I/O specification for this component in the val io = new Bundle{...} definition. You will notice that the bundle takes several arguments as part of its construction, each with a specified type (UInt, Bool, etc.), a direction (either INPUT or OUTPUT), and a bit width. If a bit width is not specified, Chisel will infer the appropriate bit width for you (in this case default to 1). The io Bundle is essentially a constructor for the component that we are constructing.

The next section of code performs the actual GCD computation for the module. The register declarations for x and y tell Chisel to treat x and y as a register of type UInt().

val x = Reg(UInt()) // declares x as UInt register 
val y = Reg(UInt()) // declares y as UInt register

The when statement tells Chisel to perform the operation on a positive clock edge if the condition is true, treating the left hand assignments as synchronous. This is similar to how Verilog uses always @ (posedge clk) to specify synchronous logic.

Finally we see the output assignments for the computation for io.z and io.v. One particular thing to notice is that, we do not have to specify the width of x and y in this example. This is because Chisel does the bit width inference for you and sets these values to their appropriate widths based on the computation they are storing.

2.1.2 Running the Chisel Simulation

Now that we are familiar with the Chisel code for the GCD.scala file, let’s try to simulate it by generating the C++ models. Change directory into the Learning Journey home directory. To speed things up, we will keep sbt running. To get started:

    $ sbt

And then, run the test as follows:

> test:run-main examples.Launcher GCD

This will fire off the Chisel emulator that will run the simulation for the component defined in GCD.scala. If the simulation succeeds, you should see some debug output followed by:

test GCD Success: 3 tests passed in 29 cycles taking 0.151776 seconds
[info] [0.123] RAN 24 CYCLES PASSED
Tutorials passing: 1
[success] Total time: 6 s, completed Jan 20, 2018 2:15:14 PM

The debug output is generated by the test harness which is found in src/test/scala/examples/GCDTests.scala file. We will talk about this more later. In addition to the debug output, the build also creates C++ models which can be used to simulate and debug more complicated designs.

Next step

Tutorial page 2

---

Tutorial Home