[FIRRTL] Add a bind op (#8384)

Currently, FIRRTL instances may be marked as "lowerToBind", which is then
lowered to a HW instance marked "doNotPrint", along with a bind op in the
global scope.

This PR adds a bind op to FIRRTL, which in conjunction with the "doNotPrint"
flag on FIRRTL instances, allows us to choose precisely where the bind
operation goes, rather than having lowerToHW choose for us.

Author: rwy7

include/circt/Dialect/FIRRTL/FIRRTLStatements.td

@@ -17,6 +17,7 @@ include "FIRRTLDialect.td"
 include "FIRRTLEnums.td"
 include "FIRRTLOpInterfaces.td"
 include "FIRRTLTypes.td"
+include "circt/Dialect/HW/HWAttributesNaming.td"
 include "circt/Dialect/HW/HWTypes.td"
 include "mlir/IR/SymbolInterfaces.td"
 include "mlir/Interfaces/SideEffectInterfaces.td"
@@ -428,4 +429,27 @@ def LayerBlockOp : FIRRTLOp<
   let hasCanonicalizeMethod = 1;
 }
 
+//===----------------------------------------------------------------------===//
+// Bind Op
+//===----------------------------------------------------------------------===//
+
+def BindOp
+    : FIRRTLOp<"bind", [DeclareOpInterfaceMethods<InnerRefUserOpInterface>]> {
+  let summary = "Indirect instantiation statement";
+  let description = [{
+    Indirectly instantiate a module from the context of another module. BindOp
+    pairs with a `firrtl.instance` which tracks all information except the
+    emission point for the bind.
+
+    This op exists to aid in the progressive lowering of FIRRTL surface level
+    constructs, such as layers, to system verilog (sv dialect).
+  }];
+  let arguments = (ins InnerRefAttr:$instance);
+  let assemblyFormat = "$instance attr-dict";
+  let builders = [OpBuilder<(ins "StringAttr":$mod, "StringAttr":$name), [{
+      auto instance = hw::InnerRefAttr::get(mod, name);
+      build(odsBuilder, odsState, instance);
+    }]>];
+}
+
 #endif // CIRCT_DIALECT_FIRRTL_FIRRTLSTATEMENTS_TD

include/circt/Dialect/FIRRTL/FIRRTLVisitors.h

@@ -241,17 +241,17 @@ class StmtVisitor {
   ResultType dispatchStmtVisitor(Operation *op, ExtraArgs... args) {
     auto *thisCast = static_cast<ConcreteType *>(this);
     return TypeSwitch<Operation *, ResultType>(op)
-        .template Case<
-            AttachOp, ConnectOp, MatchingConnectOp, RefDefineOp, ForceOp,
-            PrintFOp, FPrintFOp, SkipOp, StopOp, WhenOp, AssertOp, AssumeOp,
-            CoverOp, PropAssignOp, RefForceOp, RefForceInitialOp, RefReleaseOp,
-            RefReleaseInitialOp, FPGAProbeIntrinsicOp, VerifAssertIntrinsicOp,
-            VerifAssumeIntrinsicOp, UnclockedAssumeIntrinsicOp,
-            VerifCoverIntrinsicOp, VerifRequireIntrinsicOp,
-            VerifEnsureIntrinsicOp, LayerBlockOp, MatchOp, ViewIntrinsicOp>(
-            [&](auto opNode) -> ResultType {
-              return thisCast->visitStmt(opNode, args...);
-            })
+        .template Case<AttachOp, ConnectOp, MatchingConnectOp, RefDefineOp,
+                       ForceOp, PrintFOp, FPrintFOp, SkipOp, StopOp, WhenOp,
+                       AssertOp, AssumeOp, CoverOp, PropAssignOp, RefForceOp,
+                       RefForceInitialOp, RefReleaseOp, RefReleaseInitialOp,
+                       FPGAProbeIntrinsicOp, VerifAssertIntrinsicOp,
+                       VerifAssumeIntrinsicOp, UnclockedAssumeIntrinsicOp,
+                       VerifCoverIntrinsicOp, VerifRequireIntrinsicOp,
+                       VerifEnsureIntrinsicOp, LayerBlockOp, MatchOp,
+                       ViewIntrinsicOp, BindOp>([&](auto opNode) -> ResultType {
+          return thisCast->visitStmt(opNode, args...);
+        })
         .Default([&](auto expr) -> ResultType {
           return thisCast->visitInvalidStmt(op, args...);
         });
@@ -302,6 +302,7 @@ class StmtVisitor {
   HANDLE(LayerBlockOp);
   HANDLE(MatchOp);
   HANDLE(ViewIntrinsicOp);
+  HANDLE(BindOp);
 
 #undef HANDLE
 };

lib/Conversion/FIRRTLToHW/LowerToHW.cpp

@@ -577,6 +577,7 @@ struct FIRRTLModuleLowering
                                 CircuitLoweringState &loweringState);
   LogicalResult lowerSimulationBody(verif::SimulationOp simulationOp,
                                     CircuitLoweringState &loweringState);
+  LogicalResult lowerFileBody(emit::FileOp op);
   LogicalResult lowerBody(Operation *op, CircuitLoweringState &loweringState);
 };
 
@@ -692,6 +693,11 @@ void FIRRTLModuleLowering::runOnOperation() {
               opsToProcess.push_back(newOp);
               return success();
             })
+            .Case<emit::FileOp>([&](auto fileOp) {
+              fileOp->moveBefore(topLevelModule, topLevelModule->end());
+              opsToProcess.push_back(fileOp);
+              return success();
+            })
             .Default([&](Operation *op) {
               // We don't know what this op is.  If it has no illegal FIRRTL
               // types, we can forward the operation.  Otherwise, we emit an
@@ -1851,6 +1857,7 @@ struct FIRRTLLowering : public FIRRTLVisitor<FIRRTLLowering, LogicalResult> {
   LogicalResult visitStmt(RefForceInitialOp op);
   LogicalResult visitStmt(RefReleaseOp op);
   LogicalResult visitStmt(RefReleaseInitialOp op);
+  LogicalResult visitStmt(BindOp op);
 
   FailureOr<Value> lowerSubindex(SubindexOp op, Value input);
   FailureOr<Value> lowerSubaccess(SubaccessOp op, Value input);
@@ -1966,6 +1973,18 @@ FIRRTLModuleLowering::lowerModuleBody(hw::HWModuleOp module,
   return FIRRTLLowering(module, loweringState).run();
 }
 
+LogicalResult FIRRTLModuleLowering::lowerFileBody(emit::FileOp fileOp) {
+  OpBuilder b(&getContext());
+  fileOp->walk([&](Operation *op) {
+    if (auto bindOp = dyn_cast<BindOp>(op)) {
+      b.setInsertionPointAfter(bindOp);
+      b.create<sv::BindOp>(bindOp.getLoc(), bindOp.getInstanceAttr());
+      bindOp->erase();
+    }
+  });
+  return success();
+}
+
 LogicalResult
 FIRRTLModuleLowering::lowerBody(Operation *op,
                                 CircuitLoweringState &loweringState) {
@@ -1975,6 +1994,8 @@ FIRRTLModuleLowering::lowerBody(Operation *op,
     return lowerFormalBody(formalOp, loweringState);
   if (auto simulationOp = dyn_cast<verif::SimulationOp>(op))
     return lowerSimulationBody(simulationOp, loweringState);
+  if (auto fileOp = dyn_cast<emit::FileOp>(op))
+    return lowerFileBody(fileOp);
   return failure();
 }
 
@@ -5165,6 +5186,11 @@ LogicalResult FIRRTLLowering::visitStmt(AttachOp op) {
   return success();
 }
 
+LogicalResult FIRRTLLowering::visitStmt(BindOp op) {
+  builder.create<sv::BindOp>(op.getInstanceAttr());
+  return success();
+}
+
 LogicalResult FIRRTLLowering::fixupLTLOps() {
   if (ltlOpFixupWorklist.empty())
     return success();

lib/Dialect/FIRRTL/FIRRTLOps.cpp

@@ -6404,6 +6404,29 @@ void HierarchicalModuleNameOp::getAsmResultNames(
   setNameFn(getResult(), "hierarchicalmodulename");
 }
 
+//===----------------------------------------------------------------------===//
+// BindOp
+//===----------------------------------------------------------------------===//
+
+LogicalResult BindOp::verifyInnerRefs(hw::InnerRefNamespace &ns) {
+  auto ref = getInstanceAttr();
+  auto target = ns.lookup(ref);
+  if (!target)
+    return emitError() << "target " << ref << " cannot be resolved";
+
+  if (!target.isOpOnly())
+    return emitError() << "target " << ref << " is not an operation";
+
+  auto instance = dyn_cast<InstanceOp>(target.getOp());
+  if (!instance)
+    return emitError() << "target " << ref << " is not an instance";
+
+  if (!instance.getDoNotPrint())
+    return emitError() << "target " << ref << " is not marked doNotPrint";
+
+  return success();
+}
+
 //===----------------------------------------------------------------------===//
 // TblGen Generated Logic.
 //===----------------------------------------------------------------------===//

test/Conversion/FIRRTLToHW/lower-to-hw.mlir

@@ -725,6 +725,23 @@ firrtl.circuit "Simple"   attributes {annotations = [{class =
     firrtl.instance foo {doNotPrint} @foo()
   }
 
+  // Check that explicit bind ops are lowered to sv.bind, even if they are
+  // buried in an emit block.
+
+  firrtl.module @BoundModule() {}
+
+  // CHECK-LABEL: hw.module @ExplicitBindTest()
+  firrtl.module @ExplicitBindTest() {
+    // CHECK: hw.instance "boundInstance" sym @boundInstance @BoundModule() -> () {doNotPrint}
+    firrtl.instance boundInstance sym @boundInstance {doNotPrint} @BoundModule()
+  }
+
+  // CHECK: emit.file "some-file.sv"
+  emit.file "some-file.sv" {
+    // CHECK: sv.bind <@ExplicitBindTest::@boundInstance>
+    firrtl.bind <@ExplicitBindTest::@boundInstance>
+  }
+
   // CHECK-LABEL: hw.module private @attributes_preservation
   // CHECK-SAME: firrtl.foo = "bar"
   // CHECK-SAME: output_file = #hw.output_file<"output_fileTest.sv", excludeFromFileList>

test/Dialect/FIRRTL/errors.mlir

@@ -2885,3 +2885,43 @@ firrtl.circuit "SimulationPortType3" {
     out success: !firrtl.reset
   )
 }
+
+// -----
+
+firrtl.circuit "BindTargetMissingModule" {
+  firrtl.module @BindTargetMissing() {}
+  // expected-error @below {{target #hw.innerNameRef<@XXX::@YYY> cannot be resolved}}
+  firrtl.bind <@XXX::@YYY>
+}
+
+// -----
+
+firrtl.circuit "BindTargetMissingInstance" {
+  firrtl.module @BindTargetMissingInstance() {}
+  // expected-error @below {{target #hw.innerNameRef<@BindTargetMissingInstance::@YYY> cannot be resolved}}
+  firrtl.bind <@BindTargetMissingInstance::@YYY>
+}
+
+// -----
+
+firrtl.circuit "BindTargetNotAnInstance" {
+  firrtl.module @Target() {}
+  firrtl.module @BindTargetMissingDoNotPrintFlag() {
+    %wire = firrtl.wire sym @target : !firrtl.uint<8>
+  }
+
+  // expected-error @below {{target #hw.innerNameRef<@BindTargetMissingDoNotPrintFlag::@target> is not an instance}}
+  firrtl.bind <@BindTargetMissingDoNotPrintFlag::@target>
+}
+
+// -----
+
+firrtl.circuit "BindTargetMissingDoNotPrintFlag" {
+  firrtl.module @Target() {}
+  firrtl.module @BindTargetMissingDoNotPrintFlag() {
+    firrtl.instance target sym @target @Target()
+  }
+
+  // expected-error @below {{target #hw.innerNameRef<@BindTargetMissingDoNotPrintFlag::@target> is not marked doNotPrint}}
+  firrtl.bind <@BindTargetMissingDoNotPrintFlag::@target>
+}