From 2439974eea33017f6cea220e62f4736694ba0ed2 Mon Sep 17 00:00:00 2001 From: Abongwa Bonalais Date: Mon, 11 Oct 2021 03:33:20 +0100 Subject: Create naming.md (#2161) Added title to "Namimg Cookbook" website. Co-authored-by: Megan Wachs --- docs/src/cookbooks/naming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/src/cookbooks') 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 -- cgit v1.2.3 From 56df24b9c5664bc9a9285b780d4376b2d8d93dca Mon Sep 17 00:00:00 2001 From: Abongwa Bonalais Date: Tue, 12 Oct 2021 05:34:36 +0100 Subject: Update cookbooks.md (#2172) Added cookbooks to cookbooks.md--- docs/src/cookbooks/cookbooks.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/src/cookbooks') 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) -- cgit v1.2.3 From ef8a9c2148f01e058d2986c9d64f0c35f640790c Mon Sep 17 00:00:00 2001 From: Adam Izraelevitz Date: Wed, 27 Oct 2021 16:52:56 -0700 Subject: Add Select APIs for Hierarchy package (#2210) * Add Hierarchy trait * Add Hierarchy trait * Add Hierarchy scaladoc * Add license * Add isA and tests * Add back isA * Add new Select APIs for hierarchy package * Update scaladoc * Write outlines for tests * Add tests and fixes to new Select functions * Make calculate via lazy val * Apply suggestions from code review Co-authored-by: Megan Wachs * Apply suggestions from code review Co-authored-by: Megan Wachs * Clean up scaladoc * Add shouldNot compile * Apply suggestions from code review Co-authored-by: Megan Wachs * Bugfix all funcs should analyze root too * Add mdoc, bugfix toDefinition * Make func private, add scaladoc * Update src/test/scala/chiselTests/experimental/hierarchy/InstanceSpec.scala Co-authored-by: Jack Koenig * Made protected vals private * Apply suggestions from code review Co-authored-by: Jack Koenig * Address code review comments * Added additional null check Co-authored-by: Megan Wachs Co-authored-by: Jack Koenig --- docs/src/cookbooks/hierarchy.md | 57 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) (limited to 'docs/src/cookbooks') 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("```") +``` -- cgit v1.2.3 From 84da5fdb528bbedc9a32c3e075bb3865994cd4aa Mon Sep 17 00:00:00 2001 From: Jack Koenig Date: Thu, 28 Oct 2021 10:33:55 -0700 Subject: [docs] Improve tieoff Bundle to 0 (#2218) Previously, the example had an extra wrapping module that led to the interesting example getting optimized away.--- docs/src/cookbooks/cookbook.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'docs/src/cookbooks') 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? -- cgit v1.2.3 From 12ed3fe9a780a9914b3f5727d921b4e419967549 Mon Sep 17 00:00:00 2001 From: Øyvind Harboe Date: Sat, 4 Dec 2021 18:45:16 +0100 Subject: [docs] add minimizing output bits recipe (#2278) Co-authored-by: Jack Koenig --- docs/src/cookbooks/cookbook.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) (limited to 'docs/src/cookbooks') diff --git a/docs/src/cookbooks/cookbook.md b/docs/src/cookbooks/cookbook.md index 4b2b088e..e23b158c 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) @@ -404,6 +405,34 @@ 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)) +``` + ## Predictable Naming ### How do I get Chisel to name signals properly in blocks like when/withClockAndReset? -- cgit v1.2.3 From e85bfebb5d661de41f9ccac300fb48bf92840cfe Mon Sep 17 00:00:00 2001 From: Jack Koenig Date: Tue, 7 Dec 2021 13:18:29 -0800 Subject: [docs] Remove body from minimizing output bits recipe (#2290) Remove the body from the emitted Verilog. This was the original intent of the example, and it avoids an issue where Jekyll was not able to render the Markdown file due to Verilog concatenation looking like a variable escape.--- docs/src/cookbooks/cookbook.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/src/cookbooks') diff --git a/docs/src/cookbooks/cookbook.md b/docs/src/cookbooks/cookbook.md index e23b158c..d4cf3030 100644 --- a/docs/src/cookbooks/cookbook.md +++ b/docs/src/cookbooks/cookbook.md @@ -431,6 +431,9 @@ Unlike `Vecs` which represent a singular Chisel type and must have the same widt ```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 -- cgit v1.2.3