Change findInstancesInHierarchy to return implicit top instance

* Change FIRRTL-internal API, affecting only one corner case
* Make API more "DWIM" and consistent with other methods
* Add test cases for findInstancesInHierarchy
* Update Scaladoc

2 files changed, 48 insertions, 20 deletions

diff --git a/src/main/scala/firrtl/analyses/InstanceGraph.scala b/src/main/scala/firrtl/analyses/InstanceGraph.scala
index 59eae09b..1a453a42 100644
--- a/src/main/scala/firrtl/analyses/InstanceGraph.scala
+++ b/src/main/scala/firrtl/analyses/InstanceGraph.scala
@@ -62,13 +62,12 @@ class InstanceGraph(c: Circuit) {
     */
   lazy val fullHierarchy: mutable.LinkedHashMap[WDefInstance,Seq[Seq[WDefInstance]]] = graph.pathsInDAG(trueTopInstance)
 
-  /** A count of the *static* number of instances of each module. For
-    * any module other than the top module, this is equivalent to the
-    * number of inst statements in the circuit instantiating each
-    * module, irrespective of the number of times (if any) the
-    * enclosing module appears in the hierarchy. Note that top module
-    * of the circuit has an associated count of 1, even though it is
-    * never directly instantiated.
+  /** A count of the *static* number of instances of each module. For any module
+    * other than the top (main) module, this is equivalent to the number of inst
+    * statements in the circuit instantiating each module, irrespective of the
+    * number of times (if any) the enclosing module appears in the hierarchy.
+    * Note that top module of the circuit has an associated count of 1, even
+    * though it is never directly instantiated.
     */
   lazy val staticInstanceCount: Map[OfModule, Int] = {
     val instModules = childInstances.flatMap(_._2.view.map(_.OfModule).toSeq)
@@ -76,19 +75,17 @@ class InstanceGraph(c: Circuit) {
   }
 
   /** Finds the absolute paths (each represented by a Seq of instances
-    * representing the chain of hierarchy) of all instances of a
-    * particular module.
+    * representing the chain of hierarchy) of all instances of a particular
+    * module. Note that this includes one implicit instance of the top (main)
+    * module of the circuit. If the module is not instantiated within the
+    * hierarchy of the top module of the circuit, it will return Nil.
     *
     * @param module the name of the selected module
     * @return a Seq[ Seq[WDefInstance] ] of absolute instance paths
     */
   def findInstancesInHierarchy(module: String): Seq[Seq[WDefInstance]] = {
-    if (instantiated(module)) {
-      val instances = graph.getVertices.filter(_.module == module).toSeq
-      instances flatMap { i => fullHierarchy(i) }
-    } else {
-      Nil
-    }
+    val instances = graph.getVertices.filter(_.module == module).toSeq
+    instances flatMap { i => fullHierarchy.getOrElse(i, Nil) }
   }
 
   /** An [[firrtl.graph.EulerTour EulerTour]] representation of the [[firrtl.graph.DiGraph DiGraph]] */
diff --git a/src/test/scala/firrtlTests/analyses/InstanceGraphTests.scala b/src/test/scala/firrtlTests/analyses/InstanceGraphTests.scala
index e98c1895..eb62c564 100644
--- a/src/test/scala/firrtlTests/analyses/InstanceGraphTests.scala
+++ b/src/test/scala/firrtlTests/analyses/InstanceGraphTests.scala
@@ -1,12 +1,8 @@
 package firrtlTests.analyses
 
-import java.io._
-import org.scalatest._
-import org.scalatest.prop._
-import org.scalatest.Matchers._
 import firrtl.analyses.InstanceGraph
 import firrtl.graph.DiGraph
-import firrtl.Parser.parse
+import firrtl.WDefInstance
 import firrtl.passes._
 import firrtlTests._
 
@@ -39,6 +35,41 @@ circuit Top :
     getEdgeSet(graph) shouldBe Map("Top" -> Set("Child1", "Child2"), "Child1" -> Set("Child1a", "Child1b"), "Child2" -> Set(), "Child1a" -> Set(), "Child1b" -> Set())
   }
 
+  it should "find hierarchical instances correctly in disconnected hierarchies" in {
+    val input = """
+circuit Top :
+  module Top :
+    inst c of Child1
+  module Child1 :
+    skip
+
+  module Top2 :
+    inst a of Child2
+    inst b of Child3
+    skip
+  module Child2 :
+    inst a of Child2a
+    inst b of Child2b
+    skip
+  module Child2a :
+    skip
+  module Child2b :
+    skip
+  module Child3 :
+    skip
+"""
+
+    val circuit = ToWorkingIR.run(parse(input))
+    val iGraph = new InstanceGraph(circuit)
+    iGraph.findInstancesInHierarchy("Top") shouldBe Seq(Seq(WDefInstance("Top", "Top")))
+    iGraph.findInstancesInHierarchy("Child1") shouldBe Seq(Seq(WDefInstance("Top", "Top"), WDefInstance("c", "Child1")))
+    iGraph.findInstancesInHierarchy("Top2") shouldBe Nil
+    iGraph.findInstancesInHierarchy("Child2") shouldBe Nil
+    iGraph.findInstancesInHierarchy("Child2a") shouldBe Nil
+    iGraph.findInstancesInHierarchy("Child2b") shouldBe Nil
+    iGraph.findInstancesInHierarchy("Child3") shouldBe Nil
+  }
+
   it should "recognize disconnected hierarchies" in {
     val input = """
 circuit Top :