Add FormalTest marker (#4635)

The FIRRTL spec defines a `formal` construct to indicate that a module
should be executed as a formal test. Currently, there is no way to emit
this construct from Chisel.

This PR adds a user-facing `FormalTest` class that can be used to mark
a module as to be executed as a formal test. This would commonly be used
inside a test harness module to mark the surrounding module as a test.
For example:

    class TestHarness extends RawModule {
      FormalTest(this)
    }

The formal test can be given an optional name and a map of parameters.
The parameters are distinct from blackbox modules in that they do not
map to Verilog parameters, but instead allow for any recursive nesting
of integers, doubles, strings, arrays, and maps, as prescribed by the
FIRRTL spec. Multiple formal test markers may be added to a single
module, which may be useful if a test should be run with different sets
of user-defined parameters.

This PR also adds the necessary IR nodes to the FIRRTL and Chisel FIRRTL
IRs.

Author: fabianschuiki

core/src/main/scala/chisel3/FormalTest.scala

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3
+
+import chisel3.experimental.{BaseModule, Param}
+import chisel3.internal.Builder
+import chisel3.internal.firrtl.ir._
+import chisel3.internal.throwException
+import chisel3.experimental.{SourceInfo, UnlocatableSourceInfo}
+
+object FormalTest {
+  def apply(
+    module: BaseModule,
+    params: MapTestParam = MapTestParam(Map.empty),
+    name:   String = ""
+  )(implicit sourceInfo: SourceInfo): Unit = {
+    val proposedName = if (name != "") {
+      name
+    } else {
+      module._proposedName
+    }
+    val sanitizedName = Builder.globalNamespace.name(proposedName)
+    Builder.components += DefFormalTest(sanitizedName, module, params, sourceInfo)
+  }
+}
+
+/** Parameters for test declarations. */
+sealed abstract class TestParam
+case class IntTestParam(value: BigInt) extends TestParam
+case class DoubleTestParam(value: Double) extends TestParam
+case class StringTestParam(value: String) extends TestParam
+case class ArrayTestParam(value: Seq[TestParam]) extends TestParam
+case class MapTestParam(value: Map[String, TestParam]) extends TestParam

core/src/main/scala/chisel3/internal/firrtl/Converter.scala

@@ -397,6 +397,14 @@ private[chisel3] object Converter {
     case RawParam(value) => fir.RawStringParam(name, value)
   }
 
+  def convert(param: TestParam): fir.TestParam = param match {
+    case IntTestParam(value)    => fir.IntTestParam(value)
+    case DoubleTestParam(value) => fir.DoubleTestParam(value)
+    case StringTestParam(value) => fir.StringTestParam(value)
+    case ArrayTestParam(value)  => fir.ArrayTestParam(value.map(convert))
+    case MapTestParam(value)    => fir.MapTestParam(value.map { case (name, value) => (name, convert(value)) })
+  }
+
   // TODO: Modify Panama CIRCT to account for type aliasing information. This is a temporary hack to
   // allow Panama CIRCT to compile
   def convert(
@@ -455,6 +463,13 @@ private[chisel3] object Converter {
         (ports ++ ctx.secretPorts).map(p => convert(p, typeAliases)),
         convert(block, ctx, typeAliases)
       )
+    case ctx @ DefFormalTest(name, module, params, sourceInfo) =>
+      fir.FormalTest(
+        convert(sourceInfo),
+        name,
+        module.name,
+        convert(params).asInstanceOf[fir.MapTestParam]
+      )
   }
 
   def convertLayer(layer: Layer): fir.Layer = {

core/src/main/scala/chisel3/internal/firrtl/IR.scala

@@ -494,6 +494,17 @@ private[chisel3] object ir {
     params: Map[String, Param]
   ) extends Component
 
+  case class DefFormalTest(
+    name:       String,
+    module:     BaseModule,
+    params:     MapTestParam,
+    sourceInfo: SourceInfo
+  ) extends Component {
+    def id = module
+    val ports: Seq[Port] = Seq.empty
+    override val secretPorts = mutable.ArrayBuffer[Port]()
+  }
+
   case class DefIntrinsicModule(
     id:     BaseIntrinsicModule,
     name:   String,

firrtl/src/main/scala/firrtl/ir/IR.scala

@@ -647,6 +647,23 @@ case class IntModule(info: Info, name: String, ports: Seq[Port], intrinsic: Stri
   */
 case class DefClass(info: Info, name: String, ports: Seq[Port], body: Statement) extends DefModule with UseSerializer
 
+/** Parameters for test declarations.
+  */
+sealed abstract class TestParam extends FirrtlNode
+case class IntTestParam(value: BigInt) extends TestParam with UseSerializer
+case class DoubleTestParam(value: Double) extends TestParam with UseSerializer
+case class StringTestParam(value: String) extends TestParam with UseSerializer
+case class ArrayTestParam(value: Seq[TestParam]) extends TestParam with UseSerializer
+case class MapTestParam(value: Map[String, TestParam]) extends TestParam with UseSerializer
+
+/** Formal Test
+  */
+case class FormalTest(info: Info, name: String, moduleName: String, params: MapTestParam)
+    extends DefModule
+    with UseSerializer {
+  val ports: Seq[Port] = Seq.empty
+}
+
 case class Circuit(
   info:        Info,
   modules:     Seq[DefModule],

firrtl/src/main/scala/firrtl/ir/Serializer.scala

@@ -479,6 +479,27 @@ object Serializer {
     case other => b ++= other.serialize // Handle user-defined nodes
   }
 
+  private def s(node: TestParam)(implicit b: StringBuilder, indent: Int): Unit = node match {
+    case IntTestParam(value)    => b ++= value.toString
+    case DoubleTestParam(value) => b ++= value.toString
+    case StringTestParam(value) => b ++= StringLit(value).escape
+    case ArrayTestParam(value) =>
+      b ++= "[";
+      value.zipWithIndex.foreach { case (value, i) =>
+        if (i > 0) b ++= ", "
+        s(value)
+      }
+      b ++= "]"
+    case MapTestParam(value) =>
+      b ++= "{"
+      value.keys.toSeq.sorted.zipWithIndex.foreach { case (name, i) =>
+        if (i > 0) b ++= ", "
+        b ++= name; b ++= " = "; s(value(name))
+      }
+      b ++= "}"
+    case other => b ++= other.serialize // Handle user-defined nodes
+  }
+
   private def sIt(node: DefModule)(implicit indent: Int): Iterator[String] = node match {
     case Module(info, name, public, layers, ports, body) =>
       val start = {
@@ -519,6 +540,13 @@ object Serializer {
         b.toString
       }
       Iterator(start) ++ sIt(body)(indent + 1)
+    case FormalTest(info, name, moduleName, params) =>
+      implicit val b = new StringBuilder
+      doIndent(0); b ++= "formal "; b ++= legalize(name); b ++= " of "; b ++= legalize(moduleName); b ++= " :"; s(info)
+      params.value.keys.toSeq.sorted.foreach { case name =>
+        newLineAndIndent(1); b ++= name; b ++= " = "; s(params.value(name))
+      }
+      Iterator(b.toString)
     case other =>
       Iterator(Indent * indent, other.serialize) // Handle user-defined nodes
   }
@@ -549,6 +577,7 @@ object Serializer {
     if (layers.nonEmpty) {
       implicit val b = new StringBuilder
       layers.foreach(s)
+      newLineNoIndent()
       Iterator(b.toString)
     } else Iterator.empty
   }

src/test/scala/chiselTests/RawModuleSpec.scala

@@ -228,4 +228,43 @@ class RawModuleSpec extends ChiselFlatSpec with Utils with FileCheck {
          |""".stripMargin
     )
   }
+
+  "RawModule marked as formal test" should "emit a formal test declaration" in {
+    class Foo extends RawModule {
+      FormalTest(this)
+      FormalTest(this, MapTestParam(Map("hello" -> StringTestParam("world"))))
+      FormalTest(
+        this,
+        MapTestParam(
+          Map(
+            "a_int" -> IntTestParam(42),
+            "b_double" -> DoubleTestParam(13.37),
+            "c_string" -> StringTestParam("hello"),
+            "d_array" -> ArrayTestParam(Seq(IntTestParam(42), StringTestParam("hello"))),
+            "e_map" -> MapTestParam(
+              Map(
+                "x" -> IntTestParam(42),
+                "y" -> StringTestParam("hello")
+              )
+            )
+          )
+        ),
+        "thisBetterWork"
+      )
+    }
+
+    generateFirrtlAndFileCheck(new Foo)(
+      """|CHECK: formal Foo of [[FOO:Foo_.*]] :
+         |CHECK: formal Foo_1 of [[FOO]] :
+         |CHECK:   hello = "world"
+         |CHECK: formal thisBetterWork of [[FOO]] :
+         |CHECK:   a_int = 42
+         |CHECK:   b_double = 13.37
+         |CHECK:   c_string = "hello"
+         |CHECK:   d_array = [42, "hello"]
+         |CHECK:   e_map = {x = 42, y = "hello"}
+         |CHECK: module [[FOO]] :
+         |""".stripMargin
+    )
+  }
 }