Add new InlineAllInstances trait (#4508)

The InlineInstance trait can be attached to a module, to cause firtool to
inline instance of that module. The inline annotation is tricky to wield
because, if an inline module dedups with another module, we will inline all
instances of both modules.

To make InlineInstance easier to use, whenever we mark a module as inline, we
also mark it as "no dedup".

This of course does not work well when we have a module which we want to inline
AND dedup. So, this PR adds a new InlineAllInstances trait which allows a
module to be marked inline without blocking dedup.

Author: rwy7

src/main/scala/chisel3/util/experimental/Inline.scala

@@ -50,6 +50,17 @@ trait InlineInstance { self: BaseModule =>
     .map(chisel3.experimental.annotate(_))
 }
 
+/** Inlines all instances of a module. If this module dedups with any other
+  * module, instances of that other module will also be inlined.
+  */
+trait InlineInstanceAllowDedup { self: BaseModule =>
+  chisel3.experimental.annotate(
+    new ChiselAnnotation {
+      def toFirrtl: Annotation = InlineAnnotation(self.toNamed)
+    }
+  )
+}
+
 /** Flattens an instance of a module
   *
   * @example {{{

src/test/scala/chiselTests/InlineSpec.scala

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chiselTests
+
+import chisel3._
+import circt.stage.ChiselStage
+import org.scalatest.matchers.should.Matchers
+import chiselTests.{ChiselFlatSpec, MatchesAndOmits}
+import chisel3.util.experimental.{InlineInstance, InlineInstanceAllowDedup}
+
+class InlineInstanceSpec extends ChiselFlatSpec with MatchesAndOmits {
+  class ModuleA extends RawModule {
+    val w = dontTouch(WireInit(false.B))
+  }
+
+  class ModuleB extends RawModule with InlineInstance {
+    val w = dontTouch(WireInit(false.B))
+  }
+
+  class TopModule extends RawModule {
+    val a = Module(new ModuleA)
+    val b = Module(new ModuleB)
+  }
+
+  "InlineInstanceAllowDedup" should "Inline any module that dedups with a module marked inline" in {
+    val verilog = ChiselStage.emitSystemVerilog(new TopModule)
+    matchesAndOmits(verilog)(
+      "module TopModule()",
+      "module ModuleA();"
+    )(
+      "module ModuleB()"
+    )
+  }
+}
+
+class InlineInstanceAllowDedupSpec extends ChiselFlatSpec with MatchesAndOmits {
+  class ModuleA extends RawModule {
+    val w = dontTouch(WireInit(false.B))
+  }
+
+  class ModuleB extends RawModule with InlineInstanceAllowDedup {
+    val w = dontTouch(WireInit(false.B))
+  }
+
+  class TopModule extends RawModule {
+    val a = Module(new ModuleA)
+    val b = Module(new ModuleB)
+  }
+
+  "InlineInstanceAllowDedup" should "Inline any module that dedups with a module marked inline" in {
+    val verilog = ChiselStage.emitSystemVerilog(new TopModule)
+    matchesAndOmits(verilog)(
+      "module TopModule()"
+    )(
+      "module ModuleA()",
+      "module ModuleB()"
+    )
+  }
+}