chisel toolchain - lu-ping/chisel3 GitHub Wiki

How to build and test in simulation an interesting chisel circuit.

The Cast

There are three kinds of players here

  • The Chisel developers: People who invented and built the toolchain
  • The Chisel Library Developers: People who have added functionality and domain specific utilities, e.g. DSP tools for chisel
  • The Circuit Developer: Will assume for the moment this means you. You have a circuit you want to build.

The Tools

  • Chisel: A front-end circuit generator that implements an embedded Scala circuit DSL which compiles into a Firrtl file
  • Firrtl: An extensible multi-pass compiler that lowers high level firrtl into lower firrtl or to verilog
  • Firrtl Interpreter: A Scala level simulator that executes low firrtl.
  • chisel-

The Circuit and Its tests

  • Device Under Test or the DUT: written using Chisel in Scala
  • Device Tester: an subclass of PeekPokeTester that allows setting DUT's inputs, testing its outputs and stepping the clock
  • Device Launcher: Most commonly done in the form of a class that extends a scalatest

Act 1. Preparing to test

  1. ChiselerX checkouts the ucb-bar/chisel-template and follows the instructions, renaming it and changing it to be a new git project
  2. They decide to use the ucb-bar/dsptools library, which simply requires that they add a new dependency line in their build.sbt file in the root directory
  3. They create a DUT.scala and in it create a DUT Chisel Module, using constructs from the dsp library, including:
  4. annotations
  5. instances of black boxes
  6. They create a device tester which takes a DUT and pokes its input and outputs and steps it
  7. They create a launcher for the tester based on the Scalatest library
  8. They execute the launcher which kicks off the following flurry of activity

Act 2. Execution

  1. Options for the execution are parsed and assembled into individual configurations for each part of the execution toolchain
  2. The circuit is elaborated.
  3. The circuit is parsed
  4. An internal graph of the circuit is generated
  5. Annotations of circuit components are collected
  6. References to black boxes are checked.
  7. firrtl interpreter requires blackbox implementations be scala classes contained in black box factories
  8. verilator requires black boxes be made available as a directory of verilog implementation files
  9. The library registers any custom passes it requires with a firrtl configuration object
  10. The circuit is emitted, i.e. serialized as text. That text may be saved to disk
  11. The firrtl compiler is launched
  12. flags indicating whether it should produces low firrtl or verilog
  13. custom passes must be available as transformation passes
  14. annotations must be available as firrtl annotation classes

Act 2 with firrtl backend

  1. A firrtl interpreter is created
  2. blackbox factories must be passed as Seq of blackbox factories
  3. various other flags come in as interpreter specific options for things like verbosity, and whether to log as a vcd file
  4. The DUTTester communicates with the interpreter instance

Act 2. with verilator

  1. verilator is called to build the verilog generated by the firrtl compiler
  2. blackbox factories must be passed as directory of black box implementations written in verilog
  3. numberous other flags that control compilation options to verilator
  4. verilator builds one or more c++ files that implement a simulator
  5. c++ is called to compile the simulator into an executable binary
  6. A separate process is launched with the simulator connected to tester process via IPC
  7. The DUTTester communicates with the simulator instance over the IPC channels