Simple Streams¶
The torii.lib.streams.simple
module provides a simple and extensible unidirectional stream
interface StreamInterface
as well as an Arbiter
to join multiple
streams into a single output stream.
- class torii.lib.stream.simple.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:
- 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.
- class torii.lib.stream.simple.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 todata_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
isdata_width // 8
, it represents a set of bit flags for each byte indata
determining if that byte ofdata
is valid.For example, with
data_width
of16
,valid_width
will be2
, wherevalid[0]
is the valid flag fordata[0:8]
andvalid[1]
is the valid flag fordata[8:16]
.When set to
1
it can simply mean that the whole ofdata
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.
- connect(stream: StreamInterface, omit: set = {})¶
Connect to the target stream.
This method is an alias for
StreamInterface.attach()
.
- attach(stream: StreamInterface, omit: set = {})¶
Attach to a target stream.
This method connects our
valid
,first
,last
, anddata
fields to the downstream facingstream
, and theirready
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
- stream_eq(stream: StreamInterface, omit: set = {})¶
Receive from target stream.
This method connects the
valid
,first
,last
, anddata
fromstream
to ours, and ourready
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.
- 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, passingTrue
here will also connect that signal. (default: False)omit (set[str]) – A set of additional stream fields to exclude from the tap connection. (default: {})