Stream¶

Important

This module has been deprecated and moved to the Torii standard library under torii.lib.stream.simple.

Core stream definitions.

class sol_usb.gateware.stream.StreamInterface(*, data_width: int = 8, valid_width: int | None = 1, name: str | None = None, extra: Iterable[tuple[str, int]] = [])¶

A simple interface representing a unidirectional stream.

Parameters:

data_width (int) – The width of the stream data in bits. (default: 8)
valid_width (int | None) – The width of the valid field. If None it will default to data_width // 8. (default: 1)
name (str | None) – The name of this stream. (default: None)
extra (Iterable[tuple[str, int]]) – Any extra or ancillary fields to graft on to the stream. (default: [])

Attributes:

data (Signal(data_width), send) – The data in the stream to be transmitted.
valid (Signal(valid_width), send) – This can be two things, by default, when valid_width is data_width // 8, it represents a set of bit flags for each byte in data determining if that byte of data is valid.

For example, with data_width of 16, valid_width will be 2, where valid[0] is the valid flag for data[0:8] and valid[1] is the valid flag for data[8:16].

When set to 1 it can simply mean that the whole of data is valid for this transaction. It can be as granular or corse as you wish, as long as both sides of the stream agree.
first (Signal, send) – Indicates that the data is the first of the current packet.
last (Signal, send) – Indicates that the data is the last of the current packet.
ready (Signal, recv) – Indicates that the receiver will accept the data at the next active clock edge.
payload (Signal(data_width), send (alias)) – This is a dynamic alias to the data member of the record.

attach(stream: StreamInterface, omit: set = {})¶

Attach to a target stream.

This method connects our valid, first, last, and data fields to the downstream facing stream, and their ready field to ours.

This establishes a connection to where we are the originating stream, and stream is the receiving stream.

self.data  -> stream.data
self.valid -> stream.valid
self.first -> stream.first
self.last  -> stream.last
self.ready <- stream.ready

Parameters:

stream (torii.lib.stream.StreamInterface) – The stream we are attaching to.
omit (set[str]) – A set of additional stream fields to exclude from the tap connection. (default: {})

connect(stream: StreamInterface, omit: set = {})¶

Connect to the target stream.

This method is an alias for StreamInterface.attach().

Parameters:

stream (torii.lib.stream.StreamInterface) – The stream we are attaching to.
omit (set[str]) – A set of additional stream fields to exclude from the tap connection. (default: {})

stream_eq(stream: StreamInterface, omit: set = {})¶

Receive from target stream.

This method connects the valid, first, last, and data from stream to ours, and our ready field to theirs.

This establishes a connection to where stream is the originating stream, and we are the receiving stream.

self.data  <- stream.data
self.valid <- stream.valid
self.first <- stream.first
self.last  <- stream.last
self.ready -> stream.ready

This function is effectively the inverse of attach(), in fact, it’s implementation is just:

stream.attach(self, ...)

It is provided as a more logical way to connect streams.

Parameters:

stream (torii.lib.stream.StreamInterface) – The stream to attach to this stream.
omit (set[str]) – A set of additional stream fields to exclude from the tap connection. (default: {})

tap(stream: StreamInterface, *, tap_ready: bool = False, omit: set = {})¶

Attach a StreamInterface in read-only unidirectional tap mode.

This joints all signals from stream to their matching signals in this stream.

self.data  -> stream.data
self.valid -> stream.valid
self.first -> stream.first
self.last  -> stream.last
self.ready -> stream.ready

Parameters:

stream (torii.lib.stream.StreamInterface) – The stream to use as the interface to this tap.
tap_ready (bool) – By default the ready signal is excluded from the tap, passing True here will also connect that signal. (default: False)
omit (set[str]) – A set of additional stream fields to exclude from the tap connection. (default: {})

Arbiter¶

Stream multiplexers/arbiters.

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

A simple multi-input-single-output stream arbiter.

This uses a very simple priority scheduler and relies on the standard valid/ready handshake that occurs between streams to schedule which stream is connected to the output stream.

Parameters:

domain (str) – The domain in which the arbiter should operate. (default: sync)
stream_type (type) – The type of stream to create, must be either StreamInterface or a subtype there of. (default: torii.lib.stream.StreamInterface)

Attributes:

out (stream_type, out) – The output stream.
idle (Signal, out) – Indicates the arbiter is idle, this occurs when the input source stream is not active.

connect(stream: T, priority: int = -1) → None¶

Connect an output stream to the arbiter.

Parameters:

stream (torii.lib.stream.StreamInterface) – The stream to connect to the arbiter.
priority (int) – The stream priority. (default: -1)

Generator¶

Stream generators.

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

Gateware that generates stream of constant data.

Attributes:

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 (str) – The clock domain this generator should belong to. (default: ‘sync’)
stream_type (StreamInterface, or subclass) – The type of stream we’ll be multiplexing.
data_width (int | None) – The width of the constant payload. If not provided; will be taken from the stream’s payload width. (default: None)
max_length_width (int | None) – If provided, a max_length signal will be present that can limit the total length transmitted. (default: None)
data_endianness ('little' | 'big') – If bytes are provided, and our data width is greater. (default: ‘little’)

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

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.