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
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.
- 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
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*
WR streamers module
- The
wr-streamers.vhd
module provides a WR PTP Core -compatible communication module.
It is meant to be a used as a building block in WR-based nodes (It is enabled when the @ g_fabric_iface@ generic is set toSTREAMERS
insidexwrc-board-common.vhd
module).
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.vhd
) - RX Streamer (
xrx_streamer.vhd
) - Statistics (
xrtx_streamers_stats.vhd
) - WB config and status register
(
wr_transmission_wb.vhd
)
- Tx Streamer (
wr-streamers.vhd
module:
Interface of the -
g_streamers_op_mode
- Indicates whether this module instantiates both TX and RX streamers (set toTX_AND_RX
) or only one
of them. An application that only receives or only transmits might want to useRX_ONLY
orTX_ONLY
mode in order to save resources. -
g_tx_streamer_params
- Transmission defaults for Tx streamer. Corresponds to the Tx streamerngenerics stored in one record. -
g_rx_streamer_params
- Reception defaults for Rx streamer. Corresponds to the Rx streamer generics stored in one record. -
g_stats_cnt_width
- Width of statistics counters: frame rx/tx/lost, block lost, counter of accumuted latency (minimum 15 bits, max 32). -
g_stats_acc_width
- Width of latency accumulator (max value 64) . -
g_slave_mode
- Specifies wishbone interface mode. -
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 isTRUE
, 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 settingg_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).
-
-
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
andg_sim_startup_cnt
- Simulation specific generics. Used in order to avoid long simulation delays due to external module startup.
-
-
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 theg_escape_code_disable
generic in both tx and rx toTRUE
, 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. -
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.
/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 that uses WR Streamers (see these slides from day 1 and day 2)
- Applications:
Streamer performance statistics:
The xrtx_streamers_stats module included in the xwr-transmission
module produces streamer performance-related data that can be used for
advanced diagnostics and monitoring.
The module generates information on streamer module function in terms
of:
- Data delivery: This includes the number of frames sent, frames received as well as information on the number of lost frames and lost blocks.
- Latency: This includes information such as maximum and minimum latency values and the cumulated latency.
The streamer interface outputs can then be written to wishbone registers but are also available through SNMP.
The statistics module can be reset remotely via the reset_stats_i input port. This input can be written to via a wishbone register as is the case in the xwr_transmission module.
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
Date | Event |
2013-03-15 | Streamers developed for White Rabbit Core Hands-on Training by Tom |
2016-03-07 | Tom's streamers included into wr-cores proposed_master and documented with a wiki page (now can be found here) |
2016-03-31 | Layout of streamer's frame modified slightly to make it backward compatible with the version used in B-train, wiki updated |
4 March 2016