**************************
** RTBOX_AURORA_ADAPTER **
**************************
Version: 1.0


A) OVERVIEW

The "rtbox_aurora_adapter" IP enables an external Xilinx FPGA to exchange data
with a real-time simulation running on the Plexim RT-Box via a SFP link.

It is as a lightweight wrapper module to be used on top of the standard Xilinx
Aurora 64B/66B IP, hence the name "adapter". The Aurora 64B/66B IP must be
explicitly instantiated, configured and connected to the adapter module as
explained below. This approach tries to achieve a compromise between ease of use
and maximum flexibility.

The communication with the RT-Box is full duplex and packet based. The adapter
module exposes to the FPGA logic a transmitter interface (TX) and a receiver
interface (RX), both implementing the standard AMBA 4 AXI4-Stream interface
protocol specification. The width of the TX and RX streams is fixed at 64 bits,
since this is the natural width of the underlying Aurora 64B/66B link-layer
protocol. The concept of data packet is inherent to the AXI4-Stream interface
protocol and is implemented by means of the TLAST interface signal.

The basic unit of information that the RT-Box and the external device can
exchanged is a 32-bit word, which is interpreted by the PLECS model running on
the RT-Box as a IEEE 754 single-precision floating-point value. We will refer to
such a 32-bit word simply as a "float". The payload of a data packet consists of
a number of floats.

A PLECS model sends data to the external device by means of the "SFP Out"
library block. A data packet is sent at each simulation step; the size of the
payload, i.e. the number of floats contained in the packet, is determined by the
width of the PLECS signal feeding the "SFP Out" block. Conversely, the PLECS
model has access to incoming packets sent by the external device by means of the
"SFP In" library block; the payload size of the incoming packets must be
configured as a parameter of the "SFP In" block. In case a packet is received
whose payload size does not match the corresponding parameter of the "SFP In"
block, the real-time simulation is aborted with an error message. The incoming
packets are saved in a buffer internal to the RT-Box: only the most recent
successfully received packet is retained in the buffer. The output of the "SFP
In" library block is updated once per simulation cycle with the contents of this
buffer. Thus the frequency with which the external device sends data to the
RT-Box does not need to be related to the step size of the real-time simulation.


== AXI4-Stream packet payload

Since the width of the TX and RX streams of the Aurora adapter module
is fixed at 64 bits while the basic unit of information is a 32-bit
floating-point number, a packet containing n floats {F1, F2, ... Fn}
translates to an AXI4-Stream packet with ceil(n/2) transfers.

For n even the packet structure is the following:

Transfer #                TDATA                     TLAST
 
                          63    32 31     0
                          -----------------
0                         |  F2   |   F1  |         0
1                         |  F4   |   F3  |         0
2                         |  F6   |   F5  |         0

...                       ...                       ...

ceil(n/2)-1               |  Fn   |  Fn-1 |         1
                          -----------------


For n odd the highest 32 bits of the last data transfer (indicated by "xxxxx" in
the following figure) do not carry significant information:

Transfer #                TDATA                     TLAST
 
                          63    32 31     0
                          -----------------
0                         |  F2   |   F1  |         0
1                         |  F4   |   F3  |         0
2                         |  F6   |   F5  |         0

...                       ...                       ...

ceil(n/2)-1               | xxxxx |   Fn  |         1
                          -----------------


In the PLECS model running on the RT-Box such packets translate to a PLECS
vector signal of width n (either an input to the "SFP out" library block or an
output of the "SFP In" library block).


== AXI4-Stream packet metadata

Note that the AXI4-Stream TX and RX interfaces of the Aurora adapter module do
not implement the TKEEP signal. Information about the payload size is either
specified statically or given as side-band information by means of the TUSER
signal.

a) TX interface

In order to send a packet to the RT-Box, the Aurora adapter module needs to know
its payload size. When instantiating and configuring the IP the user can choose
whether to specify a static payload size, or to configure the IP in dynamic
mode (see the section "ADAPTER IP PARAMETERS").

When configured in dynamic mode, the payload size is specified on a per-packet
basis by means of the TUSER interface signal. The signal is sampled on the first
data beat of a packet and has the following structure:

Transfer #            TUSER                        TLAST

                      7   6                  0
                      ------------------------
0                     | x | payload size (n) |         0
1                     | x | xxxxxxxxxxxxxxxx |         0

...                   ...                              ...  

ceil(n/2)-1           | x | xxxxxxxxxxxxxxxx |         1
                      ------------------------

The payload size is contained in the seven least significant bits, whereas the
most significant bit is discarded. The payload size must not exceed 126. The
TUSER signal has no significance on data beats following the first one in a
packet.

Note that it is responsibility of the user to ensure that the actual payload
size corresponds to the value specified in TUSER.


b) RX interface

The payload size of a received packet is made available in the seven least
significant bits of the TUSER signal of the RX interface. The information is
valid for all data beats of a packet.

For proper operation with the RT-Box the Xilinx Aurora 64B/66B IP must be
configured with CRC error detection enabled (see "CONFIGURATION OF THE XILINX
AURORA 64B/66B IP"). Whether the received packet passed the CRC check is made
available in the most significant bit of the TUSER signal (1: no error detected;
0: an error was detected). The information is valid only on the last data beat
of a packet.

Transfer #            TUSER                            TLAST

                      7     6                  0
                      --------------------------
0                     |  x  | payload size (n) |       0
1                     |  x  | payload size (n) |       0

...                   ...                              ...  

ceil(n/2)-1           | 0/1 | payload size (n) |       1
                      --------------------------



== Checksum-based packet filter

The Aurora adapter module can optionally be instructed to drop incoming packets
with invalid CRC checksum (see "ADAPTER IP PARAMETERS"). When this option is
activated an incoming packet is first saved in its entirety to an internal
buffer; it is then streamed through the RX interface only if no errors were
detected.

Note that regardless of the filter settings the AXI4-Stream RX interface accepts
no back pressure (i.e. it has no TREADY signal). It is responsibility of the
user to ensure that no data is lost at the interface.


== Startup synchronization

An RT-Box configured as master can be instructed to wait for one or more slave
boxes to become ready before starting the real-time simulation. The Aurora
adapter module optionally enables the external FPGA to act as a slave device on
par with other RT-Boxes for the purpose of startup synchronization. To this end
the synchronization interface must be activated in the IP configuration
parameters (see "ADAPTER IP PARAMETERS").

Note that under certain circumstances two RT-Boxes can also be instructed to
synchronize their clocks (i.e. synchronize the discrete simulation steps they
take). This does not apply to an external FPGA device.

The startup synchronization interface consists of a "ready" signal to be
asserted by the slave, and a "start" signal asserted by the master. The RT-Box,
when configured for startup synchronization, waits until all slaves have
asserted the ready signal before starting the simulation; when the simulation
starts all slaves are notified with the start signal.

For proper operation the slave is required to hold the ready signal in the
asserted state until the start signal from the RT-Box is asserted. The start
signal will remain asserted as long as the real-time simulation runs and the
communication channel is active.



B) CONFIGURATION OF THE XILINX AURORA 64B/66B IP

This section explains how to configure the Xilinx Aurora 64B/66B IP for proper
operation with an RT-Box and how to connect the adapter module to the Aurora IP.

== Parameters of the Xilinx Aurora 64B/66B

The following parameters of the Xilinx Aurora 64B/66B IP _must_ be configured as
indicated: failure to do so will result in a non-functioning design.

a) Physical layer
- Line Rate:               6.25 Gbs

b) Link layer
- Dataflow Mode:           Duplex
- Interface:               Framing
- Flow control:            None
- User K:                  Deactivated
- Little Endian Support:   Deactivated

c) Error detection
- CRC:                     Activated

The remaining parameters may be configured as needed by the design.


== Connecting the adapter module to the Xilinx Aurora 64B/66B IP

The interface between the adapter module and the Xilinx Aurora 64B/66B IP
consists of one clock port and three interface ports. The required connections
are detailed in the following table:

------------------------------------------------------
Adapter module                Xilinx Aurora 64B/66B IP
------------------------------------------------------
aclk                          user_clk
S_AXIS_AURORA_RX              USER_DATA_M_AXIS_RX
M_AXIS_AURORA_TX              USER_DATA_S_AXIS_TX
CORE_STATUS                   CORE_STATUS
------------------------------------------------------

Note that the source of the adapter module clock "aclk" _must_ be the "user_clk"
signal provided by the Xilinx Aurora 64B/66B IP. Using a different clock source
will lead to a non-functioning design.



C) ADAPTER IP PARAMETERS

1) TX parameters

    a) 'Payload size': the user may choose between a static mode and a dynamic
    mode. For the meaning of this option refer to the section "AXI4-Stream
    packet metadata" in the overview.

    b) 'Static payload size': the payload size of all outgoing packets if static
    mode is selected.


2) RX parameters

    a) 'Drop packages with invalid checksum': when selected, incoming packages
    with incorrect checksum are filtered out of the RX stream. See the section
    "Checksum-based packet filter" in the overview for additional information.


3) Synchronization

    a) 'Enable synchronization interface': when selected, the "ready" and
    "start" signals for startup synchronization will be enabled. see the section
    "Startup synchronization" in the overview for additional information.



D) ADAPTER IP PORTS

This section contains a list of the ports of the adapter module with a short
description of their purpose.

== Clock and reset

* aclk

        Clock signal driving the entire logic of the adapter module. _Must_ be
        connected to the "user_clk" clock provided by the Xilinx Aurora 64B/66B
        IP.

* aresetn

        Active low reset signal.


== Interface to the Xilinx Aurora 64B/66B IP

* S_AXIS_AURORA_RX
    s_axis_aurora_rx_tdata[63:0]
    s_axis_aurora_rx_tkeep[7:0]
    s_axis_aurora_rx_tlast
    s_axis_aurora_rx_tvalid

        Interface to the RX stream of the Xilinx Aurora 64B/66B IP.

* M_AXIS_AURORA_TX
    m_axis_aurora_tx_tdata[63:0]
    m_axis_aurora_tx_tkeep[7:0]
    m_axis_aurora_tx_tlast
    m_axis_aurora_tx_tvalid
    m_axis_aurora_tx_tready

        Interface to the TX stream of the Xilinx Aurora 64B/66B IP.

* CORE STATUS

        Interface to the core status signals of the Xilinx Aurora 64B/66B IP.


== Interface to the user FPGA logic

* S_AXIS_TX
    s_axis_tx_tdata[63:0]
    s_axis_tx_tlast
    s_axis_tx_tvalid
    s_axis_tx_tready
    s_axis_tx_tuser[7:0] (* present only if the TX interface is configured in
                            dynamic mode; specifies the payload size *)

        Packets streamed to this interface will be sent to the RT-Box. The
        transmission starts as soon as the first data beat is accepted by the
        interface.

* M_AXIS_RX
    m_axis_rx_tdata[63:0]
    m_axis_rx_tlast
    m_axis_rx_tvalid
    m_axis_rx_tuser[7:0] (* contains the payload size and the CRC pass flag *)

        Data packets received from the RT-Box are streamed out of this
        interface. Note that the interface does _not_ accept back pressure. If
        the CRC-based packet filter is disabled an incoming packet is forwarded
        to this interface as soon as the first data beat is received; if the
        filter is enabled a packet with no errors is forwarded to this interface
        as soon as the last data beat is received.

* sync_ready (* present only if the synchronization interface is enabled *)

        Signals a master RT-Box that this slave device is ready for startup.

* sync_start (* present only if the synchronization interface is enabled *)

        Asserted When the master RT-Box starts the real-time simulation.

