Subversion Repositories neorv32

<<<
:sectnums:
==== Stream Link Interface (SLINK)

[cols="<3,<3,<4"]
[frame="topbot",grid="none"]
|=======================
| Hardware source file(s): | neorv32_slink.vhd |
| Software driver file(s): | neorv32_slink.c |
|                          | neorv32_slink.h |
| Top entity port:         | `slink_tx_dat_o` | TX link data (8x32-bit)
|                          | `slink_tx_val_o` | TX link data valid (8-bit)
|                          | `slink_tx_rdy_i` | TX link allowed to send (8-bit)
|                          | `slink_rx_dat_i` | RX link data (8x32-bit)
|                          | `slink_rx_val_i` | RX link data valid (8-bit)
|                          | `slink_rx_rdy_o` | RX link ready to receive (8-bit)
| Configuration generics:  | _SLINK_NUM_TX_  | Number of TX links to implement (0..8)
|                          | _SLINK_NUM_RX_  | Number of RX links to implement (0..8)
|                          | _SLINK_TX_FIFO_ | FIFO depth (1..32k) of TX links, has to be a power of two
|                          | _SLINK_RX_FIFO_ | FIFO depth (1..32k) of RX links, has to be a power of two
| CPU interrupts:          | fast IRQ channel 10 | RX data available (see <<_processor_interrupts>>)
|                          | fast IRQ channel 11 | TX data send (see <<_processor_interrupts>>)
|=======================

The SLINK component provides up to 8 independent RX (receiving) and TX (sending) links for transmitting
stream data. The interface provides higher bandwidth (and less latency) than the external memory bus
interface, which makes it ideally suited to couple custom stream processing units (like CORDIC, FFTs or
cryptographic accelerators).

Each individual link provides an internal FIFO for data buffering. The FIFO depth is globally defined
for all TX links via the _SLINK_TX_FIFO_ generic and for all RX links via the _SLINK_RX_FIFO_ generic.
The FIFO depth has to be at least 1, which will implement a simple input/output register. The maximum
value is limited to 32768 entries. Note that the FIFO depth has to be a power of two (for optimal
logic mapping).

The actual number of implemented RX/TX links is configured by the _SLINK_NUM_RX_ and _SLINK_NUM_TX_
generics. The SLINK module will be synthesized only if at least one of these generics is greater than
zero. All unimplemented links are internally terminated and their according output signals are pulled
to low level.

[NOTE]
The SLINK interface does not provide any additional tag signals (for example to define a "stream destination
address" or to indicate the last data word of a "package"). Use a custom controller connected
via the external memory bus interface or the processor's GPIO ports to implement custom data tags.

**Theory of Operation**

The SLINK is activated by setting the control register's (_SLINK_CT_) enable bit _SLINK_CT_EN_. 
The actual data links are accessed by reading or writing the according link data registers _SLINK_CH0_
to _SLINK_CH7_. For example, writing the _SLINK_CH0_ will put the according data into the FIFO of TX link 0.
Accordingly, reading from _SLINK_CH0_ will return one data word from the FIFO of RX link 0.

The FIFO status of each RX and TX link is available via read-only bits in the device's control register.
Bits _SLINK_CT_TX0_FREE_ to _SLINK_CT_TX7_FREE_ indicate if the FIFO of the according TX link can take another
data word. Bits _SLINK_CT_RX0_AVAIL_ to _SLINK_CT_RX7_AVAIL_ indicate if the FIFO of the according RX link
contains another data word.

The _SLINK_CT_TX_FIFO_Sx_ and _SLINK_CT_RX_FIFO_Sx_ bits allow software to determine the total TX & RX FIFO sizes.
The _SLINK_CT_TX_NUMx_ and _SLINK_CT_RX_NUMx_ bits represent the absolute number of implemented TX and RX links
with an offset of "-1" (`0b000` = 1 link implemented, ..., `0b111` = 8 links implemented.

**Blocking Link Access**

When directly accessing the link data registers (without checking the according FIFO status flags) the access
might be executed as _blocking_. That means the CPU access will stall until the accessed link responds. For
example, when reading RX link 0 (via _SLINK_CH0_ register) the CPU access will stall, if there is not data
available in the according FIFO. The CPU access will complete as soon as RX link0 receives new data.

Vice versa, writing data to TX link 0 (via _SLINK_CH0_ register) might stall the CPU access until there is
at least one free entry in the link's FIFO.

[WARNING]
The NEORV32 processor ensures that _any_ CPU access to memory-mapped devices (including the SLINK module)
will **time out** after a certain number of cycles (see section <<_bus_interface>>).
Hence, blocking access to a stream link that does not complete within a certain amount of cycles will
raise a _store bus access exception_ when writing a TX link or a _load bus access exception_ when reading
an RX link.

**Non-Blocking Link Access**

For a non-blocking link access concept, the FIFO status signal in _SLINK_CT_ needs to be checked before
reading/writing the actual link data register. For example, a non-blocking write access to a TX link 0 has
to check _SLINK_CT_TX0_FREE_ first. If the bit is set, the FIFO of TX link 0 can take another data word
and the actual data can be written to _SLINK_CH0_. If the bit is cleared, the link's FIFO is full
and the status flag can be polled until it indicates free space in the FIFO.

This concept will not raise any exception as there is no "direct" access to the link data registers.
However, non-blocking accesses require additional instruction to check the according status flags prior
to the actual link access, which will reduce performance for high-bandwidth data stream.

**Interrupts**

The stream interface provides two interrupts that are _globally_ driven by the RX and TX link's
FIFO level status. If the FIFO of **any** TX link _was full_ and _becomes empty_ again, the TX interrupt fires.
Accordingly, if the FIFO of **any** RX link _was empty_ and a _new data word_ appears in it, the RX interrupt fires.

Note that these interrupts can only fire if the SLINK module is actually enabled by setting the
_SLINK_CT_EN_ bit in the unit's control register.

**Stream Link Interface & Protocol**

The SLINK interface consists of three signals `dat`, `val` and `rdy` for each RX and TX link.
Each signal is an "array" with eight entires (one for each link). Note that an entry in `slink_*x_dat` is 32-bit
wide while entries in `slink_*x_val` and `slink_*x_rdy` are are just 1-bit wide.

The stream link protocol is based on a simple FIFO-like interface between a source (sender) and a sink (receiver).
Each link provides two signals for implementing a simple FIFO-style handshake. The `slink_*x_val` signal is set
if the according `slink_*x_dat` contains valid data. The stream source has to ensure that both signals remain
stable until the according `slink_*x_rdy` signal is set. This signal is set by the stream source to indicate it
can accept another data word.

In summary, a data word is transferred if both `slink_*x_val` and `slink_*x_rdy` are high.

.Exemplary stream link transfer
image::stream_link_interface.png[width=560,align=center]

[TIP]
The SLINK handshake protocol is compatible to the AXI4-Stream base protocol.

.SLINK register map
[cols="^4,<5,^2,^2,<14"]
[options="header",grid="all"]
|=======================
| Address | Name [C] | Bit(s) | R/W | Function
.8+<| `0xfffffec0` .8+<| _SLINK_CT_ <| `31` _SLINK_CT_EN_ ^| r/w | SLINK global enable
                                    <| `30` _reserved_    ^| r/- <| reserved, read as zero
                                    <| `29:26` _SLINK_CT_TX_FIFO_S3_ : _SLINK_CT_TX_FIFO_S0_ ^| r/- <| TX links FIFO depth, log2 of_SLINK_TX_FIFO_ generic
                                    <| `25:22` _SLINK_CT_RX_FIFO_S3_ : _SLINK_CT_RX_FIFO_S0_ ^| r/- <| RX links FIFO depth, log2 of_SLINK_RX_FIFO_ generic
                                    <| `21:19` _SLINK_CT_TX_NUM2_ : _SLINK_CT_TX_NUM0_    ^| r/- <| Number of implemented TX links minus 1
                                    <| `18:16` _SLINK_CT_RX_NUM2_ : _SLINK_CT_RX_NUM0_    ^| r/- <| Number of implemented RX links minus 1
                                    <| `15:8` _SLINK_CT_TX7_FREE_ : _SLINK_CT_TX0_FREE_   ^| r/- <| At least one free TX FIFO entry available for link 0..7
                                    <| `7:0`  _SLINK_CT_RX7_AVAIL_ : _SLINK_CT_RX0_AVAIL_ ^| r/- <| At least one data word in RX FIFO available for link 0..7
| `0xfffffec4` : `0xfffffedc` | _SLINK_CT_ |`31:0` | | _mirrored control register_
| `0xfffffee0` | _SLINK_CH0_ | `31:0` | r/w | Link 0 RX/TX data
| `0xfffffee4` | _SLINK_CH1_ | `31:0` | r/w | Link 1 RX/TX data
| `0xfffffee8` | _SLINK_CH2_ | `31:0` | r/w | Link 2 RX/TX data
| `0xfffffeec` | _SLINK_CH3_ | `31:0` | r/w | Link 3 RX/TX data
| `0xfffffef0` | _SLINK_CH4_ | `31:0` | r/w | Link 4 RX/TX data
| `0xfffffef4` | _SLINK_CH5_ | `31:0` | r/w | Link 5 RX/TX data
| `0xfffffef8` | _SLINK_CH6_ | `31:0` | r/w | Link 6 RX/TX data
| `0xfffffefc` | _SLINK_CH7_ | `31:0` | r/w | Link 7 RX/TX data
|=======================