Add DataMirror.getParent for getting parents of Modules (#2825) (#2833)

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
(cherry picked from commit fce8394bb0ddc9ae0d9c6668e034e483bd6b71c5)

Co-authored-by: Jack Koenig <koenig@sifive.com>

2 files changed, 41 insertions, 0 deletions

diff --git a/core/src/main/scala/chisel3/Data.scala b/core/src/main/scala/chisel3/Data.scala
index 52cc041c..3af5ade1 100644
--- a/core/src/main/scala/chisel3/Data.scala
+++ b/core/src/main/scala/chisel3/Data.scala
@@ -265,6 +265,14 @@ package experimental {
       }
     }
 
+    /** Returns the parent module within which a module instance is instantiated
+      *
+      * @note Top-level modules in any given elaboration do not have a parent
+      * @param target a module instance
+      * @return the parent of the `target`, if one exists
+      */
+    def getParent(target: BaseModule): Option[BaseModule] = target._parent
+
     // Internal reflection-style APIs, subject to change and removal whenever.
     object internal {
       def isSynthesizable(target: Data): Boolean = target.isSynthesizable
diff --git a/src/test/scala/chiselTests/experimental/DataMirrorSpec.scala b/src/test/scala/chiselTests/experimental/DataMirrorSpec.scala
index 731596ec..09fdf3c4 100644
--- a/src/test/scala/chiselTests/experimental/DataMirrorSpec.scala
+++ b/src/test/scala/chiselTests/experimental/DataMirrorSpec.scala
@@ -8,7 +8,26 @@ import chisel3.stage.ChiselStage
 import chisel3.experimental.DataMirror
 import chiselTests.ChiselFlatSpec
 
+object DataMirrorSpec {
+  import org.scalatest.matchers.should.Matchers._
+  class GrandChild(parent: RawModule) extends Module {
+    DataMirror.getParent(this) should be(Some(parent))
+  }
+  class Child(parent: RawModule) extends Module {
+    val inst = Module(new GrandChild(this))
+    DataMirror.getParent(inst) should be(Some(this))
+    DataMirror.getParent(this) should be(Some(parent))
+  }
+  class Parent extends Module {
+    val inst = Module(new Child(this))
+    DataMirror.getParent(inst) should be(Some(this))
+    DataMirror.getParent(this) should be(None)
+  }
+}
+
 class DataMirrorSpec extends ChiselFlatSpec {
+  import DataMirrorSpec._
+
   behavior.of("DataMirror")
 
   def assertBinding(x: Data, io: Boolean, wire: Boolean, reg: Boolean) = {
@@ -55,4 +74,18 @@ class DataMirrorSpec extends ChiselFlatSpec {
     }
     ChiselStage.elaborate(new MyModule)
   }
+
+  it should "support getParent for normal modules" in {
+    ChiselStage.elaborate(new Parent)
+  }
+
+  it should "support getParent for normal modules even when used in a D/I context" in {
+    import chisel3.experimental.hierarchy._
+    class Top extends Module {
+      val defn = Definition(new Parent)
+      val inst = Instance(defn)
+      DataMirror.getParent(this) should be(None)
+    }
+    ChiselStage.elaborate(new Top)
+  }
 }