doc: wip

8379ee5b · Dimitris Lampridis · f0e7ca99 · 8379ee5b · 8379ee5b · 8379ee5b
Commit 8379ee5b authored Jul 03, 2019 by Dimitris Lampridis
10 changed files
--- a/doc/basic_concepts.rst
+++ b/doc/basic_concepts.rst
+.. _basic_concepts:
+
+--------------
+Basic Concepts
+--------------
+
+This section introduces the various basic concepts of WRTD. These concepts are used throughout this
+document and are fundamental to understanding how WRTD works (and, by extension, how to use it).
+
+.. _node:
+
+Node
+====
+
+WRTD is made of Nodes, connected to each other over a WR network. Nodes receive input :ref:`Events
+<event>` and send output :ref:`Events <event>`. See also :numref:`fig-wrtd-overview`.
+
+Every Node has :ref:`local_channel` inputs and/or outputs allowing it to interact with its
+environment. It also has a connection to a WR network, allowing it to send and/or receive
+:ref:`Messages <message>` to other Nodes.
+
+.. _event:
+
+Event
+=====
+
+Events represent inputs and outputs of a WRTD :ref:`node`. Input Events received on a :ref:`node`
+will result in an output Event to be generated (assuming that the relevant :ref:`rule` exists to
+associate an input to an output). In that sense, inputs Events are the causes, while output Events
+are the effects.
+
+Input Events can be either a :ref:`local_channel`, an inbound network :ref:`message`, or an
+:ref:`alarm`.
+
+Output Events can be either a :ref:`local_channel`, or an outbound network :ref:`message`.
+
+An Event is essentially a combination of an :ref:`event_id` (the "what") and a :ref:`timestamp` (the
+"when").
+
+.. _event_id:
+
+Event ID
+--------
+
+Every :ref:`event` is represented by an ID.
+
+Event IDs are 15-character, null-terminated (for a total length of 16) strings that uniquely
+identify an input or output Event.
+
+:ref:`local_channel` inputs always use an Event ID in the form of ``LC-I<x>``, where x is a number
+starting from 1 (e.g. ``LC-I1``).
+
+:ref:`local_channel` outputs always use an Event ID in the form of ``LC-O<x>``, where x is a number
+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>`.
+
+.. _timestamp:
+
+Timestamp
+---------
+
+Every :ref:`event` has an associated Timestamp.
+
+For an input :ref:`event`, the Timestamp typically represents the moment in time when the
+:ref:`event` happened.
+
+For an output :ref:`event`, the Timestamp typically represents the moment in time when the
+:ref:`event` should happen.
+
+Timestamps are expressed using a 48-bit counter for seconds, a 32-bit counter for nanoseconds (which
+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`_).
+
+.. _local_channel:
+
+Local Channel
+=============
+
+Local Channels represent the connections of a :ref:`node` to its environment. They can be either
+inputs or outputs.
+
+A Local Channel input delivers input Events to the :ref:`node`. Typical examples include the
+external trigger output of a digitiser, a Time to Digital Converter (TDC) or a TTL input channel on
+a digital I/O board.
+
+A Local Channel output receives output Events from the :ref:`node`. Typical examples include the
+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>`.
+
+.. _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.
+
+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).
+
+Each Message is transmitted as a single Ethernet frame, with a UDP header and a payload as shown in
+:numref:`fig-wrtd-message`.
+
+
+.. figure:: graphics/wrtd_message.png
+   :name: fig-wrtd-message
+   :align: center
+   :alt: alternate text
+   :figclass: align-center
+
+   Contents of a WRTD Event Message
+
+The contents of a WRTD Event Message are again based on LXI Event Messages, with the "Domain" and
+"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.
+
+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.
+
+.. _rule:
+
+Rule
+====
+
+.. _alarm:
+
+Alarm
+=====
+
+An Alarm is simply a user-defined moment to generate internally an input :ref:`event`.
+
+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).
+
+
+.. _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
+
+.. _TAI time: https://en.wikipedia.org/wiki/International_Atomic_Time
+
+.. _Unix Epoch time: https://en.wikipedia.org/wiki/Unix_time
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -67,7 +67,7 @@ author = u'Dimitris Lampridis <dimitris.lampridis@cern.ch'
 # The short X.Y version.
 version = u'1.0'
 # The full version, including alpha/beta/rc tags.
-release = u'1.0.0'
+release = u'1.0'

 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -245,6 +245,8 @@ htmlhelp_basename = 'WhiteRabbitTriggerDistributiondoc'

 # -- Options for LaTeX output ---------------------------------------------

+latex_engine = 'xelatex'
+
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     #
@@ -252,11 +254,17 @@ latex_elements = {

     # The font size ('10pt', '11pt' or '12pt').
     #
-     # 'pointsize': '10pt',
+     'pointsize': '11pt',
+
+     'fontpkg': r'''
+     \setmainfont{Bitstream Charter}
+     \setsansfont{Lato}
+     \setmonofont{Inconsolata}
+     ''',

     # Additional stuff for the LaTeX preamble.
     #
-     # 'preamble': '',
+     # 'preamble' : '',

     # Latex figure (float) alignment
     #
@@ -293,7 +301,7 @@ latex_documents = [
 #
 # latex_appendices = []

-# It false, will not define \strong, \code, 	itleref, \crossref ... but only
+# It false, will not define \strong, \code,     itleref, \crossref ... but only
 # \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added
 # packages.
 #

--- a/doc/devel.rst
+++ b/doc/devel.rst
+.. _devel:
+
+-----------
+Development
+-----------
+
+.. _hw_dev:
+
+Hardware
+========
+
+.. _gw_dev:
+
+Gateware
+========
+
+.. _fw_dev:
+
+Firmware
+========
+
+
+
+
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -8,18 +8,15 @@ White Rabbit Trigger Distribution documentation
 ===============================================

 .. toctree::
-   :maxdepth: 4
-   :caption: Contents
+   :maxdepth: 2
+   :numbered:
+   :caption: Table of Contents

   introduction
-   wrtd_message
-   wrtd_api
+   installation
+   basic_concepts
+   usage
+   ref_nodes
+   devel

 .. todolist::
-
-Indices and tables
------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
--- a/doc/installation.rst
+++ b/doc/installation.rst
+.. _installation:
+
+------------
+Installation
+------------
+
+.. todo::
+   Decide on installation and document it
+
--- a/doc/introduction.rst
+++ b/doc/introduction.rst
+.. _introduction:
+
 ------------
 Introduction
 ------------

 White Rabbit Trigger Distribution (WRTD) is a generic framework for distributing triggers (Events)
-over a White Rabbit network.
+over a White Rabbit (WR) network.
+
+As can be seen in :numref:`fig-wrtd-overview`, WRTD Nodes receive "input" Events and distribute them
+to other Nodes over WR in the form of network Messages that are used to transfer the Timestamp of
+the input Event. The receiving Nodes are programmed to execute some "output Event (action) upon
+reception of a particular Message, potentially with some fixed delay added to the Timestamp.

 .. figure:: graphics/wrtd_overview.png
-   :name: wrtd-overview
+   :name: fig-wrtd-overview
+   :width: 400pt
+   :align: center
+   :alt: alternate text
+   :figclass: align-center
+
+   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.
+
+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
+can state that when a specific Event is received a Message should be transmitted or, that when a
+Message is received an output Event should be generated. This is depicted in
+:numref:`fig-wrtd-node`.
+
+.. figure:: graphics/wrtd_node_basic.png
+   :name: fig-wrtd-node
+   :width: 300pt
   :align: center
   :alt: alternate text
   :figclass: align-center

-   figure are like images but with a caption
+   Inside a WRTD Node
+
+:numref:`basic_concepts` provides a more elaborate discussion on the various basic concepts of WRTD.
+
+.. _lxi:
+
+Relation with LXI
+=================
+

-As can be seen in :numref:`wrtd-overview`
+Document Structure
+==================

-Installation
-============
-.. todo::
-   Decide on installation and document it
+The following is a description of how the remainder of this document is structured (in reverse
+order).

-Major WRTD Elements
-===================
+* :numref:`devel` provides guidelines on how to develop a WRTD Node, including hardware
+  (:numref:`hw_dev`), gateware (:numref:`gw_dev`) and firmware (:numref:`fw_dev`).

-Internally, WRTD consists of the following elements:
+* Before you embark however on a new design, please have a look first at the existing reference
+  designs. :numref:`ref_nodes` presents the currently available reference WRTD Nodes that come
+  pre-programmed with their gateware and firmware.

-  - An HDL module for FPGAs, built on top of `Mock Turtle <https://ohwr.org/project/mock-turtle>`_
-    (MT) and the `White Rabbit PTP Core <https://ohwr.org/project/wr-cores/wikis/Wrpc-core>`_. When
-    instantiated in an FPGA, this module handles the generation/reception of triggers, while
-    providing the user with MT cores to run their own application(s) (eg. to control an ADC).
-  - An embedded library framework for (MT) firmware development. This library can be used when
-    developing firmware for the MT cores, in order to connect user applications with the
-    generation/reception of triggers.
-  - A host library framework that provides a way for configuring the WRTD nodes and scheduling the
-    generation/reception of triggers.
+* Whether you develop your own Node or use one of the reference Nodes, :numref:`usage` describes how
+  to access and control your Node. :numref:`clib` provides all the details on how to use the C
+  library to develop your own applications. Alternatively, :numref:`pywrap` presents a Python
+  wrapper to the C library that can be used to develop Python-based applications. :numref:`tools`
+  describes the generic tools that are built using the Python wrapper and that provide access to a
+  WRTD node without the need to develop any application.

-However, for most use cases, only the last element (the host library) will be of importance to the
-user, since a device will come pre-programmed with the necessary gateware and firmware.
+* :numref:`basic_concepts` introduces the various basic concepts of WRTD. These concepts are used
+  throughout this document and are fundamental to understanding how WRTD works (and, by extension,
+  how to use it).

-Section :ref:`host_lib` provides all the details on how to use the host library.
+* Last but not least, :numref:`installation` takes you through the necessary steps to setup the
+  hardware and install the necessary software.
--- a/doc/ref_nodes.rst
+++ b/doc/ref_nodes.rst
+.. _ref_nodes:
+
+---------------
+Reference Nodes
+---------------
+
+SPEC150T-based FMC-ADC
+======================
+
+SVEC-based TDC+FDELAY
+=====================
--- a/doc/wrtd_api.rst
+++ b/doc/wrtd_api.rst
-.. _host_lib:
+.. _usage:

-----------------
-WRTD Host Library
-----------------
+-----
+Usage
+-----
+
+.. _clib:
+
+WRTD Library
+============

 WRTD Timestamps
-===============
+---------------
 .. doxygenstruct:: wrtd_tstamp
                   :members:

 WRTD Error Codes
-================
+----------------
 .. doxygenenum:: wrtd_status

 WRTD Attributes
-===============
+---------------
 .. doxygenenum:: wrtd_attr

 .. doxygendefine:: WRTD_GLOBAL_REP_CAP_ID

 WRTD API
-========
+--------

 Initialisation
--------------
++++++++++++++

 .. doxygenfunction:: wrtd_init
 .. doxygenfunction:: wrtd_close
 .. doxygenfunction:: wrtd_reset

 Attribute Handling
------------------
++++++++++++++++++

 .. doxygenfunction:: wrtd_set_attr_bool
 .. doxygenfunction:: wrtd_get_attr_bool
@@ -42,13 +47,13 @@ Attribute Handling
 .. doxygenfunction:: wrtd_get_attr_tstamp

 Error Handling
--------------
++++++++++++++

 .. doxygenfunction:: wrtd_get_error
 .. doxygenfunction:: wrtd_error_message

 Event Log
---------
+++++++++

 .. doxygendefine:: WRTD_LOG_ENTRY_SIZE

@@ -56,7 +61,7 @@ Event Log
 .. doxygenfunction:: wrtd_get_next_event_log_entry

 Alarms
------
++++++

 .. doxygenfunction:: wrtd_add_alarm
 .. doxygenfunction:: wrtd_disable_all_alarms
@@ -65,7 +70,7 @@ Alarms
 .. doxygenfunction:: wrtd_get_alarm_name

 Rules
-----
+++++

 .. doxygenfunction:: wrtd_add_rule
 .. doxygenfunction:: wrtd_disable_all_rules
@@ -73,3 +78,14 @@ Rules
 .. doxygenfunction:: wrtd_remove_all_rules
 .. doxygenfunction:: wrtd_get_rule_name
 .. doxygenfunction:: wrtd_reset_rule_stats
+
+.. _pywrap:
+
+Python Library
+--------------
+
+.. _tools:
+
+Tools
+-----
+
--- a/doc/wrtd_message.rst
+++ b/doc/wrtd_message.rst
-.. _wrtd_message:
-
-------------------
-WRTD Event Messages
-------------------
-
-WRTD Event messages follow the LXI Event Messaging format, as defined in the "LXI Event Messaging
-Extended Function" specification, revision 1.0.
-
-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 LXI Event Messaging
-Extended Function).
-
-Each Event message is transmitted as a single Ethernet frame, with a UDP header and a payload as
-shown in :numref:`fig-wrtd-message`.
-
-
-.. figure:: graphics/wrtd_message.png
-   :name: fig-wrtd-message
-   :align: center
-   :alt: alternate text
-   :figclass: align-center
-
-   Contents of a WRTD Event message
-
-The contents of a WRTD Event message are again based on LXI Event messages, with the "Domain" and
-Flag fields (octets 3 and 36 respectively) fixed to zero.
-
-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.
--- a/software/include/wrtd-common.h
+++ b/software/include/wrtd-common.h
@@ -25,7 +25,8 @@
 */
 // TODO: maybe distinguish between UTC and TAI
 typedef struct wrtd_tstamp {
-        /** TAI seconds since 1/1/1970 (Unix Epoch Time). */
+        /** TAI seconds since 1/Jan/1970 (Unix Epoch Time).
+            This will overflow in 7/Feb/2106... */
        uint32_t seconds;
        /** Number of nanoseconds. Wraps at 10e9. */
        uint32_t ns;