From e14bcb145860207a825f780e3d0984e869f605c9 Mon Sep 17 00:00:00 2001
From: Jack Koenig
Date: Tue, 17 Aug 2021 14:24:20 -0700
Subject: [docs] Add example of stripping directions from type (#2074)

* [docs] Add example of stripping directions from type

* Apply suggestions from code review

Co-authored-by: Megan Wachs <megan@sifive.com>

* Improve := comment

Co-authored-by: Megan Wachs <megan@sifive.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>---
 docs/src/cookbooks/cookbook.md | 54 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

(limited to 'docs')

diff --git a/docs/src/cookbooks/cookbook.md b/docs/src/cookbooks/cookbook.md
index f033c285..cff7a5b2 100644
--- a/docs/src/cookbooks/cookbook.md
+++ b/docs/src/cookbooks/cookbook.md
@@ -27,6 +27,8 @@ Please note that these examples make use of [Chisel's scala-style printing](../e
   * [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)
   * [How can I dynamically set/parametrize the name of a module?](#how-can-i-dynamically-setparametrize-the-name-of-a-module)
+* Directionality
+  * [How do I strip directions from a bidirectional Bundle (or other Data)?](#how-do-i-strip-directions-from-a-bidirectional-bundle-or-other-data)
 
 ## Type Conversions
 
@@ -462,3 +464,55 @@ ChiselStage.emitVerilog(new Salt)
 ```scala mdoc:verilog
 ChiselStage.emitVerilog(new Salt)
 ```
+
+## Directionality
+
+### How do I strip directions from a bidirectional Bundle (or other Data)?
+
+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
+import chisel3.util.Decoupled
+class BadRegConnect extends Module {
+  val io = IO(new Bundle {
+    val enq = Decoupled(UInt(8.W))
+  })
+  
+  val monitor = Reg(chiselTypeOf(io.enq))
+  monitor := io.enq
+}
+```
+
+```scala mdoc:crash
+ChiselStage.emitVerilog(new BadRegConnect)
+```
+
+While there is no construct to "strip direction" in Chisel3, wrapping a type in `Output(...)`
+(the default direction in Chisel3) will
+set all of the individual elements to output direction.
+This will have the desired result when used to construct a Register:
+
+```scala mdoc:silent
+import chisel3.util.Decoupled
+class CoercedRegConnect extends Module {
+  val io = IO(new Bundle {
+    val enq = Flipped(Decoupled(UInt(8.W)))
+  })
+  
+  // Make a Reg which contains all of the bundle's signals, regardless of their directionality
+  val monitor = Reg(Output(chiselTypeOf(io.enq)))
+  // Even though io.enq is bidirectional, := will drive all fields of monitor with the fields of io.enq
+  monitor := io.enq
+}
+```
+
+<!-- Just make sure it actually works -->
+```scala mdoc:invisible
+ChiselStage.emitVerilog(new CoercedRegConnect {
+  // Provide default connections that would just muddy the example
+  io.enq.ready := true.B
+  // dontTouch so that it shows up in the Verilog
+  dontTouch(monitor)
+})
+```
-- 
cgit v1.2.3