[FIRRTL] Add enabled layers to FModuleOp (#6627)

* [FIRRTL] Add layer colors to FModuleOp

Add the ability for FIRRTL module to enable layers.  This will have the
effect of allowing a module to interact with colored probes of instances
that it instantiates.

Signed-off-by: Schuyler Eldridge <[email protected]>

* [FIRRTL] Add verification of FModuleOp layers

Extend existing verification of 'firrtl.ref.cast', 'firrtl.ref.define',
and 'firrtl.ref.resolve' to handle modules which may enable layers.

This also refactors all the layer-coloring verification into a single
function that is reused by all three operation verifiers.

Signed-off-by: Schuyler Eldridge <[email protected]>

* [FIRRTL] Pipeline updates for module layers

Updates to the FIRRTL pass pipeline to support modules with enabled
layers.  These do not have a real effect on the pipeline itself other than
they should be removed once all ops that rely on their existence to pass
verification are removed.  I.e., this commit only removes them in
LowerXMR.

Signed-off-by: Schuyler Eldridge <[email protected]>

* [FIRRTL] Parse/emit module-enabled layers

Add FIRRTL text parsing and emission for modules with layers enabled.

Signed-off-by: Schuyler Eldridge <[email protected]>

* Update all FModules to support enabled layers

* Add parsing/emitting for enablelayer for Intmodule/Extmodule

- improve formatting of output

---------

Signed-off-by: Schuyler Eldridge <[email protected]>
Co-authored-by: Robert Young <[email protected]>

include/circt/Dialect/FIRRTL/FIRRTLAttributes.td

@@ -15,6 +15,7 @@
 
 include "FIRRTLDialect.td"
 include "mlir/IR/BuiltinAttributeInterfaces.td"
+include "circt/Types.td"
 
 //===----------------------------------------------------------------------===//
 // FIRRTL Annotations Definition
@@ -229,4 +230,10 @@ def InternalPathAttr : AttrDef<FIRRTLDialect, "InternalPath"> {
 def InternalPathArrayAttr
   : TypedArrayAttrBase<InternalPathAttr, "InternalPath array attribute">;
 
+//===----------------------------------------------------------------------===//
+// Miscellaneous attributes
+//===----------------------------------------------------------------------===//
+
+def LayerArrayAttr : TypedArrayRefAttrBase<SymbolRefAttr, "an array of layers">;
+
 #endif // CIRCT_DIALECT_FIRRTL_FIRRTLATTRIBUTES_TD

include/circt/Dialect/FIRRTL/FIRRTLOpInterfaces.td

@@ -39,6 +39,16 @@ def FModuleLike : OpInterface<"FModuleLike", [Symbol, PortList, InstanceGraphMod
     InterfaceMethod<"Get the module's instantiation convention",
       "Convention", "getConvention">,
 
+    //===------------------------------------------------------------------===//
+    // Enabled (AKA Required) Layers
+    //===------------------------------------------------------------------===//
+
+    InterfaceMethod<"Get the module's enabled layers",
+      "ArrayAttr", "getLayersAttr">,
+
+    InterfaceMethod<"Get the module's enabled layers.",
+      "ArrayRef<Attribute>", "getLayers">,
+
     //===------------------------------------------------------------------===//
     // Port Directions
     //===------------------------------------------------------------------===//

include/circt/Dialect/FIRRTL/FIRRTLStructure.td

@@ -131,7 +131,8 @@ def FModuleOp : FIRRTLModuleLike<"module", [SingleBlock, NoTerminator]> {
   let arguments =
             (ins ConventionAttr:$convention,
                  ArrayRefAttr:$portLocations,
-                 DefaultValuedAttr<AnnotationArrayAttr, "{}">:$annotations);
+                 DefaultValuedAttr<AnnotationArrayAttr, "{}">:$annotations,
+                 DefaultValuedAttr<LayerArrayAttr, "{}">:$layers);
 
   let results = (outs);
   let regions = (region SizedRegion<1>:$body);
@@ -142,7 +143,8 @@ def FModuleOp : FIRRTLModuleLike<"module", [SingleBlock, NoTerminator]> {
   let builders = [
     OpBuilder<(ins "StringAttr":$name, "ConventionAttr":$convention,
                "ArrayRef<PortInfo>":$ports,
-               CArg<"ArrayAttr", "ArrayAttr()">:$annotations)>,
+               CArg<"ArrayAttr", "ArrayAttr()">:$annotations,
+               CArg<"ArrayAttr", "ArrayAttr()">:$layers)>
   ];
 
   let extraModuleClassDeclaration = [{
@@ -188,8 +190,9 @@ def FExtModuleOp : FIRRTLModuleLike<"extmodule"> {
                    ConventionAttr:$convention,
                    ArrayRefAttr:$portLocations,
                    ParamDeclArrayAttr:$parameters,
-                   DefaultValuedAttr<AnnotationArrayAttr,
-                   "ArrayAttr()">:$annotations,
+                   DefaultValuedAttr<
+                    AnnotationArrayAttr, "{}">:$annotations,
+                   DefaultValuedAttr<LayerArrayAttr, "{}">:$layers,
                    OptionalAttr<InternalPathArrayAttr>:$internalPaths
                   );
   let results = (outs);
@@ -203,7 +206,8 @@ def FExtModuleOp : FIRRTLModuleLike<"extmodule"> {
                       CArg<"StringRef", "StringRef()">:$defnamAttr,
                       CArg<"ArrayAttr", "ArrayAttr()">:$annotations,
                       CArg<"ArrayAttr", "ArrayAttr()">:$parameters,
-                      CArg<"ArrayAttr", "ArrayAttr()">:$internalPaths)>
+                      CArg<"ArrayAttr", "ArrayAttr()">:$internalPaths,
+                      CArg<"ArrayAttr", "ArrayAttr()">:$layers)>
   ];
 
   let extraModuleClassDeclaration = [{
@@ -226,7 +230,8 @@ def FIntModuleOp : FIRRTLModuleLike<"intmodule"> {
                    ParamDeclArrayAttr:$parameters,
                    DefaultValuedAttr<AnnotationArrayAttr,
                    "ArrayAttr()">:$annotations,
-                   OptionalAttr<InternalPathArrayAttr>:$internalPaths
+                   OptionalAttr<InternalPathArrayAttr>:$internalPaths,
+                   DefaultValuedAttr<LayerArrayAttr, "{}">:$layers
                   );
   let results = (outs);
   let regions = (region AnyRegion:$body);
@@ -238,7 +243,8 @@ def FIntModuleOp : FIRRTLModuleLike<"intmodule"> {
                       CArg<"StringRef", "StringRef()">:$intrinsicNameAttr,
                       CArg<"ArrayAttr", "ArrayAttr()">:$annotations,
                       CArg<"ArrayAttr", "ArrayAttr()">:$parameters,
-                      CArg<"ArrayAttr", "ArrayAttr()">:$internalPaths)>
+                      CArg<"ArrayAttr", "ArrayAttr()">:$internalPaths,
+                      CArg<"ArrayAttr", "ArrayAttr()">:$layers)>
   ];
 
   let extraModuleClassDeclaration = [{
@@ -266,7 +272,8 @@ def FMemModuleOp : FIRRTLModuleLike<"memmodule"> {
          UI32Attr:$readLatency, UI32Attr:$writeLatency, UI64Attr:$depth,
          ArrayAttr:$extraPorts,
          ArrayRefAttr:$portLocations,
-         AnnotationArrayAttr:$annotations);
+         AnnotationArrayAttr:$annotations,
+         DefaultValuedAttr<LayerArrayAttr, "{}">:$layers);
   let results = (outs);
   let regions = (region AnyRegion:$body);
 
@@ -277,7 +284,8 @@ def FMemModuleOp : FIRRTLModuleLike<"memmodule"> {
                    "uint32_t":$numReadWritePorts, "uint32_t":$dataWidth,
                    "uint32_t":$maskBits, "uint32_t":$readLatency,
                    "uint32_t":$writeLatency, "uint64_t":$depth,
-                   CArg<"ArrayAttr", "ArrayAttr()">:$annotations)>
+                   CArg<"ArrayAttr", "ArrayAttr()">:$annotations,
+                   CArg<"ArrayAttr", "ArrayAttr()">:$layers)>
   ];
 
   let extraModuleClassDeclaration = [{
@@ -294,9 +302,10 @@ def FMemModuleOp : FIRRTLModuleLike<"memmodule"> {
 def ClassOp : FIRRTLModuleLike<"class", [
   SingleBlock, NoTerminator,
   DeclareOpInterfaceMethods<FModuleLike, [
-    // Class Ops do not support port annotations.
-    // Override this method to return an empty array attr.
-    "getPortAnnotationsAttr"]>,
+    // Class Ops do not support port annotations or enabled layers.
+    // Override these methods to return an empty array attr.
+    "getPortAnnotationsAttr",
+    "getLayersAttr"]>,
   DeclareOpInterfaceMethods<ClassLike>,
   DeclareOpInterfaceMethods<Symbol, ["canDiscardOnUseEmpty"]>]> {
   let summary = "FIRRTL Class";
@@ -350,9 +359,10 @@ def ClassOp : FIRRTLModuleLike<"class", [
 
 def ExtClassOp : FIRRTLModuleLike<"extclass", [
   DeclareOpInterfaceMethods<FModuleLike, [
-    // Class Ops do not support port annotations.
-    // Override this method to return an empty array attr.
-    "getPortAnnotationsAttr"]>,
+    // ExtClassOps do not support port annotations or enabled layers.
+    // Override these methods to return an empty array attr.
+    "getPortAnnotationsAttr",
+    "getLayersAttr"]>,
   DeclareOpInterfaceMethods<ClassLike>,
   DeclareOpInterfaceMethods<Symbol, ["canDiscardOnUseEmpty"]>]> {
   let summary = "FIRRTL external class";

lib/Conversion/FIRRTLToHW/LowerToHW.cpp

@@ -1027,17 +1027,11 @@ FIRRTLModuleLowering::lowerModule(FModuleOp oldModule, Block *topLevelModule,
     newModule.setCommentAttr(comment);
 
   // Copy over any attributes which are not required for FModuleOp.
-  SmallVector<StringRef, 12> attrNames = {"annotations",
-                                          "convention",
-                                          "portNames",
-                                          "sym_name",
-                                          "portDirections",
-                                          "portTypes",
-                                          "portAnnotations",
-                                          "portSyms",
-                                          "portLocations",
-                                          "parameters",
-                                          SymbolTable::getVisibilityAttrName()};
+  SmallVector<StringRef, 12> attrNames = {
+      "annotations",   "convention",      "layers",
+      "portNames",     "sym_name",        "portDirections",
+      "portTypes",     "portAnnotations", "portSyms",
+      "portLocations", "parameters",      SymbolTable::getVisibilityAttrName()};
 
   DenseSet<StringRef> attrSet(attrNames.begin(), attrNames.end());
   SmallVector<NamedAttribute> newAttrs(newModule->getAttrs());

lib/Dialect/FIRRTL/Export/FIREmitter.cpp

@@ -60,6 +60,7 @@ struct Emitter {
   void emitModuleParameters(Operation *op, ArrayAttr parameters);
   void emitDeclaration(LayerOp op);
   void emitDeclaration(OptionOp op);
+  void emitEnabledLayers(ArrayRef<Attribute> layers);
 
   // Statement emission
   void emitStatementsInBlock(Block &block);
@@ -408,11 +409,25 @@ void Emitter::emitCircuit(CircuitOp op) {
   symInfos = std::nullopt;
 }
 
+void Emitter::emitEnabledLayers(ArrayRef<Attribute> layers) {
+  for (auto layer : layers) {
+    ps << PP::space;
+    ps.cbox(2, IndentStyle::Block);
+    ps << "enablelayer" << PP::space;
+    emitSymbol(cast<SymbolRefAttr>(layer));
+    ps << PP::end;
+  }
+}
+
 /// Emit an entire module.
 void Emitter::emitModule(FModuleOp op) {
   startStatement();
-  ps << "module " << PPExtString(legalize(op.getNameAttr())) << " :";
+  ps.cbox(4, IndentStyle::Block);
+  ps << "module " << PPExtString(legalize(op.getNameAttr()));
+  emitEnabledLayers(op.getLayers());
+  ps << PP::nbsp << ":" << PP::end;
   emitLocation(op);
+
   ps.scopedBox(PP::bbox2, [&]() {
     setPendingNewline();
 
@@ -432,8 +447,12 @@ void Emitter::emitModule(FModuleOp op) {
 /// Emit an external module.
 void Emitter::emitModule(FExtModuleOp op) {
   startStatement();
-  ps << "extmodule " << PPExtString(legalize(op.getNameAttr())) << " :";
+  ps.cbox(4, IndentStyle::Block);
+  ps << "extmodule " << PPExtString(legalize(op.getNameAttr()));
+  emitEnabledLayers(op.getLayers());
+  ps << PP::nbsp << ":" << PP::end;
   emitLocation(op);
+
   ps.scopedBox(PP::bbox2, [&]() {
     setPendingNewline();
 
@@ -456,8 +475,12 @@ void Emitter::emitModule(FExtModuleOp op) {
 /// Emit an intrinsic module
 void Emitter::emitModule(FIntModuleOp op) {
   startStatement();
-  ps << "intmodule " << PPExtString(legalize(op.getNameAttr())) << " :";
+  ps.cbox(4, IndentStyle::Block);
+  ps << "intmodule " << PPExtString(legalize(op.getNameAttr()));
+  emitEnabledLayers(op.getLayers());
+  ps << PP::nbsp << ":" << PP::end;
   emitLocation(op);
+
   ps.scopedBox(PP::bbox2, [&]() {
     setPendingNewline();