Add FlattenInstance API

This adds a new trait, FlattenInstance, to chisel3.util.experimental. When
mixed into a module or a specific instance this trait will "flatten",
i.e., "inline that module and all of its submodules".

This includes testing (additions to InlineSpec) and ScalaDoc
documentation.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

2 files changed, 56 insertions, 1 deletions

diff --git a/src/main/scala/chisel3/util/experimental/Inline.scala b/src/main/scala/chisel3/util/experimental/Inline.scala
index 4039f3ed..8ec5219b 100644
--- a/src/main/scala/chisel3/util/experimental/Inline.scala
+++ b/src/main/scala/chisel3/util/experimental/Inline.scala
@@ -48,3 +48,38 @@ trait InlineInstance { self: BaseModule =>
         def toFirrtl: Annotation = NoDedupAnnotation(self.toNamed) })
     .map(chisel3.experimental.annotate(_))
 }
+
+/** Flattens an instance of a module
+  *
+  * @example {{{
+  * trait Internals { this: Module =>
+  *   val io = IO(new Bundle{ val a = Input(Bool()) })
+  * }
+  * class Foo extends Module with Internals with FlattenInstance
+  * class Bar extends Module with Internals {
+  *   val baz = Module(new Baz)
+  *   baz.io.a := io.a
+  * }
+  * class Baz extends Module with Internals
+  * /* The resulting instances will be:
+  *      - Top
+  *      - Top.x
+  *      - Top.y
+  *      - Top.z
+  *      - Top.z.baz */
+  * class Top extends Module with Internals {
+  *   val x = Module(new Foo)                      // x will be flattened
+  *   val y = Module(new Bar with FlattenInstance) // y will also be flattened
+  *   val z = Module(new Bar)                      // z will not be flattened
+  *   Seq(x, y, z).map(_.io.a := io.a)
+  * }
+  * }}}
+  */
+trait FlattenInstance { self: BaseModule =>
+  Seq(new ChiselAnnotation with RunFirrtlTransform {
+        def toFirrtl: Annotation = FlattenAnnotation(self.toNamed)
+        def transformClass: Class[_ <: Transform] = classOf[Flatten] },
+      new ChiselAnnotation {
+        def toFirrtl: Annotation = NoDedupAnnotation(self.toNamed) })
+  .map(chisel3.experimental.annotate(_))
+}
diff --git a/src/test/scala/chiselTests/InlineSpec.scala b/src/test/scala/chiselTests/InlineSpec.scala
index 4482d9ec..a2aabdb3 100644
--- a/src/test/scala/chiselTests/InlineSpec.scala
+++ b/src/test/scala/chiselTests/InlineSpec.scala
@@ -3,11 +3,12 @@
 package chiselTests
 
 import chisel3._
-import chisel3.util.experimental.InlineInstance
+import chisel3.util.experimental.{InlineInstance, FlattenInstance}
 import chisel3.internal.firrtl.Circuit
 import firrtl.FirrtlExecutionSuccess
 import firrtl.passes.InlineAnnotation
 import firrtl.annotations.Annotation
+import firrtl.transforms.FlattenAnnotation
 import firrtl.analyses.InstanceGraph
 import firrtl.{ir => fir}
 import firrtl.WDefInstance
@@ -54,4 +55,23 @@ class InlineSpec extends FreeSpec with ChiselRunners with Matchers {
       }
     }
   }
+
+  "Module Flattening" - {
+    class Top extends Module with Internals {
+      val x = Module(new Qux with FlattenInstance)
+      x.io.a := io.a
+    }
+    "should compile to low FIRRTL" - {
+      Driver.execute(Array("-X", "low", "--target-dir", "test_run_dir"), () => new Top) match {
+        case ChiselExecutionSuccess(Some(chiselCircuit), chirrtl, Some(firrtlResult: FirrtlExecutionSuccess)) =>
+          "emitting ONE FlattenAnnotation at the CHIRRTL level" in {
+            chiselCircuit.annotations.map(_.toFirrtl).collect{ case a: FlattenAnnotation => a }.size should be (1)
+          }
+          "low FIRRTL should contain instance x only" in {
+            val instances = collectInstances(firrtlResult.circuitState.circuit, Some("Top")).toSet
+            Set("Top", "Top.x") should be (instances)
+          }
+      }
+    }
+  }
 }