From f45216effc573d33d4aa4e525cff955ab332efbd Mon Sep 17 00:00:00 2001
From: Jiuyang Liu
Date: Thu, 4 Feb 2021 00:36:12 +0000
Subject: Remove Deprecated APIs (#1730)

---
 core/src/main/scala/chisel3/experimental/package.scala | 7 -------
 1 file changed, 7 deletions(-)

(limited to 'core/src/main/scala/chisel3/experimental')

diff --git a/core/src/main/scala/chisel3/experimental/package.scala b/core/src/main/scala/chisel3/experimental/package.scala
index ec3f2a79..4dc7ba4b 100644
--- a/core/src/main/scala/chisel3/experimental/package.scala
+++ b/core/src/main/scala/chisel3/experimental/package.scala
@@ -20,13 +20,6 @@ package object experimental {
 
   type ChiselEnum = EnumFactory
 
-  @deprecated("Use the version in chisel3._", "3.2")
-  val withClockAndReset = chisel3.withClockAndReset
-  @deprecated("Use the version in chisel3._", "3.2")
-  val withClock = chisel3.withClock
-  @deprecated("Use the version in chisel3._", "3.2")
-  val withReset = chisel3.withReset
-
   // Rocket Chip-style clonemodule
 
   /** A record containing the results of CloneModuleAsRecord
-- 
cgit v1.2.3


From 0a0d7c6aac4326f2127d6d95efa5a4e10c81946c Mon Sep 17 00:00:00 2001
From: Jack Koenig
Date: Mon, 12 Oct 2020 21:02:27 -0700
Subject: Make it possible to GC Data instances

No longer create a pointer from parent to every HasId, only do it by
default for BaseModules and MemBases. Add pointer from parent to Data
upon binding the Data.

* Add MemTypeBinding for port types of Mems

This binding is similar to the SampleElementBinding for Vecs in that
these Data are not truly hardware, but are represented in the FIRRTL IR
and thus need some representation.

* Call _onModuleClose on unbound Records

This maintains some corner-case behavior that is nevertheless relied
upon. It ensures that refs are set for the elements of Records, even if
they are not bound to any real hardware.
---
 core/src/main/scala/chisel3/experimental/Analog.scala | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

(limited to 'core/src/main/scala/chisel3/experimental')

diff --git a/core/src/main/scala/chisel3/experimental/Analog.scala b/core/src/main/scala/chisel3/experimental/Analog.scala
index df76fd70..2ce2c86d 100644
--- a/core/src/main/scala/chisel3/experimental/Analog.scala
+++ b/core/src/main/scala/chisel3/experimental/Analog.scala
@@ -45,7 +45,8 @@ final class Analog private (private[chisel3] val width: Width) extends Element {
 
   // Define setter/getter pairing
   // Analog can only be bound to Ports and Wires (and Unbound)
-  private[chisel3] override def bind(target: Binding, parentDirection: SpecifiedDirection) {
+  private[chisel3] override def bind(target: Binding, parentDirection: SpecifiedDirection): Unit = {
+    _parent.foreach(_.addId(this))
     SpecifiedDirection.fromParent(parentDirection, specifiedDirection) match {
       case SpecifiedDirection.Unspecified | SpecifiedDirection.Flip =>
       case x => throwException(s"Analog may not have explicit direction, got '$x'")
-- 
cgit v1.2.3


From 2b5466c7773c8cd7a08c48aa00d9365cbb205fd2 Mon Sep 17 00:00:00 2001
From: Schuyler Eldridge
Date: Wed, 10 Feb 2021 22:19:09 -0500
Subject: Fix stack trace trimming across Driver/ChiselStage (#1771)

* Handle MemTypeBinding in Analog

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@sifive.com>

* Fix stack trace trimming across ChiselStage

Fix bug in stack trace trimming behavior. Now, the following is what
happens:

1. The Builder, if catching accumulated errors, will now throw a
   ChiselException with a Scala-trimmed Stack trace. Previously, this
   would throw the full excpetion.
2. The Elaborate phase handles stack trace trimming. By default, any
   Throwable thrown during elaboration will have its stack
   trace *mutably* trimmed and is rethrown. A logger.error is printed
   stating that there was an error during elaboration and how the user
   can turn on the full stack trace. If the --full-stacktrace option
   is on, then the Throwable is not caught and only the first
   logger.error (saying that elaboration failed) will be printed.
3. ChiselStage (the class), ChiselStage$ (the object), and ChiselMain
   all inherit the behavior of (2).

Mutable stack trace trimming behavior is moved into an implicit
class (previously this was defined on ChiselException only) so this
can be applied to any Throwable.

No StageErrors are now thrown anymore. However, StageErrors may still
be caught by ChiselMain (since it is a StageMain).

Testing is added for ChiselMain, ChiselStage, and ChiselStage$ to test
all this behavior.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@sifive.com>---
 core/src/main/scala/chisel3/experimental/Analog.scala | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'core/src/main/scala/chisel3/experimental')

diff --git a/core/src/main/scala/chisel3/experimental/Analog.scala b/core/src/main/scala/chisel3/experimental/Analog.scala
index 2ce2c86d..6cca81f5 100644
--- a/core/src/main/scala/chisel3/experimental/Analog.scala
+++ b/core/src/main/scala/chisel3/experimental/Analog.scala
@@ -56,6 +56,7 @@ final class Analog private (private[chisel3] val width: Width) extends Element {
       case ChildBinding(parent) => parent.topBinding
       // See https://github.com/freechipsproject/chisel3/pull/946
       case SampleElementBinding(parent) => parent.topBinding
+      case a: MemTypeBinding[_] => a
     }
 
     targetTopBinding match {
@@ -83,4 +84,3 @@ final class Analog private (private[chisel3] val width: Width) extends Element {
 object Analog {
   def apply(width: Width): Analog = new Analog(width)
 }
-
-- 
cgit v1.2.3


From 6deb379b1d8bafc81a605f60476bf0f24eac60b4 Mon Sep 17 00:00:00 2001
From: Chick Markley
Date: Tue, 27 Apr 2021 12:17:17 -0700
Subject: Introduce VecLiterals (#1834)

This PR provides for support for Vec literals. They can be one of two forms
Inferred:
```
Vec.Lit(0x1.U, 0x2.U)
```
or explicit:
```
Vec(2, UInt(4.W)).Lit(0 -> 0x1.U, 1 -> 0x2.U)
```
- Explicit form allows for partial, or sparse, literals.
- Vec literals can be used as Register initializers
- Arbitrary nesting (consistent with type constraints is allowed)---
 .../main/scala/chisel3/experimental/package.scala  | 33 +++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

(limited to 'core/src/main/scala/chisel3/experimental')

diff --git a/core/src/main/scala/chisel3/experimental/package.scala b/core/src/main/scala/chisel3/experimental/package.scala
index 4dc7ba4b..e8360430 100644
--- a/core/src/main/scala/chisel3/experimental/package.scala
+++ b/core/src/main/scala/chisel3/experimental/package.scala
@@ -2,6 +2,8 @@
 
 package chisel3
 
+import chisel3.internal.sourceinfo.SourceInfo
+
 /** Package for experimental features, which may have their API changed, be removed, etc.
   *
   * Because its contents won't necessarily have the same level of stability and support as
@@ -124,10 +126,39 @@ package object experimental {
 
   object BundleLiterals {
     implicit class AddBundleLiteralConstructor[T <: Record](x: T) {
-      def Lit(elems: (T => (Data, Data))*): T = {
+      def Lit(elems: (T => (Data, Data))*)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = {
+        x._makeLit(elems: _*)
+      }
+    }
+  }
+
+  /** This class provides the `Lit` method needed to define a `Vec` literal
+    */
+  object VecLiterals {
+    implicit class AddVecLiteralConstructor[T <: Data](x: Vec[T]) {
+      /** Given a generator of a list tuples of the form [Int, Data]
+        * constructs a Vec literal, parallel concept to `BundleLiteral`
+        *
+        * @param elems tuples of an index and a literal value
+        * @return
+        */
+      def Lit(elems: (Int, T)*)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Vec[T] = {
         x._makeLit(elems: _*)
       }
     }
+
+    implicit class AddObjectLiteralConstructor(x: Vec.type) {
+      /** This provides an literal construction method for cases using
+        * object `Vec` as in `Vec.Lit(1.U, 2.U)`
+        */
+      def Lit[T <: Data](elems: T*)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Vec[T] = {
+        require(elems.nonEmpty, s"Lit.Vec(...) must have at least one element")
+        val indexElements = elems.zipWithIndex.map { case (element, index) => (index, element)}
+        val widestElement = elems.maxBy(_.getWidth)
+        val vec: Vec[T] = Vec.apply(indexElements.length, chiselTypeOf(widestElement))
+        vec.Lit(indexElements:_*)
+      }
+    }
   }
 
   // Use to add a prefix to any component generated in input scope
-- 
cgit v1.2.3


From 4d8fed00225d15221cf32177ea9147b20d0b91f7 Mon Sep 17 00:00:00 2001
From: Kevin Laeufer
Date: Thu, 29 Apr 2021 11:52:20 -0700
Subject: verification: guard statements with module reset (#1891)

---
 .../experimental/verification/package.scala        | 24 ++++++++++++----------
 1 file changed, 13 insertions(+), 11 deletions(-)

(limited to 'core/src/main/scala/chisel3/experimental')

diff --git a/core/src/main/scala/chisel3/experimental/verification/package.scala b/core/src/main/scala/chisel3/experimental/verification/package.scala
index 5c71bd5f..816299a3 100644
--- a/core/src/main/scala/chisel3/experimental/verification/package.scala
+++ b/core/src/main/scala/chisel3/experimental/verification/package.scala
@@ -2,9 +2,8 @@
 
 package chisel3.experimental
 
-import chisel3.{Bool, CompileOptions}
+import chisel3._
 import chisel3.internal.Builder
-import chisel3.internal.Builder.pushCommand
 import chisel3.internal.firrtl.{Formal, Verification}
 import chisel3.internal.sourceinfo.SourceInfo
 
@@ -13,9 +12,10 @@ package object verification {
     def apply(predicate: Bool, msg: String = "")(
       implicit sourceInfo: SourceInfo,
       compileOptions: CompileOptions): Unit = {
-      val clock = Builder.forcedClock
-      pushCommand(Verification(Formal.Assert, sourceInfo, clock.ref,
-        predicate.ref, msg))
+      when (!Module.reset.asBool) {
+        val clock = Module.clock
+        Builder.pushCommand(Verification(Formal.Assert, sourceInfo, clock.ref, predicate.ref, msg))
+      }
     }
   }
 
@@ -23,9 +23,10 @@ package object verification {
     def apply(predicate: Bool, msg: String = "")(
       implicit sourceInfo: SourceInfo,
       compileOptions: CompileOptions): Unit = {
-      val clock = Builder.forcedClock
-      pushCommand(Verification(Formal.Assume, sourceInfo, clock.ref,
-        predicate.ref, msg))
+      when (!Module.reset.asBool) {
+        val clock = Module.clock
+        Builder.pushCommand(Verification(Formal.Assume, sourceInfo, clock.ref, predicate.ref, msg))
+      }
     }
   }
 
@@ -33,9 +34,10 @@ package object verification {
     def apply(predicate: Bool, msg: String = "")(
       implicit sourceInfo: SourceInfo,
       compileOptions: CompileOptions): Unit = {
-      val clock = Builder.forcedClock
-      pushCommand(Verification(Formal.Cover, sourceInfo, clock.ref,
-        predicate.ref, msg))
+      val clock = Module.clock
+      when (!Module.reset.asBool) {
+        Builder.pushCommand(Verification(Formal.Cover, sourceInfo, clock.ref, predicate.ref, msg))
+      }
     }
   }
 }
-- 
cgit v1.2.3


From f8053db3d20b733e0119b77595f0cdfcdab71057 Mon Sep 17 00:00:00 2001
From: Deborah Soung
Date: Thu, 24 Jun 2021 14:03:28 -0700
Subject: create and extend annotatable BaseSim class for verification nodes
 (#1968)

* prototype annotating verif constructs

* switch to final class

* name emissions

* moving BaseSim to experimental

* adding name tests

* fixing quotation escapes

* emitting names, but everything has a default name

* only name things with provided/suggested names

* name every BaseSim node

* removing msg, unused imports

* fixing file exist calls---
 .../main/scala/chisel3/experimental/package.scala  |  6 +++++
 .../experimental/verification/package.scala        | 28 +++++++++++++++++-----
 2 files changed, 28 insertions(+), 6 deletions(-)

(limited to 'core/src/main/scala/chisel3/experimental')

diff --git a/core/src/main/scala/chisel3/experimental/package.scala b/core/src/main/scala/chisel3/experimental/package.scala
index e8360430..8018159f 100644
--- a/core/src/main/scala/chisel3/experimental/package.scala
+++ b/core/src/main/scala/chisel3/experimental/package.scala
@@ -2,6 +2,7 @@
 
 package chisel3
 
+import chisel3.internal.NamedComponent
 import chisel3.internal.sourceinfo.SourceInfo
 
 /** Package for experimental features, which may have their API changed, be removed, etc.
@@ -165,4 +166,9 @@ package object experimental {
   val prefix = chisel3.internal.prefix
   // Use to remove prefixes not in provided scope
   val noPrefix = chisel3.internal.noPrefix
+
+  /** Base simulation-only component. */
+  abstract class BaseSim extends NamedComponent {
+    _parent.foreach(_.addId(this))
+  }
 }
diff --git a/core/src/main/scala/chisel3/experimental/verification/package.scala b/core/src/main/scala/chisel3/experimental/verification/package.scala
index 816299a3..ca15a5c4 100644
--- a/core/src/main/scala/chisel3/experimental/verification/package.scala
+++ b/core/src/main/scala/chisel3/experimental/verification/package.scala
@@ -8,36 +8,52 @@ import chisel3.internal.firrtl.{Formal, Verification}
 import chisel3.internal.sourceinfo.SourceInfo
 
 package object verification {
+
+  /** Named class for assertions. */
+  final class Assert(val predicate: Bool) extends BaseSim
+
+  /** Named class for assumes. */
+  final class Assume(val predicate: Bool) extends BaseSim
+
+  /** Named class for covers. */
+  final class Cover(val predicate: Bool) extends BaseSim
+
   object assert {
     def apply(predicate: Bool, msg: String = "")(
       implicit sourceInfo: SourceInfo,
-      compileOptions: CompileOptions): Unit = {
+      compileOptions: CompileOptions): Assert = {
+      val a = new Assert(predicate)
       when (!Module.reset.asBool) {
         val clock = Module.clock
-        Builder.pushCommand(Verification(Formal.Assert, sourceInfo, clock.ref, predicate.ref, msg))
+        Builder.pushCommand(Verification(a, Formal.Assert, sourceInfo, clock.ref, predicate.ref, msg))
       }
+      a
     }
   }
 
   object assume {
     def apply(predicate: Bool, msg: String = "")(
       implicit sourceInfo: SourceInfo,
-      compileOptions: CompileOptions): Unit = {
+      compileOptions: CompileOptions): Assume = {
+      val a = new Assume(predicate)
       when (!Module.reset.asBool) {
         val clock = Module.clock
-        Builder.pushCommand(Verification(Formal.Assume, sourceInfo, clock.ref, predicate.ref, msg))
+        Builder.pushCommand(Verification(a, Formal.Assume, sourceInfo, clock.ref, predicate.ref, msg))
       }
+      a
     }
   }
 
   object cover {
     def apply(predicate: Bool, msg: String = "")(
       implicit sourceInfo: SourceInfo,
-      compileOptions: CompileOptions): Unit = {
+      compileOptions: CompileOptions): Cover = {
       val clock = Module.clock
+      val c = new Cover(predicate)
       when (!Module.reset.asBool) {
-        Builder.pushCommand(Verification(Formal.Cover, sourceInfo, clock.ref, predicate.ref, msg))
+        Builder.pushCommand(Verification(c, Formal.Cover, sourceInfo, clock.ref, predicate.ref, msg))
       }
+      c
     }
   }
 }
-- 
cgit v1.2.3


From 503ae520e7f997bcbc639b79869c9a4214d402ed Mon Sep 17 00:00:00 2001
From: Deborah Soung
Date: Tue, 6 Jul 2021 14:40:59 -0700
Subject: Make printf return BaseSim subclass so it can be named/annotated
 (#1992)

---
 .../chisel3/experimental/verification/package.scala     | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

(limited to 'core/src/main/scala/chisel3/experimental')

diff --git a/core/src/main/scala/chisel3/experimental/verification/package.scala b/core/src/main/scala/chisel3/experimental/verification/package.scala
index ca15a5c4..190083fd 100644
--- a/core/src/main/scala/chisel3/experimental/verification/package.scala
+++ b/core/src/main/scala/chisel3/experimental/verification/package.scala
@@ -9,16 +9,11 @@ import chisel3.internal.sourceinfo.SourceInfo
 
 package object verification {
 
-  /** Named class for assertions. */
-  final class Assert(val predicate: Bool) extends BaseSim
-
-  /** Named class for assumes. */
-  final class Assume(val predicate: Bool) extends BaseSim
+  object assert {
+    /** Named class for assertions. */
+    final class Assert(private[chisel3] val predicate: Bool) extends BaseSim
 
-  /** Named class for covers. */
-  final class Cover(val predicate: Bool) extends BaseSim
 
-  object assert {
     def apply(predicate: Bool, msg: String = "")(
       implicit sourceInfo: SourceInfo,
       compileOptions: CompileOptions): Assert = {
@@ -32,6 +27,9 @@ package object verification {
   }
 
   object assume {
+    /** Named class for assumes. */
+    final class Assume(private[chisel3] val predicate: Bool) extends BaseSim
+
     def apply(predicate: Bool, msg: String = "")(
       implicit sourceInfo: SourceInfo,
       compileOptions: CompileOptions): Assume = {
@@ -45,6 +43,9 @@ package object verification {
   }
 
   object cover {
+    /** Named class for covers. */
+    final class Cover(private[chisel3] val predicate: Bool) extends BaseSim
+
     def apply(predicate: Bool, msg: String = "")(
       implicit sourceInfo: SourceInfo,
       compileOptions: CompileOptions): Cover = {
-- 
cgit v1.2.3


From 1ceb974c55c6785c21ab3934fa750ade0702e276 Mon Sep 17 00:00:00 2001
From: Jack Koenig
Date: Thu, 12 Aug 2021 17:04:11 -0700
Subject: 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.---
 .../experimental/dataview/DataProduct.scala        |  72 ++++++
 .../chisel3/experimental/dataview/DataView.scala   | 154 +++++++++++++
 .../chisel3/experimental/dataview/package.scala    | 251 +++++++++++++++++++++
 3 files changed, 477 insertions(+)
 create mode 100644 core/src/main/scala/chisel3/experimental/dataview/DataProduct.scala
 create mode 100644 core/src/main/scala/chisel3/experimental/dataview/DataView.scala
 create mode 100644 core/src/main/scala/chisel3/experimental/dataview/package.scala

(limited to 'core/src/main/scala/chisel3/experimental')

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)
+      }
+    }
+
+}
-- 
cgit v1.2.3


From 9fa8da227569455a77596355aeb114f9c164510a Mon Sep 17 00:00:00 2001
From: Adam Izraelevitz
Date: Sun, 5 Sep 2021 12:11:32 -0700
Subject: Add Definition and Instance API (#2045)

This introduces a new experimental API for module instantiation that disentagles
elaborating the definition (or implementation) from instantiation of
a given module. This solves Chisel's longstanding reliance on
"Deduplication" for generating Verilog with multiple instances of the
same module.

The new API resides in package chisel3.experimental.hierarchy. Please
see the hierarchy ScalaDoc, documentation, and tests for examples of
use.

Co-authored-by: Jack Koenig <koenig@sifive.com>
Co-authored-by: Megan Wachs <megan@sifive.com>
Co-authored-by: Schuyler Eldridge <schuyler.eldridge@sifive.com>---
 .../experimental/hierarchy/Definition.scala        |  99 ++++++
 .../chisel3/experimental/hierarchy/Instance.scala  | 111 +++++++
 .../experimental/hierarchy/IsInstantiable.scala    |  17 +
 .../experimental/hierarchy/IsLookupable.scala      |  25 ++
 .../experimental/hierarchy/Lookupable.scala        | 368 +++++++++++++++++++++
 .../chisel3/experimental/hierarchy/package.scala   |  48 +++
 6 files changed, 668 insertions(+)
 create mode 100644 core/src/main/scala/chisel3/experimental/hierarchy/Definition.scala
 create mode 100644 core/src/main/scala/chisel3/experimental/hierarchy/Instance.scala
 create mode 100644 core/src/main/scala/chisel3/experimental/hierarchy/IsInstantiable.scala
 create mode 100644 core/src/main/scala/chisel3/experimental/hierarchy/IsLookupable.scala
 create mode 100644 core/src/main/scala/chisel3/experimental/hierarchy/Lookupable.scala
 create mode 100644 core/src/main/scala/chisel3/experimental/hierarchy/package.scala

(limited to 'core/src/main/scala/chisel3/experimental')

diff --git a/core/src/main/scala/chisel3/experimental/hierarchy/Definition.scala b/core/src/main/scala/chisel3/experimental/hierarchy/Definition.scala
new file mode 100644
index 00000000..2e917dfa
--- /dev/null
+++ b/core/src/main/scala/chisel3/experimental/hierarchy/Definition.scala
@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.experimental.hierarchy
+
+import scala.language.experimental.macros
+
+import chisel3._
+import scala.collection.mutable.HashMap
+import chisel3.internal.{Builder, DynamicContext}
+import chisel3.internal.sourceinfo.{DefinitionTransform, DefinitionWrapTransform, SourceInfo}
+import chisel3.experimental.BaseModule
+import chisel3.internal.BaseModule.IsClone
+
+/** User-facing Definition type.
+  * Represents a definition of an object of type [[A]] which are marked as @instantiable 
+  * Can be created using Definition.apply method.
+  * 
+  * These definitions are then used to create multiple [[Instance]]s.
+  *
+  * @param cloned The internal representation of the instance, which may be either be directly the object, or a clone of an object
+  */
+case class Definition[+A] private[chisel3] (private[chisel3] cloned: Either[A, IsClone[A]]) extends IsLookupable {
+  private[chisel3] def proto: A = cloned match {
+    case Left(value: A) => value
+    case Right(i: IsClone[A]) => i._proto
+  }
+  /** Used by Chisel's internal macros. DO NOT USE in your normal Chisel code!!!
+    * Instead, mark the field you are accessing with [[@public]]
+    *
+    * Given a selector function (that) which selects a member from the original, return the
+    *   corresponding member from the instance.
+    *
+    * Our @instantiable and @public macros generate the calls to this apply method
+    *
+    * By calling this function, we summon the proper Lookupable typeclass from our implicit scope.
+    *
+    * @param that a user-specified lookup function
+    * @param lookup typeclass which contains the correct lookup function, based on the types of A and B
+    * @param macroGenerated a value created in the macro, to make it harder for users to use this API
+    */
+  def _lookup[B, C](that: A => B)(implicit lookup: Lookupable[B], macroGenerated: chisel3.internal.MacroGenerated): lookup.C = {
+    lookup.definitionLookup(that, this)
+  }
+
+  /** Updated by calls to [[apply]], to avoid recloning returned Data's */
+  private [chisel3] val cache = HashMap[Data, Data]()
+
+
+  /** @return the context of any Data's return from inside the instance */
+  private[chisel3] def getInnerDataContext: Option[BaseModule] = proto match {
+    case value: BaseModule =>
+      val newChild = Module.do_apply(new internal.BaseModule.DefinitionClone(value))(chisel3.internal.sourceinfo.UnlocatableSourceInfo, chisel3.ExplicitCompileOptions.Strict)
+      newChild._circuit = value._circuit.orElse(Some(value))
+      newChild._parent = None
+      Some(newChild)
+    case value: IsInstantiable => None
+  }
+
+}
+
+/** Factory methods for constructing [[Definition]]s */
+object Definition extends SourceInfoDoc {
+  implicit class DefinitionBaseModuleExtensions[T <: BaseModule](d: Definition[T]) {
+    /** If this is an instance of a Module, returns the toTarget of this instance
+      * @return target of this instance
+      */
+    def toTarget = d.proto.toTarget
+
+    /** If this is an instance of a Module, returns the toAbsoluteTarget of this instance
+      * @return absoluteTarget of this instance
+      */
+    def toAbsoluteTarget = d.proto.toAbsoluteTarget
+  }
+  /** A construction method to build a Definition of a Module
+    *
+    * @param proto the Module being defined
+    *
+    * @return the input module as a Definition
+    */
+  def apply[T <: BaseModule with IsInstantiable](proto: => T): Definition[T] = macro DefinitionTransform.apply[T]
+
+  /** A construction method to build a Definition of a Module
+    *
+    * @param bc the Module being defined
+    *
+    * @return the input module as a Definition
+    */
+  def do_apply[T <: BaseModule with IsInstantiable](proto: => T) (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Definition[T] = {
+    val dynamicContext = new DynamicContext(Nil)
+    Builder.globalNamespace.copyTo(dynamicContext.globalNamespace)
+    dynamicContext.inDefinition = true
+    val (ir, module) = Builder.build(Module(proto), dynamicContext)
+    Builder.components ++= ir.components
+    Builder.annotations ++= ir.annotations
+    module._circuit = Builder.currentModule
+    dynamicContext.globalNamespace.copyTo(Builder.globalNamespace)
+    new Definition(Left(module))
+  }
+}
diff --git a/core/src/main/scala/chisel3/experimental/hierarchy/Instance.scala b/core/src/main/scala/chisel3/experimental/hierarchy/Instance.scala
new file mode 100644
index 00000000..aec42da3
--- /dev/null
+++ b/core/src/main/scala/chisel3/experimental/hierarchy/Instance.scala
@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.experimental.hierarchy
+
+import scala.collection.mutable.{ArrayBuffer, HashMap}
+import scala.language.experimental.macros
+
+import chisel3._
+import chisel3.internal.BaseModule.{ModuleClone, IsClone, InstantiableClone}
+import chisel3.internal.sourceinfo.{InstanceTransform, SourceInfo}
+import chisel3.experimental.BaseModule
+
+/** User-facing Instance type.
+  * Represents a unique instance of type [[A]] which are marked as @instantiable 
+  * Can be created using Instance.apply method.
+  *
+  * @param cloned The internal representation of the instance, which may be either be directly the object, or a clone of an object
+  */
+case class Instance[+A] private [chisel3] (private[chisel3] cloned: Either[A, IsClone[A]]) {
+
+  /** Returns the original object which is instantiated here.
+    * If this is an instance of a clone, return that clone's original proto
+    *
+    * @return the original object which was instantiated
+    */
+  private[chisel3] def proto: A = cloned match {
+    case Left(value: A) => value
+    case Right(i: IsClone[A]) => i._proto
+  }
+
+  /** @return the context of any Data's return from inside the instance */
+  private[chisel3] def getInnerDataContext: Option[BaseModule] = cloned match {
+    case Left(value: BaseModule)        => Some(value)
+    case Left(value: IsInstantiable)    => None
+    case Right(i: BaseModule)           => Some(i)
+    case Right(i: InstantiableClone[_]) => i._parent
+  }
+
+  /** @return the context this instance. Note that for non-module clones, getInnerDataContext will be the same as getClonedParent */
+  private[chisel3] def getClonedParent: Option[BaseModule] = cloned match {
+    case Left(value: BaseModule) => value._parent
+    case Right(i: BaseModule)           => i._parent
+    case Right(i: InstantiableClone[_]) => i._parent
+  }
+
+  /** Updated by calls to [[apply]], to avoid recloning returned Data's */
+  private [chisel3] val cache = HashMap[Data, Data]()
+
+  /** Used by Chisel's internal macros. DO NOT USE in your normal Chisel code!!!
+    * Instead, mark the field you are accessing with [[@public]]
+    *
+    * Given a selector function (that) which selects a member from the original, return the
+    *   corresponding member from the instance.
+    *
+    * Our @instantiable and @public macros generate the calls to this apply method
+    *
+    * By calling this function, we summon the proper Lookupable typeclass from our implicit scope.
+    *
+    * @param that a user-specified lookup function
+    * @param lookup typeclass which contains the correct lookup function, based on the types of A and B
+    * @param macroGenerated a value created in the macro, to make it harder for users to use this API
+    */
+  def _lookup[B, C](that: A => B)(implicit lookup: Lookupable[B], macroGenerated: chisel3.internal.MacroGenerated): lookup.C = {
+    lookup.instanceLookup(that, this)
+  }
+
+  /** Returns the definition of this Instance */
+  def toDefinition: Definition[A] = new Definition(Left(proto))
+
+}
+
+/** Factory methods for constructing [[Instance]]s */
+object Instance extends SourceInfoDoc {
+  implicit class InstanceBaseModuleExtensions[T <: BaseModule](i: Instance[T]) {
+    /** If this is an instance of a Module, returns the toTarget of this instance
+      * @return target of this instance
+      */
+    def toTarget = i.cloned match {
+      case Left(x: BaseModule) => x.toTarget
+      case Right(x: IsClone[_] with BaseModule) => x.toTarget
+    }
+
+    /** If this is an instance of a Module, returns the toAbsoluteTarget of this instance
+      * @return absoluteTarget of this instance
+      */
+    def toAbsoluteTarget = i.cloned match {
+      case Left(x) => x.toAbsoluteTarget
+      case Right(x: IsClone[_] with BaseModule) => x.toAbsoluteTarget
+    }
+
+  }
+  /** A constructs an [[Instance]] from a [[Definition]]
+    *
+    * @param definition the Module being created
+    * @return an instance of the module definition
+    */
+  def apply[T <: BaseModule with IsInstantiable](definition: Definition[T]): Instance[T] = macro InstanceTransform.apply[T]
+
+  /** A constructs an [[Instance]] from a [[Definition]]
+    *
+    * @param definition the Module being created
+    * @return an instance of the module definition
+    */
+  def do_apply[T <: BaseModule with IsInstantiable](definition: Definition[T])(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Instance[T] = {
+    val ports = experimental.CloneModuleAsRecord(definition.proto)
+    val clone = ports._parent.get.asInstanceOf[ModuleClone[T]]
+    clone._madeFromDefinition = true
+    new Instance(Right(clone))
+  }
+
+}
diff --git a/core/src/main/scala/chisel3/experimental/hierarchy/IsInstantiable.scala b/core/src/main/scala/chisel3/experimental/hierarchy/IsInstantiable.scala
new file mode 100644
index 00000000..26ba0286
--- /dev/null
+++ b/core/src/main/scala/chisel3/experimental/hierarchy/IsInstantiable.scala
@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.experimental.hierarchy
+
+/** While this is public, it is not recommended for users to extend directly.
+  * Instead, use the [[@instantiable]] annotation on your trait or class.
+  *
+  * This trait indicates whether a class can be returned from an Instance.
+  * 
+  */
+trait IsInstantiable
+
+object IsInstantiable {
+  implicit class IsInstantiableExtensions[T <: IsInstantiable](i: T) {
+    def toInstance: Instance[T] = new Instance(Left(i))
+  }
+}
diff --git a/core/src/main/scala/chisel3/experimental/hierarchy/IsLookupable.scala b/core/src/main/scala/chisel3/experimental/hierarchy/IsLookupable.scala
new file mode 100644
index 00000000..37d29a43
--- /dev/null
+++ b/core/src/main/scala/chisel3/experimental/hierarchy/IsLookupable.scala
@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.experimental.hierarchy
+
+/** A User-extendable trait to mark metadata-containers, e.g. parameter case classes, as valid to return unchanged
+  * from an instance.
+  * 
+  * This should only be true of the metadata returned is identical for ALL instances!
+  * 
+  * @example For instances of the same proto, metadata or other construction parameters
+  *   may be useful to access outside of the instance construction. For parameters that are
+  *   the same for all instances, we should mark it as IsLookupable
+  * {{{
+  * case class Params(debugMessage: String) extends IsLookupable
+  * class MyModule(p: Params) extends MultiIOModule {
+  *   printf(p.debugMessage)
+  * }
+  * val myParams = Params("Hello World")
+  * val definition = Definition(new MyModule(myParams))
+  * val i0 = Instance(definition)
+  * val i1 = Instance(definition)
+  * require(i0.p == i1.p) // p is only accessable because it extends IsLookupable
+  * }}}
+  */
+trait IsLookupable
diff --git a/core/src/main/scala/chisel3/experimental/hierarchy/Lookupable.scala b/core/src/main/scala/chisel3/experimental/hierarchy/Lookupable.scala
new file mode 100644
index 00000000..b9617723
--- /dev/null
+++ b/core/src/main/scala/chisel3/experimental/hierarchy/Lookupable.scala
@@ -0,0 +1,368 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.experimental.hierarchy
+
+import chisel3.experimental.BaseModule
+import chisel3.internal.sourceinfo.SourceInfo
+import chisel3.internal.BaseModule.{InstanceClone, InstantiableClone, IsClone, ModuleClone}
+
+import scala.annotation.implicitNotFound
+import scala.collection.mutable.HashMap
+import chisel3._
+import chisel3.experimental.dataview.{isView, reify, reifySingleData}
+import chisel3.internal.firrtl.{Arg, ILit, Index, Slot, ULit}
+import chisel3.internal.{AggregateViewBinding, Builder, ChildBinding, ViewBinding, ViewParent, throwException}
+
+/** Represents lookup typeclass to determine how a value accessed from an original IsInstantiable
+  *   should be tweaked to return the Instance's version
+  * Sealed.
+  */
+@implicitNotFound("@public is only legal within a class marked @instantiable and only on vals of type" +
+  " Data, BaseModule, IsInstantiable, IsLookupable, or Instance[_], or in an Iterable or Option")
+sealed trait Lookupable[-B] {
+  type C // Return type of the lookup
+  /** Function called to modify the returned value of type B from A, into C
+    * 
+    * @param that function that selects B from A
+    * @param instance Instance of A, used to determine C's context
+    * @return
+    */
+  def instanceLookup[A](that: A => B, instance: Instance[A]): C
+
+  /** Function called to modify the returned value of type B from A, into C
+    *
+    * @param that function that selects B from A
+    * @param definition Definition of A, used to determine C's context
+    * @return
+    */
+  def definitionLookup[A](that: A => B, definition: Definition[A]): C
+}
+
+private[chisel3] object Lookupable {
+
+  /** Clones a data and sets its internal references to its parent module to be in a new context.
+    *
+    * @param data data to be cloned
+    * @param context new context
+    * @return
+    */
+  private[chisel3] def cloneDataToContext[T <: Data](data: T, context: BaseModule)
+                                           (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = {
+    internal.requireIsHardware(data, "cross module reference type")
+    data._parent match {
+      case None => data
+      case Some(parent) =>
+        val newParent = cloneModuleToContext(Left(parent), context)
+        newParent match {
+          case Left(p) if p == parent => data
+          case Right(m: BaseModule) =>
+            val newChild = data.cloneTypeFull
+            newChild.setRef(data.getRef, true)
+            newChild.bind(internal.CrossModuleBinding)
+            newChild.setAllParents(Some(m))
+            newChild
+        }
+    }
+  }
+  // The business logic of lookupData
+  // Also called by cloneViewToContext which potentially needs to lookup stuff from ioMap or the cache
+  private[chisel3] def doLookupData[A, B <: Data](data: B, cache: HashMap[Data, Data], ioMap: Option[Map[Data, Data]], context: Option[BaseModule])
+                                        (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): B = {
+    def impl[C <: Data](d: C): C = d match {
+      case x: Data if ioMap.nonEmpty && ioMap.get.contains(x) => ioMap.get(x).asInstanceOf[C]
+      case x: Data if cache.contains(x) => cache(x).asInstanceOf[C]
+      case _ =>
+        assert(context.nonEmpty) // TODO is this even possible? Better error message here
+        val ret = cloneDataToContext(d, context.get)
+        cache(d) = ret
+        ret
+    }
+    data.binding match {
+      case Some(_: ChildBinding) => mapRootAndExtractSubField(data, impl)
+      case _ => impl(data)
+    }
+  }
+
+  // Helper for co-iterating on Elements of aggregates, they must be the same type but that is unchecked
+  private def coiterate(a: Data, b: Data): Iterable[(Element, Element)] = {
+    val as = getRecursiveFields.lazily(a, "_")
+    val bs = getRecursiveFields.lazily(b, "_")
+    as.zip(bs).collect { case ((ae: Element, _), (be: Element, _)) => (ae, be) }
+  }
+
+  /** Given a Data, find the root of its binding, apply a function to the root to get a "new root",
+    * and find the equivalent child Data in the "new root"
+    *
+    * @example {{{
+    * Given `arg = a.b[2].c` and some `f`:
+    * 1. a = root(arg) = root(a.b[2].c)
+    * 2. newRoot = f(root(arg)) = f(a)
+    * 3. return newRoot.b[2].c
+    * }}}
+    *
+    * Invariants that elt is a Child of something of the type of data is dynamically checked as we traverse
+    */
+  private def mapRootAndExtractSubField[A <: Data](arg: A, f: Data => Data): A = {
+    def err(msg: String) = throwException(s"Internal Error! $msg")
+    def unrollCoordinates(res: List[Arg], d: Data): (List[Arg], Data) = d.binding.get match {
+      case ChildBinding(parent) => d.getRef match {
+        case arg @ (_: Slot | _: Index) => unrollCoordinates(arg :: res, parent)
+        case other => err(s"Unroll coordinates failed for '$arg'! Unexpected arg '$other'")
+      }
+      case _ => (res, d)
+    }
+    def applyCoordinates(fullCoor: List[Arg], start: Data): Data = {
+      def rec(coor: List[Arg], d: Data): Data = {
+        if (coor.isEmpty) d
+        else {
+          val next = (coor.head, d) match {
+            case (Slot(_, name), rec: Record) => rec.elements(name)
+            case (Index(_, ILit(n)), vec: Vec[_]) => vec.apply(n.toInt)
+            case (arg, _) => err(s"Unexpected Arg '$arg' applied to '$d'! Root was '$start'.")
+          }
+          applyCoordinates(coor.tail, next)
+        }
+      }
+      rec(fullCoor, start)
+    }
+    val (coor, root) = unrollCoordinates(Nil, arg)
+    val newRoot = f(root)
+    val result = applyCoordinates(coor, newRoot)
+    try {
+      result.asInstanceOf[A]
+    } catch {
+        case _: ClassCastException => err(s"Applying '$coor' to '$newRoot' somehow resulted in '$result'")
+    }
+  }
+
+  // TODO this logic is complicated, can any of it be unified with viewAs?
+  // If `.viewAs` would capture its arguments, we could potentially use it
+  // TODO Describe what this is doing at a high level
+  private[chisel3] def cloneViewToContext[A, B <: Data](data: B, cache: HashMap[Data, Data], ioMap: Option[Map[Data, Data]], context: Option[BaseModule])
+                                           (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): B = {
+    // alias to shorten lookups
+    def lookupData[C <: Data](d: C) = doLookupData(d, cache, ioMap, context)
+
+    val result = data.cloneTypeFull
+
+    // We have to lookup the target(s) of the view since they may need to be cloned into the current context
+    val newBinding = data.topBinding match {
+      case ViewBinding(target) => ViewBinding(lookupData(reify(target)))
+      case avb @ AggregateViewBinding(map, targetOpt) => data match {
+        case _: Element => ViewBinding(lookupData(reify(map(data))))
+        case _: Aggregate =>
+          // Provide a 1:1 mapping if possible
+          val singleTargetOpt = targetOpt.filter(_ => avb == data.binding.get).flatMap(reifySingleData)
+          singleTargetOpt match {
+            case Some(singleTarget) => // It is 1:1!
+              // This is a little tricky because the values in newMap need to point to Elements of newTarget
+              val newTarget = lookupData(singleTarget)
+              val newMap = coiterate(result, data).map { case (res, from) =>
+                (res: Data) -> mapRootAndExtractSubField(map(from), _ => newTarget)
+              }.toMap
+              AggregateViewBinding(newMap, Some(newTarget))
+
+            case None => // No 1:1 mapping so we have to do a flat binding
+              // Just remap each Element of this aggregate
+              val newMap = coiterate(result, data).map {
+                // Upcast res to Data since Maps are invariant in the Key type parameter
+                case (res, from) => (res: Data) -> lookupData(reify(map(from)))
+              }.toMap
+              AggregateViewBinding(newMap, None)
+          }
+      }
+    }
+
+    // TODO Unify the following with `.viewAs`
+    // We must also mark non-1:1 and child Aggregates in the view for renaming
+    newBinding match {
+      case _: ViewBinding => // Do nothing
+      case AggregateViewBinding(_, target) =>
+        if (target.isEmpty) {
+          Builder.unnamedViews += result
+        }
+        // Binding does not capture 1:1 for child aggregates views
+        getRecursiveFields.lazily(result, "_").foreach {
+          case (agg: Aggregate, _) if agg != result =>
+            Builder.unnamedViews += agg
+          case _ => // Do nothing
+          }
+    }
+
+    result.bind(newBinding)
+    result.setAllParents(Some(ViewParent))
+    result.forceName(None, "view", Builder.viewNamespace)
+    result
+  }
+  /** Given a module (either original or a clone), clone it to a new context
+    *
+    * This function effectively recurses up the parents of module to find whether:
+    *   (1) A parent is already in the context; then we do nothing and return module
+    *   (2) A parent is in a different clone of the context; then we clone all the parents up
+    *         to that parent and set their parents to be in this cloned context
+    *   (3) A parent has no root; in that case, we do nothing and return the module.
+    *
+    * @param module original or clone to be cloned into a new context
+    * @param context new context
+    * @return original or clone in the new context
+    */
+  private[chisel3] def cloneModuleToContext[T <: BaseModule](module: Either[T, IsClone[T]], context: BaseModule)
+      (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Either[T, IsClone[T]] = {
+    // Recursive call
+    def rec[A <: BaseModule](m: A): Either[A, IsClone[A]] = {
+      def clone(x: A, p: Option[BaseModule], name: () => String): Either[A, IsClone[A]] = {
+        val newChild = Module.do_apply(new internal.BaseModule.InstanceClone(x, name))
+        newChild._parent = p
+        Right(newChild)
+      }
+      (m, context) match {
+        case (c, ctx) if ctx == c => Left(c)
+        case (c, ctx: IsClone[_]) if ctx.isACloneOf(c) => Right(ctx.asInstanceOf[IsClone[A]])
+        case (c, ctx) if c._parent.isEmpty => Left(c)
+        case (_, _) => 
+          cloneModuleToContext(Left(m._parent.get), context) match {
+            case Left(p) => Left(m)
+            case Right(p: BaseModule) =>
+              clone(m, Some(p), () => m.instanceName)
+          }
+      }
+    }
+    module match {
+      case Left(m) => rec(m)
+      case Right(m: ModuleClone[_]) =>
+        rec(m) match {
+          case Left(mx) => Right(mx)
+          case Right(i: InstanceClone[_]) =>
+            val newChild = Module.do_apply(new InstanceClone(m._proto, () => m.instanceName))
+            newChild._parent = i._parent
+            Right(newChild)
+        }
+      case Right(m: InstanceClone[_]) =>
+        rec(m) match {
+          case Left(mx) => Right(mx)
+          case Right(i: InstanceClone[_]) =>
+            val newChild = Module.do_apply(new InstanceClone(m._proto, () => m.instanceName))
+            newChild._parent = i._parent
+            Right(newChild)
+        }
+    }
+  }
+
+  class SimpleLookupable[X] extends Lookupable[X] {
+    type B = X
+    type C = X
+    def definitionLookup[A](that: A => B, definition: Definition[A]): C = that(definition.proto)
+    def instanceLookup[A](that: A => B, instance: Instance[A]): C = that(instance.proto)
+  }
+
+  implicit def lookupInstance[B <: BaseModule](implicit sourceInfo: SourceInfo, compileOptions: CompileOptions) = new Lookupable[Instance[B]] {
+    type C = Instance[B]
+    def definitionLookup[A](that: A => Instance[B], definition: Definition[A]): C = {
+      val ret = that(definition.proto)
+      new Instance(cloneModuleToContext(ret.cloned, definition.getInnerDataContext.get))
+    }
+    def instanceLookup[A](that: A => Instance[B], instance: Instance[A]): C = {
+      val ret = that(instance.proto)
+      instance.cloned match {
+        // If instance is just a normal module, no changing of context is necessary
+        case Left(_)  => new Instance(ret.cloned)
+        case Right(_) => new Instance(cloneModuleToContext(ret.cloned, instance.getInnerDataContext.get))
+      }
+    }
+  }
+
+  implicit def lookupModule[B <: BaseModule](implicit sourceInfo: SourceInfo, compileOptions: CompileOptions) = new Lookupable[B] {
+    type C = Instance[B]
+    def definitionLookup[A](that: A => B, definition: Definition[A]): C = {
+      val ret = that(definition.proto)
+      new Instance(cloneModuleToContext(Left(ret), definition.getInnerDataContext.get))
+    }
+    def instanceLookup[A](that: A => B, instance: Instance[A]): C = {
+      val ret = that(instance.proto)
+      instance.cloned match {
+        // If instance is just a normal module, no changing of context is necessary
+        case Left(_)  => new Instance(Left(ret))
+        case Right(_) => new Instance(cloneModuleToContext(Left(ret), instance.getInnerDataContext.get))
+      }
+    }
+  }
+
+  implicit def lookupData[B <: Data](implicit sourceInfo: SourceInfo, compileOptions: CompileOptions) = new Lookupable[B] {
+    type C = B
+    def definitionLookup[A](that: A => B, definition: Definition[A]): C = {
+      val ret = that(definition.proto)
+      if (isView(ret)) {
+        ???  // TODO!!!!!!  cloneViewToContext(ret, instance, ioMap, instance.getInnerDataContext)
+      } else {
+        doLookupData(ret, definition.cache, None, definition.getInnerDataContext)
+      }
+    }
+    def instanceLookup[A](that: A => B, instance: Instance[A]): C = {
+      val ret = that(instance.proto)
+      val ioMap: Option[Map[Data, Data]] = instance.cloned match {
+        case Right(x: ModuleClone[_]) => Some(x.ioMap)
+        case Left(x: BaseModule) => Some(x.getChiselPorts.map { case (_, data) => data -> data }.toMap)
+        case _ => None
+      }
+      if (isView(ret)) {
+        cloneViewToContext(ret, instance.cache, ioMap, instance.getInnerDataContext)
+      } else {
+        doLookupData(ret, instance.cache, ioMap, instance.getInnerDataContext)
+      }
+
+    }
+  }
+
+  import scala.language.higherKinds // Required to avoid warning for lookupIterable type parameter
+  implicit def lookupIterable[B, F[_] <: Iterable[_]](implicit sourceInfo: SourceInfo, compileOptions: CompileOptions, lookupable: Lookupable[B]) = new Lookupable[F[B]] {
+    type C = F[lookupable.C]
+    def definitionLookup[A](that: A => F[B], definition: Definition[A]): C = {
+      val ret = that(definition.proto).asInstanceOf[Iterable[B]]
+      ret.map{ x: B => lookupable.definitionLookup[A](_ => x, definition) }.asInstanceOf[C]
+    }
+    def instanceLookup[A](that: A => F[B], instance: Instance[A]): C = {
+      import instance._
+      val ret = that(proto).asInstanceOf[Iterable[B]]
+      ret.map{ x: B => lookupable.instanceLookup[A](_ => x, instance) }.asInstanceOf[C]
+    }
+  }
+  implicit def lookupOption[B](implicit sourceInfo: SourceInfo, compileOptions: CompileOptions, lookupable: Lookupable[B]) = new Lookupable[Option[B]] {
+    type C = Option[lookupable.C]
+    def definitionLookup[A](that: A => Option[B], definition: Definition[A]): C = {
+      val ret = that(definition.proto)
+      ret.map{ x: B => lookupable.definitionLookup[A](_ => x, definition) }
+    }
+    def instanceLookup[A](that: A => Option[B], instance: Instance[A]): C = {
+      import instance._
+      val ret = that(proto)
+      ret.map{ x: B => lookupable.instanceLookup[A](_ => x, instance) }
+    }
+  }
+  implicit def lookupIsInstantiable[B <: IsInstantiable](implicit sourceInfo: SourceInfo, compileOptions: CompileOptions) = new Lookupable[B] {
+    type C = Instance[B]
+    def definitionLookup[A](that: A => B, definition: Definition[A]): C = {
+      val ret = that(definition.proto)
+      val cloned = new InstantiableClone(ret)
+      cloned._parent = definition.getInnerDataContext
+      new Instance(Right(cloned))
+    }
+    def instanceLookup[A](that: A => B, instance: Instance[A]): C = {
+      val ret = that(instance.proto)
+      val cloned = new InstantiableClone(ret)
+      cloned._parent = instance.getInnerDataContext
+      new Instance(Right(cloned))
+    }
+  }
+
+  implicit def lookupIsLookupable[B <: IsLookupable](implicit sourceInfo: SourceInfo, compileOptions: CompileOptions) = new SimpleLookupable[B]()
+  
+  implicit val lookupInt = new SimpleLookupable[Int]()
+  implicit val lookupByte = new SimpleLookupable[Byte]()
+  implicit val lookupShort = new SimpleLookupable[Short]()
+  implicit val lookupLong = new SimpleLookupable[Long]()
+  implicit val lookupFloat = new SimpleLookupable[Float]()
+  implicit val lookupChar = new SimpleLookupable[Char]()
+  implicit val lookupString = new SimpleLookupable[String]()
+  implicit val lookupBoolean = new SimpleLookupable[Boolean]()
+  implicit val lookupBigInt = new SimpleLookupable[BigInt]()
+}
diff --git a/core/src/main/scala/chisel3/experimental/hierarchy/package.scala b/core/src/main/scala/chisel3/experimental/hierarchy/package.scala
new file mode 100644
index 00000000..c309ab52
--- /dev/null
+++ b/core/src/main/scala/chisel3/experimental/hierarchy/package.scala
@@ -0,0 +1,48 @@
+package chisel3.experimental
+
+package object hierarchy {
+
+  /** Classes or traits which will be used with the [[Definition]] + [[Instance]] api should be marked
+    * with the [[@instantiable]] annotation at the class/trait definition.
+    *
+    * @example {{{
+    * @instantiable
+    * class MyModule extends Module {
+    *   ...
+    * }
+    *
+    * val d = Definition(new MyModule)
+    * val i0 = Instance(d)
+    * val i1 = Instance(d)
+    * }}}
+    */
+  class instantiable extends chisel3.internal.instantiable
+
+  /** Classes marked with [[@instantiable]] can have their vals marked with the [[@public]] annotation to
+    * enable accessing these values from a [[Definition]] or [[Instance]] of the class.
+    *
+    * Only vals of the the following types can be marked [[@public]]:
+    *   1. IsInstantiable
+    *   2. IsLookupable
+    *   3. Data
+    *   4. BaseModule
+    *   5. Iterable/Option containing a type that meets these requirements
+    *   6. Basic type like String, Int, BigInt etc.
+    *
+    * @example {{{
+    * @instantiable
+    * class MyModule extends Module {
+    *   @public val in = IO(Input(UInt(3.W)))
+    *   @public val out = IO(Output(UInt(3.W)))
+    *   ..
+    * }
+    *
+    * val d = Definition(new MyModule)
+    * val i0 = Instance(d)
+    * val i1 = Instance(d)
+    *
+    * i1.in := i0.out
+    * }}}
+    */
+  class public extends chisel3.internal.public
+}
-- 
cgit v1.2.3


From 2b51053fe7744d6860416c7de8bcb99d4aa9e532 Mon Sep 17 00:00:00 2001
From: Jack Koenig
Date: Wed, 8 Sep 2021 14:31:10 -0700
Subject: Restore return type of BaseModule.toTarget to ModuleTarget (#2117)

Definition/Instance introduced the need for representing the targets of
instances as InstanceTargets. This original implementation changed the
return type of BaseModule.toTarget to express this need. This is a
backwards incompatible change that is actually unnecessary because it is
impossible for users to get references to the internal InstanceClone
objects, instead only accessing such modules via Instance[_] wrappers
and cloned Data. We restored the old API by adding a new internal method
"getTarget" which will give the correct targets for InstanceClones while
maintaining the API of BaseModule.toTarget.---
 .../scala/chisel3/experimental/hierarchy/Definition.scala    |  7 ++++---
 .../main/scala/chisel3/experimental/hierarchy/Instance.scala | 12 ++++++------
 2 files changed, 10 insertions(+), 9 deletions(-)

(limited to 'core/src/main/scala/chisel3/experimental')

diff --git a/core/src/main/scala/chisel3/experimental/hierarchy/Definition.scala b/core/src/main/scala/chisel3/experimental/hierarchy/Definition.scala
index 2e917dfa..0cc3d131 100644
--- a/core/src/main/scala/chisel3/experimental/hierarchy/Definition.scala
+++ b/core/src/main/scala/chisel3/experimental/hierarchy/Definition.scala
@@ -3,13 +3,14 @@
 package chisel3.experimental.hierarchy
 
 import scala.language.experimental.macros
-
 import chisel3._
+
 import scala.collection.mutable.HashMap
 import chisel3.internal.{Builder, DynamicContext}
 import chisel3.internal.sourceinfo.{DefinitionTransform, DefinitionWrapTransform, SourceInfo}
 import chisel3.experimental.BaseModule
 import chisel3.internal.BaseModule.IsClone
+import firrtl.annotations.{IsModule, ModuleTarget}
 
 /** User-facing Definition type.
   * Represents a definition of an object of type [[A]] which are marked as @instantiable 
@@ -64,12 +65,12 @@ object Definition extends SourceInfoDoc {
     /** If this is an instance of a Module, returns the toTarget of this instance
       * @return target of this instance
       */
-    def toTarget = d.proto.toTarget
+    def toTarget: ModuleTarget = d.proto.toTarget
 
     /** If this is an instance of a Module, returns the toAbsoluteTarget of this instance
       * @return absoluteTarget of this instance
       */
-    def toAbsoluteTarget = d.proto.toAbsoluteTarget
+    def toAbsoluteTarget: IsModule = d.proto.toAbsoluteTarget
   }
   /** A construction method to build a Definition of a Module
     *
diff --git a/core/src/main/scala/chisel3/experimental/hierarchy/Instance.scala b/core/src/main/scala/chisel3/experimental/hierarchy/Instance.scala
index aec42da3..9b17bfce 100644
--- a/core/src/main/scala/chisel3/experimental/hierarchy/Instance.scala
+++ b/core/src/main/scala/chisel3/experimental/hierarchy/Instance.scala
@@ -4,11 +4,11 @@ package chisel3.experimental.hierarchy
 
 import scala.collection.mutable.{ArrayBuffer, HashMap}
 import scala.language.experimental.macros
-
 import chisel3._
-import chisel3.internal.BaseModule.{ModuleClone, IsClone, InstantiableClone}
+import chisel3.internal.BaseModule.{InstantiableClone, IsClone, ModuleClone}
 import chisel3.internal.sourceinfo.{InstanceTransform, SourceInfo}
 import chisel3.experimental.BaseModule
+import firrtl.annotations.IsModule
 
 /** User-facing Instance type.
   * Represents a unique instance of type [[A]] which are marked as @instantiable 
@@ -75,15 +75,15 @@ object Instance extends SourceInfoDoc {
     /** If this is an instance of a Module, returns the toTarget of this instance
       * @return target of this instance
       */
-    def toTarget = i.cloned match {
-      case Left(x: BaseModule) => x.toTarget
-      case Right(x: IsClone[_] with BaseModule) => x.toTarget
+    def toTarget: IsModule = i.cloned match {
+      case Left(x: BaseModule) => x.getTarget
+      case Right(x: IsClone[_] with BaseModule) => x.getTarget
     }
 
     /** If this is an instance of a Module, returns the toAbsoluteTarget of this instance
       * @return absoluteTarget of this instance
       */
-    def toAbsoluteTarget = i.cloned match {
+    def toAbsoluteTarget: IsModule = i.cloned match {
       case Left(x) => x.toAbsoluteTarget
       case Right(x: IsClone[_] with BaseModule) => x.toAbsoluteTarget
     }
-- 
cgit v1.2.3