Skip to content

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

doc: wip

parent e01dd91e
Hide whitespace changes
Inline Side-by-side
Showing with 101 additions and 22 deletions
doc/basic_concepts.rst
View file @ 785235f6
......@@ -56,10 +56,20 @@ starting from 1 (e.g. ``LC-O1``).
An :ref:`alarm` Event ID will always have a prefix of ``alarm`` or ``ALARM``, followed by any other
characters (always limited to 16 characters, including null-termination).
An Event ID that is filled with null characters is invalid.
All other Event IDs are considered to refer to network :ref:`messages <message>`.
.. attention:: An Event ID that is longer than 16 characters (including null-termination) or that is
filled with null characters is invalid.
.. note:: Rule 6.4.4 of the `LXI Core Specification`_ also defines some reserved Event IDs. These
are:
* ``LXI<x>`` with x being an integer between 0 and 7 (e.g. ``LXI5``)
* ``LAN<x>`` with x being an integer between 0 and 7 (e.g. ``LAN3``)
* ``LXIERROR``
Users are advised to not use these identifiers in their own applications.
.. _timestamp:
Timestamp
......@@ -77,8 +87,12 @@ Timestamps are expressed using a 48-bit counter for seconds, a 32-bit counter fo
is reset every time the counter reaches 10\ :sup:`9`\ ) and a 16-bit counter for fractional
nanoseconds (where every "tick" represents 2\ :sup:`-16`\ ns).
All Timestamps represent `TAI time`_ since ``00:00:00 Thursday, 1 January 1970`` (`Unix Epoch
time`_).
.. hint:: All Timestamps represent `TAI time`_ since ``00:00:00 Thursday, 1 January 1970`` (`Unix
Epoch time`_).
.. hint:: For most applications, the upper 16 bits of the seconds counter can be ignored/assumed to
be zero. A 32-bit seconds counter that was started on ``00:00:00 Thursday, 1 January 1970`` will
overflow on ``06:26:16 Sunday, 7 February 2106``.
.. _local_channel:
......@@ -96,18 +110,18 @@ A Local Channel output receives output Events from the :ref:`node`. Typical exam
external trigger input of a digitiser, a Fine Delay generator or a TTL output channel on a digital
I/O board.
All Local Channels uses reserved :ref:`Event IDs <event_id>`.
All Local Channels use reserved :ref:`Event IDs <event_id>`.
.. _message:
Message
=======
WRTD Event Messages (or, simply, Messages) follow the LXI Event Messaging format, as defined in the
`LXI Event Messaging Extended Function specification`_, revision 1.0.
WRTD Event Messages (or, simply, Messages) follow the LXI Event Messaging format, as defined in Rule
4.3 of the `LXI Event Messaging Extended Function specification`_.
To ensure compatibility and interoperability with LXI devices, WRTD Event Messages are transmitted
using multicast UDP on address 224.0.23.159, port 5044 (Rule 3.3.1 of the specification).
using multicast UDP on address ``224.0.23.159``, port ``5044`` (Rule 3.3.1 of the specification).
Each Message is transmitted as a single Ethernet frame, with a UDP header and a payload as shown in
:numref:`fig-wrtd-message`.
......@@ -125,13 +139,14 @@ The contents of a WRTD Event Message are again based on LXI Event Messages, with
"Flag" fields (octets 3 and 36 respectively) fixed to zero.
Each Message contains an :ref:`event_id`, a :ref:`timestamp` and a sequence number. The latter is a
counter that gets increased by one every time a new Event is generated, to help detect lost or
duplicate Messages.
counter that gets increased by one every time a new Event is generated.
.. hint:: The sequence counter can be used to detect lost or duplicate Messages.
Altough there are currently no "Data Fields" defined (octets 37 and beyond), it should be
highlighted that the LXI Event message format supports an arbitrary number of data fields, in the
form of Type/Length/Value (TLV) triplets, which could be used to provide additional functionality to
WRTD in the future.
.. hint:: Altough there are currently no "Data Fields" defined (octets 37 and beyond), it should be
highlighted that the LXI Event message format supports an arbitrary number of data fields, in the
form of Type/Length/Value (TLV) triplets, which could be used to provide additional functionality
to WRTD in the future.
Please refer to Section 4.3 of the `LXI Event Messaging Extended Function specification`_ for more
details.
......@@ -141,11 +156,54 @@ details.
Repeated Capability
===================
IVI uses the term Repeated Capability to express functionality that is duplicated in an instrument,
with each instance potentially having different settings. A typical example of a Repeated Capability
is a channel of an oscilloscope; the instrument has many channels, each one offering the exact same
functionality, but each one with its own settings (:ref:`Attributes <attribute>`). An instance of a
Repeated Capability is designated by a *Repeated Capability ID*.
Furthermore, IVI defines the API for accessing Repeated Capabilities in Section 12 of `IVI-3.4: API
Style Guide`_.
WRTD defines the following Repeated Capabilities:
* :ref:`rule` (see also :ref:`api_rule`)
* :ref:`alarm` (see also :ref:`api_alarm`)
* :ref:`application`
WRTD uses the *Parameter Style* API, defined in Section 12.1 of `IVI-3.4: API Style Guide`_, where
each function related to a Repeated Capability expects the ID of the Repeated Capability instance as
a parameter. This parameter is also called a Repeated Capability *Selector* in IVI terminology.
.. hint:: Section 4.4 of `IVI-3.1: Driver Architecture Specification`_ shows that a Selector can
include groups of IDs, ranges, nested IDs and much more. For now, WRTD only supports *simple
selectors*, allowing a single ID to be selected at a time, but this could change in future
releases.
.. _attribute:
Attribute
=========
WRTD uses Attributes to represent the various settings of the instrument and defines get/set
functions to access them. This behaviour is identical to IVI.
Attributes can be of one of the following types:
* Boolean
* Integer
* String
* Timestamp
Attributes can be attached to a :ref:`rep_cap`, or they can be "global" (apply to the whole
Node).
.. note:: Since global Attributes are not attached to any :ref:`rep_cap`, when using one of the
functions to get/set a global Attribute, a special Repeated Capability ID must be passed to the
function (:c:macro:`WRTD_GLOBAL_REP_CAP_ID`) as the Selector.
Please refer to the :ref:`api_attr_list` and the :ref:`api_attr` for more details.
.. _rule:
Rule
......@@ -185,8 +243,20 @@ other characters (always limited to 16 characters, including null-termination).
Anatomy of an Alarm
.. _application:
Application
===========
.. _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 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
.. _IVI-3.1\: Driver Architecture Specification: http://ivifoundation.org/downloads/Architecture%20Specifications/IVIspecstopost10-22-2018/IVI-3.1_Architecture_2018-10-19.pdf
.. _IVI-3.4\: API Style Guide: http://ivifoundation.org/downloads/Architecture%20Specifications/IVIspecstopost10-22-2018/IVI-3.4_APIStyleGuide_2018-10-19.pdf
.. _TAI time: https://en.wikipedia.org/wiki/International_Atomic_Time
.. _Unix Epoch time: https://en.wikipedia.org/wiki/Unix_time
doc/usage.rst
View file @ 785235f6
......@@ -18,8 +18,11 @@ WRTD Error Codes
----------------
.. doxygenenum:: wrtd_status
WRTD Attributes
---------------
.. _api_attr_list:
List of Attributes
------------------
.. doxygenenum:: wrtd_attr
.. doxygendefine:: WRTD_GLOBAL_REP_CAP_ID
......@@ -34,8 +37,10 @@ Initialisation
.. doxygenfunction:: wrtd_close
.. doxygenfunction:: wrtd_reset
Attribute Handling
++++++++++++++++++
.. _api_attr:
Attribute Handling API
++++++++++++++++++++++
.. doxygenfunction:: wrtd_set_attr_bool
.. doxygenfunction:: wrtd_get_attr_bool
......@@ -60,8 +65,10 @@ Event Log
.. doxygenfunction:: wrtd_clear_event_log_entries
.. doxygenfunction:: wrtd_get_next_event_log_entry
Alarms
++++++
.. _api_alarm:
Alarms API
++++++++++
.. doxygenfunction:: wrtd_add_alarm
.. doxygenfunction:: wrtd_disable_all_alarms
......@@ -69,8 +76,10 @@ Alarms
.. doxygenfunction:: wrtd_remove_all_alarms
.. doxygenfunction:: wrtd_get_alarm_name
Rules
+++++
.. _api_rule:
Rules API
+++++++++
.. doxygenfunction:: wrtd_add_rule
.. doxygenfunction:: wrtd_disable_all_rules
......
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