Add Target utility referringModule

This adds a utility method, referringModule, to the Target object that
behaves like IsMember.pathlessTarget except that it returns the module
of an InstanceTarget. This is useful for situations where you want to
get at "the module" a target is pointing at, but you want behavior
to get an actual module from an instance.

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

1 files changed, 13 insertions, 0 deletions

diff --git a/src/main/scala/firrtl/annotations/Target.scala b/src/main/scala/firrtl/annotations/Target.scala
index 1571f98e..c7cb98d2 100644
--- a/src/main/scala/firrtl/annotations/Target.scala
+++ b/src/main/scala/firrtl/annotations/Target.scala
@@ -185,6 +185,19 @@ object Target {
       }
     }.tryToComplete
   }
+
+  /** Returns the module that a [[Target]] "refers" to.
+    *
+    * For a [[ModuleTarget]] or a [[ReferenceTarget]], this is simply the deepest module. For an [[InstanceTarget]] this
+    * is *the module of the instance*.
+    *
+    * @note This differs from [[InstanceTarget.pathlessTarget]] which refers to the module instantiating the instance.
+    */
+  def referringModule(a: IsMember): ModuleTarget = a match {
+    case b: ModuleTarget    => b
+    case b: InstanceTarget  => b.ofModuleTarget
+    case b: ReferenceTarget => b.pathlessTarget.moduleTarget
+  }
 }
 
 /** Represents incomplete or non-standard [[Target]]s