Interface of Transmit and Receive Streamer modules
The Transmit and Receive Streamers are xtx_streamer.vhd and
xrx_streamer.vhd located in modules/wr_streamers folder of
The figure below provide an overview of interfaces that
are used to write data words to the Tx Streamer and read data words from
the Rx Streamer.
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).
g_use_ref_clk_for_data - when non-zero, the datapath (tx_/rx_ ports) are in the clk_ref_i
clock domain instead of clk_sys_i. This is a must for fixed latency mode if
clk_sys_i is asynchronous (i.e. not locked) to the WR timing.
g_simulation - when set to 1, some processes run faster (startaup-timer for tx, TAI second for RX
g_clk_ref_rate - rate of the White Rabbit reference clock.
By default, this clock is 125MHz for WR Nodes. There are some WR Nodes that work with 62.5MHz.
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. The way this generic is currently
implemented is explained in issue #1595. Test 4 of the
simulation also shows how this
generic behaves in practice.
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_sim_startup_cnt - startup counter (value in 16ns cycles), used only in simulation mode (i.e. only if g_simulation = 1)
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).
g_sim_cycle_counter_range - shorten the duration of second to see TAI seconds for simulation only (i.e. only if g_simulation = 1)
FIFO-like interface (Tx and Rx Streamer):
The interface is synchronous to clk_sys_i by default (or clk_ref_i if configured in g_rx/tx_streamer_params, see)
These signal assertions are shown in a waveform
Input data word of generic width to be sent by the Tx Streamer
HIGH indicates that the tx_data_i contains a valid data word*
Synchronous data request: HIGH indicates that the Tx Streamer can accommodate a data word in the following clock cycle
Last data word signal. Asserted for 1 clock cycle and indicates the last data word in a block
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.
(to be implemented) sync signal, allowing to align transmission of the frames to the least supported WR reference clock frequency. Used in fixed latency mode
Synchronous data request input: when HIGH, the streamer can output another data word in the subsequent clock cycle.
Output data word of a generic width received by the Rx Streamer
HIGH indicted that rx_data_o is outputting a valid data word*.
HIGH indicates the 1st data word of the block* on rx_data_o.
HIGH indicates the last word of the data block on rx_data_o.
Indicates the frame has been reproduced later than its desired fixed latency
Indicates the frame has been reproduced earlier than its desired fixed latency due to the RX timeout
Configuration, control and statistics interface for Tx and Rx Streamer:
The interface is synchronous to clk_sys_i (regardless of configuration)
Asserted for one clock cycle to signify successful streamer frame transmission.
Reset sequence number. When asserted, the internal sequence number generator used to detect loss of frames is reset to 0. Advanced feature.
Networking configuration, see below
Asserted for one clock cycle to signify successful streamer frame reception
Lost output: HIGH indicates that one or more blocks or frames have been lost.
Indicates that one or more blocks within one frame are missing
Indicates that one or more frames are missing, the number of frames is provided
The number of lost frames. 0xF...F means that the counter overflowed
Latency measurement output: indicates the transport latency (between the TX streamer in remote device and this streamer), in clk_ref_i clock cycles.
HIGH when the latency on rx_latency_o is valid.
(to be implemented)
Indicates that fixed-latency was executed successfully (the data was delayed until the latency matched)
Indicates that the fixed-latency deadline was missed (possibly because data arrived too late)
Indicates that buffering of the received data exceeded the configured timeout before reaching the intended fixed-latency value, the execution timestamp was too far in the future
Networking configuration, see below
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.
Networking configuration (Tx and Rx Streamer):
Information on network configuration is provided in VHDL records,
respectively t_tx_streamer_cfg and t_rx_streamer_cfg. This interface
allows application-specific logic to provide network configuration
directly. This network configuration provided directly in the VHDL
records can be overriden by configuration provided in wishbone
registers, see wishbone memory
t_tx_streamer_cfg 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 - Destination MAC address from Tx 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 - Ethernet frame priority.
sw_reset - Reset of tx path, intended to be controlled by application-specific logic or software (available via WB interface)
mac_local - Same description as in Tx.
mac_remote - Source MAC address to Rx module.
ethertype - Same description as in Tx.
accept_broadcasts - This is set to 1 if Rx must accept all
broadcast packets, otherwise clear in order to accept only unicast
filter_remote - Filtering source MAC adress of streamer frames on
reception. 1 To accept packets from any source. 0 to accept only those
from device specified in mac_remote.
fixed_latency - Network latency can be configured to a fixed
value. The receiver does not output received data until desired latency
has elapsed to emulate a network with constant latency. Set to 0 to
disable. The fixed network latency is ensured between
the beginning of transmission of Ethernet frame (SOF) carrying WR
Streamer words and
the time the first word transported in this Etherent frame is
presented (rx_valid_ and rx_first_p1_o are HIGH) Note: The configured value of fixed network latency guarantees a
fixed latency internally (inside the FPGA) with a jitter of + /- one
clock cycle (+/-8ns) unless the ultra-fixed latency configuration is used. The latency observed by the application might see
a static offset to the configured value. This static offset should
be repeatable and measurable (per board, per bitstream), it is expected to be in the order of few ns.
fixed_latency_timeout - Value in cycles of fixed-latency timeout (if it takes longer than this value for the data to wait for presentation to the application logic, it's dropped)
sw_reset - Reset of rx path, intended to be controlled by application-specific logic or software (available via WB interface)