Skip to content

W
White Rabbit Trigger Distribution
Commit e01dd91e authored by Dimitris Lampridis's avatar Dimitris Lampridis
Browse files
Options

doc: wip

parent 8379ee5b
Hide whitespace changes
Inline Side-by-side
Showing with 101 additions and 14 deletions
doc/basic_concepts.rst
View file @ e01dd91e
......@@ -136,11 +136,37 @@ WRTD in the future.
Please refer to Section 4.3 of the `LXI Event Messaging Extended Function specification`_ for more
details.
.. _rep_cap:
Repeated Capability
===================
.. _attribute:
Attribute
=========
.. _rule:
Rule
====
.. figure:: graphics/wrtd_rule_rx.png
:name: fig-wrtd-rule-rx
:align: center
:alt: alternate text
:figclass: align-center
RX path of a Rule
.. figure:: graphics/wrtd_rule_tx.png
:name: fig-wrtd-rule-tx
:align: center
:alt: alternate text
:figclass: align-center
TX path of a Rule
.. _alarm:
Alarm
......@@ -151,6 +177,13 @@ An Alarm is simply a user-defined moment to generate internally an input :ref:`e
The :ref:`event_id` of an Alarm will always have a prefix of ``alarm`` or ``ALARM``, followed by any
other characters (always limited to 16 characters, including null-termination).
.. figure:: graphics/wrtd_alarm.png
:name: fig-wrtd-alarm
:align: center
:alt: alternate text
:figclass: align-center
Anatomy of an Alarm
.. _LXI Event Messaging Extended Function specification: http://www.lxistandard.org/members/Adopted%20Specifications/Latest%20Version%20of%20Standards_/LXI%20Standard%201.5%20Specifications/LXI%20Event%20Messaging%20Extended%20Function.pdf
......
doc/introduction.rst
View file @ e01dd91e
......@@ -21,18 +21,23 @@ reception of a particular Message, potentially with some fixed delay added to th
Overview of WRTD
There are two main ways of using WRTD. In scenario #1, a "source" Node simply receives an input
Event, adds a fixed delay to its Timestamp and distributes it to other Nodes. As long as the fixed
delay added is greater than the upper-bound latency of the network (a fundamental feature of WR
itself), all receiving nodes will receive the Message before the programmed time and will execute
simultaneously their action (thanks to the sub-ns synchronisation provided by WR).
In scenario #2, the receiving Nodes are "recording" devices (e.g. digitisers) with a recording
buffer. In this scenario, the source Node transmits the Message, with or without a fixed delay. When
one of the destination Nodes receives the Message, it stops recording and rolls-back its buffer to
the moment specified by the Timestamp in the received Message (provided that it has a large enough
buffer to compensate for the latency). Thus, all Nodes will deliver recorded data from the moment in
the past when the input Event was initially received at the source Node.
There are two main categories of WRTD applications:
#. A "source" Node receives an input Event, adds a fixed delay to its Timestamp and distributes it
to other Nodes. As long as the fixed delay added is greater than the upper-bound latency of the
network (a fundamental feature of WR itself), all receiving nodes will receive the Message before
the programmed time and will execute simultaneously their action (thanks to the sub-ns
synchronisation provided by WR).
#. The receiving Nodes are "recording" devices (e.g. digitisers), capable of storing data in a
recording buffer. Te source Node transmits the Message, with or without a fixed delay. When one
of the destination Nodes receives the Message, it stops recording and rolls-back its buffer to
the moment specified by the Timestamp in the received Message (provided that it has a large
enough buffer to compensate for the latency). Thus, all Nodes will deliver recorded data from the
moment in the past when the input Event was originally received at the source Node.
Of course, the above list is not exhaustive, there are many other potential applications but they
are usually permutations of one of the above scenarios.
In WRTD, the programming of Events, Messages and associated actions is done by defining Rules. A
Rule simply declares a relationship between an input (cause) and an output (effect) Event. A Rule
......@@ -53,9 +58,46 @@ Message is received an output Event should be generated. This is depicted in
.. _lxi:
Relation with LXI
=================
Relation to IVI and LXI
=======================
`LAN eXtensions for Instrumentation (LXI) <http://www.lxistandard.org>`_ is a standard, defining a
communication protocol for the remote control of instrumentation over an Ethernet-based LAN.
Version 1.5 of the LXI splits the specification in two parts:
#. The `LXI Core Specification`_, to which all LXI Devices must conform.
#. A set of optional Extended Functions, to which vendors may choose to conform.
Among these "Extended Functions", several are related to the synchronisation (via IEEE-1588 PTP) and
exchange of real-time event messages between instruments. These include:
* `LXI Event Log Extended Function`_
* `LXI Timestamped Data Extended Function`_
* `LXI Clock Synchronization Extended Function`_
* `LXI Event Messaging Extended Function`_
The core specification requires (Rule 6.1) that all LXI devices provide an `Interchangeable Virtual
Instruments (IVI) <http://ivifoundation.org/>`_ driver. Furthermore, it requires (Rule 6.1.1) that
all LXI devices supporting the exchnage of event messages, do so by providing an API that conforms
to the `IVI-3.15 IviLxiSync Specification`_.
Since the LXI event exchanging mechanism is conceptually very close to WRTD, it was decided to
design WRTD to be as close to LXI as possible. In particular:
* WRTD uses the same :ref:`Message format <message>`. This already allows LXI and WRTD devices on
the same network to exchange events, even if the API for programming these events is different.
* the :ref:`WRTD library API <clib>` mimics that of an IVI driver, with a strong influence from the
`IVI-3.15 IviLxiSync Specification`_, even if several of the :ref:`Repeated Capabilities
<rep_cap>` and :ref:`Attributes <attribute>` are different.
In the future, and with `White Rabbit being standardized within the next release of IEEE-1588
<https://www.ohwr.org/project/wr-std/wikis/home>`_, it is foreseen to try to merge WRTD with
IVI/LXI. A possible way to do this would be to add a new IVI specification, similar to IVI-3.15,
describing the API to control WRTD-enabled devices. This API would be an extension, allowing any
instrument with an IVI driver and a WR interface to exchange event messages with any other WRTD
node.
Document Structure
==================
......@@ -83,3 +125,15 @@ order).
* Last but not least, :numref:`installation` takes you through the necessary steps to setup the
hardware and install the necessary software.
.. _LXI Core Specification: http://www.lxistandard.org/members/Adopted%20Specifications/Latest%20Version%20of%20Standards_/LXI%20Standard%201.5%20Specifications/LXI%20Device%20Specification%20v1_5_01.pdf
.. _LXI Event Log Extended Function: http://www.lxistandard.org/members/Adopted%20Specifications/Latest%20Version%20of%20Standards_/LXI%20Standard%201.5%20Specifications/LXI%20Event%20Log%20Extended%20Function.pdf
.. _LXI Timestamped Data Extended Function: http://www.lxistandard.org/members/Adopted%20Specifications/Latest%20Version%20of%20Standards_/LXI%20Standard%201.5%20Specifications/LXI%20Timestamped%20Data%20Extended%20Function.pdf
.. _LXI Clock Synchronization Extended Function: http://www.lxistandard.org/members/Adopted%20Specifications/Latest%20Version%20of%20Standards_/LXI%20Standard%201.5%20Specifications/LXI%20Clock%20Synchronization%20Extended%20Function.pdf
.. _LXI Event Messaging Extended Function: http://www.lxistandard.org/members/Adopted%20Specifications/Latest%20Version%20of%20Standards_/LXI%20Standard%201.5%20Specifications/LXI%20Event%20Messaging%20Extended%20Function.pdf
.. _IVI-3.15 IviLxiSync Specification: http://www.ivifoundation.org/downloads/Architecture%20Specifications/IVI-3.15_LxiSync_2018-08-23.pdf
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment