From 945416c628656498be7a98dcd4899f2b9e830c00 Mon Sep 17 00:00:00 2001
From: mergify[bot]
Date: Tue, 2 Aug 2022 16:28:23 +0000
Subject: Fix example in Chisel Type vs Scala Type article (#2655) (#2657)

(cherry picked from commit 0b2c211beefeefb72c86ea69a0b2a0101b2f2c20)

Co-authored-by: Megan Wachs <megan@sifive.com>---
 docs/src/explanations/chisel-type-vs-scala-type.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

(limited to 'docs/src')

diff --git a/docs/src/explanations/chisel-type-vs-scala-type.md b/docs/src/explanations/chisel-type-vs-scala-type.md
index 6c311a21..ead509d3 100644
--- a/docs/src/explanations/chisel-type-vs-scala-type.md
+++ b/docs/src/explanations/chisel-type-vs-scala-type.md
@@ -245,13 +245,13 @@ that you have more information than it can infer to convert Scala types:
 
 ```scala mdoc:silent
 class ScalaCastingModule(gen: () => Bundle) extends Module {
-  val io = gen().asInstanceOf[MyBundle]
+  val io = IO(Output(gen().asInstanceOf[MyBundle]))
   io.foo := 0.U
 }
 ```
 
 This works if we do indeed have more information than the compiler:
-``` scala mdoc:silent
+```scala mdoc:silent
 ChiselStage.elaborate(new ScalaCastingModule( () => new MyBundle(3)))
 ```
 
-- 
cgit v1.2.3


From 7bad3d2ec316f24f3da79d1dfef19e128cfe8bf5 Mon Sep 17 00:00:00 2001
From: mergify[bot]
Date: Fri, 12 Aug 2022 20:04:33 +0000
Subject: Add ability to suppress enum cast warnings (#2671) (#2674)

(cherry picked from commit 1ad820f7f549eddcd7188b737f59a240e48a7f0a)

Co-authored-by: Zachary Yedidia <zyedidia@gmail.com>---
 docs/src/explanations/chisel-enum.md | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

(limited to 'docs/src')

diff --git a/docs/src/explanations/chisel-enum.md b/docs/src/explanations/chisel-enum.md
index a390aea4..16b5570d 100644
--- a/docs/src/explanations/chisel-enum.md
+++ b/docs/src/explanations/chisel-enum.md
@@ -17,6 +17,7 @@ import chisel3._
 import chisel3.util._
 import chisel3.stage.ChiselStage
 import chisel3.experimental.ChiselEnum
+import chisel3.experimental.suppressEnumCastWarning
 ```
 
 ```scala mdoc:invisible
@@ -167,6 +168,30 @@ val (log2, _) = grabLog(ChiselStage.emitChirrtl(new SafeFromUInt))
 println(s"```\n$log2```")
 ```
 
+You can also suppress the warning by using `suppressEnumCastWarning`. This is
+primarily used for casting from [[UInt]] to a Bundle type that contains an
+Enum, where the [[UInt]] is known to be valid for the Bundle type.
+
+```scala mdoc
+class MyBundle extends Bundle {
+  val addr = UInt(8.W)
+  val op = Opcode()
+}
+
+class SuppressedFromUInt extends Module {
+  val in = IO(Input(UInt(15.W)))
+  val out = IO(Output(new MyBundle()))
+  suppressEnumCastWarning {
+    out := in.asTypeOf(new MyBundle)
+  }
+}
+```
+
+```scala mdoc:invisible
+val (log3, _) = grabLog(ChiselStage.emitChirrtl(new SuppressedFromUInt))
+assert(log3.isEmpty)
+```
+
 ## Testing
 
 The _Type_ of the enums values is `<ChiselEnum Object>.Type` which can be useful for passing the values
-- 
cgit v1.2.3


From 96830a4ad502019ff1040889a89375ff1e3a6c6b Mon Sep 17 00:00:00 2001
From: mergify[bot]
Date: Tue, 16 Aug 2022 16:57:34 +0000
Subject: Add a cookbook and publicly visible scaladoc for prefix, noPrefix
 (#2687) (#2690)

* Add a cookbook and publicly visible scaladoc for prefix, noPrefix

(cherry picked from commit ae7dc30b3b99f1fbd91c35f54bc19be7c55f74a3)

Co-authored-by: Megan Wachs <megan@sifive.com>---
 docs/src/cookbooks/naming.md | 66 ++++++++++++++++++++++++++++++++++++++------
 1 file changed, 57 insertions(+), 9 deletions(-)

(limited to 'docs/src')

diff --git a/docs/src/cookbooks/naming.md b/docs/src/cookbooks/naming.md
index c7ccdd96..ff3cb892 100644
--- a/docs/src/cookbooks/naming.md
+++ b/docs/src/cookbooks/naming.md
@@ -6,20 +6,66 @@ section: "chisel3"
 
 ```scala mdoc:invisible
 import chisel3._
-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
-`-Xplugin:<path/to/jar>`. You can check which compiler plugins are enabled by running `show Compile / scalacOptions` in
-the sbt prompt.
+See the next answer!
+
+### I have so many wires with the same name, like `x`, `x_1` and `x_2`. How can I make them easier to understand?
+
+Signals with `_T` names or names that Chisel has to uniquify
+often are intermediate values generated within loops, function calls, or `when` predicates.
+They can also be consumed by verification statements like `assert` or `prints`.
+In these cases, the compiler plugin often can't find a good prefix for the generated
+intermediate signals and can't name them at all or has to make up a unique name for them.
+
+We recommend you manually insert calls to `prefix` to clarify these cases:
+
+```scala mdoc:silent
+import chisel3.experimental.prefix
+class ExamplePrefix extends Module {
+
+  Seq.tabulate{2} {i =>
+    Seq.tabulate{2}{ j =>
+      prefix(s"loop_${i}_${j}"){
+        val x = WireInit((i*0x10+j).U(8.W))
+        dontTouch(x)
+      }
+    }
+  }
+}
+```
+```scala mdoc:verilog
+ChiselStage.emitVerilog(new ExamplePrefix)
+```
+### How can I get better names for code generated by `when` clauses?
+
+The `prefix` API can help with code inside `when` clauses:
+
+```scala mdoc:silent
+class ExampleWhenPrefix extends Module {
 
-If the plugin is enabled, these signals could be intermediate values which are consumed by either assertions or when
-predicates. In these cases, the compiler plugin often can't find a good prefix for the generated intermediate signals.
-We recommend you manually insert calls to `prefix` to fix these cases. We did this to Rocket Chip and saw huge benefits!
+  val in = IO(Input(UInt(4.W)))
+  val out = IO(Output(UInt(4.W)))
+
+  out := DontCare
+
+  Seq.tabulate{2}{ i =>
+    val j = i + 1
+    when (in === j.U) { prefix(s"clause_${j}"){
+      val foo = Wire(UInt(4.W))
+      foo := in +& j.U(4.W)
+      out := foo
+    }}
+  }
+}
+```
+```scala mdoc:verilog
+ChiselStage.emitVerilog(new ExampleWhenPrefix)
+```
 
 ### I still see _GEN signals, can this be fixed?
 
@@ -43,11 +89,13 @@ name collisions, which are what triggers all those annoying signal name bumps!
 
 Use the `.suggestName` method, which is on all classes which subtype `Data`.
 
-### All this prefixing is annoying, how do I fix it?
+### How can I omit the prefix in certain parts of the code?
 
 You can use the `noPrefix { ... }` to strip the prefix from all signals generated in that scope.
 
 ```scala mdoc
+import chisel3.experimental.noPrefix
+
 class ExampleNoPrefix extends Module {
   val in = IO(Input(UInt(2.W)))
   val out = IO(Output(UInt()))
-- 
cgit v1.2.3


From fc3fedaa9c16d7861b452388a70ec2f6e2a3dc30 Mon Sep 17 00:00:00 2001
From: mergify[bot]
Date: Tue, 20 Sep 2022 18:54:01 +0000
Subject: Cleanup Cookbook and printing docs (#2727) (#2742)

* Cleanup Cookbook and printing docs
* Format specifiers are actually concise now

Co-authored-by: Megan Wachs <megan@sifive.com>
(cherry picked from commit df2a71833ffc8ee8a053a1e8ea41c482e46be132)

Co-authored-by: Aditya Naik <91489422+adkian-sifive@users.noreply.github.com>---
 docs/src/cookbooks/cookbook.md    |  8 ++++----
 docs/src/explanations/printing.md | 34 ++++++++++++++++------------------
 2 files changed, 20 insertions(+), 22 deletions(-)

(limited to 'docs/src')

diff --git a/docs/src/cookbooks/cookbook.md b/docs/src/cookbooks/cookbook.md
index ab8e76d3..14bf9706 100644
--- a/docs/src/cookbooks/cookbook.md
+++ b/docs/src/cookbooks/cookbook.md
@@ -55,7 +55,7 @@ class Foo extends RawModule {
   bundle.foo := 0xc.U
   bundle.bar := 0x3.U
   val uint = bundle.asUInt
-  printf(p"$uint") // 195
+  printf(cf"$uint") // 195
 
   // Test
   assert(uint === 0xc3.U)
@@ -78,7 +78,7 @@ class Foo extends RawModule {
   val uint = 0xb4.U
   val bundle = uint.asTypeOf(new MyBundle)
   
-  printf(p"$bundle") // Bundle(foo -> 11, bar -> 4)
+  printf(cf"$bundle") // Bundle(foo -> 11, bar -> 4)
 
   // Test
   assert(bundle.foo === 0xb.U)
@@ -126,7 +126,7 @@ class Foo extends RawModule {
   val uint = 0xc.U
   val vec = VecInit(uint.asBools)
 
-  printf(p"$vec") // Vec(0, 0, 1, 1)
+  printf(cf"$vec") // Vec(0, 0, 1, 1)
 
   // Test
   assert(vec(0) === false.B)
@@ -147,7 +147,7 @@ class Foo extends RawModule {
   val vec = VecInit(true.B, false.B, true.B, true.B)
   val uint = vec.asUInt
 
-  printf(p"$uint") // 13
+  printf(cf"$uint") // 13
 
   // Test
   // (remember leftmost Bool in Vec is low order bit)
diff --git a/docs/src/explanations/printing.md b/docs/src/explanations/printing.md
index abd1a427..71a6f5cf 100644
--- a/docs/src/explanations/printing.md
+++ b/docs/src/explanations/printing.md
@@ -13,22 +13,22 @@ Chisel provides the `printf` function for debugging purposes. It comes in two fl
 
 ### Scala-style
 
-Chisel also supports printf in a style similar to [Scala's String Interpolation](http://docs.scala-lang.org/overviews/core/string-interpolation.html). Chisel provides a custom string interpolator `p` which can be used as follows:
+Chisel also supports printf in a style similar to [Scala's String Interpolation](http://docs.scala-lang.org/overviews/core/string-interpolation.html). Chisel provides a custom string interpolator `cf` which follows C-style format specifiers (see section [C-style](#c-style) below). Here's a few examples of using the `cf` interpolator:
 
 ```scala mdoc:invisible
 import chisel3._
 ```
 ```scala mdoc:compile-only
 val myUInt = 33.U
-printf(p"myUInt = $myUInt") // myUInt = 33
+printf(cf"myUInt = $myUInt") // myUInt = 33
 ```
 
-Note that when concatenating `p"..."` strings, you need to start with a `p"..."` string:
+Note that when concatenating `cf"..."` strings, you need to start with a `cf"..."` string:
 
 ```scala mdoc:compile-only
 // Does not interpolate the second string
 val myUInt = 33.U
-printf("my normal string" + p"myUInt = $myUInt")
+printf("my normal string" + cf"myUInt = $myUInt")
 ```
 
 #### Simple formatting
@@ -38,22 +38,20 @@ Other formats are available as follows:
 ```scala mdoc:compile-only
 val myUInt = 33.U
 // Hexadecimal
-printf(p"myUInt = 0x${Hexadecimal(myUInt)}") // myUInt = 0x21
+printf(cf"myUInt = 0x$myUInt%x") // myUInt = 0x21
 // Binary
-printf(p"myUInt = ${Binary(myUInt)}") // myUInt = 100001
+printf(cf"myUInt = $myUInt%b") // myUInt = 100001
 // Character
-printf(p"myUInt = ${Character(myUInt)}") // myUInt = !
+printf(cf"myUInt = $myUInt%c") // myUInt = !
 ```
 
-We recognize that the format specifiers are verbose, so we are working on a more concise syntax.
-
 #### Aggregate data-types
 
 Chisel provides default custom "pretty-printing" for Vecs and Bundles. The default printing of a Vec is similar to printing a Seq or List in Scala while printing a Bundle is similar to printing a Scala Map.
 
 ```scala mdoc:compile-only
 val myVec = VecInit(5.U, 10.U, 13.U)
-printf(p"myVec = $myVec") // myVec = Vec(5, 10, 13)
+printf(cf"myVec = $myVec") // myVec = Vec(5, 10, 13)
 
 val myBundle = Wire(new Bundle {
   val foo = UInt()
@@ -61,7 +59,7 @@ val myBundle = Wire(new Bundle {
 })
 myBundle.foo := 3.U
 myBundle.bar := 11.U
-printf(p"myBundle = $myBundle") // myBundle = Bundle(a -> 3, b -> 11)
+printf(cf"myBundle = $myBundle") // myBundle = Bundle(a -> 3, b -> 11)
 ```
 
 #### Custom Printing
@@ -76,11 +74,11 @@ class Message extends Bundle {
   val data = UInt(64.W)
   override def toPrintable: Printable = {
     val char = Mux(valid, 'v'.U, '-'.U)
-    p"Message:\n" +
-    p"  valid  : ${Character(char)}\n" +
-    p"  addr   : 0x${Hexadecimal(addr)}\n" +
-    p"  length : $length\n" +
-    p"  data   : 0x${Hexadecimal(data)}\n"
+    cf"Message:\n" +
+    cf"  valid  : $char%c\n" +
+    cf"  addr   : $addr%x\n" +
+    cf"  length : $length\n" +
+    cf"  data   : $data%x\n"
   }
 }
 
@@ -90,7 +88,7 @@ myMessage.addr := "h1234".U
 myMessage.length := 10.U
 myMessage.data := "hdeadbeef".U
 
-printf(p"$myMessage")
+printf(cf"$myMessage")
 ```
 
 Which prints the following:
@@ -103,7 +101,7 @@ Message:
   data   : 0x00000000deadbeef
 ```
 
-Notice the use of `+` between `p` interpolated "strings". The results of `p` interpolation can be concatenated by using the `+` operator. For more information, please see the documentation
+Notice the use of `+` between `cf` interpolated "strings". The results of `cf` interpolation can be concatenated by using the `+` operator.
 
 ### C-Style
 
-- 
cgit v1.2.3


From cb1bb67194ccf4c17d76f5ad2e8b1e8818c252b8 Mon Sep 17 00:00:00 2001
From: mergify[bot]
Date: Fri, 30 Sep 2022 01:53:09 +0000
Subject: Cookbooks: use more mdoc power, fix issues (#2752) (#2754)

Co-authored-by: Jack Koenig <koenig@sifive.com>
(cherry picked from commit fc970ca28e562f2ea3ba160963604ea3deaf3467)

Co-authored-by: Megan Wachs <megan@sifive.com>---
 docs/src/cookbooks/cookbook.md | 152 +++++++++++++++++++++++++----------------
 1 file changed, 94 insertions(+), 58 deletions(-)

(limited to 'docs/src')

diff --git a/docs/src/cookbooks/cookbook.md b/docs/src/cookbooks/cookbook.md
index 14bf9706..ac3a0c5d 100644
--- a/docs/src/cookbooks/cookbook.md
+++ b/docs/src/cookbooks/cookbook.md
@@ -50,7 +50,7 @@ class MyBundle extends Bundle {
   val bar = UInt(4.W)
 }
 
-class Foo extends RawModule {
+class Foo extends Module {
   val bundle = Wire(new MyBundle)
   bundle.foo := 0xc.U
   bundle.bar := 0x3.U
@@ -62,6 +62,11 @@ class Foo extends RawModule {
 }
 ```
 
+```scala mdoc:invisible
+// Hidden but will make sure this actually compiles
+getVerilogString(new Foo)
+```
+
 ### How do I create a Bundle from a UInt?
 
 Use the [`asTypeOf`](https://www.chisel-lang.org/api/latest/chisel3/UInt.html#asTypeOf[T%3C:chisel3.Data](that:T):T) method to reinterpret the [`UInt`](https://www.chisel-lang.org/api/latest/chisel3/UInt.html) as the type of the [`Bundle`](https://www.chisel-lang.org/api/latest/chisel3/Bundle.html).
@@ -74,7 +79,7 @@ class MyBundle extends Bundle {
   val bar = UInt(4.W)
 }
 
-class Foo extends RawModule {
+class Foo extends Module {
   val uint = 0xb4.U
   val bundle = uint.asTypeOf(new MyBundle)
   
@@ -86,6 +91,11 @@ class Foo extends RawModule {
 }
 ```
 
+```scala mdoc:invisible
+// Hidden but will make sure this actually compiles
+getVerilogString(new Foo)
+```
+
 ### How can I tieoff a Bundle/Vec to 0?
 
 You can use `asTypeOf` as above. If you don't want to worry about the type of the thing
@@ -100,7 +110,7 @@ class MyBundle extends Bundle {
   val bar = Vec(4, UInt(1.W))
 }
 
-class Foo(typ: MyBundle) extends RawModule {
+class Foo(typ: MyBundle) extends Module {
   val bundleA = IO(Output(typ))
   val bundleB = IO(Output(typ))
   
@@ -122,7 +132,7 @@ Use [`VecInit`](https://www.chisel-lang.org/api/latest/chisel3/VecInit$.html) gi
 ```scala mdoc:silent:reset
 import chisel3._
 
-class Foo extends RawModule {
+class Foo extends Module {
   val uint = 0xc.U
   val vec = VecInit(uint.asBools)
 
@@ -136,6 +146,11 @@ class Foo extends RawModule {
 }
 ```
 
+```scala mdoc:invisible
+// Hidden but will make sure this actually compiles
+getVerilogString(new Foo)
+```
+
 ### How do I create a UInt from a Vec of Bool?
 
 Use the builtin function [`asUInt`](https://www.chisel-lang.org/api/latest/chisel3/Vec.html#asUInt():chisel3.UInt)
@@ -143,7 +158,7 @@ Use the builtin function [`asUInt`](https://www.chisel-lang.org/api/latest/chise
 ```scala mdoc:silent:reset
 import chisel3._
 
-class Foo extends RawModule {
+class Foo extends Module {
   val vec = VecInit(true.B, false.B, true.B, true.B)
   val uint = vec.asUInt
 
@@ -156,6 +171,11 @@ class Foo extends RawModule {
 }
 ```
 
+```scala mdoc:invisible
+// Hidden but will make sure this actually compiles
+getVerilogString(new Foo)
+```
+
 ### How do I connect a subset of Bundle fields?
 
 See the [DataView cookbook](dataview#how-do-i-connect-a-subset-of-bundle-fields).
@@ -220,7 +240,7 @@ For more information, the API Documentation for [`Vec`](https://www.chisel-lang.
 ```scala mdoc:silent:reset
 import chisel3._
 
-class Foo extends RawModule {
+class Foo extends Module {
   val regOfVec = Reg(Vec(4, UInt(32.W))) // Register of 32-bit UInts
   regOfVec(0) := 123.U                   // Assignments to elements of the Vec
   regOfVec(1) := 456.U
@@ -234,6 +254,10 @@ class Foo extends RawModule {
   val initRegOfVec = RegInit(VecInit(Seq.fill(4)(0.U(32.W))))
 }
 ```
+```scala mdoc:invisible
+// Hidden but will make sure this actually compiles
+getVerilogString(new Foo)
+```
 
 
 ### How do I partially reset an Aggregate Reg?
@@ -273,6 +297,12 @@ class MyModule2 extends Module {
 }
 ```
 
+```scala mdoc:invisible
+// Hidden but will make sure this actually compiles
+getVerilogString(new MyModule)
+getVerilogString(new MyModule2)
+```
+
 
 ## Bundles
 
@@ -467,6 +497,11 @@ class DetectTwoOnes extends Module {
 }
 ```
 
+```scala mdoc:invisible
+// Hidden but will make sure this actually compiles
+getVerilogString(new DetectTwoOnes)
+```
+
 Note: the `is` statement can take multiple conditions e.g. `is (sTwo1s, sOne1) { ... }`.
 
 ### How do I unpack a value ("reverse concatenation") like in Verilog?
@@ -497,7 +532,7 @@ class MyBundle extends Bundle {
 The easiest way to accomplish this in Chisel would be:
 
 ```scala mdoc:silent
-class Foo extends RawModule {
+class Foo extends Module {
   val z = Wire(UInt(9.W))
   z := DontCare // This is a dummy connection
   val unpacked = z.asTypeOf(new MyBundle)
@@ -507,6 +542,11 @@ class Foo extends RawModule {
 }
 ```
 
+```scala mdoc:invisible
+// Hidden but will make sure this actually compiles
+getVerilogString(new Foo)
+```
+
 If you **really** need to do this for a one-off case (Think thrice! It is likely you can better structure the code using bundles), then rocket-chip has a [Split utility](https://github.com/freechipsproject/rocket-chip/blob/723af5e6b69e07b5f94c46269a208a8d65e9d73b/src/main/scala/util/Misc.scala#L140) which can accomplish this.
 
 ### How do I do subword assignment (assign to some bits in a UInt)?
@@ -516,7 +556,7 @@ Below, the left-hand side connection to `io.out(0)` is not allowed.
 
 ```scala mdoc:silent:reset
 import chisel3._
-import chisel3.stage.{ChiselStage, ChiselGeneratorAnnotation}
+import chisel3.stage.ChiselStage
 
 class Foo extends Module {
   val io = IO(new Bundle {
@@ -529,7 +569,7 @@ class Foo extends Module {
 
 If you try to compile this, you will get an error.
 ```scala mdoc:crash
-(new ChiselStage).execute(Array("-X", "verilog"), Seq(new ChiselGeneratorAnnotation(() => new Foo)))
+getVerilogString(new Foo)
 ```
 
 Chisel3 *does not support subword assignment*.
@@ -552,6 +592,10 @@ class Foo extends Module {
 }
 ```
 
+```scala mdoc:invisible
+// Hidden but will make sure this actually compiles
+getVerilogString(new Foo)
+```
 
 ### How do I create an optional I/O?
 
@@ -574,6 +618,11 @@ class ModuleWithOptionalIOs(flag: Boolean) extends Module {
 }
 ```
 
+```scala mdoc:invisible
+// Hidden but will make sure this actually compiles
+getVerilogString(new ModuleWithOptionalIOs(true))
+```
+
 The following is an example where an entire `IO` is optional:
 
 ```scala mdoc:silent:reset
@@ -587,6 +636,11 @@ class ModuleWithOptionalIO(flag: Boolean) extends Module {
 }
 ```
 
+```scala mdoc:invisible
+// Hidden but will make sure this actually compiles
+getVerilogString(new ModuleWithOptionalIO(true))
+```
+
 ### How do I create I/O without a prefix?
 
 In most cases, you can simply call `IO` multiple times:
@@ -670,7 +724,9 @@ Use the compiler plugin, and check out the [Naming Cookbook](naming) if that sti
 
 ### How do I get Chisel to name the results of vector reads properly?
 Currently, name information is lost when using dynamic indexing. For example:
-```scala mdoc:silent
+```scala mdoc:silent:reset
+import chisel3._
+
 class Foo extends Module {
   val io = IO(new Bundle {
     val in = Input(Vec(4, Bool()))
@@ -686,26 +742,9 @@ class Foo extends Module {
 ```
 
 The above code loses the `x` name, instead using `_GEN_3` (the other `_GEN_*` signals are expected).
-```verilog
-module Foo(
-  input        clock,
-  input        reset,
-  input        io_in_0,
-  input        io_in_1,
-  input        io_in_2,
-  input        io_in_3,
-  input  [1:0] io_idx,
-  input        io_en,
-  output       io_out
-);
-  wire  _GEN_1; // @[main.scala 15:13]
-  wire  _GEN_2; // @[main.scala 15:13]
-  wire  _GEN_3; // @[main.scala 15:13]
-  assign _GEN_1 = 2'h1 == io_idx ? io_in_1 : io_in_0; // @[main.scala 15:13]
-  assign _GEN_2 = 2'h2 == io_idx ? io_in_2 : _GEN_1; // @[main.scala 15:13]
-  assign _GEN_3 = 2'h3 == io_idx ? io_in_3 : _GEN_2; // @[main.scala 15:13]
-  assign io_out = _GEN_3 & io_en; // @[main.scala 16:10]
-endmodule
+
+```scala mdoc:verilog
+getVerilogString(new Foo)
 ```
 
 This can be worked around by creating a wire and connecting the dynamic index to the wire:
@@ -713,28 +752,26 @@ This can be worked around by creating a wire and connecting the dynamic index to
 val x = WireInit(io.in(io.idx))
 ```
 
+```scala mdoc:invisible
+class Foo2 extends Module {
+  val io = IO(new Bundle {
+    val in = Input(Vec(4, Bool()))
+    val idx = Input(UInt(2.W))
+    val en = Input(Bool())
+    val out = Output(Bool())
+  })
+
+  val x = WireInit(io.in(io.idx))
+  val y = x && io.en
+  io.out := y
+}
+```
+
 Which produces:
-```verilog
-module Foo(
-  input        clock,
-  input        reset,
-  input        io_in_0,
-  input        io_in_1,
-  input        io_in_2,
-  input        io_in_3,
-  input  [1:0] io_idx,
-  input        io_en,
-  output       io_out
-);
-  wire  _GEN_1;
-  wire  _GEN_2;
-  wire  x;
-  assign _GEN_1 = 2'h1 == io_idx ? io_in_1 : io_in_0;
-  assign _GEN_2 = 2'h2 == io_idx ? io_in_2 : _GEN_1;
-  assign x = 2'h3 == io_idx ? io_in_3 : _GEN_2;
-  assign io_out = x & io_en; // @[main.scala 16:10]
-endmodule
+```scala mdoc:verilog
+getVerilogString(new Foo2)
 ```
+
 ### How can I dynamically set/parametrize the name of a module?
 
 You can override the `desiredName` function. This works with normal Chisel modules and `BlackBox`es. Example:
@@ -758,14 +795,9 @@ class Salt extends Module {
 ```
 
 Elaborating the Chisel module `Salt` yields our "desired names" for `Salt` and `Coffee` in the output Verilog:
-```scala mdoc:silent
-import chisel3.stage.ChiselStage
-
-ChiselStage.emitVerilog(new Salt)
-```
 
 ```scala mdoc:verilog
-ChiselStage.emitVerilog(new Salt)
+getVerilogString(new Salt)
 ```
 
 ## Directionality
@@ -775,7 +807,9 @@ ChiselStage.emitVerilog(new Salt)
 Given a bidirectional port like a `Decoupled`, you will get an error if you try to connect it directly
 to a register:
 
-```scala mdoc:silent
+```scala mdoc:silent:reset
+import chisel3._
+import chisel3.stage.ChiselStage
 import chisel3.util.Decoupled
 class BadRegConnect extends Module {
   val io = IO(new Bundle {
@@ -796,7 +830,9 @@ While there is no construct to "strip direction" in Chisel3, wrapping a type in
 set all of the individual elements to output direction.
 This will have the desired result when used to construct a Register:
 
-```scala mdoc:silent
+```scala mdoc:silent:reset
+import chisel3._
+import chisel3.stage.ChiselStage
 import chisel3.util.Decoupled
 class CoercedRegConnect extends Module {
   val io = IO(new Bundle {
-- 
cgit v1.2.3


From d997acb05e5a307afb7c9ad4c136b9b4e1506efc Mon Sep 17 00:00:00 2001
From: mergify[bot]
Date: Sun, 23 Oct 2022 19:01:43 +0000
Subject: Don't invalidate ExtModule ports in an explicitInvalidate = true
 context (backport #2795) (#2799)

* Don't invalidate ExtModule ports in an explicitInvalidate = true context (#2795)

* Don't invalidate ExtModule ports in an explicitInvalidate = true context

ExtModule ports were previously invalidated in the emitted FIRRTL, which is correct in a NonStrict / `Chisel._` compatibility context but not in newer chisel3 code where `explicitInvalidate = true`.

(cherry picked from commit 8e24a281545d25f6501dcc872eabdfb30bacd69d)

# Conflicts:
#	core/src/main/scala/chisel3/BlackBox.scala

* Resolve backport conflicts

Co-authored-by: Jared Barocsi <82000041+jared-barocsi@users.noreply.github.com>
Co-authored-by: Jack Koenig <koenig@sifive.com>---
 docs/src/cookbooks/cookbook.md | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'docs/src')

diff --git a/docs/src/cookbooks/cookbook.md b/docs/src/cookbooks/cookbook.md
index ac3a0c5d..e7485e66 100644
--- a/docs/src/cookbooks/cookbook.md
+++ b/docs/src/cookbooks/cookbook.md
@@ -791,6 +791,8 @@ class Salt extends Module {
     val io = IO(new Bundle {})
     val drink = Module(new Coffee)
     override def desiredName = "SodiumMonochloride"
+
+    drink.io.I := 42.U
 }
 ```
 
-- 
cgit v1.2.3


From 4149157df6531d124483d992daf96cf4e62a0f0c Mon Sep 17 00:00:00 2001
From: mergify[bot]
Date: Fri, 4 Nov 2022 18:20:07 +0000
Subject: Add PartialDataView.supertype (backport #2826) (#2827)

* Add PartialDataView.supertype (#2826)

This factory method makes it easy to create PartialDataViews from a
Bundle type to its supertype. Because of the typing relationship, there
is no need to provide a mapping between fields. The only thing necessary
is to provide a function for constructing an instance of the supertype
from an instance of the subtype.

(cherry picked from commit 251d454a224e5a961438ba0ea41134d7da7a5992)

# Conflicts:
#	core/src/main/scala/chisel3/experimental/dataview/package.scala
#	src/test/scala/chiselTests/experimental/DataView.scala

* Resolve backport conflicts

Co-authored-by: Jack Koenig <koenig@sifive.com>---
 docs/src/cookbooks/dataview.md | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

(limited to 'docs/src')

diff --git a/docs/src/cookbooks/dataview.md b/docs/src/cookbooks/dataview.md
index ed969ca1..f970cfe4 100644
--- a/docs/src/cookbooks/dataview.md
+++ b/docs/src/cookbooks/dataview.md
@@ -12,6 +12,7 @@ section: "chisel3"
 * [How do I connect a subset of Bundle fields?](#how-do-i-connect-a-subset-of-bundle-fields)
     * [How do I view a Bundle as a parent type (superclass)?](#how-do-i-view-a-bundle-as-a-parent-type-superclass)
     * [How do I view a Bundle as a parent type when the parent type is abstract (like a trait)?](#how-do-i-view-a-bundle-as-a-parent-type-when-the-parent-type-is-abstract-like-a-trait)
+    * [How can I use `.viewAs` instead of `.viewAsSupertype(type)`?](#how-can-i-use-viewas-instead-of-viewassupertypetype)
 
 ## How do I view a Data as a UInt or vice versa?
 
@@ -177,3 +178,37 @@ As indicated in the comment, abstract methods must still be implemented.
 This is the same that happens when one writes `new Bundle {}`,
 the curly braces create a new concrete subclass; however, because `Bundle` has no abstract methods,
 the contents of the body can be empty.
+
+### How can I use `.viewAs` instead of `.viewAsSupertype(type)`?
+
+While `viewAsSupertype` is helpful for one-off casts, the need to provide a type template object
+each time can be onerous.
+Because of the subtyping relationship, you can use `PartialDataView.supertype` to create a
+`DataView` from a Bundle type to a parent type by just providing the function to construct an
+instance of the parent type from an instance of the child type.
+The mapping of corresponding fields is automatically determined by Chisel to be the fields defined
+in the supertype.
+
+```scala mdoc:silent:reset
+import chisel3._
+import chisel3.experimental.dataview._
+
+class Foo(x: Int) extends Bundle {
+  val foo = UInt(x.W)
+}
+class Bar(val x: Int) extends Foo(x) {
+  val bar = UInt(x.W)
+}
+// Define a DataView without having to specify the mapping!
+implicit val view = PartialDataView.supertype[Bar, Foo](b => new Foo(b.x))
+
+class MyModule extends Module {
+  val foo = IO(Input(new Foo(8)))
+  val bar = IO(Output(new Bar(8)))
+  bar.viewAs[Foo] := foo // bar.foo := foo.foo
+  bar.bar := 123.U       // all fields need to be connected
+}
+```
+```scala mdoc:verilog
+chisel3.stage.ChiselStage.emitVerilog(new MyModule)
+```
-- 
cgit v1.2.3


From c51fcfea32b6c73e623657442460fb782ff0733b Mon Sep 17 00:00:00 2001
From: Aditya Naik
Date: Thu, 10 Nov 2022 13:41:00 -0800
Subject:  Warn on S-interpolator usage for assert, assume and printf (backport
 #2751) (#2757)

* Add internal methods to maintain binary compatibility

Co-authored-by: Megan Wachs <megan@sifive.com>
Co-authored-by: Jack Koenig <koenig@sifive.com>---
 docs/src/explanations/printing.md | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

(limited to 'docs/src')

diff --git a/docs/src/explanations/printing.md b/docs/src/explanations/printing.md
index 71a6f5cf..80e9ec70 100644
--- a/docs/src/explanations/printing.md
+++ b/docs/src/explanations/printing.md
@@ -13,11 +13,23 @@ Chisel provides the `printf` function for debugging purposes. It comes in two fl
 
 ### Scala-style
 
-Chisel also supports printf in a style similar to [Scala's String Interpolation](http://docs.scala-lang.org/overviews/core/string-interpolation.html). Chisel provides a custom string interpolator `cf` which follows C-style format specifiers (see section [C-style](#c-style) below). Here's a few examples of using the `cf` interpolator:
+Chisel also supports printf in a style similar to [Scala's String Interpolation](http://docs.scala-lang.org/overviews/core/string-interpolation.html). Chisel provides a custom string interpolator `cf` which follows C-style format specifiers (see section [C-style](#c-style) below).
+
+Note that the Scala s-interpolator is not supported in Chisel constructs and will issue a compile-time warning:
 
 ```scala mdoc:invisible
 import chisel3._
 ```
+
+```scala mdoc:warn
+class MyModule extends Module {
+  val in = IO(Input(UInt(8.W)))
+  printf(s"in = $in\n")
+}
+```
+
+Instead, use Chisel's `cf` interpolator as in the following examples:
+
 ```scala mdoc:compile-only
 val myUInt = 33.U
 printf(cf"myUInt = $myUInt") // myUInt = 33
-- 
cgit v1.2.3