Black Boxes and Treadle

Black boxes are a way of extending the functionality of the Chisel/Firrtl circuit. Treadle is not able to execute the verilog contained in Chisel black boxes, so instead it provides a mechanism by which the developer can implement arbitrary logic in Scala. The Treadle ScalaBlackBox API is a work in progress.

The Treadle Black Box API

A developer wishing to create a treadle blackbox must extend ScalaBlackBox. A ScalaBlackBoxFactory must also be created, this factory is what creates instance of the black box for execution.

Implementing methods

method	parameters	description
getDependencies	-	This specifies what inputs each output depends on. The simplest thing to do here is say that each output depends on all inputs (perhaps this should be a default). Without this information treadle will not guarantee to call inputChanged for the inputs before getOutput is called
inputChanged	name, value	This method will be called whenever the treadle engine has computed a new value for this input, this value provided should, most likely, be saved in an instance variable within the black box
getOutput	inputValues, tpe, outputName	This is called when value for outputName from the black box is needed by the treadle engine. It is recommended to ignore the inputValues and instead use what internal values have been saved during the inputChanged call.
clockChanged	transition, clockName	This is called by treadle whenever the value of clockName is computed by the treadle engine, i.e. it will be called even when there is no transition. The implementor should check for the transition they care about and update internal state accordingly
setParams	params	These are parameter values, the same as would be passed to a parameterized verilog black box. The implementation can use the values to configure the black box for this specific instance
outputDependencies	outputName	DO NOT USE, this is an old method scheduled for deprecation

The BlackBox factory

Treadle uses the black box factory to generate an instance of the ScalaBlackBox code. The factory currently must be provided via an OptionsManager instead of the alternative command line strings based launcher. When using the ChiselTesters drivers to run tests this looks like.

class MyUnitTest extends FreeSpec with Matchers {
  ...
  val optionsManager: TesterOptionsManager = new TesterOptionsManager {
    treadleOptions = treadleOptions.copy(
      blackBoxFactories = treadleOptions.blackBoxFactories :+ new MyBlackBoxFactory
    )
  }

  "circuit with scala black box should run" in {
    iotesters.Driver.execute( () => new MyCircuitWithBlackBox, optionsManager){ c =>
      new MyBlackBoxPeekPokeTester(c)
    } should be (true)
  }
}

For a full example see chisel-testers AccumBlackBoxSpec

Going forward.

There are a couple of ideas that will probably be implemented soon.

Preserving Internal State

The treadle engine use a DataStore object where it keeps track of the value of every Symbol in the circuit. We would like to provide a API that allows the implementor to keep the black box's internal state in that DataStore. When the snapshot/restore facility is used (currently a little known feature of REPL) these internal state variables would be restored properly.

VCD

We would like to provide an API so the implementor can record internal state changes to VCD output. This would likely be predicated on the preserving internal state API above.