Stream

Core stream definitions.

class sol_usb.gateware.stream.StreamInterface(payload_width=8, valid_width=1, extra_fields=None)

Simple record implementing a unidirectional data stream.

This class is similar to LiteX’s streams; but instances may be optimized for interaction with USB PHYs. Accordingly, some uses may add restrictions; this is typically indicated by subclassing this interface.

Variables:

  • valid (Signal(), from originator) – Indicates that the current payload bytes are valid pieces of the current transaction.

  • first (Signal(), from originator) – Indicates that the payload byte is the first byte of a new packet.

  • last (Signal(), from originator) – Indicates that the payload byte is the last byte of the current packet.

  • payload (Signal(payload_width), from originator) – The data payload to be transmitted.

  • ready (Signal(), from receiver) – Indicates that the receiver will accept the payload byte at the next active clock edge. Can be de-asserted to put backpressure on the transmitter.

Parameters:

  • payload_width (int) – The width of the stream’s payload, in bits.

  • extra_fields (list of tuples, optional) – A flat (non-nested) list of tuples indicating any extra fields present. Similar to a record’s layout field; but cannot be nested.

stream_eq(interface, *, omit=None)

A hopefully more clear version of.connect() that more clearly indicates data_flow direction.

This will either solve a common footgun or introduce a new one. We’ll see and adapt accordingly.

tap(interface, *, tap_ready=False, **kwargs)

Simple extension to stream_eq() that captures a read-only view of the stream.

This connects all signals from interface to their equivalents in this stream.

Arbiter

Stream multiplexers/arbiters.

class sol_usb.gateware.stream.arbiter.StreamMultiplexer(*args, src_loc_at: int = 0, **kwargs)

Gateware that merges a collection of StreamInterfaces into a single interface.

This variant performs no scheduling. Assumes that only one stream will be communicating at once.

Variables:

output (StreamInterface(), output stream) – Our output interface; has all of the active busses merged together.

add_input(input_interface)

Adds a transmit interface to the multiplexer.

class sol_usb.gateware.stream.arbiter.StreamArbiter(*args, src_loc_at: int = 0, **kwargs)

Gateware that merges a collection of StreamInterfaces into a single interface.

This variant uses a simple priority scheduler; and will use a standard valid/ready handshake to schedule a single stream to communicate at a time. Bursts of valid will never be interrupted, so streams will only be switched once the current transmitter drops valid low.

Variables:

  • source (StreamInterface(), output stream) – Our output interface; has all of the active busses merged together.

  • idle (Signal(), output) – Asserted when none of our streams is currently active.

Parameters:

  • stream_type (subclass of StreamInterface) – If provided, sets the type of stream we’ll be multiplexing (and thus our output type).

  • domain (str) – The name of the domain in which this arbiter should operate. Defaults to ‘ sync’ .

add_stream(stream)

Adds a stream to our arbiter.

Parameters:

stream (StreamInterface subclass) – The stream to be added. Streams added first will have higher priority.

Generator

Stream generators.

class sol_usb.gateware.stream.generator.ConstantStreamGenerator(*args, src_loc_at: int = 0, **kwargs)

Gateware that generates stream of constant data.

Variables:

  • start (Signal(), input) – Strobe that indicates when the stream should be started.

  • done (Signal(), output) – Strobe that pulses high when we’re finishing a transmission.

  • start_position (Signal(range(len(data)), input) – Specifies the starting position in the constant stream; applied when start() is pulsed.

  • max_length (Signal(max_length_width), input) – The maximum length to be sent -in bytes-. Defaults to the length of the stream. Only present if the max_length_width parameter is provided on creation.

  • output_length (Signal(max_length_width), output) – Indicates the actual data length for the stream currently being output. Will always be the lesser of our data length and :attr:max_length. Only present if the max_length_width parameter is provided on creation.

  • stream (stream_type(), output stream) – The generated stream interface.

Parameters:

  • constant_data (bytes, or equivalent) – The constant data for the stream to be generated. Should be an iterable of integers; or, if data_width is divisible by 8, a bytes-like object.

  • domain (string) – The clock domain this generator should belong to. Defaults to ‘sync’.

  • stream_type (StreamInterface, or subclass) – The type of stream we’ll be multiplexing.

  • data_width (int, optional) – The width of the constant payload. If not provided; will be taken from the stream’s payload width.

  • max_length_width (int) – If provided, a max_length signal will be present that can limit the total length transmitted.

  • data_endianness (little) – If bytes are provided, and our data width is greater

class sol_usb.gateware.stream.generator.StreamSerializer(*args, src_loc_at: int = 0, **kwargs)

Gateware that serializes a short Array input onto a stream.

I/O port:

I: start – Strobe that indicates when the stream should be started. O: done – Strobe that pulses high when we’re finishing a transmission.

I: data[] – The data stream to be sent out. Length is set by the data_length initializer argument. I: max_length[] – The maximum length to be sent. Defaults to the length of the stream.

Only present if the max_length_width parameter is provided on creation.

*: stream – The generated stream interface.