Commit 71657cc9 authored by Javier Serrano's avatar Javier Serrano Committed by Dimitris Lampridis

[doc] review of documentation

parent da3f42d9
......@@ -119,7 +119,7 @@ a digital I/O board.
A Local Channel output transmits output Events from the :ref:`node`. Typical examples include a Fine
Delay generator or a TTL output channel on a digital I/O board.
All Local Channels use reserved :ref:`Event IDs <event_id>`.
All Local Channels use specific IDs as described in :ref:`Event IDs <event_id>`.
.. _message:
......@@ -152,7 +152,7 @@ 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.
.. hint:: Altough there are currently no "Data Fields" defined (octets 37 and beyond), it should be
.. hint:: Although 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.
......@@ -217,8 +217,8 @@ Attributes can be attached to a :ref:`rep_cap`, or they can be "global" (apply t
:ref:`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 :ref:`rep_cap_id` must be passed to the
function (:c:macro:`WRTD_GLOBAL_REP_CAP_ID`) as the Selector.
functions to get/set a global Attribute, a special :ref:`rep_cap_id`
(:c:macro:`WRTD_GLOBAL_REP_CAP_ID`) must be passed to the function as the Selector.
Please refer to the :ref:`api_attr` for more details.
......
......@@ -116,7 +116,8 @@ Other than that, the only requirement on the hardware is that it supports `White
<https://www.ohwr.org/project/white-rabbit>`_.
If you are designing your own board and you would like to have something as a reference, here's a
few open-source boards that already support WR:
page which can `help you <https://www.ohwr.org/project/white-rabbit/wikis/WRReferenceDesign>`_, or,
more specifically, here's a list with a few open-source boards that already support WR:
* `SPEC <https://www.ohwr.org/projects/spec/wikis>`_ (Xilinx Spartan6 FPGA)
* `FASEC <https://www.ohwr.org/projects/fasec/wikis>`_ (Xilinx Zynq SoC FPGA)
......
.. _introduction:
ssh://git@ohwr.org:7999/project/wrtd.git.. _introduction:
------------
Introduction
......@@ -9,7 +9,7 @@ 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
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
......@@ -30,7 +30,7 @@ There are two main categories of WRTD applications:
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
recording buffer. 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
......@@ -80,7 +80,7 @@ exchange of real-time event messages between instruments. These include:
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
all LXI devices supporting the exchange 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
......@@ -95,7 +95,7 @@ design WRTD to be as close to LXI as possible. In particular:
.. hint:: Do not worry if you do not understand some of the terminology yet. It will be explained in
:numref:`basic_concepts`.
In the future, and with `White Rabbit being standardized within the next release of IEEE-1588
In the future, and with `White Rabbit being standardised 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
......
......@@ -75,7 +75,7 @@ The five :ref:`Local Input Channels <local_channel>` are mapped as follows:
.. note:: In order for any of the :ref:`Local Input Channels <local_channel>` to produce an
:ref:`event`, the user must also properly configure the trigger source of the FMC-ADC via
the ADC library. This falls outside the the scope of WRTD library.
the ADC library. This falls outside the scope of WRTD library.
The single :ref:`Local Output Channel <local_channel>` (``LC-O1``) is mapped to the "WRTD" trigger
input of the FMC-ADC.
......
......@@ -39,12 +39,12 @@ This is a WRTD :ref:`node` based on the `Simple VME FMC Carrier (SVEC)
the FMCs attached, the :ref:`Node` will work if only one of the two (TDC or FD) is
present, as long as it is connected to the correct FMC slot.
The basic principle of this :ref:`node` is simple: It takes in external pulses on its FMC-TDC
The basic principle of this :ref:`node` is simple: it takes in external pulses on its FMC-TDC
inputs, timestamps them using WR time and converts them to WRTD :ref:`Messages <message>`, to be
sent over the WR network. Conversely, the :ref:`node` also receives WRTD :ref:`Messages <message>`
which are then used to generate pulses at a predefined moment on one of the FMC-FD outputs. As such,
it can be seen as a "pulse-to-message" and "message-to-pulse" converter with apllications in the
field of pulse distribution, trigger syncrhonisation, etc.
fields of pulse distribution, trigger synchronisation, etc.
.. figure:: graphics/wrtd_ref_design_svec_list_simple.png
:name: fig-ref_svec_list
......
......@@ -167,11 +167,13 @@ parameter should be set to :c:macro:`WRTD_GLOBAL_REP_CAP_ID`.
int main(void) {
wrtd_dev *wrtd;
wrtd_status status;
bool log_empty;
status = wrtd_init("MT01", false, NULL, &wrtd);
status = wrtd_get_attr_bool(wrtd, WRTD_GLOBAL_REP_CAP_ID,
WRTD_ATTR_EVENT_LOG_EMPTY);
WRTD_ATTR_EVENT_LOG_EMPTY,
&log_empty);
wrtd_close(wrtd);
}
......@@ -350,12 +352,12 @@ Configuration of an Alarm happens by setting the relevant :ref:`Attributes <attr
status = wrtd_remove_all_alarms(wrtd);
/* Add three alarms */
status = wrtd_add_alarm("alarm1");
status = wrtd_add_alarm("alarm2");
status = wrtd_add_alarm("alarm3");
status = wrtd_add_alarm(wrtd, "alarm1");
status = wrtd_add_alarm(wrtd, "alarm2");
status = wrtd_add_alarm(wrtd, "alarm3");
/* Remove the 2nd alarm */
status = wrtd_remove_alarm("alarm2");
status = wrtd_remove_alarm(wrtd, "alarm2");
/* Get number of defined alarms */
status = wrtd_get_attr_int32(wrtd, WRTD_GLOBAL_REP_CAP_ID,
......@@ -409,12 +411,12 @@ Configuration of a Rule happens by setting the relevant :ref:`Attributes <attrib
status = wrtd_remove_all_rules(wrtd);
/* Add three rules */
status = wrtd_add_rule("rule1");
status = wrtd_add_rule("rule2");
status = wrtd_add_rule("rule3");
status = wrtd_add_rule(wrtd, "rule1");
status = wrtd_add_rule(wrtd, "rule2");
status = wrtd_add_rule(wrtd, "rule3");
/* Remove the 2nd rule */
status = wrtd_remove_rule("rule2");
status = wrtd_remove_rule(wrtd, "rule2");
/* Get number of defined rules */
status = wrtd_get_attr_int32(wrtd, WRTD_GLOBAL_REP_CAP_ID,
......@@ -446,7 +448,7 @@ Configuration of a Rule happens by setting the relevant :ref:`Attributes <attrib
status = wrtd_init("MT01", false, NULL, &wrtd);
/* Add a rule */
status = wrtd_add_rule("rule1");
status = wrtd_add_rule(wrtd, "rule1");
/* Set rule to listen for events coming on local channel
input 1 and generate a message on the network with
......
......@@ -180,7 +180,7 @@ Alarms API
>>> wrtd.set_attr_bool('alarm1', PyWrtd.WRTD_ATTR_ALARM_ENABLED, True)
>>> wrtd.get_attr_bool('alarm1', PyWrtd.WRTD_ATTR_ALARM_ENABLED)
True
>>> wrtd.disable_all_rules()
>>> wrtd.disable_all_alarms()
>>> wrtd.get_attr_bool('alarm1', PyWrtd.WRTD_ATTR_ALARM_ENABLED)
False
......@@ -207,7 +207,7 @@ Alarms API
.. automethod:: PyWrtd.get_alarm_name
.. code-block:: python
>>> wrtd.add_rule('alarm1')
>>> wrtd.add_alarm('alarm1')
>>> count = wrtd.get_attr_int32(PyWrtd.WRTD_GLOBAL_REP_CAP_ID, PyWrtd.WRTD_ATTR_ALARM_COUNT)
>>> print(count)
1
......
......@@ -28,7 +28,7 @@ typedef struct wrtd_tstamp {
/** 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. */
/** Number of nanoseconds. Wraps at 1e9. */
uint32_t ns;
/** Number of fractional nanoseconds. Unit is 2e-32 ns. */
uint32_t frac;
......
......@@ -953,7 +953,7 @@ wrtd_status wrtd_get_attr_tstamp(wrtd_dev *wrtd,
* - `log tstamp` is the timestamp of when the event was logged.
* - `event tstamp` is the timestamp of when the event happened.
* - `log type` is the type of the event.
* - `log tstamp` is the specific reason for this type of event.
* - `log reason` is the specific reason for this type of event.
*
* All event log entries have a fixed length of #WRTD_LOG_ENTRY_SIZE.
*
......@@ -973,7 +973,7 @@ wrtd_status wrtd_get_attr_tstamp(wrtd_dev *wrtd,
* finished executing. The exact meaning of this log type is application-specific.
* - `DISCARDED|NO SYNC` : An Event was discarded because the device was not syncrhonized
to White Rabbit. See also #WRTD_ATTR_STAT_RULE_MISSED_NOSYNC.
* - `DISCARDED|HOLD OFF`: An Event was discarded because violated the programmed hold-off
* - `DISCARDED|HOLD OFF`: An Event was discarded because it violated the programmed hold-off
* value. See also #WRTD_ATTR_STAT_RULE_MISSED_HOLDOFF.
* - `DISCARDED|TIME OUT`: An Event was discarded because it arrived too late. See also
* #WRTD_ATTR_STAT_RULE_MISSED_LATE.
......
......@@ -98,7 +98,7 @@ typedef enum wrtd_attr {
/** `RO` `bool` `global` True if the Event Log is empty. */
WRTD_ATTR_EVENT_LOG_EMPTY = __WRTD_ATTR_BASE + 0x00,
/** `RW` `bool` `global` Enable/dsiable the Event Log. */
/** `RW` `bool` `global` Enable/disable the Event Log. */
WRTD_ATTR_EVENT_LOG_ENABLED = __WRTD_ATTR_BASE + 0x01,
/** `RO` `bool` `global` True if the device is synchronized to White Rabbit time. */
WRTD_ATTR_IS_TIME_SYNCHRONIZED = __WRTD_ATTR_BASE + 0x02,
......@@ -128,16 +128,16 @@ typedef enum wrtd_attr {
/** `RW` `bool` `rule` Enable/disable a Rule. */
WRTD_ATTR_RULE_ENABLED = __WRTD_ATTR_BASE + 0x21,
/** `RW` `int32` `rule` Specifies the number of times a Rule will fire before becoming
automatically disabled. 0 means infinite. 1 means that the alarm will fire only once.
automatically disabled. 0 means infinite. 1 means that the Rule will fire only once.
When read, it returns the remaining repetitions. */
WRTD_ATTR_RULE_REPEAT_COUNT = __WRTD_ATTR_BASE + 0x22,
/** `RW` `string` `rule` Get/set Rule source. Rule sources can be:
- Local source Event IDs (in the form of **LCI-x**)
- Local source Event IDs (in the form of **LC-I<x>**)
- Alarm IDs (any ID with an **alarm** prefix)
- Any other string which will be interpreted as a network message Event ID. */
WRTD_ATTR_RULE_SOURCE = __WRTD_ATTR_BASE + 0x23,
/** `RW` `string` `rule` Get/set Rule destinations. Rule destinations can be:
- Local destination Event IDs (in the form of **LCO-x**)
- Local destination Event IDs (in the form of **LC-O<x>**)
- Any other string which will be interpreted as a network message Event ID. */
WRTD_ATTR_RULE_DESTINATION = __WRTD_ATTR_BASE + 0x24,
/** `RW` `bool` `rule` If true, events that arrive late (with a timestamp in
......
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