More Advanced Streams

[anuejn]

In IRC, we just discussed, that it would be cool to have more advanced streams (at least packetized ones with a last signal) upstream. Additionally, a collection of cores for common functionality would be nice.

This discussion could be a place to collect cores / types of streams that people in the community already built and find useful for their work.

[anuejn]

Over at naps we have a bunch of code that started as a video processing related project.

Stream Types

For this we gathered mostly 3 kinds of streams:

• plain streams with only payload
• PacketizedStream (has last and payload)
• ImageStream (has line_last, frame_last and payload)
• (Additionally we have a PacketizedFirstStream (with first and payload), but it is only used in one place. That one is not really necessary to have for us (but sometimes might be nice?)

Then we have some streams for AXI related code:

• AxiAddressStream with (payload, id, burst_type, burst_len, beat_size_bytes, protection_type)
• AxiDataStream with (payload, resp / byte_strobe, last, id)
• AxiWriteResponseStream with (resp, id)

These should maybe live in a dedicated AXI library somewhere else than upstream and motivate that there should be a good way to define custom stream types downstream.

Cores

Cores wise, we have (can all be found here but currently use our nonstandard streams and predate lib.wiring):

• CounterSource (nice for debugging stuff)
• FIFOs (BufferedSyncStreamFIFO, UnbufferedSyncStreamFIFO, BufferedAsyncStreamFIFO, UnbufferedAsyncStreamFIFO) that output exactly the kind of stream that they ingest
• StreamBuffer (basically a 1 deep FIFO; mostly used inside cores as an easy way to make their ports conform to the valid must not depend on ready rule. Or to improve timing)
• StreamGearbox (has n-bit input and m-bit output. Outputs not every cycle (n < m) / stalls the input(n > m))
• StreamMemoryReader (has an input stream for addresses and an output stream for data at these addresses)
• LastWrapper (wraps a core that has a plain stream (no last) input and output into a core that can handle last by basically shoving last into a FIFO and then recombining it with the output of the wrapped core. We use this to read image frames from a StreamMemoryReader by generating an ImageStream with the appropriate memory addresses).
• GenericMetadataWrapper (basically a generic version of LastWrapper that can be used with other kinds of streams - like ImageStream)
• StreamSplitter (Routes a single N-bit stream to multiple (M) outputs, which are each N/M bit wide.)
• StreamTee (Routes a single stream input to multiple outputs (like a tee shaped piece of pipe).
• StreamCombiner (Combines multiple streams into one wider stream)

These are the generic ones that I could imagine as helpful for many uses. We then have some more specialized ones (for example for AXI DMA) but these don't need any extra functionality from the Streams abstraction and probably should not go upstream.

Some of these cores require a mechanism to list what I would call "out-of-band signals" like last and handle them separately from the "real" payload. Functionality to do that would enable for example GenericMetadataWrapper to work with all kinds of streams (including plain ones). In other cases however it is tricky: StreamGearbox needs knowledge of the semantics of last to work with both packetized streams and non-packetized ones but could apply that then also to frame_last and line_last. StreamTee and its kin also could possibly be implemented in a generic way if we can agree on how to merge "out-of-band signals".

Cores that would be nice:

• "universal FIFO" ("you give it the depth and acceptable latency and clock domains and gearing ratio, it instantiates the right kind of FIFO inside" - @whitequark. We currently use a combination of FIFO and gearbox atm, but that's clearly suboptimal and having a "universal FIFO" would be very nice)

[whitequark]

AXI libraries should probably land in amaranth-soc.