Add optional group API

[seldridge]

Add optional groups.

Example

Chisel:

object A extends group.Declaration(group.Convention.Bind) {
  object B extends group.Declaration(group.Convention.Bind)
}

class Foo extends RawModule {
  val a = IO(Input(Bool()))

  group(A) {
    val w = WireInit(a)
    dontTouch(w)
    group(A.B) {
      val x = WireInit(w)
      dontTouch(x)
    }
  }

}

Output FIRRTL:

FIRRTL version 3.2.0
circuit Foo :%[[
  {
    "class":"firrtl.transforms.DontTouchAnnotation",
    "target":"~Foo|Foo>w"
  },
  {
    "class":"firrtl.transforms.DontTouchAnnotation",
    "target":"~Foo|Foo>x"
  }
]]
  declgroup A, bind :
    declgroup B, bind :
  module Foo :
    input a : UInt<1>

    group A:
      wire w : UInt<1>
      connect w, a
      group B:
        wire x : UInt<1>
        connect x, w

Output Verilog:

// Generated by CIRCT firtool-1.56.1-32-g4da6a4d83
module Foo_A_B(
  input _w
);

  wire x = _w;
endmodule

module Foo_A(
  input _a
);

  wire w = _a;
  wire w_probe = w;
endmodule

module Foo(
  input a
);

endmodule


// ----- 8< ----- FILE "groups_Foo_A_B.sv" ----- 8< -----

// Generated by CIRCT firtool-1.56.1-32-g4da6a4d83
`include "groups_Foo_A.sv"
`ifndef groups_Foo_A_B
`define groups_Foo_A_B
bind Foo Foo_A_B foo_A_B (
  ._w (Foo.foo_A.w_probe)
);
`endif

// ----- 8< ----- FILE "groups_Foo_A.sv" ----- 8< -----

// Generated by CIRCT firtool-1.56.1-32-g4da6a4d83
`ifndef groups_Foo_A
`define groups_Foo_A
bind Foo Foo_A foo_A (
  ._a (a)
);
`endif

Release Notes

Add optional groups. This is a feature that can be used to add optional verification functionality, e.g., asserts or debug code, that does not affect the main design. These groups are lowered to FIRRTL Optional Groups (see: chipsalliance/firrtl-spec#108) with the "bind" convention.

[seldridge]

The documentation will fail until firtool has the LowerGroups pass on by default. This is the case for firtool top-of-tree, but not on a published release, yet.

[lsteveol]

Hey Schuyler, thanks for working on this. Do you guys have an idea when this will make it into a Chisel v6 release (v6.0.0-M4 I assume)?

[seldridge]

Hey Schuyler, thanks for working on this. Do you guys have an idea when this will make it into a Chisel v6 release (v6.0.0-M4 I assume)?

That's a @jackkoenig question. I think we're probably ready for a true 6.0 release and not a milestone at this point.

[jackkoenig]

This is awesome, nice work Schuyler! I've included some suggestions, but overall looks really good.