[FIRRTL] Lower firrtl.simulation to verif.simulation (#8312)

Add a lowering from `firrtl.simulation` to `verif.simulation` in the
FIRRTL-to-HW conversion. The lowering creates a `verif.simulation` op
that simply instantiates the module pointed to by `firrtl.simulation`,
connecting its `clock` and `init` ports to the simulation op's block
arguments, and yielding the `done` and `success` ports back. We may want
to inline the instance in the future, but that is purely cosmetic.

This now allows FIR files to contain `simulation` unit tests that can be
lowered to HW through `firtool` and then executed using `arcilator`.

Author: fabianschuiki

lib/Conversion/FIRRTLToHW/LowerToHW.cpp

@@ -575,6 +575,8 @@ struct FIRRTLModuleLowering
                                       CircuitLoweringState &loweringState);
   LogicalResult lowerFormalBody(verif::FormalOp formalOp,
                                 CircuitLoweringState &loweringState);
+  LogicalResult lowerSimulationBody(verif::SimulationOp simulationOp,
+                                    CircuitLoweringState &loweringState);
 };
 
 } // end anonymous namespace
@@ -618,6 +620,7 @@ void FIRRTLModuleLowering::runOnOperation() {
 
   SmallVector<hw::HWModuleOp, 32> modulesToProcess;
   SmallVector<verif::FormalOp> formalOpsToProcess;
+  SmallVector<verif::SimulationOp> simulationOpsToProcess;
 
   AnnotationSet circuitAnno(circuit);
   moveVerifAnno(getOperation(), circuitAnno, extractAssertAnnoClass,
@@ -668,14 +671,26 @@ void FIRRTLModuleLowering::runOnOperation() {
               state.recordModuleMapping(&op, loweredMod);
               return success();
             })
-            .Case<FormalOp>([&](auto oldFormalOp) {
+            .Case<FormalOp>([&](auto oldOp) {
               auto builder = OpBuilder::atBlockEnd(topLevelModule);
-              auto newFormalOp = builder.create<verif::FormalOp>(
-                  oldFormalOp.getLoc(), oldFormalOp.getNameAttr(),
-                  oldFormalOp.getParametersAttr());
-              newFormalOp.getBody().emplaceBlock();
-              state.recordModuleMapping(oldFormalOp, newFormalOp);
-              formalOpsToProcess.push_back(newFormalOp);
+              auto newOp = builder.create<verif::FormalOp>(
+                  oldOp.getLoc(), oldOp.getNameAttr(),
+                  oldOp.getParametersAttr());
+              newOp.getBody().emplaceBlock();
+              state.recordModuleMapping(oldOp, newOp);
+              formalOpsToProcess.push_back(newOp);
+              return success();
+            })
+            .Case<SimulationOp>([&](auto oldOp) {
+              auto loc = oldOp.getLoc();
+              auto builder = OpBuilder::atBlockEnd(topLevelModule);
+              auto newOp = builder.create<verif::SimulationOp>(
+                  loc, oldOp.getNameAttr(), oldOp.getParametersAttr());
+              auto &body = newOp.getRegion().emplaceBlock();
+              body.addArgument(seq::ClockType::get(builder.getContext()), loc);
+              body.addArgument(builder.getI1Type(), loc);
+              state.recordModuleMapping(oldOp, newOp);
+              simulationOpsToProcess.push_back(newOp);
               return success();
             })
             .Default([&](Operation *op) {
@@ -748,6 +763,13 @@ void FIRRTLModuleLowering::runOnOperation() {
   if (failed(result))
     return signalPassFailure();
 
+  // Lower all simulation op bodies.
+  result = mlir::failableParallelForEach(
+      &getContext(), simulationOpsToProcess,
+      [&](auto op) { return lowerSimulationBody(op, state); });
+  if (failed(result))
+    return signalPassFailure();
+
   // Move binds from inside modules to outside modules.
   for (auto bind : state.binds) {
     bind->moveBefore(bind->getParentOfType<hw::HWModuleOp>());
@@ -1418,22 +1440,18 @@ LogicalResult FIRRTLModuleLowering::lowerModulePortsAndMoveBody(
 /// Run on each `verif.formal` to populate its body based on the original
 /// `firrtl.formal` operation.
 LogicalResult
-FIRRTLModuleLowering::lowerFormalBody(verif::FormalOp formalOp,
+FIRRTLModuleLowering::lowerFormalBody(verif::FormalOp newOp,
                                       CircuitLoweringState &loweringState) {
-  auto builder = OpBuilder::atBlockEnd(&formalOp.getBody().front());
+  auto builder = OpBuilder::atBlockEnd(&newOp.getBody().front());
 
   // Find the module targeted by the `firrtl.formal` operation. The `FormalOp`
   // verifier guarantees the module exists and that it is an `FModuleOp`. This
   // we can then translate to the corresponding `HWModuleOp`.
-  auto oldFormalOp = cast<FormalOp>(loweringState.getOldModule(formalOp));
-  auto moduleName = oldFormalOp.getModuleNameAttr().getAttr();
+  auto oldOp = cast<FormalOp>(loweringState.getOldModule(newOp));
+  auto moduleName = oldOp.getModuleNameAttr().getAttr();
   auto oldModule = cast<FModuleOp>(
       loweringState.getInstanceGraph().lookup(moduleName)->getModule());
-  auto newModule =
-      dyn_cast_or_null<hw::HWModuleOp>(loweringState.getNewModule(oldModule));
-  if (!newModule)
-    return oldFormalOp->emitOpError()
-           << "could not find module " << oldModule.getSymNameAttr();
+  auto newModule = cast<hw::HWModuleOp>(loweringState.getNewModule(oldModule));
 
   // Create a symbolic input for every input of the lowered module.
   SmallVector<Value> symbolicInputs;
@@ -1442,11 +1460,36 @@ FIRRTLModuleLowering::lowerFormalBody(verif::FormalOp formalOp,
         builder.create<verif::SymbolicValueOp>(arg.getLoc(), arg.getType()));
 
   // Instantiate the module with the given symbolic inputs.
-  builder.create<hw::InstanceOp>(formalOp.getLoc(), newModule,
+  builder.create<hw::InstanceOp>(newOp.getLoc(), newModule,
                                  newModule.getNameAttr(), symbolicInputs);
   return success();
 }
 
+/// Run on each `verif.simulation` to populate its body based on the original
+/// `firrtl.simulation` operation.
+LogicalResult
+FIRRTLModuleLowering::lowerSimulationBody(verif::SimulationOp newOp,
+                                          CircuitLoweringState &loweringState) {
+  auto builder = OpBuilder::atBlockEnd(newOp.getBody());
+
+  // Find the module targeted by the `firrtl.simulation` operation.
+  auto oldOp = cast<SimulationOp>(loweringState.getOldModule(newOp));
+  auto moduleName = oldOp.getModuleNameAttr().getAttr();
+  auto oldModule = cast<FModuleLike>(
+      *loweringState.getInstanceGraph().lookup(moduleName)->getModule());
+  auto newModule =
+      cast<hw::HWModuleLike>(loweringState.getNewModule(oldModule));
+
+  // Instantiate the module with the simulation op's block arguments as inputs,
+  // and yield the module's outputs.
+  SmallVector<Value> inputs(newOp.getBody()->args_begin(),
+                            newOp.getBody()->args_end());
+  auto instOp = builder.create<hw::InstanceOp>(newOp.getLoc(), newModule,
+                                               newModule.getNameAttr(), inputs);
+  builder.create<verif::YieldOp>(newOp.getLoc(), instOp.getResults());
+  return success();
+}
+
 //===----------------------------------------------------------------------===//
 // Module Body Lowering Pass
 //===----------------------------------------------------------------------===//

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

@@ -1744,6 +1744,38 @@ firrtl.circuit "Foo" {
 
 // -----
 
+firrtl.circuit "Foo" {
+  // CHECK-LABEL: hw.module.extern @Foo
+  // CHECK-SAME:    in %clock : !seq.clock
+  // CHECK-SAME:    in %init : i1
+  // CHECK-SAME:    out done : i1
+  // CHECK-SAME:    out success : i1
+  firrtl.extmodule @Foo(
+    in clock: !firrtl.clock,
+    in init: !firrtl.uint<1>,
+    out done: !firrtl.uint<1>,
+    out success: !firrtl.uint<1>
+  )
+  // CHECK-LABEL: verif.simulation @MyTest1
+  // CHECK-SAME:    {hello = 42 : i64} {
+  // CHECK-NEXT:  ([[CLOCK:%.+]]: !seq.clock, [[INIT:%.+]]: i1):
+  // CHECK-NEXT:    [[DONE:%.+]], [[SUCCESS:%.+]] = hw.instance "Foo" @Foo
+  // CHECK-SAME:      (clock: [[CLOCK]]: !seq.clock, init: [[INIT]]: i1) -> (done: i1, success: i1)
+  // CHECK-NEXT:    verif.yield [[DONE]], [[SUCCESS]] : i1, i1
+  // CHECK-NEXT:  }
+  firrtl.simulation @MyTest1, @Foo {hello = 42 : i64}
+  // CHECK-LABEL: verif.simulation @MyTest2
+  // CHECK-SAME:    {world = "abc"} {
+  // CHECK-NEXT:  ([[CLOCK:%.+]]: !seq.clock, [[INIT:%.+]]: i1):
+  // CHECK-NEXT:    [[DONE:%.+]], [[SUCCESS:%.+]] = hw.instance "Foo" @Foo
+  // CHECK-SAME:      (clock: [[CLOCK]]: !seq.clock, init: [[INIT]]: i1) -> (done: i1, success: i1)
+  // CHECK-NEXT:    verif.yield [[DONE]], [[SUCCESS]] : i1, i1
+  // CHECK-NEXT:  }
+  firrtl.simulation @MyTest2, @Foo {world = "abc"}
+}
+
+// -----
+
 firrtl.circuit "Foo" {
   // CHECK-LABEL: hw.module @Foo
   firrtl.module @Foo(in %a: !firrtl.uint<42>, in %b: !firrtl.uint<1337>) {