Add PacketStream protocol.

[rowanG077]

Todos:

• Test haddock and make nicer
• Copy over tests
• Make top-level PacketStream module that exports all sub-modules
• Top-level module should hide inner modules
• Add forceResetSanity to async fifo
• Remove code duplication in the tests

[bgamari]

The motivation here is a bit unclear to me. The documentation says

Provides the PacketStream protocol, a simple streaming protocol for transferring packets of data between components

However the "data" in question appears to be only bytes. Presumably there is a specific use-case in mind here but it is not clear to me what it is; network packets, perhaps?

It seems to me like ideally protocols in clash-protocols should be polymorphic in the type of the data that they transfer. Afterall, I wouldn't expect packets of bytes to be terribly prevalent in the "interior" of most designs. Unless you are building actual networking hardware, I would imagine you would typically want to parse the packet into a more structured form somewhere near the "edge" of the design.

[t-wallet]

The motivation here is a bit unclear to me. The documentation says

Provides the PacketStream protocol, a simple streaming protocol for transferring packets of data between components

However the "data" in question appears to be only bytes. Presumably there is a specific use-case in mind here but it is not clear to me what it is; network packets, perhaps?

It seems to me like ideally protocols in clash-protocols should be polymorphic in the type of the data that they transfer. Afterall, I wouldn't expect packets of bytes to be terribly prevalent in the "interior" of most designs. Unless you are building actual networking hardware, I would imagine you would typically want to parse the packet into a more structured form somewhere near the "edge" of the design.

This protocol was indeed specifically created for a hardware-based MAC/IP/UDP stack (which will soon be coming to clash-cores). However, it is just a simpler version of AXI Stream with stricter metadata invariants. You can use it for any other purpose that needs high-speed data streaming, like video streaming. This PR also provides several circuits which are able to read these unstructured bytes into arbitrary types.

[rowanG077]

@bgamari It was discussed with @lmbollen whether to make the payload polymorphic. In theory there isn't anything that currently really looks at the payload so it would not be super hard to do add a type variable for the payload.

But in my experience working with packetized streams there usually is not a sane way to have an interior type. You are almost certainly only dealing with fragments, these will generally not have a clear structure at the scope of a single cycle. The structure comes from the fragments together.

Do you have some concrete idea how you see a packet stream packet with a non-byte oriented payload? I'm not against the idea but just don't see the advantage.

[martijnbastiaan]

But in my experience working with packetized streams there usually is not a sane way to have an interior type.

This is my experience too. In particular, any protocol that has byte enables (including the interface of block RAMs) are a pain to deal with if they're not having bits/bytes/bitvector as an interior type.

Still, ADTs are the killer feature of Clash IMO, so perhaps we should also offer API compatible versions without byte enables.