|
|
# WR Streamers
|
|
|
|
|
|
WR Streamers provide to the user a FIFO-like interface over Ethernet. WR
|
|
|
Streamers comprise of VHDL modules to send and receive data:
|
|
|
|
|
|
- **TX steamer** takes a series of data words and encapsulates them
|
|
|
into Ethernet Frames
|
|
|
- **RX streamer** does the opposite: decodes Ethernet frames into
|
|
|
series of data
|
|
|
words
|
|
|
|
|
|
![](/uploads/21b064f7c8ddaba77f1b49ed4a952f30/streamers-overview-small.jpg)
|
|
|
|
|
|
-----
|
|
|
|
|
|
## Streamers principles of data transfer
|
|
|
|
|
|
- **Tx Streamer** transfer **data words** that are of width (n \* 16)
|
|
|
bits. The width is defined by generic *g\_data\_width* that must be
|
|
|
identical for the Tx and Rx Steamer.
|
|
|
- **Data words** can be grouped in **blocks** of any size with upper
|
|
|
limit defined by *g\_tx\_max\_words\_per\_frame*, each **block** has
|
|
|
independent sequence number and CRC.
|
|
|
- A stream of **data words** arranged in one or more **blocks** is
|
|
|
encapsulated into an Ethernet Frame. At transmission, the frame is
|
|
|
timestamped and the timestamp included in the frame.
|
|
|
- Ethernet Frame is sent when one of the following is true:
|
|
|
- a complete **block** was written to the buffer of the Tx
|
|
|
Streamer, and the number of **data words** waiting for
|
|
|
transmission exceeds the number defined by generic
|
|
|
*g\_tx\_threshold*,
|
|
|
- there are **data words** in the buffer of the Tx Streamer, and
|
|
|
the time elapsed from the latest write to Tx Streamer exceeded
|
|
|
timeout defined by generic *g\_tx\_timeout*,
|
|
|
- the user asserts *tx\_flush\_i* to explicitly request
|
|
|
transmission of the data that has been written to the buffer of
|
|
|
the Tx Streamer.
|
|
|
|
|
|
-----
|
|
|
|
|
|
## Encapsulation of **data words** and **blocks** into Ethernet Frame
|
|
|
|
|
|
The number of **data words** grouped into **blocks** is specified by the
|
|
|
user who indicates the last **data word**. Inside the frame, each
|
|
|
*block** ends with a CRC and an *escape code* (0xCAFE).
|
|
|
The Streamer Frame consists of a transmission timestamp and a collection
|
|
|
of **blocks**, it is sent in the payload of an Ethernet Frame, as
|
|
|
depicted in the figure below.
|
|
|
Each **block** starts with an ID number
|
|
|
|
|
|
- the ID number of the **block** that immediately follows the Ethernet
|
|
|
Header, is the sequence number of the frame
|
|
|
- the ID number of the subsequent **blocks**, is the inter-frame
|
|
|
sequence number of the
|
|
|
*block**
|
|
|
|
|
|
![](/uploads/e9f6b568d102f612b4e1e034378629bb/Streamer-frame.v2.jpg)
|
|
|
|
|
|
-----
|
|
|
|
|
|
## Transmission module (currently available only in branch ML-addressReviewFeedback)
|
|
|
|
|
|
- It is meant to be a used as a building block in WR-based nodes.
|
|
|
Additionally to transmission and reception of data, it provides
|
|
|
advanced diagnostics and debugging capabilities that can be accessed
|
|
|
via SNMP and WB registers (via PCI or VME).
|
|
|
- It includes the following sub-modules:
|
|
|
- Tx Streamer (xtx\_streamer)
|
|
|
- RX Straamer (xrx\_streamer)
|
|
|
- Statistics (xrtx\_streamers\_stats)
|
|
|
- WB config and status register
|
|
|
(wr\_transmission\_wb)
|
|
|
|
|
|
![](/uploads/edd22866e5eef5320c48d20260d0fc25/xwr_transmissionx700.jpg)
|
|
|
|
|
|
## Interface of Tx and Rx Streamer modules
|
|
|
|
|
|
- **Transmission configuration:**
|
|
|
- *g\_data\_width* - generic defines the width of input/output
|
|
|
data in (n\*16) bits, it must be identical for the Tx and Rx
|
|
|
Streamer.
|
|
|
- *g\_tx\_threshold* - generic defines minimum number of data
|
|
|
words in the buffer of the Tx Streamer that will trigger
|
|
|
transmission of an Ethernet Frame.
|
|
|
- *g\_tx\_max\_words\_per\_frame* - generic defines maximum number
|
|
|
of data words in a single Ethernet Frame. It also defines the
|
|
|
maximum block size.
|
|
|
- *g\_tx\_timeout* - generic defines transmission timeout (in
|
|
|
clk\_sys\_i cycles), after which the content of the buffer in
|
|
|
the Tx Streamer is sent regardless of the amount of data that is
|
|
|
currently stored in the buffer, so that data in the buffer does
|
|
|
not get stuck.
|
|
|
- *g\_buffer\_size* - generic defines size of the buffer in the Rx
|
|
|
Streamer, in data words.
|
|
|
- *g\_filter\_remote\_mac* - generic, when it is TRUE, the Rx
|
|
|
Streamer receives only packets whose destination MAC equals
|
|
|
*cfg\_mac\_remote\_i*. When false, it accepts all incoming
|
|
|
frames.
|
|
|
- *g\_escape\_code\_disable* - generic, when it is TRUE, the
|
|
|
*escape code* is not used and only a single **block** can be
|
|
|
sent. Don't use it unless you know what you are doing.
|
|
|
- *g\_expected\_words\_number* - generic defines the number of
|
|
|
words that is expected by the receiver. Don't use it unless you
|
|
|
know what you are doing.
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
- **Networking configuration (Tx and Rx Streamer):**
|
|
|
- cfg\_mac\_local\_i - local MAC address. Leave at 0 when using
|
|
|
with the WR MAC/Core, it will insert its own source MAC.
|
|
|
- cfg\_mac\_target\_i - Destination MAC address
|
|
|
- cfg\_ethertype\_i - Ethertype of Streamer Frames. Default value
|
|
|
is accepted by standard configuration of the WR PTP Core
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
- **WR timing input (optional, to allow latency measurement, Tx and Rx
|
|
|
Streamer):**
|
|
|
- clk\_ref\_i - White Rabbit reference clock
|
|
|
- tm\_time\_valid\_i - Time valid flag
|
|
|
- tm\_tai\_i - TAI seconds
|
|
|
- tm\_cycles\_i - Fractional part of the second (in clk\_ref\_i
|
|
|
cycles)
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
- **FIFO-like interface (Tx and Rx Streamer)**:
|
|
|
- the figure and tables below provide information on interfaces
|
|
|
that are used to write data words to the Tx Streamer and read
|
|
|
data words from the Rx Streamer
|
|
|
- waveform with the described signals is available
|
|
|
[here](https://www.ohwr.org/project/wr-cores/uploads/45936912d749480295414451e2e399f2/streamer_timing.jpg):
|
|
|
|
|
|
/4216
|
|
|
|
|
|
*Tx Streamer**
|
|
|
| \* I/F name **|** Description \*|
|
|
|
| tx\_data\_i | Input **data word** of generic width to be sent by the
|
|
|
Tx Streamer|
|
|
|
| tx\_valid\_i | HIGH indicates that the tx\_data\_i contains a valid
|
|
|
*data word** |
|
|
|
| tx\_dreq\_o | Synchronous data request: HIGH indicates that the Tx
|
|
|
Streamer can accommodate a **data word** in the following clock cycle
|
|
|
|
|
|
|
| tx\_last\_i | Last **data word** signal. When asserted, it indicates
|
|
|
the last data word in a **block** |
|
|
|
| tx\_flush\_i | Flush input. When asserted, the streamer will
|
|
|
immediately send out all the data that is stored in its TX buffer,
|
|
|
ignoring g\_tx\_timeout. |
|
|
|
| tx\_reset\_seq\_i | Reset sequence number. When asserted, the internal
|
|
|
sequence number generator used to detect loss of frames is reset to 0.
|
|
|
Advanced feature. |
|
|
|
|
|
|
*Rx Streamer**
|
|
|
| \* I/F name **|** Description \*|
|
|
|
| rx\_data\_o | Output **data word** of a generic width received by the
|
|
|
Rx Streamer |
|
|
|
| rx\_valid\_o | HIGH indicted that rx\_data\_o is outputting a valid
|
|
|
*data word**. |
|
|
|
| rx\_dreq\_i | Synchronous data request input: when HIGH, the streamer
|
|
|
can output another data word in the subsequent clock cycle. |
|
|
|
| rx\_first\_o | HIGH indicates the 1st **data word** of the **block**
|
|
|
on rx\_data\_o. |
|
|
|
| rx\_last\_o | HIGH indicates the last word of the data block on
|
|
|
rx\_data\_o. |
|
|
|
| rx\_lost\_o | Lost output: HIGH indicates that one or more of
|
|
|
*blocks** have been lost. |
|
|
|
| rx\_latency\_o | Latency measurement output: indicates the transport
|
|
|
latency (between the TX streamer in remote device and this streamer), in
|
|
|
clk\_ref\_i clock cycles. |
|
|
|
| rx\_latency\_valid\_o | HIGH when the latency on rx\_latency\_o is
|
|
|
valid. |
|
|
|
|
|
|
-----
|
|
|
|
|
|
More information:
|
|
|
|
|
|
- [White Rabbit PTP Core Hands-on Training
|
|
|
materials](handson-training) that uses WR Streamers (see these
|
|
|
slides from
|
|
|
[day 1](https://www.ohwr.org/project/wr-cores/uploads/7c1ed31c6ef18e7f9f2ffdb16026a1c0/wr_course_day1.pdf)
|
|
|
and
|
|
|
[day 2](https://www.ohwr.org/project/wr-cores/uploads/8438664f15d57ded201db82f6cc15435/wr_course_day2_new.pdf))
|
|
|
- Applications:
|
|
|
- WR-Btrain: [POPS: Magnetic Field and Magnet Current Information
|
|
|
Distribution via White
|
|
|
Rabbit](https://edms.cern.ch/ui/#!master/navigator/document?d:1492270156:1492270156:subdocs)
|
|
|
and [White Rabbit Based Revolution Frequency Program From the
|
|
|
Longitudinal Beam Control of the CERN
|
|
|
PS](http://icalepcs.synchrotron.org.au/papers/mopgf091.pdf)
|
|
|
|
|
|
-----
|
|
|
|
|
|
## Features to be added in future:
|
|
|
|
|
|
- configurable delay of publishing data received by rx\_streamer, so
|
|
|
that the latency between transmission and reception is fixed at
|
|
|
ns-level
|
|
|
- statistics: number of lost frames, avg/max/min latency
|
|
|
|
|
|
-----
|
|
|
|
|
|
## Project Status
|
|
|
|
|
|
<table>
|
|
|
<tbody>
|
|
|
<tr class="odd">
|
|
|
<td><strong>Date</strong></td>
|
|
|
<td><strong>Event</strong></td>
|
|
|
</tr>
|
|
|
<tr class="even">
|
|
|
<td>2013-03-15</td>
|
|
|
<td>Streamers developed for White Rabbit Core Hands-on Training by Tom</td>
|
|
|
</tr>
|
|
|
<tr class="odd">
|
|
|
<td>2016-03-07</td>
|
|
|
<td>Tom's streamers included into wr-cores proposed_master and documented with a wiki page (now can be found [here](/WR-Streamers-old))</td>
|
|
|
</tr>
|
|
|
<tr class="even">
|
|
|
<td>2016-03-31</td>
|
|
|
<td>Layout of streamer's frame modified slightly to make it backward compatible with the version used in B-train, wiki updated</td>
|
|
|
</tr>
|
|
|
</tbody>
|
|
|
</table>
|
|
|
|
|
|
-----
|
|
|
|
|
|
4 March 2016
|
|
|
|
|
|
|
|
|
|
|
|
### Files
|
|
|
* [wr_streamers_wb.pdf](/uploads/123c8f37ddad8747f18e780978d7bc03/wr_streamers_wb.pdf) |
|
|
\ No newline at end of file |