Treadle -- A Chisel/Firrtl Execution Engine

Treadle is an experimental circuit simulator that executes low Firrtl IR. It is based on earlier work on the firrtl_interpreter It will be one of the standard back-ends available as part of the chisel-testers project, and thus one of the tools in the freechipsproject/chisel3 hardware synthesis toolbox. This project provides a test harness supporting a peek, poke expect model.
It also provides a interactive simulator shell or repl (see treadle.sh) that allows fine grained incremental execution of a circuit. In combination with a scala debugger such as Eclipse or IntelliJ it can be a very powerful way of analyzing problematic behavior.

Chisel3 is a high-level functional circuit generator. It produces Flexible Intermediate Representation for RTL or FIRRTL. The Firrtl project parses and transforms firrtl. It also provides mechanisms for emitting verilog, for processing by downstream toolchains. Treadle parses and execute the LoFirrtl subset of Firrtl. Treadle has a short spin up time and is close to the performance of verilator simulations. It can be useful for an initial debugging of Chisel circuits and is also used for other forms of circuit analysis.

Using Treadle

Attach it to your project

If you are using the freechipsproject/chisel-testers you will have access to Treadle through it's dependency declarations.

If chisel-testers is not part of your tool chain then you must add the dependency explicitly. To do so, in your project build.sbt add a dependency on

"edu.berkeley.cs" %% "treadle" % "1.1-SNAPSHOT"

There are a number of different ways to specify this dependency in the build.sbt file. If you have based your circuit on the Chisel-template the addition should look like

libraryDependencies ++= Seq(
  "edu.berkeley.cs" %% "chisel3" % chiselVersion,
  "edu.berkeley.cs" %% "chisel-iotesters" % "1.0",
  "edu.berkeley.cs" %% "treadle" % "1.1-SNAPSHOT",
  "org.scalatest" %% "scalatest" % "3.2.8" % "test",
  "org.scalacheck" %% "scalacheck" % "1.12.4")

for other usage consult sbt documentation

Use the Tester Metaphor

The easiest way to invoke the interpreter is through a test based harness. The InterpretiveTester is very similar to the chisel ClassicTester, it's api consists of poke, peek and expect statements. Here is an example of a GCD Circuit

import chisel3._
import treadle.TreadleTester
import org.scalatest.{Matchers, FlatSpec}

object GCDCalculator {
  def computeGcd(a: Int, b: Int): (Int, Int) = {
    var x = a
    var y = b
    var depth = 1
    while(y > 0 ) {
      if (x > y) {
        x -= y
      }
      else {
        y -= x
      }
      depth += 1
    }
    (x, depth)
  }
}

class GCD extends Module {
  val io = IO(new Bundle {
    val a  = Input(UInt(16.W))
    val b  = Input(UInt(16.W)))
    val e  = Input(Bool())
    val z  = Output(UInt(16.W))
    val v  = Output(Bool())
  })
  val x  = Reg(UInt())
  val y  = Reg(UInt())
  when(x > y) { x := x - y }
    .elsewhen(x <= y) { y := y - x }
  when (io.e) { x := io.a; y := io.b }
  io.z := x
  io.v := y === UInt(0)
}

class TreadleUsageSpec extends FlatSpec with Matchers {

  "GCD" should "return correct values for a range of inputs" in {
    val s = Driver.emit(() => new GCD)

    val tester = TreadleTester(s)

    for {
      i <- 1 to 100
      j <- 1 to 100
    } {
      tester.poke("io_a", i)
      tester.poke("io_b", j)
      tester.poke("io_e", 1)
      tester.step()
      tester.poke("io_e", 0)

      var cycles = 0
      while (tester.peek("io_v") != BigInt(1)) {
        tester.step()
        cycles += 1
      }
      tester.expect("io_z", BigInt(GCDCalculator.computeGcd(i, j)._1))
      // uncomment the println to see a lot of output
      // println(f"GCD(${i}%3d, ${j}%3d) => ${interpretiveTester.peek("io_z")}%3d in $cycles%3d cycles")
    }
    tester.report()
  }
}

Style conventions ScalaFmt

Treadle is the first repo in the chisel family to use the ScalaFmt code formatter. The plan going forward from 12/9/2019 is that all Scala code in PRs to Treadle after that date must be formatted using the specification in the .scalafmt.conf file. Doing the formatting is simple and can be done via IntelliJ or sbt. More details can be found on the link above. For the present we are also interested in comments on the formatting decisions we have made. Keep in mind that there is no set of rules that will satisfy everyone.

About ports and names

The firrtl transformations that result in LoFirrtl alter the names of ports. What would be io.a becomes io_a and so forth.