Add DataView (#1955)

DataView is a mechanism for "viewing" Scala objects as a subtype of
`Data`. Often, this is useful for viewing one subtype of `Data`, as
another. One can think about a DataView as a cross between a
customizable cast and an untagged union.

A DataView has a Target type `T`, and a View type `V`. DataView requires
that an implementation of `DataProduct` is available for Target types.
DataProduct is a type class that provides a way to iterate on `Data`
children of objects of implementing types.

If a DataView is provided for a type T to a type V, then the function
.viewAs[V] (of type T => V) is available. The object (of type T) returned
by .viewAs is called a "View" and can be used as both an rvalue and an
lvalue. Unlike when using an .asTypeOf cast, connecting to a "View" will
connect to the associated field or fields of the underlying Target.

DataView also enables .viewAsSupertype which is available for viewing
Bundles as a parent Bundle type. It is similar to .viewAs but requires
a prototype object of the Target type which will be cloned in order to
create the returned View. .viewAsSupertype maps between the
corresponding fields of the parent and child Bundle types.

1 files changed, 91 insertions, 0 deletions

diff --git a/src/test/scala/chiselTests/experimental/ModuleDataProductSpec.scala b/src/test/scala/chiselTests/experimental/ModuleDataProductSpec.scala
new file mode 100644
index 00000000..78986517
--- /dev/null
+++ b/src/test/scala/chiselTests/experimental/ModuleDataProductSpec.scala
@@ -0,0 +1,91 @@
+// See LICENSE for license details.
+
+package chiselTests.experimental
+
+import chisel3._
+import chisel3.experimental.{BaseModule, ExtModule}
+import chisel3.experimental.dataview.DataProduct
+import chiselTests.ChiselFlatSpec
+
+object ModuleDataProductSpec {
+  class MyBundle extends Bundle {
+    val foo = UInt(8.W)
+    val bar = UInt(8.W)
+  }
+  trait MyIntf extends BaseModule {
+    val in = IO(Input(new MyBundle))
+    val out = IO(Output(new MyBundle))
+  }
+  class Passthrough extends RawModule {
+    val in = IO(Input(UInt(8.W)))
+    val out = IO(Output(UInt(8.W)))
+    out := in
+  }
+  class MyUserModule extends Module with MyIntf {
+    val inst = Module(new Passthrough)
+    inst.in := in.foo
+    val r = RegNext(in)
+    out := r
+  }
+
+  class MyExtModule extends ExtModule with MyIntf
+  class MyExtModuleWrapper extends RawModule with MyIntf {
+    val inst = Module(new MyExtModule)
+    inst.in := in
+    out := inst.out
+  }
+}
+
+class ModuleDataProductSpec extends ChiselFlatSpec {
+  import ModuleDataProductSpec._
+
+  behavior of "DataProduct"
+
+  it should "work for UserModules (recursively)" in {
+    val m = elaborateAndGetModule(new MyUserModule)
+    val expected = Seq(
+      m.clock -> "m.clock",
+      m.reset -> "m.reset",
+      m.in -> "m.in",
+      m.in.foo -> "m.in.foo",
+      m.in.bar -> "m.in.bar",
+      m.out -> "m.out",
+      m.out.foo -> "m.out.foo",
+      m.out.bar -> "m.out.bar",
+      m.r -> "m.r",
+      m.r.foo -> "m.r.foo",
+      m.r.bar -> "m.r.bar",
+      m.inst.in -> "m.inst.in",
+      m.inst.out -> "m.inst.out"
+    )
+
+    val impl = implicitly[DataProduct[MyUserModule]]
+    val set = impl.dataSet(m)
+    for ((d, _) <- expected) {
+      set(d) should be (true)
+    }
+    val it = impl.dataIterator(m, "m")
+    it.toList should contain theSameElementsAs (expected)
+  }
+
+  it should "work for (wrapped) ExtModules" in {
+    val m = elaborateAndGetModule(new MyExtModuleWrapper).inst
+    val expected = Seq(
+      m.in -> "m.in",
+      m.in.foo -> "m.in.foo",
+      m.in.bar -> "m.in.bar",
+      m.out -> "m.out",
+      m.out.foo -> "m.out.foo",
+      m.out.bar -> "m.out.bar"
+    )
+
+    val impl = implicitly[DataProduct[MyExtModule]]
+    val set = impl.dataSet(m)
+    for ((d, _) <- expected) {
+      set(d) should be (true)
+    }
+    val it = impl.dataIterator(m, "m")
+    it.toList should contain theSameElementsAs (expected)
+  }
+
+}