Add command line options to control elaboration of inline tests (#4826)

Author: tmckay-sifive

core/src/main/scala/chisel3/experimental/hierarchy/core/Definition.scala

@@ -120,7 +120,8 @@ object Definition extends SourceInfoDoc {
         context.loggerOptions,
         context.definitions,
         context.contextCache,
-        context.layerMap
+        context.layerMap,
+        context.inlineTestIncluder
       )
     }
     dynamicContext.inDefinition = true

core/src/main/scala/chisel3/internal/Builder.scala

@@ -472,10 +472,11 @@ private[chisel3] class DynamicContext(
   val sourceRoots:         Seq[File],
   val defaultNamespace:    Option[Namespace],
   // Definitions from other scopes in the same elaboration, use allDefinitions below
-  val loggerOptions: LoggerOptions,
-  val definitions:   ArrayBuffer[Definition[_]],
-  val contextCache:  BuilderContextCache,
-  val layerMap:      Map[layer.Layer, layer.Layer]
+  val loggerOptions:      LoggerOptions,
+  val definitions:        ArrayBuffer[Definition[_]],
+  val contextCache:       BuilderContextCache,
+  val layerMap:           Map[layer.Layer, layer.Layer],
+  val inlineTestIncluder: InlineTestIncluder
 ) {
   val importedDefinitionAnnos = annotationSeq.collect { case a: ImportDefinitionAnnotation[_] => a }
 

core/src/main/scala/chisel3/internal/InlineTestIncluder.scala

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.internal
+
+import java.nio.file.{FileSystems, PathMatcher, Paths}
+
+class InlineTestIncluder private (includeModuleGlobs: Seq[String], includeTestNameGlobs: Seq[String]) {
+  private def copy(
+    includeModuleGlobs:   Seq[String] = this.includeModuleGlobs,
+    includeTestNameGlobs: Seq[String] = this.includeTestNameGlobs
+  ) = new InlineTestIncluder(includeModuleGlobs, includeTestNameGlobs)
+
+  def includeModule(glob: String) = copy(includeModuleGlobs = includeModuleGlobs ++ Seq(glob))
+  def includeTest(glob:   String) = copy(includeTestNameGlobs = includeTestNameGlobs ++ Seq(glob))
+
+  private val filesystem = FileSystems.getDefault()
+
+  private def matchesGlob(glob: String, path: String): Boolean = {
+    val matcher = filesystem.getPathMatcher(s"glob:$glob")
+    matcher.matches(Paths.get(path))
+  }
+
+  def shouldElaborateTest(moduleDesiredName: String, testName: String): Boolean = {
+    val (resolvedModuleGlobs, resolvedTestNameGlobs) = (includeModuleGlobs, includeTestNameGlobs) match {
+      case x @ (Seq(), Seq()) => x
+      // If only one type of glob is provided, default to "*" for the other.
+      case (Seq(), ts) => (Seq("*"), ts)
+      case (ms, Seq()) => (ms, Seq("*"))
+      case x           => x
+    }
+
+    resolvedModuleGlobs.exists { glob => matchesGlob(glob, moduleDesiredName) } &&
+    resolvedTestNameGlobs.exists { glob => matchesGlob(glob, testName) }
+  }
+}
+
+object InlineTestIncluder {
+
+  /** Create an InlineTestIncluder that does not include any tests */
+  def none: InlineTestIncluder = new InlineTestIncluder(Nil, Nil)
+
+  /** Create an InlineTestIncluder that includes all tests */
+  def all: InlineTestIncluder = new InlineTestIncluder(Seq("*"), Seq("*"))
+
+  /** Create an InlineTestIncluder with module and test name globs */
+  def apply(
+    includeModuleGlobs:   Seq[String],
+    includeTestNameGlobs: Seq[String]
+  ): InlineTestIncluder = new InlineTestIncluder(includeModuleGlobs, includeModuleGlobs)
+}

src/main/scala/chisel3/experimental/inlinetest/InlineTest.scala

@@ -96,6 +96,14 @@ object TestHarnessGenerator {
 trait HasTests { module: RawModule =>
   type M = module.type
 
+  /** Whether inline tests will be elaborated as a top-level definition to the circuit. */
+  protected def elaborateTests: Boolean = true
+
+  private val inlineTestIncluder = internal.Builder.captureContext().inlineTestIncluder
+
+  private def shouldElaborateTest(testName: String) =
+    inlineTestIncluder.shouldElaborateTest(module.desiredName, testName)
+
   /** A Definition of the DUT to be used for each of the tests. */
   private lazy val moduleDefinition =
     module.toDefinition.asInstanceOf[Definition[module.type]]
@@ -116,12 +124,14 @@ trait HasTests { module: RawModule =>
   protected final def test[R](
     testName: String
   )(testBody: Instance[M] => R)(implicit th: TestHarnessGenerator[M, R]): Unit =
-    elaborateParentModule { moduleDefinition =>
-      val resetType = module match {
-        case module: Module => Some(module.resetType)
-        case _ => None
+    if (elaborateTests && shouldElaborateTest(testName)) {
+      elaborateParentModule { moduleDefinition =>
+        val resetType = module match {
+          case module: Module => Some(module.resetType)
+          case _ => None
+        }
+        val test = new TestParameters[M, R](desiredName, testName, moduleDefinition, testBody, resetType)
+        th.generate(test)
       }
-      val test = new TestParameters[M, R](desiredName, testName, moduleDefinition, testBody, resetType)
-      th.generate(test)
     }
 }

src/main/scala/chisel3/stage/ChiselAnnotations.scala

@@ -582,3 +582,33 @@ case object UseSRAMBlackbox extends NoTargetAnnotation with ChiselOption with Ha
     )
   )
 }
+
+case class IncludeInlineTestsForModuleAnnotation(glob: String)
+    extends NoTargetAnnotation
+    with Unserializable
+    with ChiselOption
+
+case object IncludeInlineTestsForModule extends HasShellOptions {
+  val options = Seq(
+    new ShellOption[String](
+      longOption = "include-tests-module",
+      toAnnotationSeq = glob => Seq(IncludeInlineTestsForModuleAnnotation(glob)),
+      helpText = "Elaborate inline tests when the module-under-test name matches this glob"
+    )
+  )
+}
+
+case class IncludeInlineTestsWithNameAnnotation(glob: String)
+    extends NoTargetAnnotation
+    with Unserializable
+    with ChiselOption
+
+case object IncludeInlineTestsWithName extends HasShellOptions {
+  val options = Seq(
+    new ShellOption[String](
+      longOption = "include-tests-name",
+      toAnnotationSeq = glob => Seq(IncludeInlineTestsWithNameAnnotation(glob)),
+      helpText = "Elaborate inline tests whose name matches this glob"
+    )
+  )
+}

src/main/scala/chisel3/stage/ChiselOptions.scala

@@ -3,7 +3,7 @@
 package chisel3.stage
 
 import chisel3.internal.firrtl.ir.Circuit
-import chisel3.internal.WarningFilter
+import chisel3.internal.{InlineTestIncluder, WarningFilter}
 import chisel3.layer.Layer
 import chisel3.ElaboratedCircuit
 import java.io.File
@@ -18,7 +18,8 @@ class ChiselOptions private[stage] (
   val layerMap:            Map[Layer, Layer] = Map.empty,
   val includeUtilMetadata: Boolean = false,
   val useSRAMBlackbox:     Boolean = false,
-  val elaboratedCircuit:   Option[ElaboratedCircuit] = None
+  val elaboratedCircuit:   Option[ElaboratedCircuit] = None,
+  val inlineTestIncluder:  InlineTestIncluder = InlineTestIncluder.none
 ) {
 
   private[stage] def copy(
@@ -31,7 +32,8 @@ class ChiselOptions private[stage] (
     layerMap:            Map[Layer, Layer] = layerMap,
     includeUtilMetadata: Boolean = includeUtilMetadata,
     useSRAMBlackbox:     Boolean = useSRAMBlackbox,
-    elaboratedCircuit:   Option[ElaboratedCircuit] = elaboratedCircuit
+    elaboratedCircuit:   Option[ElaboratedCircuit] = elaboratedCircuit,
+    inlineTestIncluder:  InlineTestIncluder = inlineTestIncluder
   ): ChiselOptions = {
 
     new ChiselOptions(
@@ -44,7 +46,8 @@ class ChiselOptions private[stage] (
       layerMap = layerMap,
       includeUtilMetadata = includeUtilMetadata,
       useSRAMBlackbox = useSRAMBlackbox,
-      elaboratedCircuit = elaboratedCircuit
+      elaboratedCircuit = elaboratedCircuit,
+      inlineTestIncluder = inlineTestIncluder
     )
 
   }

src/main/scala/chisel3/stage/package.scala

@@ -34,6 +34,10 @@ package object stage {
           case RemapLayer(oldLayer, newLayer) => c.copy(layerMap = c.layerMap + ((oldLayer, newLayer)))
           case IncludeUtilMetadata            => c.copy(includeUtilMetadata = true)
           case UseSRAMBlackbox                => c.copy(useSRAMBlackbox = true)
+          case IncludeInlineTestsForModuleAnnotation(glob) =>
+            c.copy(inlineTestIncluder = c.inlineTestIncluder.includeModule(glob))
+          case IncludeInlineTestsWithNameAnnotation(glob) =>
+            c.copy(inlineTestIncluder = c.inlineTestIncluder.includeTest(glob))
         }
       }
 

src/main/scala/chisel3/stage/phases/Elaborate.scala

@@ -53,7 +53,8 @@ class Elaborate extends Phase {
             loggerOptions,
             ArrayBuffer[Definition[_]](),
             BuilderContextCache.empty,
-            chiselOptions.layerMap
+            chiselOptions.layerMap,
+            chiselOptions.inlineTestIncluder
           )
         val (elaboratedCircuit, dut) = {
           Builder.build(Module(gen()), context)

src/main/scala/circt/stage/Shell.scala

@@ -6,6 +6,8 @@ import chisel3.stage.{
   ChiselCircuitAnnotation,
   ChiselGeneratorAnnotation,
   CircuitSerializationAnnotation,
+  IncludeInlineTestsForModule,
+  IncludeInlineTestsWithName,
   IncludeUtilMetadata,
   PrintFullStackTraceAnnotation,
   RemapLayer,
@@ -48,7 +50,9 @@ trait CLI extends BareShell { this: BareShell =>
     DumpFir,
     RemapLayer,
     IncludeUtilMetadata,
-    UseSRAMBlackbox
+    UseSRAMBlackbox,
+    IncludeInlineTestsForModule,
+    IncludeInlineTestsWithName
   ).foreach(_.addOptions(parser))
 
   parser.note("CIRCT (MLIR FIRRTL Compiler) options")