|
# WR Streamers
|
|
# WR Streamers
|
|
|
|
|
|
WR Streamers provide to the user a FIFO-like interface over Ethernet. WR
|
|
WR Streamers provide the user with a FIFO-like interface over Ethernet
|
|
Streamers comprise of VHDL modules to send and receive data:
|
|
(See figure below). WR Streamers comprises VHDL modules to ensure data
|
|
|
|
communication as well statistics on tranceiver performance.
|
|
|
|
|
|
- **TX steamer** takes a series of data words and encapsulates them
|
|
Wr Streamers come included as of [Release 4 of the
|
|
into Ethernet Frames
|
|
WRPC](/Current-release), instantiated inside the xwrc\_board\_common.vhd
|
|
- **RX streamer** does the opposite: decodes Ethernet frames into
|
|
module. They can be enabled by setting the @ g\_fabric\_iface@ generic
|
|
series of data
|
|
to
|
|
words
|
|
`STREAMERS`.
|
|
|
|
|
|
![](/uploads/21b064f7c8ddaba77f1b49ed4a952f30/streamers-overview-small.jpg)
|
|
![](/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)
|
|
|
|
|
|
|
|
-----
|
|
|
|
|
|
|
|
## WR streamers module
|
|
## WR streamers module
|
|
|
|
|
|
- The `wr-streamers.vhd` module provides a [WR PTP Core](/Wrpc-core)
|
|
-
|
|
|
|
-
|
|
|
|
The `wr-streamers.vhd` module provides a [WR PTP Core](/Wrpc-core)
|
|
-compatible communication module.
|
|
-compatible communication module.
|
|
It is meant to be a used as a building block in WR-based nodes (It
|
|
It is meant to be a used as a building block in WR-based nodes.
|
|
is enabled when the @ g\_fabric\_iface@ generic is set to
|
|
|
|
`STREAMERS` inside `xwrc-board-common.vhd` module).
|
|
|
|
Additionally to transmission and reception of data, it provides
|
|
Additionally to transmission and reception of data, it provides
|
|
advanced diagnostics and debugging capabilities that can be accessed
|
|
advanced diagnostics and debugging capabilities that can be accessed
|
|
via SNMP and WB registers (via PCI or VME).
|
|
via SNMP and WB registers (via PCI or VME).
|
|
|
|
|
|
- It includes the following sub-modules:
|
|
- It includes the following sub-modules:
|
|
- Tx Streamer (`xtx_streamer.vhd`)
|
|
|
|
- RX Streamer (`xrx_streamer.vhd`)
|
|
- \*[TX steamer](/TxRx-Streamers)* (`xtx_streamer.vhd`) - Takes a
|
|
|
|
series of data words and encapsulates them into Ethernet Frames
|
|
|
|
to be transmitted over the WR fabric interface.
|
|
|
|
- \*[RX streamer](/TxRx-Streamers)* (`xrx_streamer.vhd`) -
|
|
|
|
Receives Ethernet frames via the WR fabric interface and decodes
|
|
|
|
them into a series of data words .
|
|
- Statistics (`xrtx_streamers_stats.vhd`)
|
|
- Statistics (`xrtx_streamers_stats.vhd`)
|
|
- WB config and status register (`wr_transmission_wb.vhd`)
|
|
- WB config and status register (`wr_transmission_wb.vhd`)
|
|
|
|
|
... | @@ -78,6 +40,8 @@ Each **block** starts with an ID number |
... | @@ -78,6 +40,8 @@ Each **block** starts with an ID number |
|
|
|
|
|
### Interface of the `wr-streamers.vhd` module:
|
|
### Interface of the `wr-streamers.vhd` module:
|
|
|
|
|
|
|
|
- Configuration
|
|
|
|
|
|
* `g_streamers_op_mode` - Indicates whether this module instantiates
|
|
* `g_streamers_op_mode` - Indicates whether this module instantiates
|
|
both TX and RX streamers (set to `TX_AND_RX`) or only one
|
|
both TX and RX streamers (set to `TX_AND_RX`) or only one
|
|
of them. An application that only receives or only transmits might want
|
|
of them. An application that only receives or only transmits might want
|
... | @@ -94,171 +58,6 @@ max 32). |
... | @@ -94,171 +58,6 @@ max 32). |
|
* `g_slave_mode` - Specifies wishbone interface mode.
|
|
* `g_slave_mode` - Specifies wishbone interface mode.
|
|
* `g_slave_granularity` - Set wishbone address granularity.
|
|
* `g_slave_granularity` - Set wishbone address granularity.
|
|
|
|
|
|
## Interface of Tx and Rx Streamer modules
|
|
|
|
|
|
|
|
### **Transceiver configuration:**
|
|
|
|
|
|
|
|
VHDL generics to specify Tx and Rx pair configuration:
|
|
|
|
|
|
|
|
- **Common to Tx and Rx**
|
|
|
|
- `g_data_width` - Generic defines the width of input/output data
|
|
|
|
in multiples of 16 bits (n\*16). It must be identical for the Tx
|
|
|
|
and Rx Streamer.
|
|
|
|
- `g_escape_code_disable` - Generic, when it is `TRUE`, the
|
|
|
|
*escape code* is not used and only a single **block** can be
|
|
|
|
sent. In this case, for the receiver to interpret such a frame
|
|
|
|
correctly, it needs to have this same generic set to true, in
|
|
|
|
addition to setting `g_expected_words_number` generic to the
|
|
|
|
expected number of words in the single block.
|
|
|
|
- `g_tx_buffer_size` / `g_rx_buffer_size` - Generic defines size
|
|
|
|
of Tx/Rx buffer, in data words. In the case of the Tx streamer,
|
|
|
|
it is recommended that this value exceeds 2\*g\_tx\_threshold
|
|
|
|
(Description to follow).
|
|
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
|
|
- **Tx specific**
|
|
|
|
- `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_simulation` and `g_sim_startup_cnt` - **Simulation specific**
|
|
|
|
generics. Used in order to avoid long simulation delays due to
|
|
|
|
external module startup.
|
|
|
|
|
|
|
|
<!-- end list -->
|
|
|
|
|
|
|
|
- **Rx specific**
|
|
|
|
- `g_expected_words_number` - generic defines the number of words
|
|
|
|
that is expected by the receiver. This is a legacy feature, when
|
|
|
|
only a fixed number of words is ever received. By setting it to
|
|
|
|
a non-zero value, and combined with setting the
|
|
|
|
`g_escape_code_disable` generic in both tx and rx to `TRUE`,
|
|
|
|
this feature can be enabled (Though **not recommended**).
|
|
|
|
|
|
|
|
### **Networking configuration (Tx and Rx Streamer):**
|
|
|
|
|
|
|
|
Information on network configuration is stored in VHDL records,
|
|
|
|
respectively `t_tx_streamer_cfg` and `t_rx_streamer_cfg`.
|
|
|
|
|
|
|
|
The Tx record contains the following fields:
|
|
|
|
|
|
|
|
* `mac_local` - local MAC address. Leave at 0 when using with the WR
|
|
|
|
MAC/Core, as it will insert its own source MAC.
|
|
|
|
|
|
|
|
* `mac_target` / `mac_remote` - Destination MAC address on Tx module,
|
|
|
|
source MAC address for Rx module.
|
|
|
|
|
|
|
|
* `ethertype` - Ethertype of streamer frames. Default value is
|
|
|
|
accepted by the standard configuration of the [WR PTP Core](/Wrpc-core).
|
|
|
|
|
|
|
|
* `qtag_ena` - Enables tagging with VLAN tags.
|
|
|
|
|
|
|
|
* `qtag_vid` - The ID of the VLAN used to tag.
|
|
|
|
|
|
|
|
* `qtag_prio` - Tagging
|
|
|
|
priority.
|
|
|
|
|
|
|
|
### **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 number of
|
|
|
|
clk\_ref\_i cycles).
|
|
|
|
|
|
|
|
* `link_ok_i` - Status of the link, in principle the transmitter can
|
|
|
|
be done only if link is OK.
|
|
|
|
|
|
|
|
### **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.
|
|
|
|
|
|
|
|
* These signal assertions are shown in a [waveform
|
|
|
|
example](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_p1_i` | Last **data word** signal. Asserted for 1 clock cycle
|
|
|
|
and indicates the last data word in a **block** |
|
|
|
|
| `tx_flush_p1_i` | Flush input. When asserted for 1 clock cycle, 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. |
|
|
|
|
| `tx_frame_p1_o` | Asserted for one clock cycle to signify successful
|
|
|
|
streamer frame transmission. |
|
|
|
|
|
|
|
|
*Rx Streamer**
|
|
|
|
| \* I/F name **|** Description \*|
|
|
|
|
| `rx_dreq_i` | Synchronous data request input: when HIGH, the streamer
|
|
|
|
can output another data word in the subsequent clock cycle. |
|
|
|
|
| `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_first_p1_o` | HIGH indicates the 1st **data word** of the
|
|
|
|
*block** on rx\_data\_o. |
|
|
|
|
| `rx_last_p1_o` | HIGH indicates the last word of the data block on
|
|
|
|
rx\_data\_o. |
|
|
|
|
| `rx_frame_p1_o` | Asserted for one clock cycle to signify successful
|
|
|
|
streamer frame reception|
|
|
|
|
| `rx_lost_p1_o` | Lost output: HIGH indicates that one or more
|
|
|
|
*blocks** or **frames** have been lost. |
|
|
|
|
| `rx_lost_blocks_p1_o` | Indicates that one or more blocks within one
|
|
|
|
frame are missing |
|
|
|
|
| `rx_lost_frames_p1_o` | Indicates that one or more frames are missing,
|
|
|
|
the number of frames is provided |
|
|
|
|
| `rx_lost_frames_cnt_o` | The number of lost frames. 0xF...F means that
|
|
|
|
the counter overflowed |
|
|
|
|
| `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)
|
|
|
|
|
|
|
|
-----
|
|
|
|
|
|
|
|
## Streamer performance statistics:
|
|
## Streamer performance statistics:
|
|
|
|
|
|
The xrtx\_streamers\_stats module included in the xwr-transmission
|
|
The xrtx\_streamers\_stats module included in the xwr-transmission
|
... | | ... | |