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

diff --git a/core/src/main/scala/chisel3/RawModule.scala b/core/src/main/scala/chisel3/RawModule.scala
index fadb8dae..74e9db6c 100644
--- a/core/src/main/scala/chisel3/RawModule.scala
+++ b/core/src/main/scala/chisel3/RawModule.scala
@@ -11,6 +11,7 @@ import chisel3.internal.BaseModule.ModuleClone
 import chisel3.internal.Builder._
 import chisel3.internal.firrtl._
 import chisel3.internal.sourceinfo.UnlocatableSourceInfo
+import _root_.firrtl.annotations.{IsModule, ModuleTarget}
 
 /** Abstract base class for Modules that contain Chisel RTL.
   * This abstract base class is a user-defined module which does not include implicit clock and reset and supports
@@ -157,6 +158,9 @@ trait RequireSyncReset extends Module {
 
 package object internal {
 
+  /** Marker trait for modules that are not true modules */
+  private[chisel3] trait PseudoModule extends BaseModule
+
   // Private reflective version of "val io" to maintain Chisel.Module semantics without having
   // io as a virtual method. See https://github.com/freechipsproject/chisel3/pull/1550 for more
   // information about the removal of "val io"
@@ -264,4 +268,31 @@ package object internal {
       }
     }
   }
+
+  /** Internal API for [[ViewParent]] */
+  sealed private[chisel3] class ViewParentAPI extends RawModule()(ExplicitCompileOptions.Strict) with PseudoModule {
+    // We must provide `absoluteTarget` but not `toTarget` because otherwise they would be exactly
+    // the same and we'd have no way to distinguish the kind of target when renaming view targets in
+    // the Converter
+    // Note that this is not overriding .toAbsoluteTarget, that is a final def in BaseModule that delegates
+    // to this method
+    private[chisel3] val absoluteTarget: IsModule = ModuleTarget(this.circuitName, "_$$AbsoluteView$$_")
+
+    // This module is not instantiable
+    override private[chisel3] def generateComponent(): Option[Component] = None
+    override private[chisel3] def initializeInParent(parentCompileOptions: CompileOptions): Unit = ()
+    // This module is not really part of the circuit
+    _parent = None
+
+    // Sigil to mark views, starts with '_' to make it a legal FIRRTL target
+    override def desiredName = "_$$View$$_"
+
+    private[chisel3] val fakeComponent: Component = DefModule(this, desiredName, Nil, Nil)
+  }
+
+  /** Special internal object representing the parent of all views
+    *
+    * @note this is a val instead of an object because of the need to wrap in Module(...)
+    */
+  private[chisel3] val ViewParent = Module.do_apply(new ViewParentAPI)(UnlocatableSourceInfo, ExplicitCompileOptions.Strict)
 }