The sense and nonsense of different protocols

[lmbollen]

I'd like to have an open discussion regarding the protocols we'd like to have in this package. I think in the end it makes sense to allow all standardized, existing protocols commonly used in RTL. However, often these protocols have many many features that are useless for specific applications.

This results in high implementation complexity for generic components with our current record based approach.
In theory we could maybe encode supported features in the protocol datatypes, but this leads to incredibly bulky types that will probably do more harm than good.

Without such encoding we get components with datatypes that are overly complex to implement or make type based promises they don't deliver on.

Currently clash-protocols features one non-standardized protocol for simple data streaming and there are two more protocols in the pipeline (haha).

Existing non-standardized protocols

• Df

Proposed protocols

• PacketStream
• ReqResp
• BiDf

Df
Simplest possible streaming protocol, allows us to communicate streams of type a.
Rules:

• Once a master initiates a transaction, it must offer the same data until the slave acknowledges it.
• The backward channel may only be observed when the forward channel is sending data.

PacketStream
Simple protocol capable of communicating a packet over multiple transactions. Initial proposal for the type is:

-- | The packet stream protocol for communication between components
data PacketStream (dom :: Domain) (dataWidth :: Nat) (metaType :: Type)

-- | Data sent from manager to subordinate, a simplified AXI4-Stream like interface
-- with metadata that can only change on packet delineation.
-- _tdest, _tuser and _tid are bundled into one big _meta field which holds metadata.
-- There are no null or position bytes so _tstrb is replaced by a last indicator
-- that indicates the index of the last valid byte in the _data vector.
-- _tvalid is modeled via wrapping this in a `Maybe`.
data PacketStreamM2S (dataWidth :: Nat) (metaType :: Type)
  = PacketStreamM2S {
  _data :: Vec dataWidth (BitVector 8),
  -- ^ The bytes to be transmitted
  _last :: Maybe (Index dataWidth),
  -- ^ If Nothing, we are not yet at the last byte, otherwise index of last valid byte of _data
  _meta :: metaType,
  -- ^ the metadata of a packet. Must be constant during a packet.
  _abort :: Bool
  -- ^ If True, the current transfer is aborted and the subordinate should ignore the current transfer
} deriving (Generic, ShowX, Show, NFData, Bundle, Functor)

-- | Data sent from the subordinate to the manager
-- The only information transmitted is whether the subordinate is ready to receive data
newtype PacketStreamS2M = PacketStreamS2M {
  _ready :: Bool
  -- ^ Iff True, the subordinate is ready to receive data
} deriving (Generic, ShowX, Show, NFData, Bundle, Eq, NFDataX)

Rules:

• Once a master initiates a transaction, it must offer the same data until the slave acknowledges it.
• The backward channel may only be observed when the forward channel is sending data.
• The metadata must remain the same for the entire duration of the packet transfer.
• A sink that observes abort being asserted must propagate the abort (e.g. for scaling components) or drop the packet itself.
• A packet may not be interrupted by another packet.

ReqResp
The simplest request-response protocol possible. You offer a request and once the subordinate offered a response, a transaction has been completed. The idea is that this is as simple as Df, but for bidirectional transactions.

{- | For simple request-response protocols. The forward channel is used to send requests
and the backward channel is used to send responses.
Rules:
* When the forward channel is @Just a@, it must not change until the transaction
  is completed.
* The forward channel can not depend on the backward channel.
* When the forward channel is @Nothing@, the backward channel may not be observed.
-}
data ReqResp (dom :: C.Domain) (req :: Type) (resp :: Type)

instance Protocol (ReqResp dom req resp) where
  -- | Forward channel for ReqResp protocol:
  type Fwd (ReqResp dom req resp) = C.Signal dom (Maybe req)

  -- | Backward channel for ReqResp protocol:
  type Bwd (ReqResp dom req resp) = C.Signal dom (Maybe resp)

BiDf
A way to represent circuits that consume a Df request and produce a Df response.
It is very similar to ReqResp, but the extra handshaking mechanisms allow for pipelining.

From #109

-- | A 'Protocol' allowing requests to be passed downstream, with corresponding
-- responses being passed back upstream. Responses are provided in the order that
-- their corresponding requests were submitted.
--
-- *Correctness conditions*
--
--  - The response channel must not produce a value before the request channel
--    has produced a value.
--
--  - Each request must be paired with exactly one response.
--
--  - Responses must be issued in the order that their corresponding requests arrived.
--
--  - Both the request and response channels must obey usual 'Df' correctness
--    conditions.
--
--  - There must not be a combinational path from the request channel to the
--    response channel.
--
type BiDf dom req resp =
  (Df dom req, Reverse (Df dom resp))

I took a short look at some existing protocols for which I have the spec at hand and made a short table that summarizes some of the aspects:

Protocol	Support	Routing	Fwd payload	Bwd payload	Faults	Meta info	Partial transfer	Burst	Async ready / valid
Df	✔️		a	()	None
BiDf	✔️		req	resp	None			✔️	✔️
PacketStream	✔️	✔️	Multiple (Vec n a)	()	Error	✔️	✔️
ReqResp	✔️		req	resp	None
Axi4Stream	✔️	✔️	Multiple (Vec n a)	()	None	✔️	✔️
AHB Lite		✔️	BitVector n	BitVector m	Error		✔️	✔️
APB		✔️	BitVector n	BitVector m	Error
Avalon MM	✔️	✔️	BitVector n	BitVector m	Multiple		✔️		✔️
Avalon ST	✔️	✔️	Multiple (Vec n a)	()	Error		✔️
Wishbone C	✔️	✔️	BitVector n	BitVector m	Multiple		✔️
Wishbone P	✔️	✔️	BitVector n	BitVector m	Multiple		✔️	✔️	✔️

Legend:

Protocol	Explanation
Support	If there is any support in this package yet
Routing	Does the payload have a source of destination? (usually addressing or channels)
Fwd payload	Data from manager to subordinate. Multiple => Spans multiple transactions
Bwd payload	Data from subordinate to manager. Multiple => Spans multiple transactions
Faults	Error reporting features. None => No information, Error => Can detect faults, Multiple => Supports multiple response types
Meta info	Is there a side channel that can be used for extra information? e.g. for routing
Partial transfer	Transactions with only partially valid data, usually means it has byte enables.
Burst	Are there any bust mode features
Async ready / valid	Are there features where requests and response do not "handshake" in the same cycle? e.g. pipelining

^ If you spot a mistake or have questions, feel free to post a comment!

The question here is, what is the minimal set of features and protocols we can implement to cover most, if not all use cases?

[leonschoorl]

I'm a unsure about PacketStream:

Rules:

• Once a master initiates a transaction, it must offer the same data until the slave acknowledges it.
• The backward channel may only be observed when the forward channel is sending data.

newtype PacketStreamS2M = PacketStreamS2M {
  _ready :: Bool
  -- ^ Iff True, the subordinate is ready to receive data
}

The rules talk about acknowledges, which to me is it signalling back from the subordinate that what the manager sent was received, and the manager can now (attempt to) send something else.
But the PacketStreamS2M field name and comment talk about a ready signal, which to me is a signal from the subordinate to the manager that that it is ready to receive data, and something that the manager should check before sending data, not after like with the acknowledgements.

Also how does PacketStream handle validity? Or in other words how does the manager indicate there is nothing to send right now?
Does it just set _abort to True?
Or is there some extra layer around PacketStreamM2S?

[rowanG077]

The _ready nomenclature was taken from axi stream which I believe have the exact same semantics as Df Ack. Personally I think ready better captures how it actually works then ack. See for example the question on the Clash slack yesterday. Where the question arose whether what Df.registerFwd was doing was legal. It is sending out Ack True when it was not receiving an input. Something which I think is obviously allowed if you view it as a ready signal. But shouldn't be allowed if you view it as an ack signal.

The advantage of the ack nomenclature is that it does impose an ordering like you suggest but I don't think ready suggest an ordering at all.

Validity in PacketStream is handled by wrapping it in a Maybe.

[lmbollen]

@rowanG077 Just opened the initial PR for reference: #85

[DigitalBrains1]

I'm pretty sure Avalon ST has pipelining!