Merge branch 'master' into update/sbt-mdoc-2.2.24

4 files changed, 63 insertions, 4 deletions

diff --git a/docs/src/cookbooks/cookbook.md b/docs/src/cookbooks/cookbook.md
index ce49b668..4b2b088e 100644
--- a/docs/src/cookbooks/cookbook.md
+++ b/docs/src/cookbooks/cookbook.md
@@ -88,13 +88,14 @@ you are tying off, you can use `chiselTypeOf`:
 
 ```scala mdoc:silent:reset
 import chisel3._
+import chisel3.stage.ChiselStage
 
 class MyBundle extends Bundle {
   val foo = UInt(4.W)
   val bar = Vec(4, UInt(1.W))
 }
 
-class Foo(typ: Data) extends RawModule {
+class Foo(typ: MyBundle) extends RawModule {
   val bundleA = IO(Output(typ))
   val bundleB = IO(Output(typ))
   
@@ -107,9 +108,7 @@ class Foo(typ: Data) extends RawModule {
   bundleB := 0.U.asTypeOf(chiselTypeOf(bundleB)) 
 }
 
-class Bar extends RawModule {
-  val foo = Module(new Foo(new MyBundle()))
-}
+ChiselStage.emitVerilog(new Foo(new MyBundle))
 ```
 ### How do I create a Vec of Bools from a UInt?
 
diff --git a/docs/src/cookbooks/hierarchy.md b/docs/src/cookbooks/hierarchy.md
index 91d99aa6..350d20eb 100644
--- a/docs/src/cookbooks/hierarchy.md
+++ b/docs/src/cookbooks/hierarchy.md
@@ -10,6 +10,8 @@ section: "chisel3"
 * [How do I access internal fields of an instance?](#how-do-i-access-internal-fields-of-an-instance)
 * [How do I make my parameters accessable from an instance?](#how-do-i-make-my-parameters-accessable-from-an-instance)
 * [How do I reuse a previously elaborated module, if my new module has the same parameterization?](#how-do-i-reuse-a-previously-elaborated-module-if-my-new-module-has-the-same-parameterization)
+* [How do I parameterize a module by its children instances?](#how-do-I-parameterize-a-module-by-its-children-instances)
+* [How do I use the new hierarchy-specific Select functions?](#how-do-I-use-the-new-hierarchy-specific-Select-functions)
 
 ## How do I instantiate multiple instances with the same module parameterization?
 
@@ -202,3 +204,58 @@ class AddTwo(addOneDef: Definition[AddOne]) extends Module {
 ```scala mdoc:verilog
 chisel3.stage.ChiselStage.emitVerilog(new AddTwo(Definition(new AddOne(10))))
 ```
+
+## How do I use the new hierarchy-specific Select functions?
+
+Select functions can be applied after a module has been elaborated, either in a Chisel Aspect or in a parent module applied to a child module.
+
+There are six hierarchy-specific functions, which either return `Instance`'s or `Definition`'s:
+ - `instancesIn(parent)`: Return all instances directly instantiated locally within `parent`
+ - `instancesOf[type](parent)`: Return all instances of provided `type` directly instantiated locally within `parent`
+ - `allInstancesOf[type](root)`: Return all instances of provided `type` directly and indirectly instantiated, locally and deeply, starting from `root`
+ - `definitionsIn`: Return definitions of all instances directly instantiated locally within `parent`
+ - `definitionsOf[type]`: Return definitions of all instances of provided `type` directly instantiated locally within `parent`
+ - `allDefinitionsOf[type]`: Return all definitions of instances of provided `type` directly and indirectly instantiated, locally and deeply, starting from `root`
+
+To demonstrate this, consider the following. We mock up an example where we are using the `Select.allInstancesOf` and `Select.allDefinitionsOf` to annotate instances and the definition of `EmptyModule`. When converting the `ChiselAnnotation` to firrtl's `Annotation`, we print out the resulting `Target`. As shown, despite `EmptyModule` actually only being elaborated once, we still provide different targets depending on how the instance or definition is selected.
+
+```scala mdoc:reset
+import chisel3._
+import chisel3.experimental.hierarchy.{Definition, Instance, Hierarchy, instantiable, public}
+import firrtl.annotations.{IsModule, NoTargetAnnotation}
+case object EmptyAnnotation extends NoTargetAnnotation
+case class MyChiselAnnotation(m: Hierarchy[RawModule], tag: String) extends experimental.ChiselAnnotation {
+  def toFirrtl = {
+    println(tag + ": " + m.toTarget)
+    EmptyAnnotation
+  }
+}
+
+@instantiable
+class EmptyModule extends Module {
+  println("Elaborating EmptyModule!")
+}
+
+@instantiable
+class TwoEmptyModules extends Module {
+  val definition = Definition(new EmptyModule)
+  val i0         = Instance(definition)
+  val i1         = Instance(definition)
+}
+
+class Top extends Module {
+  val definition = Definition(new TwoEmptyModules)
+  val instance   = Instance(definition)
+  aop.Select.allInstancesOf[EmptyModule](instance).foreach { i =>
+    experimental.annotate(MyChiselAnnotation(i, "instance"))
+  }
+  aop.Select.allDefinitionsOf[EmptyModule](instance).foreach { d =>
+    experimental.annotate(MyChiselAnnotation(d, "definition"))
+  }
+}
+```
+```scala mdoc:passthrough
+println("```")
+val x = chisel3.stage.ChiselStage.emitFirrtl(new Top)
+println("```")
+```
diff --git a/docs/src/explanations/multi-clock.md b/docs/src/explanations/multi-clock.md
index 6e9afd5a..eafb5372 100644
--- a/docs/src/explanations/multi-clock.md
+++ b/docs/src/explanations/multi-clock.md
@@ -3,6 +3,8 @@ layout: docs
 title:  "Multiple Clock Domains"
 section: "chisel3"
 ---
+# Multiple Clock Domains
+
 Chisel 3 supports multiple clock domains as follows.
 
 Note that in order to cross clock domains safely, you will need appropriate synchronization logic (such as an asynchronous FIFO). You can use the [AsyncQueue library](https://github.com/ucb-bar/asyncqueue) to do this easily.
diff --git a/docs/src/explanations/naming.md b/docs/src/explanations/naming.md
index 60c653aa..a9f21936 100644
--- a/docs/src/explanations/naming.md
+++ b/docs/src/explanations/naming.md
@@ -3,6 +3,7 @@ layout: docs
 title:  "Naming"
 section: "chisel3"
 ---
+# Naming
 
 Historically, Chisel has had trouble reliably capturing the names of signals. The reasons for this are due to (1)
 primarily relying on reflection to find names, (2) using `@chiselName` macro which had unreliable behavior.