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(*, domain: str = 'sync', stream_type: type[~torii.lib.stream.simple.T] = <class 'torii.lib.stream.simple.StreamInterface'>) → None

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)

class torii.lib.stream.simple.StreamInterface(*, data_width: int = 8, valid_width: int | None = 1, name: str | None = None, extra: Iterable[tuple[str, int]] = []) → None

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.

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: {})

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: {})

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: {})