Enhance views to [sometimes] support dynamic indexing and implement FlatIO (backport #2476) (#2479)

* Capture 1:1 mappings of Aggregates inside of views

This is implemented by including any corresponding Aggregates from the
DataView.mapping in the AggregateViewBinding.childMap (which is now of
type Map[Data, Data]).

This enables dynamically indexing Vecs that are themselves elements of
larger Aggregates in views when the corresponding element of the view is
a Vec of the same type. It also increases the number of cases where a
single Target can represent part of a view.

(cherry picked from commit 1f6b1ca14ccf86918065073c3f6f3626dd83a68e)

* Add FlatIO API for creating ports from Bundles without a prefix

(cherry picked from commit 772a3a1fe3b9372b7c2d7cd2d424b2adcd633cdb)

* [docs] Add FlatIO to the general cookbook

(cherry picked from commit b4159641350f238f0f899b69954142ce8ee11544)

Co-authored-by: Jack Koenig <koenig@sifive.com>

3 files changed, 82 insertions, 3 deletions

diff --git a/src/test/scala/chiselTests/experimental/DataView.scala b/src/test/scala/chiselTests/experimental/DataView.scala
index 0285a524..e7caacfd 100644
--- a/src/test/scala/chiselTests/experimental/DataView.scala
+++ b/src/test/scala/chiselTests/experimental/DataView.scala
@@ -332,6 +332,36 @@ class DataViewSpec extends ChiselFlatSpec {
     chirrtl should include("dataOut <= vec[addr]")
   }
 
+  it should "support dynamic indexing for Vecs that correspond 1:1 in a view" in {
+    class MyBundle extends Bundle {
+      val foo = Vec(4, UInt(8.W))
+      val bar = UInt(2.W)
+    }
+    implicit val myView = DataView[(Vec[UInt], UInt), MyBundle](
+      _ => new MyBundle,
+      _._1 -> _.foo,
+      _._2 -> _.bar
+    )
+    class MyModule extends Module {
+      val dataIn = IO(Input(UInt(8.W)))
+      val addr = IO(Input(UInt(2.W)))
+      val dataOut = IO(Output(UInt(8.W)))
+
+      val vec = RegInit(0.U.asTypeOf(Vec(4, UInt(8.W))))
+      val addrReg = Reg(UInt(2.W))
+      val view = (vec, addrReg).viewAs[MyBundle]
+      // Dynamic indexing is more of a "generator" in Chisel3 than an individual node
+      // This style is not recommended, this is just testing the behavior
+      val selected = view.foo(view.bar)
+      view.bar := addr
+      selected := dataIn
+      dataOut := selected
+    }
+    val chirrtl = ChiselStage.emitChirrtl(new MyModule)
+    chirrtl should include("vec[addrReg] <= dataIn")
+    chirrtl should include("dataOut <= vec[addrReg]")
+  }
+
   it should "error if you try to dynamically index a Vec view that does not correspond to a Vec target" in {
     class MyModule extends Module {
       val inA, inB = IO(Input(UInt(8.W)))
diff --git a/src/test/scala/chiselTests/experimental/DataViewTargetSpec.scala b/src/test/scala/chiselTests/experimental/DataViewTargetSpec.scala
index da27c9c8..ddeeab6e 100644
--- a/src/test/scala/chiselTests/experimental/DataViewTargetSpec.scala
+++ b/src/test/scala/chiselTests/experimental/DataViewTargetSpec.scala
@@ -125,9 +125,7 @@ class DataViewTargetSpec extends ChiselFlatSpec {
     val pairs = annos.collect { case DummyAnno(t, idx) => (idx, t.toString) }.sortBy(_._1)
     val expected = Seq(
       0 -> "~MyParent|MyChild>out.foo",
-      // The child of the view that was itself an Aggregate got split because 1:1 is lacking here
-      1 -> "~MyParent|MyChild>out.foo[0]",
-      1 -> "~MyParent|MyChild>out.foo[1]",
+      1 -> "~MyParent|MyChild>out.foo",
       2 -> "~MyParent|MyParent/inst:MyChild>out.foo",
       3 -> "~MyParent|MyParent/inst:MyChild>out"
     )
diff --git a/src/test/scala/chiselTests/experimental/FlatIOSpec.scala b/src/test/scala/chiselTests/experimental/FlatIOSpec.scala
new file mode 100644
index 00000000..dfce447f
--- /dev/null
+++ b/src/test/scala/chiselTests/experimental/FlatIOSpec.scala
@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chiselTests.experimental
+
+import chisel3._
+import chisel3.util.Valid
+import chisel3.stage.ChiselStage.emitChirrtl
+import chisel3.experimental.FlatIO
+import chiselTests.ChiselFlatSpec
+
+class FlatIOSpec extends ChiselFlatSpec {
+  behavior.of("FlatIO")
+
+  it should "create ports without a prefix" in {
+    class MyModule extends RawModule {
+      val io = FlatIO(new Bundle {
+        val in = Input(UInt(8.W))
+        val out = Output(UInt(8.W))
+      })
+      io.out := io.in
+    }
+    val chirrtl = emitChirrtl(new MyModule)
+    chirrtl should include("input in : UInt<8>")
+    chirrtl should include("output out : UInt<8>")
+    chirrtl should include("out <= in")
+  }
+
+  it should "support bulk connections between FlatIOs and regular IOs" in {
+    class MyModule extends RawModule {
+      val in = FlatIO(Input(Valid(UInt(8.W))))
+      val out = IO(Output(Valid(UInt(8.W))))
+      out := in
+    }
+    val chirrtl = emitChirrtl(new MyModule)
+    chirrtl should include("out.bits <= bits")
+    chirrtl should include("out.valid <= valid")
+  }
+
+  it should "dynamically indexing Vecs inside of FlatIOs" in {
+    class MyModule extends RawModule {
+      val io = FlatIO(new Bundle {
+        val addr = Input(UInt(2.W))
+        val in = Input(Vec(4, UInt(8.W)))
+        val out = Output(Vec(4, UInt(8.W)))
+      })
+      io.out(io.addr) := io.in(io.addr)
+    }
+    val chirrtl = emitChirrtl(new MyModule)
+    chirrtl should include("out[addr] <= in[addr]")
+  }
+}