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')

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