diff options
| -rw-r--r-- | docs/src/explanations/connection-operators.md | 364 | ||||
| -rw-r--r-- | docs/src/explanations/explanations.md | 3 | ||||
| -rw-r--r-- | docs/src/explanations/interfaces-and-connections.md | 81 | ||||
| -rw-r--r-- | docs/src/images/chisel_01.png | bin | 0 -> 91783 bytes |
4 files changed, 441 insertions, 7 deletions
diff --git a/docs/src/explanations/connection-operators.md b/docs/src/explanations/connection-operators.md new file mode 100644 index 00000000..8a2117e1 --- /dev/null +++ b/docs/src/explanations/connection-operators.md @@ -0,0 +1,364 @@ +--- + +layout: docs + +title: "Deep Dive into Connection Operators" + +section: "chisel3" + +--- + +# Deep Dive into Connection Operators + +Chisel contains two connection operators, `:=` and `<>`. This document provides a deeper explanation of the differences of the two and when to use one or the other. The differences are demonstrated with experiments using Scastie examples which use `DecoupledIO`. + + + +### Experiment Setup + +```scala mdoc +// Imports used by the following examples +import chisel3._ +import chisel3.stage.ChiselStage +import chisel3.util.DecoupledIO +``` + +The diagram for the experiment can be viewed [here](https://docs.google.com/document/d/14C918Hdahk2xOGSJJBT-ZVqAx99_hg3JQIq-vaaifQU/edit?usp=sharing). + + +```scala mdoc:silent + +class Wrapper extends Module{ + val io = IO(new Bundle { + val in = Flipped(DecoupledIO(UInt(8.W))) + val out = DecoupledIO(UInt(8.W)) + }) + val p = Module(new PipelineStage) + val c = Module(new PipelineStage) + // connect Producer to IO + p.io.a <> io.in + // connect producer to consumer + c.io.a <> p.io.b + // connect consumer to IO + io.out <> c.io.b +} +class PipelineStage extends Module{ + val io = IO(new Bundle{ + val a = Flipped(DecoupledIO(UInt(8.W))) + val b = DecoupledIO(UInt(8.W)) + }) + io.b <> io.a +} +``` +Below we can see the resulting Verilog for this example: +```scala mdoc +ChiselStage.emitVerilog(new Wrapper) +``` +## Concept 1: `<>` is Commutative + + + +This experiment is set up to test for the function of `<>` using the experiment above. + +Achieving this involves flipping the RHS and LHS of the `<>` operator and seeing how `<>` will react. +( Scastie link for the experiment:https://scastie.scala-lang.org/Shorla/LVhlbkFQQnq7X3trHfgZZQ ) + + + + +```scala mdoc:silent:reset +import chisel3._ +import chisel3.stage.ChiselStage +import chisel3.util.DecoupledIO + +class Wrapper extends Module{ + val io = IO(new Bundle { + val in = Flipped(DecoupledIO(UInt(8.W))) + val out = DecoupledIO(UInt(8.W)) + }) + val p = Module(new PipelineStage) + val c = Module(new PipelineStage) + // connect producer to I/O + io.in <> p.io.a + // connect producer to consumer + p.io.b <> c.io.a + // connect consumer to I/O + c.io.b <> io.out +} +class PipelineStage extends Module{ + val io = IO(new Bundle{ + val a = Flipped(DecoupledIO(UInt(8.W))) + val b = DecoupledIO(UInt(8.W)) + }) + io.a <> io.b +} +``` +Below we can see the resulting Verilog for this example: +```scala mdoc +ChiselStage.emitVerilog(new Wrapper) +``` +### Conclusion: +The Verilog remained the same without incurring errors, showing that the `<>` operator is commutative. + + + + +## Concept 2: `:=` means assign ALL LHS signals from the RHS, regardless of the direction on the LHS. +Using the same experiment code as above, we set to test for the function of `:=` +We replace all instances of `<>` with `:=` in the sample code above. +(Scastie link to the experiment: https://scastie.scala-lang.org/Shorla/o1ShdaY3RWKf0IIFwwQ1UQ/1) + +```scala mdoc:silent:reset +import chisel3._ +import chisel3.stage.ChiselStage +import chisel3.util.DecoupledIO + +class Wrapper extends Module{ + val io = IO(new Bundle { + val in = Flipped(DecoupledIO(UInt(8.W))) + val out = DecoupledIO(UInt(8.W)) + }) + val p = Module(new PipelineStage) + val c = Module(new PipelineStage) + // connect producer to I/O + p.io.a := io.in + // connect producer to consumer + c.io.a := p.io.b + // connect consumer to I/O + io.out := c.io.b +} +class PipelineStage extends Module{ + val io = IO(new Bundle{ + val a = Flipped(DecoupledIO(UInt(8.W))) + val b = DecoupledIO(UInt(8.W)) + }) + io.a := io.b +} +``` +Below we can see the resulting error message for this example: +```scala mdoc:crash +ChiselStage.emitVerilog(new Wrapper) +``` +### Conclusion: +The := operator goes field-by-field on the LHS and attempts to connect it to the same-named signal from the RHS. If something on the LHS is actually an Input, or the corresponding signal on the RHS is an Output, you will get an error as shown above. + +## Concept 3: Always Use `:=` to assign DontCare to Wires +When assigning `DontCare` to something that is not directioned, should you use `:=` or `<>`? +We will find out using the sample codes below: +( Scastie link for the experiment:https://scastie.scala-lang.org/Shorla/ZIGsWcylRqKJhZCkKWlSIA/1) + +```scala mdoc:silent:reset +import chisel3._ +import chisel3.stage.ChiselStage +import chisel3.util.DecoupledIO + +class Wrapper extends Module{ + val io = IO(new Bundle { + val in = Flipped(DecoupledIO(UInt(8.W))) + val out = DecoupledIO(UInt(8.W)) + }) + val p = Module(new PipelineStage) + val c = Module(new PipelineStage) + //connect Producer to IO + io.in := DontCare + p.io.a <> DontCare + val tmp = Wire(Flipped(DecoupledIO(UInt(8.W)))) + tmp := DontCare + p.io.a <> io.in + // connect producer to consumer + c.io.a <> p.io.b + //connect consumer to IO + io.out <> c.io.b +} +class PipelineStage extends Module{ + val io = IO(new Bundle{ + val a = Flipped(DecoupledIO(UInt(8.W))) + val b = DecoupledIO(UInt(8.W)) + }) + io.b <> io.a +} +``` +Below we can see the resulting Verilog for this example: +```scala mdoc +ChiselStage.emitVerilog(new Wrapper) +``` +### Conclusion: +If `<>` were used to assign the unidrectioned wire `tmp` to DontCare, we would get an error. But in the example above, we used `:=` and no errors occurred. +But when `:=` was used to assign the wire to DontCare, no errors will occur. + +Thus, when assigning `DontCare` to a `Wire`, always use `:=`. + + +## Concept 4: You can use `<>` or `:=` to assign `DontCare` to directioned things (IOs) +When assigning `DontCare` to something that is directioned, should you use `:=` or `<>`? +We will find out using the sample codes below: +( Scastie link for the experiment:https://scastie.scala-lang.org/Shorla/ZIGsWcylRqKJhZCkKWlSIA/1) + +```scala mdoc:silent:reset +import chisel3._ +import chisel3.stage.ChiselStage +import chisel3.util.DecoupledIO + +class Wrapper extends Module{ + val io = IO(new Bundle { + val in = Flipped(DecoupledIO(UInt(8.W))) + val out = DecoupledIO(UInt(8.W)) + }) + val p = Module(new PipelineStage) + val c = Module(new PipelineStage) + //connect Producer to IO + io.in := DontCare + p.io.a <> DontCare + val tmp = Wire(Flipped(DecoupledIO(UInt(8.W)))) + tmp := DontCare + p.io.a <> io.in + // connect producer to consumer + c.io.a <> p.io.b + //connect consumer to IO + io.out <> c.io.b +} +class PipelineStage extends Module{ + val io = IO(new Bundle{ + val a = Flipped(DecoupledIO(UInt(8.W))) + val b = DecoupledIO(UInt(8.W)) + }) + io.b <> io.a +} +``` +Below we can see the resulting Verilog for this example: +```scala mdoc +ChiselStage.emitVerilog(new Wrapper) +``` +### Conclusion: +Both `<>` and `:=` can be used to assign directioned things (IOs) to DontCare as shown in `io.in` and `p.io.a` respectively. This is basically equivalent because in this case both `<>` and `:=` will determine the direction from the LHS. + + +## Concept 5: `<>` works between things with at least one known flow (An IO or child's IO). + +If there is at least one known flow what will `<>` do? This will be shown using the experiment code below: +( Scastie link for the experiment:https://scastie.scala-lang.org/Shorla/gKx9ReLVTTqDTk9vmw5ozg) + +```scala mdoc:silent:reset +import chisel3._ +import chisel3.stage.ChiselStage +import chisel3.util.DecoupledIO + +class Wrapper extends Module{ + val io = IO(new Bundle { + val in = Flipped(DecoupledIO(UInt(8.W))) + val out = DecoupledIO(UInt(8.W)) + }) + val p = Module(new PipelineStage) + val c = Module(new PipelineStage) + //connect Producer to IO + // For this experiment, we add a temporary wire and see if it works... + //p.io.a <> io.in + val tmp = Wire(DecoupledIO(UInt(8.W))) + // connect intermediate wire + tmp <> io.in + p.io.a <> tmp + // connect producer to consumer + c.io.a <> p.io.b + //connect consumer to IO + io.out <> c.io.b +} +class PipelineStage extends Module{ + val io = IO(new Bundle{ + val a = Flipped(DecoupledIO(UInt(8.W))) + val b = DecoupledIO(UInt(8.W)) + }) + io.b <> io.a +} +``` +Below we can see the resulting Verilog for this example: +```scala mdoc +ChiselStage.emitVerilog(new Wrapper) +``` +### Conclusion: +The connection above went smoothly with no errors, this goes to show `<>` will work as long as there is at least one directioned thing (IO or submodule's IO) to "fix" the direction. + + +## Concept 6: `<>` and `:=` connect signals by field name. +This experiment creates a MockDecoupledIO which has the same fields by name as a DecoupledIO. Chisel lets us connect it and produces the same verilog, even though MockDecoupledIO and DecoupledIO are different types. +( Scastie link for the experiment:https://scastie.scala-lang.org/Uf4tQquvQYigZAW705NFIQ) + +```scala mdoc:silent:reset +import chisel3._ +import chisel3.stage.ChiselStage +import chisel3.util.DecoupledIO + +class MockDecoupledIO extends Bundle { + val valid = Output(Bool()) + val ready = Input(Bool()) + val bits = Output(UInt(8.W)) +} +class Wrapper extends Module{ + val io = IO(new Bundle { + val in = Flipped(new MockDecoupledIO()) + val out = new MockDecoupledIO() + }) + val p = Module(new PipelineStage) + val c = Module(new PipelineStage) + // connect producer to I/O + p.io.a <> io.in + // connect producer to consumer + c.io.a <> p.io.b + // connect consumer to I/O + io.out <> c.io.b +} +class PipelineStage extends Module{ + val io = IO(new Bundle{ + val a = Flipped(DecoupledIO(UInt(8.W))) + val b = DecoupledIO(UInt(8.W)) + }) + io.a <> io.b +} +``` +Below we can see the resulting Verilog for this example: +```scala mdoc +ChiselStage.emitVerilog(new Wrapper) +``` +And here is another experiment, where we remove one of the fields of MockDecoupledIO: +( Scastie link for the experiment:https://scastie.scala-lang.org/ChtkhKCpS9CvJkjjqpdeIA) + +```scala mdoc:silent:reset +import chisel3._ +import chisel3.stage.ChiselStage +import chisel3.util.DecoupledIO + +class MockDecoupledIO extends Bundle { + val valid = Output(Bool()) + val ready = Input(Bool()) + //val bits = Output(UInt(8.W)) +} +class Wrapper extends Module{ + val io = IO(new Bundle { + val in = Flipped(new MockDecoupledIO()) + val out = new MockDecoupledIO() + }) + val p = Module(new PipelineStage) + val c = Module(new PipelineStage) + // connect producer to I/O + p.io.a <> io.in + // connect producer to consumer + c.io.a <> p.io.b + // connect consumer to I/O + io.out <> c.io.b +} +class PipelineStage extends Module{ + val io = IO(new Bundle{ + val a = Flipped(DecoupledIO(UInt(8.W))) + val b = DecoupledIO(UInt(8.W)) + }) + io.a <> io.b +} +``` +Below we can see the resulting error for this example: +```scala mdoc:crash +ChiselStage.emitVerilog(new Wrapper) +``` +This one fails because there is a field `bits` missing. + +### Conclusion: +For `:=`, the Scala types do not need to match but all the signals on the LHS must be provided by the RHS or you will get a Chisel elaboration error. There may be additional signals on the RHS, these will be ignored. For `<>`, the Scala types do not need to match, but all signals must match exactly between LHS and RHS. In both cases, the order of the fields does not matter. + diff --git a/docs/src/explanations/explanations.md b/docs/src/explanations/explanations.md index 595bb48c..9e0227d5 100644 --- a/docs/src/explanations/explanations.md +++ b/docs/src/explanations/explanations.md @@ -28,7 +28,7 @@ read these documents in the following order: * [Memories](memories) * [Interfaces and Connections](interfaces-and-connections) * [Black Boxes](blackboxes) -* [Enumerations](enumerations) +* [Enumerations](chisel-enum) * [Functional Module Creation](functional-module-creation) * [Muxes and Input Selection](muxes-and-input-selection) * [Multiple Clock Domains](multi-clock) @@ -38,3 +38,4 @@ read these documents in the following order: * [Naming](naming) * [Unconnected Wires](unconnected-wires) * [Annotations](annotations) +* [Deep Dive into Connection Operators](connection-operators) diff --git a/docs/src/explanations/interfaces-and-connections.md b/docs/src/explanations/interfaces-and-connections.md index 9f48b642..0fb8bae8 100644 --- a/docs/src/explanations/interfaces-and-connections.md +++ b/docs/src/explanations/interfaces-and-connections.md @@ -4,7 +4,7 @@ title: "Interfaces and Connections" section: "chisel3" --- -# Interfaces & Bulk Connections +# Interfaces & Connections For more sophisticated modules it is often useful to define and instantiate interface classes while defining the IO for a module. First and foremost, interface classes promote reuse allowing users to capture once and for all common interfaces in a useful form. @@ -18,6 +18,7 @@ As we saw earlier, users can define their own interfaces by defining a class tha ```scala mdoc:invisible import chisel3._ +import chisel3.stage.ChiselStage ``` ```scala mdoc:silent @@ -67,8 +68,34 @@ class CrossbarIo(n: Int) extends Bundle { where Vec takes a size as the first argument and a block returning a port as the second argument. ## Bulk Connections +Once we have a defined Interface, we can connect to it via a [`MonoConnect`](https://www.chisel-lang.org/api/latest/chisel3/Data.html#:=) operator (`:=`) or [`BiConnect`](https://www.chisel-lang.org/api/latest/chisel3/Data.html#%3C%3E) operator (`<>`). -We can now compose two filters into a filter block as follows: +### `MonoConnect` Algorithm +`MonoConnect.connect`, or `:=`, executes a mono-directional connection element-wise. + +Note that this isn't commutative. There is an explicit source and sink +already determined before this function is called. + +The connect operation will recurse down the left Data (with the right Data). +An exception will be thrown if a movement through the left cannot be matched +in the right. The right side is allowed to have extra fields. +Vecs must still be exactly the same size. + +Note that the LHS element must be writable so, one of these must hold: +- Is an internal writable node (`Reg` or `Wire`) +- Is an output of the current module +- Is an input of a submodule of the current module + +Note that the RHS element must be readable so, one of these must hold: +- Is an internal readable node (`Reg`, `Wire`, `Op`) +- Is a literal +- Is a port of the current module or submodule of the current module + + +### `BiConnect` Algorithm +`BiConnect.connect`, or `<>`, executes a bidirectional connection element-wise. Note that the arguments are left and right (not source and sink) so the intent is for the operation to be commutative. The connect operation will recurse down the left `Data` (with the right `Data`). An exception will be thrown if a movement through the left cannot be matched in the right, or if the right side has extra fields. + +Using the biconnect `<>` operator, we can now compose two filters into a filter block as follows: ```scala mdoc:silent class Block extends Module { val io = IO(new FilterIO) @@ -79,11 +106,53 @@ class Block extends Module { f2.io.y <> io.y } ``` -where <> bulk connects interfaces of opposite gender between sibling modules or interfaces of the same gender between parent/child modules. -Bulk connections connect leaf ports of the same name to each other. If the names do not match or are missing, Chisel does not generate a connection. +The bidirectional bulk connection operator `<>` connects leaf ports of the same name to each other. The Scala types of the Bundles are not required to match. If one named signal is missing from either side, Chisel will give an error such as in the following example: + +```scala mdoc:silent + +class NotReallyAFilterIO extends Bundle { + val x = Flipped(new PLink) + val y = new PLink + val z = Output(new Bool()) +} +class Block2 extends Module { + val io1 = IO(new FilterIO) + val io2 = IO(Flipped(new NotReallyAFilterIO)) + + io1 <> io2 +} +``` +Below we can see the resulting error for this example: +```scala mdoc:crash +ChiselStage.emitVerilog(new Block2) +``` +Bidirectional connections should only be used with **directioned elements** (like IOs), e.g. connecting two wires isn't supported since Chisel can't necessarily figure out the directions automatically. +For example, putting two temporary wires and connecting them here will not work, even though the directions could be known from the endpoints: + +```scala mdoc:silent + +class BlockWithTemporaryWires extends Module { + val io = IO(new FilterIO) + val f1 = Module(new Filter) + val f2 = Module(new Filter) + f1.io.x <> io.x + val tmp1 = Wire(new FilterIO) + val tmp2 = Wire(new FilterIO) + f1.io.y <> tmp1 + tmp1 <> tmp2 + tmp2 <> f2.io.x + f2.io.y <> io.y +} + +``` +Below we can see the resulting error for this example: +```scala mdoc:crash +ChiselStage.emitVerilog(new BlockWithTemporaryWires) +``` +For more details and information, see [Deep Dive into Connection Operators](connection-operators.md) -Caution: bulk connections should only be used with **directioned elements** (like IOs), and is not magical (e.g. connecting two wires isn't supported since Chisel can't necessarily figure out the directions automatically [chisel3#603](https://github.com/freechipsproject/chisel3/issues/603)). +NOTE: When using `Chisel._` (compatibility mode) instead of `chisel3._`, the `:=` operator works in a bidirectional fashion similar to `<>`, but not exactly the same. ## The standard ready-valid interface (ReadyValidIO / Decoupled) @@ -144,6 +213,6 @@ class ConsumingData extends Module { That means `ready` and `valid` can also be deasserted without a data transfer. `IrrevocableIO` is a ready-valid interface with the *convention* that the value of `bits` will not change while `valid` is asserted and `ready` is deasserted. -Also the consumer shall keep `ready` asserted after a cycle where `ready` was high and `valid` was low. +Also, the consumer shall keep `ready` asserted after a cycle where `ready` was high and `valid` was low. Note that the *irrevocable* constraint *is only a convention* and cannot be enforced by the interface. Chisel does not automatically generate checkers or assertions to enforce the *irrevocable* convention. diff --git a/docs/src/images/chisel_01.png b/docs/src/images/chisel_01.png Binary files differnew file mode 100644 index 00000000..8fb1c8bf --- /dev/null +++ b/docs/src/images/chisel_01.png |
