From 7360c81509420fdf94962abed42cd19de7331619 Mon Sep 17 00:00:00 2001 From: Nick Date: Sat, 2 Oct 2021 23:41:00 -0400 Subject: Fix typos in documentation (#2141) Close #2138--- docs/src/explanations/functional-abstraction.md | 8 ++++---- docs/src/explanations/modules.md | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) (limited to 'docs/src') diff --git a/docs/src/explanations/functional-abstraction.md b/docs/src/explanations/functional-abstraction.md index 4e3900b6..596d869a 100644 --- a/docs/src/explanations/functional-abstraction.md +++ b/docs/src/explanations/functional-abstraction.md @@ -23,10 +23,10 @@ def clb(a: UInt, b: UInt, c: UInt, d: UInt): UInt = where ```clb``` is the function which takes ```a```, ```b```, ```c```, ```d``` as arguments and returns a wire to the output of a boolean circuit. The ```def``` keyword is part of Scala and -introduces a function definition, with each argument followed by a colon then its type, -and the function return type given after the colon following the -argument list. The equals (```=})```sign separates the function argument list from the function -definition. +introduces a function definition, with each argument followed by a colon then +its type, and the function return type given after the colon following the +argument list. The equals (`=`) sign separates the function argument list +from the function definition. We can then use the block in another circuit as follows: ```scala mdoc:silent diff --git a/docs/src/explanations/modules.md b/docs/src/explanations/modules.md index f82a14d6..fcdc6020 100644 --- a/docs/src/explanations/modules.md +++ b/docs/src/explanations/modules.md @@ -132,7 +132,7 @@ class FooWrapper extends RawModule { In the example above, the `RawModule` is used to change the reset polarity of module `SlaveSpi`. Indeed, the reset is active high by default in Chisel modules, then using `withClockAndReset(clock, !rstn)` we can use an active low -reset in entire design. +reset in the entire design. -The clock is just wired as it, but if needed, `RawModule` can be used in +The clock is just wired as is, but if needed, `RawModule` can be used in conjunction with `BlackBox` to connect a differential clock input for example. -- cgit v1.2.3 From 98c5ef031893aacc7cd6a17e8a715ab3a83f05db Mon Sep 17 00:00:00 2001 From: Jack Koenig Date: Tue, 5 Oct 2021 02:39:21 +0200 Subject: Remove workaround for fixed issue in mdoc crash blocks (#2147) Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>--- docs/src/explanations/dataview.md | 4 ---- 1 file changed, 4 deletions(-) (limited to 'docs/src') diff --git a/docs/src/explanations/dataview.md b/docs/src/explanations/dataview.md index 2f229bfc..b1f48f20 100644 --- a/docs/src/explanations/dataview.md +++ b/docs/src/explanations/dataview.md @@ -285,7 +285,6 @@ class BundleB extends Bundle { ``` ```scala mdoc:crash -{ // Using an extra scope here to avoid a bug in mdoc (documentation generation) // We forgot BundleA.foo in the mapping! implicit val myView = DataView[BundleA, BundleB](_ => new BundleB, _.bar -> _.fizz) class BadMapping extends Module { @@ -295,7 +294,6 @@ class BadMapping extends Module { } // We must run Chisel to see the error emitVerilog(new BadMapping) -} ``` As that error suggests, if we *want* the view to be non-total, we can use a `PartialDataView`: @@ -321,7 +319,6 @@ This has the consequence that `PartialDataViews` are **not** invertible in the s For example: ```scala mdoc:crash -{ // Using an extra scope here to avoid a bug in mdoc (documentation generation) implicit val myView2 = myView.invert(_ => new BundleA) class PartialDataViewModule2 extends Module { val in = IO(Input(new BundleA)) @@ -331,7 +328,6 @@ class PartialDataViewModule2 extends Module { } // We must run Chisel to see the error emitVerilog(new PartialDataViewModule2) -} ``` As noted, the mapping must **always** be total for the `View`. -- cgit v1.2.3 From ce15ad50a5c175db06c3bba5e3bf46b6c5466c47 Mon Sep 17 00:00:00 2001 From: Megan Wachs Date: Tue, 5 Oct 2021 10:27:18 -0700 Subject: Remove all Bundle cloneTypes and chiselRuntimeDeprecate its use (#2052) * Remove all manual cloneTypes and make it chisel runtime deprecated to add one * runtime deprecate cloneType with runtime reflection * [Backport this commit] Bundle: add check that override def cloneType still works (will be made an error later) * Plugin: make it an error to override cloneType and add a test for that * Docs: can't compile the cloneType anymore * BundleSpec: comment out failing test I cannot get to fail or ignore Co-authored-by: Jack Koenig --- docs/src/explanations/bundles-and-vecs.md | 65 ++++++++++--------------------- 1 file changed, 20 insertions(+), 45 deletions(-) (limited to 'docs/src') diff --git a/docs/src/explanations/bundles-and-vecs.md b/docs/src/explanations/bundles-and-vecs.md index 78626c42..e683667d 100644 --- a/docs/src/explanations/bundles-and-vecs.md +++ b/docs/src/explanations/bundles-and-vecs.md @@ -128,48 +128,19 @@ class ModuleProgrammaticMixedVec(x: Int, y: Int) extends Module { } ``` -### A note on `cloneType` +### A note on `cloneType` (For Chisel < 3.5) -Since Chisel is built on top of Scala and the JVM, it needs to know how to construct copies of bundles for various -purposes (creating wires, IOs, etc). If you have a parametrized bundle and Chisel can't automatically figure out how to -clone your bundle, you will need to create a custom `cloneType` method in your bundle. Most of the time, this is as -simple as `override def cloneType = (new YourBundleHere(...)).asInstanceOf[this.type]`. +NOTE: This section **only applies to Chisel before Chisel 3.5**. +As of Chisel 3.5, `Bundle`s should **not** `override def cloneType`, +as this is a compiler error when using the chisel3 compiler plugin for inferring `cloneType`. -Note that in the vast majority of cases, **this is not required** as Chisel can figure out how to clone most bundles -automatically. - -Here is an example of a parametrized bundle (`ExampleBundle`) that features a custom `cloneType`. - -```scala mdoc:silent -class ExampleBundle(a: Int, b: Int) extends Bundle { - val foo = UInt(a.W) - val bar = UInt(b.W) - override def cloneType = (new ExampleBundle(a, b)).asInstanceOf[this.type] -} - -class ExampleBundleModule(btype: ExampleBundle) extends Module { - val io = IO(new Bundle { - val out = Output(UInt(32.W)) - val b = Input(chiselTypeOf(btype)) - }) - io.out := io.b.foo + io.b.bar -} - -class Top extends Module { - val io = IO(new Bundle { - val out = Output(UInt(32.W)) - val in = Input(UInt(17.W)) - }) - val x = Wire(new ExampleBundle(31, 17)) - x := DontCare - val m = Module(new ExampleBundleModule(x)) - m.io.b.foo := io.in - m.io.b.bar := io.in - io.out := m.io.out -} -``` - -Generally cloneType can be automatically defined if all arguments to the Bundle are vals e.g. +Since Chisel is built on top of Scala and the JVM, +it needs to know how to construct copies of `Bundle`s for various +purposes (creating wires, IOs, etc). +If you have a parametrized `Bundle` and Chisel can't automatically figure out how to +clone it, you will need to create a custom `cloneType` method in your bundle. +In the vast majority of cases, **this is not required** +as Chisel can figure out how to clone most `Bundle`s automatically: ```scala mdoc:silent class MyCloneTypeBundle(val bitwidth: Int) extends Bundle { @@ -178,13 +149,15 @@ class MyCloneTypeBundle(val bitwidth: Int) extends Bundle { } ``` -The only caveat is if you are passing something of type Data as a "generator" parameter, in which case you should make -it a `private val`. +The only caveat is if you are passing something of type `Data` as a "generator" parameter, +in which case you should make it a `private val`, and define a `cloneType` method with +`override def cloneType = (new YourBundleHere(...)).asInstanceOf[this.type]`. -For example, consider the following Bundle. Because its `gen` variable is not a `private val`, the user has to -explicitly define the `cloneType` method. +For example, consider the following `Bundle`. Because its `gen` variable is not a `private val`, the user has to +explicitly define the `cloneType` method: -```scala mdoc:silent + +```scala import chisel3.util.{Decoupled, Irrevocable} class RegisterWriteIOExplicitCloneType[T <: Data](gen: T) extends Bundle { val request = Flipped(Decoupled(gen)) @@ -196,8 +169,10 @@ class RegisterWriteIOExplicitCloneType[T <: Data](gen: T) extends Bundle { We can make this this infer cloneType by making `gen` private since it is a "type parameter": ```scala mdoc:silent +import chisel3.util.{Decoupled, Irrevocable} class RegisterWriteIO[T <: Data](private val gen: T) extends Bundle { val request = Flipped(Decoupled(gen)) val response = Irrevocable(Bool()) } ``` + -- cgit v1.2.3 From cba0ba65e9a4f95430087a13627bc6b3c5ae5885 Mon Sep 17 00:00:00 2001 From: Jack Koenig Date: Thu, 7 Oct 2021 13:38:28 -0700 Subject: Fix link in DataView explanation (#2153) --- docs/src/explanations/dataview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/src') diff --git a/docs/src/explanations/dataview.md b/docs/src/explanations/dataview.md index b1f48f20..a04bbec7 100644 --- a/docs/src/explanations/dataview.md +++ b/docs/src/explanations/dataview.md @@ -390,7 +390,7 @@ resolution error. This section draws heavily from [[1]](https://stackoverflow.com/a/5598107/2483329) and -[[2]](https://stackoverflow.com/a/5598107/2483329). +[[2]](https://stackoverflow.com/a/8694558/2483329). In particular, see [1] for examples. #### Implicit Resolution Example -- cgit v1.2.3 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') 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 d06ba691859122330c83d1b8ec0e14be89af2bff Mon Sep 17 00:00:00 2001 From: Abongwa Bonalais Date: Mon, 11 Oct 2021 18:03:29 +0100 Subject: Added title to blackboxes.md (#2168) * Added title * Update docs/src/explanations/blackboxes.md Co-authored-by: Megan Wachs Co-authored-by: Megan Wachs --- docs/src/explanations/blackboxes.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/src') diff --git a/docs/src/explanations/blackboxes.md b/docs/src/explanations/blackboxes.md index 4ecd1ea0..a2a041a7 100644 --- a/docs/src/explanations/blackboxes.md +++ b/docs/src/explanations/blackboxes.md @@ -3,6 +3,9 @@ layout: docs title: "Blackboxes" section: "chisel3" --- + +# BlackBoxes + Chisel *BlackBoxes* are used to instantiate externally defined modules. This construct is useful for hardware constructs that cannot be described in Chisel and for connecting to FPGA or other IP not defined in Chisel. -- cgit v1.2.3 From 0556c61ca40ae7740102fc99600224f64da39f47 Mon Sep 17 00:00:00 2001 From: Abongwa Bonalais Date: Mon, 11 Oct 2021 22:18:56 +0100 Subject: Added dataview to explanations.md (#2167) * Added dataview to explanations.md * Update docs/src/explanations/explanations.md Co-authored-by: Megan Wachs Co-authored-by: Megan Wachs --- docs/src/explanations/explanations.md | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/src') diff --git a/docs/src/explanations/explanations.md b/docs/src/explanations/explanations.md index 01894ad7..595bb48c 100644 --- a/docs/src/explanations/explanations.md +++ b/docs/src/explanations/explanations.md @@ -16,6 +16,7 @@ read these documents in the following order: * [Motivation](motivation) * [Supported Hardware](supported-hardware) * [Data Types](data-types) +* [DataView](dataview) * [Bundles and Vecs](bundles-and-vecs) * [Combinational Circuits](combinational-circuits) * [Operators](operators) -- 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') 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 463a352e044341d38524b791be8a74d7815239d3 Mon Sep 17 00:00:00 2001 From: Abongwa Bonalais Date: Wed, 13 Oct 2021 05:00:12 +0100 Subject: Update experimental-features.md (#2175) * Update experimental-features.md Added title to Experimental features * Update experimental-features.md * Update docs/src/appendix/experimental-features.md Co-authored-by: Megan Wachs Co-authored-by: Megan Wachs --- docs/src/appendix/experimental-features.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/src') diff --git a/docs/src/appendix/experimental-features.md b/docs/src/appendix/experimental-features.md index 4b1208aa..92226f8f 100644 --- a/docs/src/appendix/experimental-features.md +++ b/docs/src/appendix/experimental-features.md @@ -3,6 +3,7 @@ layout: docs title: "Experimental Features" section: "chisel3" --- +# Experimental Features Chisel has a number of new features that are worth checking out. This page is an informal list of these features and projects. @@ -12,6 +13,7 @@ Chisel has a number of new features that are worth checking out. This page is a - [Interval Type](#interval-type) - [Loading Memories for simulation or FPGA initialization](#loading-memories) + ### FixedPoint FixedPoint numbers are basic *Data* type along side of UInt, SInt, etc. Most common math and logic operations are supported. Chisel allows both the width and binary point to be inferred by the Firrtl compiler which can simplify -- cgit v1.2.3 From ce8e42077d69e041dddb41843379a0fb4e5b4f23 Mon Sep 17 00:00:00 2001 From: Shorla Date: Wed, 13 Oct 2021 05:49:28 +0100 Subject: Update bundles-and-vecs.md (#2173) * Update bundles-and-vecs.md * Update docs/src/explanations/bundles-and-vecs.md Co-authored-by: Megan Wachs Co-authored-by: Megan Wachs --- docs/src/explanations/bundles-and-vecs.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/src') diff --git a/docs/src/explanations/bundles-and-vecs.md b/docs/src/explanations/bundles-and-vecs.md index e683667d..75230c41 100644 --- a/docs/src/explanations/bundles-and-vecs.md +++ b/docs/src/explanations/bundles-and-vecs.md @@ -4,6 +4,8 @@ title: "Bundles and Vecs" section: "chisel3" --- +# Bundles and Vecs + `Bundle` and `Vec` are classes that allow the user to expand the set of Chisel datatypes with aggregates of other types. Bundles group together several named fields of potentially different types into a coherent unit, much like a `struct` in -- cgit v1.2.3 From 9c026fd3a9beb2b39ad0d675afdcc31dbcc6819d Mon Sep 17 00:00:00 2001 From: Shorla Date: Fri, 22 Oct 2021 16:33:47 +0100 Subject: Add name to Naming Explanation page (#2199) * Update bundles-and-vecs.md * Update docs/src/explanations/bundles-and-vecs.md Co-authored-by: Megan Wachs * Update naming.md Added a title to the cookbook * Add name to Multiple Clock Domain page * Update multi-clock.md Co-authored-by: Megan Wachs --- docs/src/explanations/multi-clock.md | 2 ++ docs/src/explanations/naming.md | 1 + 2 files changed, 3 insertions(+) (limited to 'docs/src') 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. -- 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') 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') 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') 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') 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 From 08271081e4af2025fc6c6af97511fd110ef65e5c Mon Sep 17 00:00:00 2001 From: Jack Koenig Date: Wed, 8 Dec 2021 14:21:44 -0800 Subject: Implement DataViews for Seq and Tuple (#2277) * DataProducts for Seq and Tuple2-10 in DataProduct companion object * DataViews for Seq and Tuple 2-10 in DataView companion object * HWTuple2-10 Bundles in chisel3.experimental * Implicit conversions from Seq to Vec and Tuple to HWTuple in chisel3.experimental.conversions--- docs/src/explanations/dataview.md | 40 ++++++++++++++++++--------------------- 1 file changed, 18 insertions(+), 22 deletions(-) (limited to 'docs/src') diff --git a/docs/src/explanations/dataview.md b/docs/src/explanations/dataview.md index a04bbec7..bb8dbdd1 100644 --- a/docs/src/explanations/dataview.md +++ b/docs/src/explanations/dataview.md @@ -10,7 +10,6 @@ _New in Chisel 3.5_ ```scala mdoc:invisible import chisel3._ -import chisel3.stage.ChiselStage.emitVerilog ``` ## Introduction @@ -91,7 +90,7 @@ class MyModule extends RawModule { Of course, this would result in very different looking Verilog: ```scala mdoc:verilog -emitVerilog(new MyModule { +getVerilogString(new MyModule { override def desiredName = "MyModule" axi := DontCare // Just to generate Verilog in this stub }) @@ -147,7 +146,7 @@ class AXIStub extends RawModule { This will generate Verilog that matches the standard naming convention: ```scala mdoc:verilog -emitVerilog(new AXIStub) +getVerilogString(new AXIStub) ``` Note that if both the _Target_ and the _View_ types are subtypes of `Data` (as they are in this example), @@ -175,7 +174,7 @@ class ConnectionExample extends RawModule { This results in the corresponding fields being connected in the emitted Verilog: ```scala mdoc:verilog -emitVerilog(new ConnectionExample) +getVerilogString(new ConnectionExample) ``` ## Other Use Cases @@ -206,17 +205,6 @@ The issue, is that Chisel primitives like `Mux` and `:=` only operate on subtype Tuples (as members of the Scala standard library), are not subclasses of `Data`. `DataView` provides a mechanism to _view_ a `Tuple` as if it were a `Data`: - - -```scala mdoc:invisible -// ProductDataProduct -implicit val productDataProduct: DataProduct[Product] = new DataProduct[Product] { - def dataIterator(a: Product, path: String): Iterator[(Data, String)] = { - a.productIterator.zipWithIndex.collect { case (d: Data, i) => d -> s"$path._$i" } - } -} -``` - ```scala mdoc // We need a type to represent the Tuple class HWTuple2[A <: Data, B <: Data](val _1: A, val _2: B) extends Bundle @@ -259,16 +247,24 @@ class TupleExample extends RawModule { ```scala mdoc:invisible // Always emit Verilog to make sure it actually works -emitVerilog(new TupleExample) +getVerilogString(new TupleExample) ``` Note that this example ignored `DataProduct` which is another required piece (see [the documentation about it below](#dataproduct)). -All of this is slated to be included the Chisel standard library. +All of this is available to users via a single import: +```scala mdoc:reset +import chisel3.experimental.conversions._ +``` ## Totality and PartialDataView +```scala mdoc:reset:invisible +import chisel3._ +import chisel3.experimental.dataview._ +``` + A `DataView` is _total_ if all fields of the _Target_ type and all fields of the _View_ type are included in the mapping. Chisel will error if a field is accidentally left out from a `DataView`. @@ -293,7 +289,7 @@ class BadMapping extends Module { out := in.viewAs[BundleB] } // We must run Chisel to see the error -emitVerilog(new BadMapping) +getVerilogString(new BadMapping) ``` As that error suggests, if we *want* the view to be non-total, we can use a `PartialDataView`: @@ -309,7 +305,7 @@ class PartialDataViewModule extends Module { ``` ```scala mdoc:verilog -emitVerilog(new PartialDataViewModule) +getVerilogString(new PartialDataViewModule) ``` While `PartialDataViews` need not be total for the _Target_, both `PartialDataViews` and `DataViews` @@ -327,7 +323,7 @@ class PartialDataViewModule2 extends Module { out.viewAs[BundleA] := in } // We must run Chisel to see the error -emitVerilog(new PartialDataViewModule2) +getVerilogString(new PartialDataViewModule2) ``` As noted, the mapping must **always** be total for the `View`. @@ -440,7 +436,7 @@ class FooToBar extends Module { ``` ```scala mdoc:verilog -emitVerilog(new FooToBar) +getVerilogString(new FooToBar) ``` However, it's possible that some user of `Foo` and `Bar` wants different behavior, @@ -460,7 +456,7 @@ class FooToBarSwizzled extends Module { ``` ```scala mdoc:verilog -emitVerilog(new FooToBarSwizzled) +getVerilogString(new FooToBarSwizzled) ``` ### DataProduct -- cgit v1.2.3 From 2e2c7c0857bf9f7d0bde75e22f01b5f092d6e33c Mon Sep 17 00:00:00 2001 From: Jack Koenig Date: Wed, 8 Dec 2021 15:20:27 -0800 Subject: [docs] Update versioning appendix to include 3.5 (#2293) Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>--- docs/src/appendix/versioning.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) (limited to 'docs/src') diff --git a/docs/src/appendix/versioning.md b/docs/src/appendix/versioning.md index 8c5ef91c..9f799275 100644 --- a/docs/src/appendix/versioning.md +++ b/docs/src/appendix/versioning.md @@ -17,19 +17,23 @@ Historically, due to a mistake in versioning with chisel-iotesters as well as so the compatible versions of Chisel-related projects has not been obvious. We are taking steps to improve the situation by bringing the major versions more in line (the `B` part in `A.B.C`), but the inconsistencies remain in previously published versions. +Beginning with Chisel 3.5, the major versions for all projects are aligned on `A.5`). Please use the following table to determine which versions of the related projects are compatible. In particular, versions of projects in this table were compiled against the version of any dependencies listed in the same row. For example, `chisel-iotesters` version 1.4 was compiled against `chisel3` version 3.3. -| chisel3 | chiseltest | chisel-iotesters | firrtl | treadle | diagrammer | firrtl-interpreter2 | -| ------- | ---------- | ---------------- | ------ | ------- | ---------- | ----- | -| 3.4 | 0.3 | 1.5 | 1.4 | 1.3 | 1.3 | 1.4 | -| 3.3 | 0.2 | 1.4 | 1.3 | 1.2 | 1.2 | 1.3 | -| 3.2 | 0.11 | 1.3 | 1.2 | 1.1 | 1.1 | 1.2 | -| 3.1 | - | 1.2 | 1.1 | 1.0 | 1.0 | 1.1 | -| 3.0 | - | 1.1 | 1.0 | -3 | - | 1.0 | +| chisel3 | chiseltest | chisel-iotesters3 | firrtl | treadle | diagrammer | firrtl-interpreter2 | +| ------- | ---------- | ---------------- | ------ | ------- | ---------- | ----- | +| 3.5 | 0.54 | 2.55 | 1.5 | 1.54 | 1.54 | - | +| 3.4 | 0.3 | 1.5 | 1.4 | 1.3 | 1.3 | 1.4 | +| 3.3 | 0.2 | 1.4 | 1.3 | 1.2 | 1.2 | 1.3 | +| 3.2 | 0.11 | 1.3 | 1.2 | 1.1 | 1.1 | 1.2 | +| 3.1 | - | 1.2 | 1.1 | 1.0 | 1.0 | 1.1 | +| 3.0 | - | 1.1 | 1.0 | - | - | 1.0 | 1 chiseltest 0.1 was published under artifact name [chisel-testers2](https://search.maven.org/search?q=a:chisel-testers2_2.12) (0.2 was published under both artifact names) -2 Replaced by Treadle, in maintenance mode only since version 1.1 -3 Treadle was preceded by the firrtl-interpreter +2 Replaced by Treadle, in maintenance mode only since version 1.1, final version is 1.4 +3 Replaced by chiseltest, final version is 2.5 +4 chiseltest, treadle, and diagrammer skipped X.4 to have a consistent major version with Chisel +5 chisel-iotesters skipped from 1.5 to 2.5 to have a consistent major version with Chisel -- cgit v1.2.3 From 8a60679bd742f6824a73e93811e423aa7feccc43 Mon Sep 17 00:00:00 2001 From: Jack Koenig Date: Wed, 15 Dec 2021 12:15:30 -0800 Subject: Add "Upgrading From Chisel 3.4 to 3.5" (#2275) This new document is a place to describe issues users may run into when upgrading from Chisel 3.4 to 3.5. This initial version includes the solution for the removal of virtual method "val io". Co-authored-by: Megan Wachs --- docs/src/appendix/appendix.md | 1 + docs/src/appendix/upgrading-from-chisel-3-4.md | 145 +++++++++++++++++++++++++ docs/src/appendix/upgrading-from-scala-2-11.md | 2 + 3 files changed, 148 insertions(+) create mode 100644 docs/src/appendix/upgrading-from-chisel-3-4.md (limited to 'docs/src') diff --git a/docs/src/appendix/appendix.md b/docs/src/appendix/appendix.md index 0efedbfe..55244cdb 100644 --- a/docs/src/appendix/appendix.md +++ b/docs/src/appendix/appendix.md @@ -11,4 +11,5 @@ This section covers some less-common Chisel topics. * [Differences between Chisel3 and Chisel2](chisel3-vs-chisel2) * [Experimental Features](experimental-features) * [Upgrading from Scala 2.11](upgrading-from-scala-2-11) +* [Upgrading from Chisel 3.4](upgrading-from-chisel-3-4) * [Versioning](versioning) diff --git a/docs/src/appendix/upgrading-from-chisel-3-4.md b/docs/src/appendix/upgrading-from-chisel-3-4.md new file mode 100644 index 00000000..f7b02820 --- /dev/null +++ b/docs/src/appendix/upgrading-from-chisel-3-4.md @@ -0,0 +1,145 @@ +--- +layout: docs +title: "Upgrading From Chisel 3.4 to 3.5" +section: "chisel3" +--- + + +```scala mdoc:invisible +import chisel3._ +``` + + +## Upgrading From Chisel 3.4 to 3.5 + +Chisel 3.5 was a major step forward. It added support for Scala 2.13 as well as dropped many long deprecated APIs. +Some users may run into issues while upgrading so this page serves as a central location to describe solutions to common issues. + + +### General Strategy for Upgrade + +Users are encouraged to first upgrade to the latest version of Chisel 3.4 (3.4.4 at the time of writing) and resolve all deprecation warnings. Doing so should enable a smoother transition to Chisel 3.5. + +### Common Issues + +#### Value io is not a member of chisel3.Module + +This issue most often arises when there are two implementations of a given `Module` that may be chosen between by a generator parameter. +For example: + +```scala mdoc +class Foo extends Module { + val io = IO(new Bundle { + val in = Input(UInt(8.W)) + val out = Output(UInt(8.W)) + }) + io.out := io.in +} + +class Bar extends Module { + val io = IO(new Bundle { + val in = Input(UInt(8.W)) + val out = Output(UInt(8.W)) + }) + io.out := io.in + 1.U +} +``` + +```scala mdoc:fail +class Example(useBar: Boolean) extends Module { + val io = IO(new Bundle { + val in = Input(UInt(8.W)) + val out = Output(UInt(8.W)) + }) + + val inst = if (useBar) { + Module(new Bar) + } else { + Module(new Foo) + } + + inst.io.in := io.in + io.out := inst.io.out +} +``` + +`Foo` and `Bar` clearly have the same interface, yet we get a type error in Chisel 3.5. +Notably, while this does work in Chisel 3.4, it does throw a deprecation warning. +In short, this code is relying on old behavior of the Scala type inferencer. +In Scala 2.11 and before, the type inferred for `val inst` is: `Module { def io : { def in : UInt; def out : UInt } }`. +And in fact, if we manually ascribe this type to `val inst`, our same code from above works in Chisel 3.5: + +```scala mdoc +class Example(useBar: Boolean) extends Module { + val io = IO(new Bundle { + val in = Input(UInt(8.W)) + val out = Output(UInt(8.W)) + }) + + val inst: Module { def io : { def in : UInt; def out : UInt } } = if (useBar) { + Module(new Bar) + } else { + Module(new Foo) + } + + inst.io.in := io.in + io.out := inst.io.out +} +``` + +So what is going on and why is this type so ugly? +This is called a [_structural_ (or _duck_) type](https://en.wikipedia.org/wiki/Structural_type_system). +Basically, code does not provide any unifying type for `Foo` and `Bar` so the compiler does its best to make one up. +One negative consequence of the old Scala behavior is that structural type inference makes it very easy to accidentally +change the public API of your code without meaning to. +Thus, in the bump from Scala 2.11 to 2.12, the behavior of the Scala compiler changed to not do structural type inference by default. + +The solution, is to explicitly provide a type to the Scala compiler: + +```scala mdoc:invisible:reset +import chisel3._ +``` + +```scala mdoc +trait HasCommonInterface extends Module { + val io = IO(new Bundle { + val in = Input(UInt(8.W)) + val out = Output(UInt(8.W)) + }) +} + +class Foo extends Module with HasCommonInterface { + io.out := io.in +} + +class Bar extends Module with HasCommonInterface { + io.out := io.in + 1.U +} +``` + +Now our original code works: + +```scala mdoc +class Example(useBar: Boolean) extends Module { + val io = IO(new Bundle { + val in = IO(Input(UInt(8.W))) + val out = IO(Output(UInt(8.W))) + }) + + // Now, inst is inferred to be of type "HasCommonInterface" + val inst = if (useBar) { + Module(new Bar) + } else { + Module(new Foo) + } + + inst.io.in := io.in + io.out := inst.io.out +} +``` + +**Historical Note** + +This may sound similar because a very similar error is included in [Common Issues](upgrading-from-scala-2-11#common-issues) in the Appendix for upgrading from Scala 2.11 to 2.12. +The workaround employed in Chisel for Scala 2.12 did not work in Scala 2.13, so we came up with the more robust solution described above. + diff --git a/docs/src/appendix/upgrading-from-scala-2-11.md b/docs/src/appendix/upgrading-from-scala-2-11.md index 26e2d252..6724e3e1 100644 --- a/docs/src/appendix/upgrading-from-scala-2-11.md +++ b/docs/src/appendix/upgrading-from-scala-2-11.md @@ -14,6 +14,8 @@ import chisel3._ ## Upgrading From Scala 2.11 to 2.12 +**As of Chisel 3.5, support for Scala 2.11 has been dropped. This page is only relevant to Chisel versions 3.4 and earlier** + As the latest (and probably last) release of Scala 2.11 (2.11.12) was released on 2 November 2017, the time has come to deprecate support for Scala 2.11. Chisel 3.4 is the last version of Chisel that will support Scala 2.11, so users should upgrade to Scala 2.12 This document is intended to help guide Chisel users through this process; both the "Why?" and the "How?". -- cgit v1.2.3