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, 57 insertions, 0 deletions

diff --git a/src/test/scala/chiselTests/experimental/DataViewIntegrationSpec.scala b/src/test/scala/chiselTests/experimental/DataViewIntegrationSpec.scala
new file mode 100644
index 00000000..3f149f75
--- /dev/null
+++ b/src/test/scala/chiselTests/experimental/DataViewIntegrationSpec.scala
@@ -0,0 +1,57 @@
+// See LICENSE for license details.
+
+package chiselTests.experimental
+
+import chisel3._
+import chisel3.experimental.{BaseModule, ExtModule}
+import chisel3.experimental.dataview._
+import chisel3.util.{Decoupled, DecoupledIO, Queue, QueueIO, log2Ceil}
+import chiselTests.ChiselFlatSpec
+import firrtl.transforms.DontTouchAnnotation
+
+// Let's put it all together!
+object DataViewIntegrationSpec {
+
+  class QueueIntf[T <: Data](gen: T, entries: Int) extends Bundle {
+    val ports = new QueueIO(gen, entries)
+    // Let's grab a reference to something internal too
+    // Output because can't have directioned and undirectioned stuff
+    val enq_ptr = Output(UInt(log2Ceil(entries).W))
+  }
+
+  // It's not clear if a view of a Module ever _can_ be total since internal nodes are part of the Module
+  implicit def queueView[T <: Data] = PartialDataView[Queue[T], QueueIntf[T]](
+    q => new QueueIntf(q.gen, q.entries),
+    _.io -> _.ports,
+    // Some token internal signal
+    _.enq_ptr.value -> _.enq_ptr
+  )
+
+  object MyQueue {
+    def apply[T <: Data](enq: DecoupledIO[T], n: Int): QueueIntf[T] = {
+      val queue = Module(new Queue[T](enq.bits.cloneType, n))
+      val view = queue.viewAs[QueueIntf[T]]
+      view.ports.enq <> enq
+      view
+    }
+  }
+
+  class MyModule extends Module {
+    val enq = IO(Flipped(Decoupled(UInt(8.W))))
+    val deq = IO(Decoupled(UInt(8.W)))
+
+    val queue = MyQueue(enq, 4)
+    deq <> queue.ports.deq
+    dontTouch(queue.enq_ptr)
+  }
+}
+
+class DataViewIntegrationSpec extends ChiselFlatSpec {
+  import DataViewIntegrationSpec.MyModule
+
+  "Users" should "be able to view and annotate Modules" in {
+    val (_, annos) = getFirrtlAndAnnos(new MyModule)
+    val ts = annos.collect { case DontTouchAnnotation(t) => t.serialize }
+    ts should equal (Seq("~MyModule|Queue>enq_ptr_value"))
+  }
+}