>`.
* The payload type is a tuple type.
- * `Opt` contains the real data we want to send through the wires.
+ * `Option
` contains the real data we want to send through the wires.
* `U<{ clog2(N) }>` is the index of the ingress interfaces represented in bits. `clog2(N)` is the bit-width for representing integer `N`.
* The payload will be sent to the FIFO queue.
* The element in the FIFO queue is a tuple containing the actual data and the index of the ingress interface that sends the data.
* The resolver is an array of `bool` of size `N`.
- * This resolver is send back from the FIFO queue.
+ * This resolver is sent back from the FIFO queue.
* It indicates which ingress interfaces are present in the current queue.
* If there are 4 ingress interfaces and the array is `[true, false, false, true]`, it indicates the ingress interface 1's and ingress interface 2's payloads are not currently in the queue.
The Masked Merge combinator will try to choose the ingress interface whose payload is not in the queue and send it to the FIFO queue in the next clock cycle.
-### FIFO Queue
-
-The FIFO Queue ingress interface:
-* The payload is a tuple containing the actual data we want to transfer and also the index of the ingress interface of the Masked Merge combinator that sends the data.
-* The resolver indicates which ingress interfaces are present in the current queue.
-
-The FIFO Queue egress interface is a simple valid-ready interface `Vr
`.
-
## Modular Design
@@ -55,7 +50,7 @@ The FIFO Queue egress interface is a simple valid-ready interface `Vr
`.
* `FifoS` indicates the current state of the FIFO queue.
* This combinator will leave the payload untouched and transfer it from ingress interface to egress interface.
-**`naked_fifo` combinator:**
+**`transparent_fifo` combinator:**
* This is a primitive combinator offered by the standard library.
* It takes one element from the ingress payload and stores it in the queue every clock cycle.
@@ -63,9 +58,15 @@ The FIFO Queue egress interface is a simple valid-ready interface `Vr
`.
* It pops out one element from the queue as the egress payload every clock cycle.
* The egress resolver is a simple ready signal.
+
+
**`map` combinator:**
-* It transforms the ingress payload `Opt` into `Opt` for filtering out the unnecessary index information.
+* It transforms the ingress payload `Option` into `Option` for filtering out the unnecessary index information.
## Implementation
@@ -82,7 +83,7 @@ The FIFO Queue egress interface is a simple valid-ready interface `Vr
`.
* The implementation of the `masked_merge()` combinator will be explained in the [Implementing Combinators](../advanced/combinator.md) section.
```rust,noplayground
-/// Masked Merge Combinator
+/// Example module using `masked_merge` combinator.
pub fn m(ingress: [Vr; 5]) -> Vr {
ingress
.masked_merge()
diff --git a/doc/docs/tutorial/tutorial.md b/doc/docs/tutorial/tutorial.md
index 91e6dd2..37554bd 100644
--- a/doc/docs/tutorial/tutorial.md
+++ b/doc/docs/tutorial/tutorial.md
@@ -2,11 +2,9 @@
We will introduce some basic concepts in the HazardFlow HDL programming model and use HazardFlow HDL to describe an [FIR (finite impulse response) filter](https://en.wikipedia.org/wiki/Finite_impulse_response) and a masked merge combinator.
-## Hazard Interface and Combinator
-
-HazardFlow HDL's implementation is based on two important concepts: [hazard interface](./interface.md) and [combinator](./module.md).
+HazardFlow HDL's implementation is based on the concept of [hazard interface](../lang/interface.md).
We will give a brief explanation here about the interface and combinator for you to understand how to use them to implement the FIR filter and fair multiplexer.
-For more details please refer to the [Language Reference](./reference.md) section.
+For more details please refer to the [Concepts](../lang/concepts.md) section.
### Hazard Interface
@@ -15,73 +13,139 @@ We model the hazard interface as a structure containing its forward signal, back
We define the hazard protocol as `H`, its payload and resolver as `H::P` and `H::R` respectively.
- 
+ 
-**Forward signal:**
-* The forward signal is the payload of the interface.
+```rust,noplayground
+// Hazard specification.
+trait Hazard {
+ type P: Copy;
+ type R: Copy;
+
+ fn ready(p: Self::P, r: Self::R) -> bool;
+}
+
+// Hazard interface.
+struct I;
+
+impl Interface for I {
+ type Fwd = Option,
+ type Bwd = H::R,
+}
+```
+
+**Forward signal:** the payload of the interface
* It is the data will be sent from the sender to the receiver.
* We define it as an `Opt` type. When it is `Some(p)`, the sender is sending a valid payload, else it is sending an invalid payload.
-**Backward signal:**
-* The backward signal is the resolver of the interface.
+**Backward signal:** the resolver of the interface
* It represents the hazard generated by the later stage from the circuits and it will be sent from the receiver to the sender.
* We define the resolver signal as `H::R`
-**Ready condition:**
-* Indicates whether the receiver is ready to receive the payload.
+**Ready condition:** the indicator whether the receiver is ready to receive the payload
* We define the ready condition as `fn ready(p: Self::P, r: Self::R) -> bool;` where the `p` is the payload and `r` is the resolver.
* When the forward signal is `Some(p)`, which means the forward signal is valid, **and** the ready condition returns `true`, which means the receiver is ready to receive the valid payload, then the transfer happens.
* When the forward signal is `None`, which means the forward signal is invalid, **or** the ready condition returns `false`, which means the receiver is not ready to receive the valid payload, then the transfer is not happening.
+
+
+### Module
+
+A module has a state of type `S` and ingress and egress hazard interface types, say `IH` and `EH`.
+
+Conceptually, the module's behavior can be represented as a function of the following signature:
+
+
+ 
+
+
+```rust,noplayground
+comb: impl Fn(Option, EH::R, S) -> (Option, IH::R, S)
+```
+
+It takes three input signals:
+
+- Ingress interface's forward signal (`Option`)
+- Egress interface's backward signal (`EH::R`)
+- Current state (`S`)
+
+and returns three output signals:
+
+- Egress interface's forward signal (`Option`)
+- Ingress interface's backward signal (`IH::R`)
+- Next state (`S`)
+
+Here, `Option` is `Some` is the payload is *valid*; otherwise it's `None`.
+
+
+
+
+
### Combinator
-Combinator is the idiomatic mechanism of chaining two interfaces together in HazardFlow HDL.
+Combinator is the idiomatic mechanism of attaching a module to an interface.
- 
+ 
-We define a combinator as a function `fsm` within each hazard interface in the HazardFlow HDL and it will be called each clock cycle.
-It will take the initial state of the combinator and an anonymous function as input return the new interface and chain these two interfaces together as shown in the above figure.
-The anonymous function specifies the logic of calculating the payload will be sent to the next combinator, the resolver will be sent to the previous combinator, and the next state of the current combinator.
+
+
+We define a combinator as a function `fsm` within each hazard interface in the HazardFlow HDL and it will be called each clock cycle:
+
+```rust,noplayground
+impl I {
+ fn fsm(
+ self,
+ init_state: S,
+ f: impl Fn(Option, EH::R, S) -> (Option, IH::R, S),
+ ) -> I {
+ ..
+ }
+}
+```
+
+
+
+
-We define the hazard type for the ingress interface as `H` and `EH` for the egress interface.
+It specifies the type of ingress, egress, and state.
-**Ingress payload:**
-* This is the forward signal of the ingress interface.
+- Ingress hazard interface type (`IH`)
+- Egress hazard interface type (`EH`)
+- State type (`S`)
+
+Also, it accepts two arguments for representing the module's behavior:
+
+- Initial state when reset happened (`init_state`)
+- Combinational logic of the module's behavior (`f`)
+
+
+
+
+
+HazardFlow HDL provide standard combinator library for developers to facilitate their work.
-HazardFlow HDL defines some primitive combinators and hazard interfaces for developers.
-The users can use these primitive combinators and hazard interfaces to construct their own combinational logic conveniently.
+For more details, please refer to the [Interface Combinators](../lang/combinators.md) section.