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.

3 files changed, 477 insertions, 0 deletions

diff --git a/core/src/main/scala/chisel3/experimental/dataview/DataProduct.scala b/core/src/main/scala/chisel3/experimental/dataview/DataProduct.scala
new file mode 100644
index 00000000..55dd8505
--- /dev/null
+++ b/core/src/main/scala/chisel3/experimental/dataview/DataProduct.scala
@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.experimental.dataview
+
+import chisel3.experimental.BaseModule
+import chisel3.{Data, getRecursiveFields}
+
+import scala.annotation.implicitNotFound
+
+/** Typeclass interface for getting elements of type [[Data]]
+  *
+  * This is needed for validating [[DataView]]s targeting type `A`.
+  * Can be thought of as "can be the Target of a DataView".
+  *
+  * Chisel provides some implementations in [[DataProduct$ object DataProduct]] that are available
+  * by default in the implicit scope.
+  *
+  * @tparam A Type that has elements of type [[Data]]
+  * @see [[https://www.chisel-lang.org/chisel3/docs/explanations/dataview#dataproduct Detailed Documentation]]
+  */
+@implicitNotFound("Could not find implicit value for DataProduct[${A}].\n" +
+  "Please see https://www.chisel-lang.org/chisel3/docs/explanations/dataview#dataproduct")
+trait DataProduct[-A] {
+  /** Provides [[Data]] elements within some containing object
+    *
+    * @param a Containing object
+    * @param path Hierarchical path to current signal (for error reporting)
+    * @return Data elements and associated String paths (Strings for error reporting only!)
+    */
+  def dataIterator(a: A, path: String): Iterator[(Data, String)]
+
+  /** Returns a checker to test if the containing object contains a `Data` object
+    * @note Implementers may want to override if iterating on all `Data` is expensive for `A` and `A`
+    *       will primarily be used in `PartialDataViews`
+    * @note The returned value is a function, not a true Set, but is describing the functionality of
+    *       Set containment
+    * @param a Containing object
+    * @return A checker that itself returns True if a given `Data` is contained in `a`
+    *         as determined by an `==` test
+    */
+  def dataSet(a: A): Data => Boolean = dataIterator(a, "").map(_._1).toSet
+}
+
+/** Encapsulating object for automatically provided implementations of [[DataProduct]]
+  *
+  * @note DataProduct implementations provided in this object are available in the implicit scope
+  */
+object DataProduct {
+  /** [[DataProduct]] implementation for [[Data]] */
+  implicit val dataDataProduct: DataProduct[Data] = new DataProduct[Data] {
+    def dataIterator(a: Data, path: String): Iterator[(Data, String)] =
+      getRecursiveFields.lazily(a, path).iterator
+  }
+
+  /** [[DataProduct]] implementation for [[BaseModule]] */
+  implicit val userModuleDataProduct: DataProduct[BaseModule] = new DataProduct[BaseModule] {
+    def dataIterator(a: BaseModule, path: String): Iterator[(Data, String)] = {
+      a.getIds.iterator.flatMap {
+        case d: Data if d.getOptionRef.isDefined => // Using ref to decide if it's truly hardware in the module
+          Seq(d -> s"${path}.${d.instanceName}")
+        case b: BaseModule => dataIterator(b, s"$path.${b.instanceName}")
+        case _ => Seq.empty
+      }
+    }
+    // Overridden for performance
+    override def dataSet(a: BaseModule): Data => Boolean = {
+      val lastId = a._lastId // Not cheap to compute
+      // Return a function
+      e => e._id > a._id && e._id <= lastId
+    }
+  }
+}
diff --git a/core/src/main/scala/chisel3/experimental/dataview/DataView.scala b/core/src/main/scala/chisel3/experimental/dataview/DataView.scala
new file mode 100644
index 00000000..caf004c2
--- /dev/null
+++ b/core/src/main/scala/chisel3/experimental/dataview/DataView.scala
@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.experimental.dataview
+
+import chisel3._
+import chisel3.internal.sourceinfo.SourceInfo
+import scala.reflect.runtime.universe.WeakTypeTag
+
+import annotation.implicitNotFound
+
+
+/** Mapping between a target type `T` and a view type `V`
+  *
+  * Enables calling `.viewAs[T]` on instances of the target type.
+  *
+  * ==Detailed documentation==
+  *   - [[https://www.chisel-lang.org/chisel3/docs/explanations/dataview Explanation]]
+  *   - [[https://www.chisel-lang.org/chisel3/docs/cookbooks/dataview Cookbook]]
+  *
+  * @example {{{
+  * class Foo(val w: Int) extends Bundle {
+  *   val a = UInt(w.W)
+  * }
+  * class Bar(val w: Int) extends Bundle {
+  *   val b = UInt(w.W)
+  * }
+  * // DataViews are created using factory methods in the companion object
+  * implicit val view = DataView[Foo, Bar](
+  *   // The first argument is a function constructing a Foo from a Bar
+  *   foo => new Bar(foo.w)
+  *   // The remaining arguments are a variable number of field pairings
+  *   _.a -> _.b
+  * )
+  * }}}
+  *
+  * @tparam T Target type (must have an implementation of [[DataProduct]])
+  * @tparam V View type
+  * @see [[DataView$ object DataView]] for factory methods
+  * @see [[PartialDataView object PartialDataView]] for defining non-total `DataViews`
+  */
+@implicitNotFound("Could not find implicit value for DataView[${T}, ${V}].\n" +
+  "Please see https://www.chisel-lang.org/chisel3/docs/explanations/dataview")
+sealed class DataView[T : DataProduct, V <: Data] private[chisel3] (
+  /** Function constructing an object of the View type from an object of the Target type */
+  private[chisel3] val mkView: T => V,
+  /** Function that returns corresponding fields of the target and view */
+  private[chisel3] val mapping: (T, V) => Iterable[(Data, Data)],
+  // Aliasing this with a def below to make the ScalaDoc show up for the field
+  _total: Boolean
+)(
+  implicit private[chisel3] val sourceInfo: SourceInfo
+) {
+  /** Indicates if the mapping contains every field of the target */
+  def total: Boolean = _total
+
+  override def toString: String = {
+    val base = sourceInfo.makeMessage(x => x)
+    val loc = if (base.nonEmpty) base else "@unknown"
+    val name = if (total) "DataView" else "PartialDataView"
+    s"$name(defined $loc)"
+  }
+
+  /** Compose two `DataViews` together to construct a view from the target of this `DataView` to the
+    * view type of the second `DataView`
+    *
+    * @param g a DataView from `V` to new view-type `V2`
+    * @tparam V2 View type of `DataView` `g`
+    * @return a new `DataView` from the original `T` to new view-type `V2`
+    */
+  def andThen[V2 <: Data](g: DataView[V, V2])(implicit sourceInfo: SourceInfo): DataView[T, V2] = {
+    val self = this
+    // We have to pass the DataProducts and DataViews manually to .viewAs below
+    val tdp = implicitly[DataProduct[T]]
+    val vdp = implicitly[DataProduct[V]]
+    new DataView[T, V2](
+      t => g.mkView(mkView(t)),
+      { case (t, v2) => List(t.viewAs[V](tdp, self).viewAs[V2](vdp, g) -> v2) },
+      this.total && g.total
+    ) {
+      override def toString: String = s"$self andThen $g"
+    }
+  }
+}
+
+/** Factory methods for constructing [[DataView]]s, see class for example use */
+object DataView {
+
+  /** Default factory method, alias for [[pairs]] */
+  def apply[T : DataProduct, V <: Data](mkView: T => V, pairs: ((T, V) => (Data, Data))*)(implicit sourceInfo: SourceInfo): DataView[T, V] =
+    DataView.pairs(mkView, pairs: _*)
+
+  /** Construct [[DataView]]s with pairs of functions from the target and view to corresponding fields */
+  def pairs[T : DataProduct, V <: Data](mkView: T => V, pairs: ((T, V) => (Data, Data))*)(implicit sourceInfo: SourceInfo): DataView[T, V] =
+    mapping(mkView: T => V, swizzle(pairs))
+
+  /** More general factory method for complex mappings */
+  def mapping[T : DataProduct, V <: Data](mkView: T => V, mapping: (T, V) => Iterable[(Data, Data)])(implicit sourceInfo: SourceInfo): DataView[T, V] =
+    new DataView[T, V](mkView, mapping, _total = true)
+
+  /** Provides `invert` for invertible [[DataView]]s
+    *
+    * This must be done as an extension method because it applies an addition constraint on the `Target`
+    * type parameter, namely that it must be a subtype of [[Data]].
+    *
+    * @note [[PartialDataView]]s are **not** invertible and will result in an elaboration time exception
+    */
+  implicit class InvertibleDataView[T <: Data : WeakTypeTag, V <: Data : WeakTypeTag](view: DataView[T, V]) {
+    def invert(mkView: V => T): DataView[V, T] = {
+      // It would've been nice to make this a compiler error, but it's unclear how to make that work.
+      // We tried having separate TotalDataView and PartialDataView and only defining inversion for
+      // TotalDataView. For some reason, implicit resolution wouldn't invert TotalDataViews. This is
+      // probably because it was looking for the super-type DataView and since invertDataView was
+      // only defined on TotalDataView, it wasn't included in implicit resolution. Thus we end up
+      // with a runtime check.
+      if (!view.total) {
+        val tt = implicitly[WeakTypeTag[T]].tpe
+        val vv = implicitly[WeakTypeTag[V]].tpe
+        val msg = s"Cannot invert '$view' as it is non-total.\n  Try providing a DataView[$vv, $tt]." +
+          s"\n  Please see https://www.chisel-lang.org/chisel3/docs/explanations/dataview."
+        throw InvalidViewException(msg)
+      }
+      implicit val sourceInfo = view.sourceInfo
+      new DataView[V, T](mkView, swapArgs(view.mapping), view.total)
+    }
+  }
+
+  private[dataview] def swizzle[A, B, C, D](fs: Iterable[(A, B) => (C, D)]): (A, B) => Iterable[(C, D)] = {
+    case (a, b) => fs.map(f => f(a, b))
+  }
+
+  private def swapArgs[A, B, C, D](f: (A, B) => Iterable[(C, D)]): (B, A) => Iterable[(D, C)] = {
+    case (b, a) => f(a, b).map(_.swap)
+  }
+
+  /** All Chisel Data are viewable as their own type */
+  implicit def identityView[A <: Data](implicit sourceInfo: SourceInfo): DataView[A, A] =
+    DataView[A, A](chiselTypeOf.apply, { case (x, y) => (x, y) })
+}
+
+/** Factory methods for constructing non-total [[DataView]]s */
+object PartialDataView {
+
+  /** Default factory method, alias for [[pairs]] */
+  def apply[T: DataProduct, V <: Data](mkView: T => V, pairs: ((T, V) => (Data, Data))*)(implicit sourceInfo: SourceInfo): DataView[T, V] =
+    PartialDataView.pairs(mkView, pairs: _*)
+
+  /** Construct [[DataView]]s with pairs of functions from the target and view to corresponding fields */
+  def pairs[T: DataProduct, V <: Data](mkView: T => V, pairs: ((T, V) => (Data, Data))*)(implicit sourceInfo: SourceInfo): DataView[T, V] =
+    mapping(mkView, DataView.swizzle(pairs))
+
+  /** More general factory method for complex mappings */
+  def mapping[T: DataProduct, V <: Data](mkView: T => V, mapping: (T, V) => Iterable[(Data, Data)])(implicit sourceInfo: SourceInfo): DataView[T, V] =
+    new DataView[T, V](mkView, mapping, _total = false)
+}
diff --git a/core/src/main/scala/chisel3/experimental/dataview/package.scala b/core/src/main/scala/chisel3/experimental/dataview/package.scala
new file mode 100644
index 00000000..1acf43e1
--- /dev/null
+++ b/core/src/main/scala/chisel3/experimental/dataview/package.scala
@@ -0,0 +1,251 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.experimental
+
+import chisel3._
+import chisel3.internal._
+import chisel3.internal.sourceinfo.SourceInfo
+
+import scala.annotation.{implicitNotFound, tailrec}
+import scala.collection.mutable
+import scala.collection.immutable.LazyList // Needed for 2.12 alias
+
+package object dataview {
+  case class InvalidViewException(message: String) extends ChiselException(message)
+
+  /** Provides `viewAs` for types that have an implementation of [[DataProduct]]
+    *
+    * Calling `viewAs` also requires an implementation of [[DataView]] for the target type
+    */
+  implicit class DataViewable[T](target: T) {
+    def viewAs[V <: Data](implicit dataproduct: DataProduct[T], dataView: DataView[T, V]): V = {
+      // TODO put a try catch here for ExpectedHardwareException and perhaps others
+      // It's likely users will accidentally use chiselTypeOf or something that may error,
+      // The right thing to use is DataMirror...chiselTypeClone because of composition with DataView.andThen
+      // Another option is that .andThen could give a fake binding making chiselTypeOfs in the user code safe
+      val result: V = dataView.mkView(target)
+      requireIsChiselType(result, "viewAs")
+
+      doBind(target, result, dataView)
+
+      // Setting the parent marks these Data as Views
+      result.setAllParents(Some(ViewParent))
+      // The names of views do not matter except for when a view is annotated. For Views that correspond
+      // To a single Data, we just forward the name of the Target. For Views that correspond to more
+      // than one Data, we return this assigned name but rename it in the Convert stage
+      result.forceName(None, "view", Builder.viewNamespace)
+      result
+    }
+  }
+
+  // This private type alias lets us provide a custom error message for misuing the .viewAs for upcasting Bundles
+  @implicitNotFound("${A} is not a subtype of ${B}! Did you mean .viewAs[${B}]? " +
+    "Please see https://www.chisel-lang.org/chisel3/docs/cookbooks/dataview")
+  private type SubTypeOf[A, B] = A <:< B
+
+  /** Provides `viewAsSupertype` for subclasses of [[Bundle]] */
+  implicit class BundleUpcastable[T <: Bundle](target: T) {
+    /** View a [[Bundle]] or [[Record]] as a parent type (upcast) */
+    def viewAsSupertype[V <: Bundle](proto: V)(implicit ev: SubTypeOf[T, V], sourceInfo: SourceInfo): V = {
+      implicit val dataView = PartialDataView.mapping[T, V](_ => proto, {
+        case (a, b) =>
+          val aElts = a.elements
+          val bElts = b.elements
+          val bKeys = bElts.keySet
+          val keys = aElts.keysIterator.filter(bKeys.contains)
+          keys.map(k => aElts(k) -> bElts(k)).toSeq
+      })
+      target.viewAs[V]
+    }
+  }
+
+  private def nonTotalViewException(dataView: DataView[_, _], target: Any, view: Data, targetFields: Seq[String], viewFields: Seq[String]) = {
+    def missingMsg(name: String, fields: Seq[String]): Option[String] = {
+      val str = fields.mkString(", ")
+      fields.size match {
+        case 0 => None
+        case 1 => Some(s"$name field '$str' is missing")
+        case _ => Some(s"$name fields '$str' are missing")
+      }
+    }
+    val vs = missingMsg("view", viewFields)
+    val ts = missingMsg("target", targetFields)
+    val reasons = (ts ++ vs).mkString(" and ").capitalize
+    val suggestion = if (ts.nonEmpty) "\n  If the view *should* be non-total, try a 'PartialDataView'." else ""
+    val msg = s"Viewing $target as $view is non-Total!\n  $reasons.\n  DataView used is $dataView.$suggestion"
+    throw InvalidViewException(msg)
+  }
+
+  // TODO should this be moved to class Aggregate / can it be unified with Aggregate.bind?
+  private def doBind[T : DataProduct, V <: Data](target: T, view: V, dataView: DataView[T, V]): Unit = {
+    val mapping = dataView.mapping(target, view)
+    val total = dataView.total
+    // Lookups to check the mapping results
+    val viewFieldLookup: Map[Data, String] = getRecursiveFields(view, "_").toMap
+    val targetContains: Data => Boolean = implicitly[DataProduct[T]].dataSet(target)
+
+    // Resulting bindings for each Element of the View
+    val childBindings =
+      new mutable.HashMap[Data, mutable.ListBuffer[Element]] ++
+        viewFieldLookup.view
+          .collect { case (elt: Element, _) => elt }
+          .map(_ -> new mutable.ListBuffer[Element])
+
+    def viewFieldName(d: Data): String =
+      viewFieldLookup.get(d).map(_ + " ").getOrElse("") + d.toString
+
+    // Helper for recording the binding of each
+    def onElt(te: Element, ve: Element): Unit = {
+      // TODO can/should we aggregate these errors?
+      def err(name: String, arg: Data) =
+        throw InvalidViewException(s"View mapping must only contain Elements within the $name, got $arg")
+
+      // The elements may themselves be views, look through the potential chain of views for the Elements
+      // that are actually members of the target or view
+      val tex = unfoldView(te).find(targetContains).getOrElse(err("Target", te))
+      val vex = unfoldView(ve).find(viewFieldLookup.contains).getOrElse(err("View", ve))
+
+      if (tex.getClass != vex.getClass) {
+        val fieldName = viewFieldName(vex)
+        throw InvalidViewException(s"Field $fieldName specified as view of non-type-equivalent value $tex")
+      }
+      // View width must be unknown or match target width
+      if (vex.widthKnown && vex.width != tex.width) {
+        def widthAsString(x: Element) = x.widthOption.map("<" + _ + ">").getOrElse("<unknown>")
+        val fieldName = viewFieldName(vex)
+        val vwidth = widthAsString(vex)
+        val twidth = widthAsString(tex)
+        throw InvalidViewException(s"View field $fieldName has width ${vwidth} that is incompatible with target value $tex's width ${twidth}")
+      }
+      childBindings(vex) += tex
+    }
+
+    mapping.foreach {
+      // Special cased because getMatchedFields checks typeEquivalence on Elements (and is used in Aggregate path)
+      // Also saves object allocations on common case of Elements
+      case (ae: Element, be: Element) => onElt(ae, be)
+
+      case (aa: Aggregate, ba: Aggregate) =>
+        if (!ba.typeEquivalent(aa)) {
+          val fieldName = viewFieldLookup(ba)
+          throw InvalidViewException(s"field $fieldName specified as view of non-type-equivalent value $aa")
+        }
+        getMatchedFields(aa, ba).foreach {
+          case (aelt: Element, belt: Element) => onElt(aelt, belt)
+          case _ => // Ignore matching of Aggregates
+        }
+    }
+
+    // Errors in totality of the View, use var List to keep fast path cheap (no allocation)
+    var viewNonTotalErrors: List[Data] = Nil
+    var targetNonTotalErrors: List[String] = Nil
+
+    val targetSeen: Option[mutable.Set[Data]] = if (total) Some(mutable.Set.empty[Data]) else None
+
+    val resultBindings = childBindings.map { case (data, targets) =>
+      val targetsx = targets match {
+        case collection.Seq(target: Element) => target
+        case collection.Seq() =>
+          viewNonTotalErrors = data :: viewNonTotalErrors
+          data.asInstanceOf[Element] // Return the Data itself, will error after this map, cast is safe
+        case x =>
+          throw InvalidViewException(s"Got $x, expected Seq(_: Direct)")
+      }
+      // TODO record and report aliasing errors
+      targetSeen.foreach(_ += targetsx)
+      data -> targetsx
+    }.toMap
+
+    // Check for totality of Target
+    targetSeen.foreach { seen =>
+      val lookup = implicitly[DataProduct[T]].dataIterator(target, "_")
+      for (missed <- lookup.collect { case (d: Element, name) if !seen(d) => name }) {
+        targetNonTotalErrors = missed :: targetNonTotalErrors
+      }
+    }
+    if (viewNonTotalErrors != Nil || targetNonTotalErrors != Nil) {
+      val viewErrors = viewNonTotalErrors.map(f => viewFieldLookup.getOrElse(f, f.toString))
+      nonTotalViewException(dataView, target, view, targetNonTotalErrors, viewErrors)
+    }
+
+    view match {
+      case elt: Element => view.bind(ViewBinding(resultBindings(elt)))
+      case agg: Aggregate =>
+        // We record total Data mappings to provide a better .toTarget
+        val topt = target match {
+          case d: Data if total => Some(d)
+          case _ =>
+            // Record views that don't have the simpler .toTarget for later renaming
+            Builder.unnamedViews += view
+            None
+        }
+        // TODO We must also record children as unnamed, some could be namable but this requires changes to the Binding
+        getRecursiveFields.lazily(view, "_").foreach {
+          case (agg: Aggregate, _) if agg != view =>
+            Builder.unnamedViews += agg
+          case _ => // Do nothing
+        }
+        agg.bind(AggregateViewBinding(resultBindings, topt))
+    }
+  }
+
+  // Traces an Element that may (or may not) be a view until it no longer maps
+  // Inclusive of the argument
+  private def unfoldView(elt: Element): LazyList[Element] = {
+    def rec(e: Element): LazyList[Element] = e.topBindingOpt match {
+      case Some(ViewBinding(target)) => target #:: rec(target)
+      case Some(AggregateViewBinding(mapping, _)) =>
+        val target = mapping(e)
+        target #:: rec(target)
+      case Some(_) | None => LazyList.empty
+    }
+    elt #:: rec(elt)
+  }
+
+  // Safe for all Data
+  private[chisel3] def isView(d: Data): Boolean = d._parent.contains(ViewParent)
+
+  /** Turn any [[Element]] that could be a View into a concrete Element
+    *
+    * This is the fundamental "unwrapping" or "tracing" primitive operation for handling Views within
+    * Chisel.
+    */
+  private[chisel3] def reify(elt: Element): Element =
+    reify(elt, elt.topBinding)
+
+  /** Turn any [[Element]] that could be a View into a concrete Element
+    *
+    * This is the fundamental "unwrapping" or "tracing" primitive operation for handling Views within
+    * Chisel.
+    */
+  @tailrec private[chisel3] def reify(elt: Element, topBinding: TopBinding): Element =
+    topBinding match {
+      case ViewBinding(target) => reify(target, elt.topBinding)
+      case _ => elt
+    }
+
+    /** Determine the target of a View if it is a single Target
+      *
+      * @note An Aggregate may be a view of unrelated [[Data]] (eg. like a Seq or tuple) and thus this
+      *       there is no single Data representing the Target and this function will return None
+      * @return The single Data target of this view or None if a single Data doesn't exist
+      */
+    private[chisel3] def reifySingleData(data: Data): Option[Data] = {
+      val candidate: Option[Data] =
+        data.binding.collect { // First check if this is a total mapping of an Aggregate
+          case AggregateViewBinding(_, Some(t)) => t
+        }.orElse { // Otherwise look via top binding
+          data.topBindingOpt match {
+            case None => None
+            case Some(ViewBinding(target)) => Some(target)
+            case Some(AggregateViewBinding(lookup, _)) => lookup.get(data)
+            case Some(_) => None
+          }
+        }
+      candidate.flatMap { d =>
+        // Candidate may itself be a view, keep tracing in those cases
+        if (isView(d)) reifySingleData(d) else Some(d)
+      }
+    }
+
+}