Merge branch 'master' into 3.5-release

4 files changed, 95 insertions, 5 deletions

diff --git a/docs/src/cookbooks/cookbook.md b/docs/src/cookbooks/cookbook.md
index ce49b668..d4cf3030 100644
--- a/docs/src/cookbooks/cookbook.md
+++ b/docs/src/cookbooks/cookbook.md
@@ -24,6 +24,7 @@ Please note that these examples make use of [Chisel's scala-style printing](../e
 * [How do I unpack a value ("reverse concatenation") like in Verilog?](#how-do-i-unpack-a-value-reverse-concatenation-like-in-verilog)
 * [How do I do subword assignment (assign to some bits in a UInt)?](#how-do-i-do-subword-assignment-assign-to-some-bits-in-a-uint)
 * [How do I create an optional I/O?](#how-do-i-create-an-optional-io)
+* [How do I minimize the number of bits used in an output vector](#how-do-i-minimize-the-number-of-bits-used-in-an-output-vector)
 * Predictable Naming
   * [How do I get Chisel to name signals properly in blocks like when/withClockAndReset?](#how-do-i-get-chisel-to-name-signals-properly-in-blocks-like-whenwithclockandreset)
   * [How do I get Chisel to name the results of vector reads properly?](#how-do-i-get-chisel-to-name-the-results-of-vector-reads-properly)
@@ -88,13 +89,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 +109,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?
 
@@ -405,6 +405,37 @@ class ModuleWithOptionalIO(flag: Boolean) extends Module {
 }
 ```
 
+### How do I minimize the number of bits used in an output vector?
+
+Use inferred width and a `Seq` instead of a `Vec`:
+
+Consider:
+
+```scala mdoc:silent:reset
+import chisel3._
+
+// Count the number of set bits up to and including each bit position
+class CountBits(width: Int) extends Module {
+  val bits = IO(Input(UInt(width.W)))
+  val countSequence = Seq.tabulate(width)(i => IO(Output(UInt())))
+  val countVector = IO(Output(Vec(width, UInt())))
+  countSequence.zipWithIndex.foreach { case (port, i) =>
+    port := util.PopCount(bits(i, 0))
+  }
+  countVector := countSequence
+}
+```
+
+Unlike `Vecs` which represent a singular Chisel type and must have the same width for every element,
+`Seq` is a purely Scala construct, so their elements are independent from the perspective of Chisel and can have different widths.
+
+```scala mdoc:verilog
+chisel3.stage.ChiselStage.emitVerilog(new CountBits(4))
+  // remove the body of the module by removing everything after ');'
+  .split("\\);")
+  .head + ");\n"
+```
+
 ## Predictable Naming
 
 ### How do I get Chisel to name signals properly in blocks like when/withClockAndReset?
diff --git a/docs/src/cookbooks/cookbooks.md b/docs/src/cookbooks/cookbooks.md
index ee6f5e45..7c3eb8b9 100644
--- a/docs/src/cookbooks/cookbooks.md
+++ b/docs/src/cookbooks/cookbooks.md
@@ -13,3 +13,5 @@ please [file an issue](https://github.com/chipsalliance/chisel3/issues/new) and
 * [General Cookbooks](cookbook)
 * [Naming Cookbook](naming)
 * [Troubleshooting Guide](troubleshooting)
+* [Hierarchy Cookbook](hierarchy)
+* [DataView Cookbook](dataview)
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/cookbooks/naming.md b/docs/src/cookbooks/naming.md
index a41a1e9a..c7ccdd96 100644
--- a/docs/src/cookbooks/naming.md
+++ b/docs/src/cookbooks/naming.md
@@ -10,7 +10,7 @@ import chisel3.experimental.prefix
 import chisel3.experimental.noPrefix
 import chisel3.stage.ChiselStage
 ```
-
+# Naming Cookbook
 ### I still have _T signals, can this be fixed?
 
 First check - is the compiler plugin properly enabled? Scalac plugins are enabled via the scalac option