Extending Data Types or way to add information

Question

It appears that most/all of the Data types in Chisel are sealed classes which do not allow a user to extend from them. Is it possible to add information regarding some user defined fields or to add support in the future?

I think there are a few cases where it could be helpful to have additional information:

Port descriptions possibly for documentation
Voltage levels/biases
- If you are doing some chip top level connections you may have to make certain connection
- Also many times signals will have a set_dont_touch (an SDC, not to be confused with Chisel dontTouch) placed on them, so it may be possible to add these for auto SDC constraints.
Modeling purposes
- Chisel obviously doesn't deal with behavioral modeling, but there are times where a Verilog/SV real is used for modeling. This could be used to print out where these signals are for any post processing.

I don't expect Chisel to handle all of the actual cases (such as making the document or dealing with connections), but if these members can be added/extended a user can either check these during construction and/or after elaboration for additional flows.

Thanks

Jack Koenig Jack Koenig · Accepted Answer · 2020-09-22T17:08:57

Chisel and FIRRTL have a fairly robust annotation system for handling such metadata. It is an area of active development, the handling of annotating instances (rather than modules) is improved in soon-to-be-released Chisel 3.4.0 / FIRRTL 1.4.0. That being said, I can provide a simple example to give a flavor of how it works

Basically, FIRRTL has this notion of an Annotation which can be associated with zero, one, or many Targets. A Target is the name of a hardware component (like a register or wire) or a module. This is exactly how Chisel's dontTouch is implemented

import chisel3._
import chisel3.stage._
import firrtl.annotations.JsonProtocol
import firrtl.transforms.DontTouchAnnotation

class Foo extends Module {
  val io = IO(new Bundle {
    val in = Input(Bool())
    val out = Output(Bool())
  })
  dontTouch(io)

  io.out := ~io.in
}


val resultAnnos = (new ChiselStage).run(ChiselGeneratorAnnotation(() => new Foo) :: Nil)

val dontTouches = resultAnnos.collect { case dt: DontTouchAnnotation => dt }
println(JsonProtocol.serialize(dontTouches))
/* Prints:
[
  {
    "class":"firrtl.transforms.DontTouchAnnotation",
    "target":"~Foo|Foo>io_in"
  },
  {
    "class":"firrtl.transforms.DontTouchAnnotation",
    "target":"~Foo|Foo>io_out"
  }
]
*/

Note that this is fully extensible, it is fairly straightforward (though not well-documented) to define your own "dontTouch-like" API. Unfortunately, this flow does not have as much documentation as the Chisel APIs, but the overall structure is there and in heavy use in projects like FireSim (https://fires.im/).

A common use of annotations is to associate certain metadata with annotations (like physical design information), propagate it through compilation, and then emit a file in whatever format to hook into follow on flows.

Any exciting feature also coming in Chisel 3.4 that helps with this is the new "CustomFileEmission" API. When writing custom annotations it will be possible to tell FIRRTL how to emit the annotation such that you could, for example, have some annotation with physical design information and emit a TCL file.

Extending Data Types or way to add information

1 Answers