Tools

This course makes extensive use of open-source tools.

Chisel in Jupyter Notebooks

Jupyter Notebooks are helpful for quickly getting to concepts and obviating startup overheads. We use them for both lectures and labs. With Binder, one can use the notebooks in the browser without needing to install anything. To set up a Chisel in Jupyter environment locally, we provide install.sh in our repos. In summary, it involves installing almond and including some files in the notebook. The infrastructure for Chisel in Jupyter and hosting these on Binder was developed by the chisel-bootcamp.

Scala Build Tool (sbt)

sbt is a standard tool for working with Scala projects. Not only does it handle building and launching a Scala program, but it can also pull in versioned dependencies including even the desired version of Scala itself. We use sbt for the homework assignments and project in the course, as these are full-fledged Scala projects. sbt is available on many platforms’ package managers for easy installation. As long as the version installed is sufficiently recent, sbt can even bring in the desired version of itself.

We recommend, perusing the sbt documentation, but here is a small primer of commands:

• sbt - launches the sbt shell where the following commands can be typed. Although you can launch sbt for each of the following commands individually (e.g. sbt command), we recommend working with a sbt shell open to avoid waiting for it to start up. You can exit the shell with exit or control-d.
• compile - builds the project including fetching dependencies if it hasn’t done that already. sbt will automatically compile things if necessary, so you may not need to use this command often.
• run - executes main, and if there is more than one main, you will need to specify which one with runMain. You can provide command-line arguments to your program following run.
• test - executes tests for your project, which are typically found in src/tests/scala
• console - launches a Scala REPL. Handy because it is the exact Scala version of your project (your platform’s Scala might be slightly different), and it has your project’s dependences available to be imported.
• clean - tosses out build files so a future compile can start from scratch

Using an Integrated Development Environment (IDE)

We recommend working with an IDE such as IntelliJ. Although an IDE can be intimidating at first, its benefits outweigh the downsides. We find syntax warnings and being able to look up implementations to be extremely useful. To use IntelliJ IDEA, you will need to install the Scala plugin first, and select sbt when setting up the project. For IntelliJ, we find the Community Edition (CE) to be more than sufficient.

Working With a Text Editor

If working with a text editor, we recommend installing Scala Metals. It provides many of the features we recommend the IDE for (syntax warnings & code lookups), and it is available for a fair number of editors (vim, emacs, VS Code, sublime).

Simulating Chisel Designs

There are a variety of ways to simulate a Chisel design, whether it be by using a conventional Verilog simulator or even using an FPGA. In this course, we use ChiselTest for testing, which constrains our choice of simulator. The test harness is a Scala program, and thus the simulator must interface with it. ChiselTest currently has backends to support:

• treadle simulates the design directly in Scala. It is easy to install (add it is a dependence in sbt). For small designs, it is faster than other simulators due to its near-instant startup time. We use this simulator primarily for the course.
• Verilator is a fast open-source Verilog simulator. Although we don’t set it up for this course, ChiselTest natively supports it.

Generating a Waveform from a Simulation

Using ChiselTest with treadle:

1. Add import treadle._ to the imports (and re-execute notebook cell)

2. Slightly different instructions for notebooks (labs) vs sbt (homework) due to slight version changes in ChiselTest:

   • Notebook: Inside the call to test, add Seq(WriteVcdAnnotation) (example)

   • sbt: Append .withAnnotations(Seq(WriteVcdAnnotation)) to the call to test (example)

3. Examine test_run_dir to find the directory created for the simulation, and within there find the .vcd file.

4. View the waveform. We recommend Surfer for most platforms, GTKWave is also portable, Scansion for macOS, WaveTrace for VSCode, and VCDrom for the web.