Skip to content

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

doc: wip

parent a575fbae
Hide whitespace changes
Inline Side-by-side
Showing with 140 additions and 42 deletions
doc/basic_concepts.rst
View file @ bc19c9e1
......@@ -159,22 +159,31 @@ 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*.
functionality, but each one with its own settings (:ref:`Attributes <attribute>`).
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:
WRTD defines the following Repeated Capabilities for each :ref:`node`:
* :ref:`rule` (see also :ref:`api_rule`)
* :ref:`alarm` (see also :ref:`api_alarm`)
* :ref:`application`
* :ref:`application` (see also :ref:`api_app`)
.. _rep_cap_id:
Repeated Capability ID
----------------------
An instance of a :ref:`rep_cap` is designated by a unique Repeated Capability ID.
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.
.. note:: Similar to an :ref:`event_id`, a Repeated Capability ID is limited to 16 characters,
including null termination.
.. 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
......@@ -185,21 +194,21 @@ a parameter. This parameter is also called a Repeated Capability *Selector* in I
Attribute
=========
WRTD uses Attributes to represent the various settings of the instrument and defines get/set
WRTD uses Attributes to represent the various settings of the :ref:`node` 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
* 32-bit Integer
* String
* Timestamp
* Timestamp (new type, does not exist in IVI)
Attributes can be attached to a :ref:`rep_cap`, or they can be "global" (apply to the whole
Node).
: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 Repeated Capability ID must be passed to 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.
Please refer to the :ref:`api_attr_list` and the :ref:`api_attr` for more details.
......@@ -209,13 +218,27 @@ Please refer to the :ref:`api_attr_list` and the :ref:`api_attr` for more detail
Rule
====
A Rule is a :ref:`rep_cap` instance inside a :ref:`node` that links input to output :ref:`Events
<event>`.
Rules are declared (and deleted) using the :ref:`api_rule`. Their configuration is controlled via
:ref:`Attributes <attribute>` that can be manipulated using the :ref:`api_attr`.
When an input :ref:`event` is received by a :ref:`Node`, WRTD tries to match it with any declared
(and enabled) Rule. The process that is followed for each input :ref:`event` is depicted in
:numref:`fig-wrtd-rule-rx`.
.. figure:: graphics/wrtd_rule_rx.png
:name: fig-wrtd-rule-rx
:align: center
:alt: alternate text
:figclass: align-center
RX path of a Rule
RX path of a Rule. The red hexagons represent :ref:`Attributes <attribute>`.
Once an input :ref:`event` has been matched and all delays have been applied to it, it is forwarded
to the next processing block that generates the preconfigured output :ref:`event`. This is depicted
in :numref:`fig-wrtd-rule-tx`.
.. figure:: graphics/wrtd_rule_tx.png
:name: fig-wrtd-rule-tx
......@@ -223,7 +246,12 @@ Rule
:alt: alternate text
:figclass: align-center
TX path of a Rule
TX path of a Rule. The red hexagons represent :ref:`Attributes <attribute>`.
.. hint:: There are actually more :ref:`Attributes <attribute>` than the ones shown in
:numref:`fig-wrtd-rule-rx` and :numref:`fig-wrtd-rule-tx`. Please refer to the
:ref:`api_attr_list` for the complete list, as well as an explanation of each
:ref:`Attribute`.
.. _alarm:
......@@ -232,8 +260,20 @@ 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).
Similar to a :ref:`Rule`, an Alarm is a :ref:`rep_cap` instance inside a :ref:`node`
Alarms are declared (and deleted) using the :ref:`api_alarm`. Their configuration is controlled via
:ref:`Attributes <attribute>` that can be manipulated using the :ref:`api_attr`.
.. note:: The :ref:`rep_cap_id` of an Alarm must always have a prefix of ``alarm`` or ``ALARM``,
followed by any other characters (always limited to 16 characters, including
null-termination).
The :ref:`event_id` of the input :ref:`event` generated by an Alarm will match its
:ref:`rep_cap_id`.
Every :ref:`node` checks periodically if any of the declared (and enabled) Alarms need to be
triggered, following the process depicted in :numref:`fig-wrtd-alarm`.
.. figure:: graphics/wrtd_alarm.png
:name: fig-wrtd-alarm
......@@ -243,11 +283,29 @@ other characters (always limited to 16 characters, including null-termination).
Anatomy of an Alarm
.. hint:: There are actually more :ref:`Attributes <attribute>` than the ones shown in
:numref:`fig-wrtd-alarm`. Please refer to the :ref:`api_attr_list` for the complete list,
as well as an explanation of each :ref:`Attribute`.
.. _application:
Application
===========
A :ref:`node` may be running one or more Applications (firmware). As an example, the
:ref:`spec150t_ref_adc` runs a single Application (to communicate with the ADC), while the
:ref:`svec_ref_tdc_fd` runs two Applications (one for the TDC and one for the Fine Delay generator).
As such, an Application is also a :ref:`rep_cap` instance inside a :ref:`node`.
Unlike :ref:`Rules <rule>` and :ref:`Alarms <alarm>`, users cannot declare or remove
Applications. They can only get their (read-only) :ref:`Attributes <attribute>` which provide
information regarding firmware version, number and direction of :ref:`Local Channels
<local_channel>`, etc.
Please refer to the :ref:`api_attr_list` for the complete list of Application-related
:ref:`Attributes <attribute>`. The :ref:`rep_cap_id` of each Application can be retrieved using the
:ref:`api_app`.
.. _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
......
doc/ref_nodes.rst
View file @ bc19c9e1
......@@ -4,8 +4,12 @@
Reference Nodes
---------------
.. _spec150t_ref_adc:
SPEC150T-based FMC-ADC
======================
.. _svec_ref_tdc_fd:
SVEC-based TDC+FDELAY
=====================
doc/usage.rst
View file @ bc19c9e1
......@@ -88,6 +88,13 @@ Rules API
.. doxygenfunction:: wrtd_get_rule_name
.. doxygenfunction:: wrtd_reset_rule_stats
.. _api_app:
Applications API
++++++++++++++++
.. doxygenfunction:: wrtd_get_fw_name
.. _pywrap:
Python Library
......@@ -97,4 +104,3 @@ Python Library
Tools
-----
software/lib/libwrtd.c
View file @ bc19c9e1
......@@ -162,8 +162,9 @@ wrtd_status wrtd_reset(wrtd_dev *wrtd)
}
/**
* Retrieve and clear the last error from the device. Modelled after the IVI-C
* GetError function.
* Retrieve and clear the last error from the device.
*
* Modelled after the IVI-C GetError function.
*
* This function complies with IVI-3.2, section 3.1.2.1 (Additional Compliance Rules
* for C Functions with ViChar Array Output Parameters), with the exception of
......@@ -237,8 +238,9 @@ wrtd_status wrtd_get_error(wrtd_dev *wrtd,
}
/**
* Convert a #wrtd_status error code to a string. Modelled after the IVI-C
* ErrorMessage function.
* Convert a #wrtd_status error code to a string.
*
* Modelled after the IVI-C ErrorMessage function.
*
* @param[in] wrtd Device token. Can be NULL to allow calling this function
* even when initialisation has failed.
......@@ -354,8 +356,9 @@ wrtd_status wrtd_error_message(wrtd_dev *wrtd,
*/
/**
* Set an attribute of type `bool`. Modelled after the IVI-C
* SetAttribute family of functions.
* Set an attribute of type `bool`.
*
* Modelled after the IVI-C SetAttribute family of functions.
*
* @param[in] wrtd Device token.
* @param[in] rep_cap_id ID (string) of concerned repeated capability.
......@@ -407,8 +410,9 @@ wrtd_status wrtd_set_attr_bool(wrtd_dev *wrtd,
}
/**
* Get an attribute of type `bool`. Modelled after the IVI-C
* GetAttribute family of functions.
* Get an attribute of type `bool`.
*
* Modelled after the IVI-C GetAttribute family of functions.
*
* @param[in] wrtd Device token.
* @param[in] rep_cap_id ID (string) of concerned repeated capability.
......@@ -474,8 +478,9 @@ wrtd_status wrtd_get_attr_bool(wrtd_dev *wrtd,
}
/**
* Set an attribute of type `int32`. Modelled after the IVI-C
* SetAttribute family of functions.
* Set an attribute of type `int32`.
*
* Modelled after the IVI-C SetAttribute family of functions.
*
* @param[in] wrtd Device token.
* @param[in] rep_cap_id ID (string) of concerned repeated capability.
......@@ -537,8 +542,9 @@ wrtd_status wrtd_set_attr_int32(wrtd_dev *wrtd,
}
/**
* Get an attribute of type `int32`. Modelled after the IVI-C
* GetAttribute family of functions.
* Get an attribute of type `int32`.
*
* Modelled after the IVI-C GetAttribute family of functions.
*
* @param[in] wrtd Device token.
* @param[in] rep_cap_id ID (string) of concerned repeated capability.
......@@ -671,8 +677,9 @@ wrtd_status wrtd_get_attr_int32(wrtd_dev *wrtd,
}
/**
* Set an attribute of type `string`. Modelled after the IVI-C
* SetAttribute family of functions.
* Set an attribute of type `string`.
*
* Modelled after the IVI-C SetAttribute family of functions.
*
* @param[in] wrtd Device token.
* @param[in] rep_cap_id ID (string) of concerned repeated capability.
......@@ -710,8 +717,9 @@ wrtd_status wrtd_set_attr_string(wrtd_dev *wrtd,
}
/**
* Get an attribute of type `string`. Modelled after the IVI-C
* GetAttribute family of functions.
* Get an attribute of type `string`.
*
* Modelled after the IVI-C GetAttribute family of functions.
*
* This function complies with IVI-3.2 section, 3.1.2.1 (Additional Compliance Rules
* for C Functions with ViChar Array Output Parameters), with the exception of
......@@ -763,8 +771,9 @@ wrtd_status wrtd_get_attr_string(wrtd_dev *wrtd,
}
/**
* Set an attribute of type `timestamp`. Modelled after the IVI-C
* SetAttribute family of functions.
* Set an attribute of type `timestamp`.
*
* Modelled after the IVI-C SetAttribute family of functions.
*
* @param[in] wrtd Device token.
* @param[in] rep_cap_id ID (string) of concerned repeated capability.
......@@ -831,8 +840,9 @@ wrtd_status wrtd_set_attr_tstamp(wrtd_dev *wrtd,
}
/**
* Get an attribute of type `timestamp`. Modelled after the IVI-C
* GetAttribute family of functions.
* Get an attribute of type `timestamp`.
*
* Modelled after the IVI-C GetAttribute family of functions.
*
* @param[in] wrtd Device token.
* @param[in] rep_cap_id ID (string) of concerned repeated capability.
......@@ -923,8 +933,9 @@ wrtd_status wrtd_get_attr_tstamp(wrtd_dev *wrtd,
*/
/**
* Retrieve and clear the last entry from the Event Log. Modelled after the IVI-C
* GetNextEventLogEntry function (from IVI-3.15).
* Retrieve and clear the last entry from the Event Log.
*
* Modelled after the IVI-C GetNextEventLogEntry function (from IVI-3.15).
*
* This function complies with IVI-3.2, section 3.1.2.1 (Additional Compliance Rules
* for C Functions with ViChar Array Output Parameters), with the exception of
......@@ -1164,8 +1175,9 @@ wrtd_status wrtd_get_next_event_log_entry(wrtd_dev *wrtd,
}
/**
* Clear all entries from the Event Log. Modelled after the IVI-C
* ClearEventLog function (from IVI-3.15).
* Clear all entries from the Event Log.
*
* Modelled after the IVI-C ClearEventLog function (from IVI-3.15).
*
* @param[in] wrtd Device token.
* @return #wrtd_status.
......@@ -1200,7 +1212,9 @@ wrtd_status wrtd_clear_event_log_entries(wrtd_dev *wrtd)
*/
/**
* Create a new Alarm. Complies with the IVI "Parameter style"
* Create a new Alarm.
*
* Complies with the IVI "Parameter style"
* for repeated capabilities (see IVI-3.4, section 12).
*
* @param[in] wrtd Device token.
......@@ -1266,7 +1280,9 @@ wrtd_status wrtd_add_alarm(wrtd_dev *wrtd,
}
/**
* Disable all defined Alarms. Complies with the IVI "Parameter style"
* Disable all defined Alarms.
*
* Complies with the IVI "Parameter style"
* for repeated capabilities (see IVI-3.4, section 12).
*
* See also, #WRTD_ATTR_ALARM_ENABLED and #wrtd_set_attr_bool
......@@ -1306,6 +1322,7 @@ wrtd_status wrtd_disable_all_alarms(wrtd_dev *wrtd)
/**
* Remove an Alarm. The Alarm must not be enabled.
*
* Complies with the IVI "Parameter style"
* for repeated capabilities (see IVI-3.4, section 12).
*
......@@ -1343,6 +1360,7 @@ wrtd_status wrtd_remove_alarm(wrtd_dev *wrtd,
/**
* Remove all defined Alarms. The Alarms must not be enabled.
*
* Complies with the IVI "Parameter style"
* for repeated capabilities (see IVI-3.4, section 12).
*
......@@ -1382,6 +1400,7 @@ extern wrtd_status wrtd_remove_all_alarms(wrtd_dev *wrtd)
/**
* Retrieve the name of an Alarm, based on the provided index.
*
* Complies with the IVI "Parameter style"
* for repeated capabilities (see IVI-3.4, section 12).
*
......@@ -1443,7 +1462,9 @@ wrtd_status wrtd_get_alarm_name(wrtd_dev *wrtd,
*/
/**
* Create a new Rule. Complies with the IVI "Parameter style"
* Create a new Rule.
*
* Complies with the IVI "Parameter style"
* for repeated capabilities (see IVI-3.4, section 12).
*
* @param[in] wrtd Device token.
......@@ -1503,7 +1524,9 @@ wrtd_status wrtd_add_rule(wrtd_dev *wrtd,
}
/**
* Disable all defined Rules. Complies with the IVI "Parameter style"
* Disable all defined Rules.
*
* Complies with the IVI "Parameter style"
* for repeated capabilities (see IVI-3.4, section 12).
*
* See also, #WRTD_ATTR_RULE_ENABLED and #wrtd_set_attr_bool
......@@ -1542,6 +1565,7 @@ wrtd_status wrtd_disable_all_rules(wrtd_dev *wrtd)
/**
* Remove a Rule. The Rule must not be enabled.
*
* Complies with the IVI "Parameter style"
* for repeated capabilities (see IVI-3.4, section 12).
*
......@@ -1579,6 +1603,7 @@ wrtd_status wrtd_remove_rule(wrtd_dev *wrtd,
/**
* Remove all defined Rules. The Rules must not be enabled.
*
* Complies with the IVI "Parameter style"
* for repeated capabilities (see IVI-3.4, section 12).
*
......@@ -1620,6 +1645,7 @@ wrtd_status wrtd_remove_all_rules(wrtd_dev *wrtd)
/**
* Retrieve the name of a Rule, based on the provided index.
*
* Complies with the IVI "Parameter style"
* for repeated capabilities (see IVI-3.4, section 12).
*
......@@ -1673,6 +1699,9 @@ wrtd_status wrtd_get_rule_name(wrtd_dev *wrtd,
/**
* Reset all statistics for the given rule. The Rule must not be enabled.
*
* Complies with the IVI "Parameter style"
* for repeated capabilities (see IVI-3.4, section 12).
*
* @param[in] wrtd Device token.
* @param[in] rep_cap_id Name of the Rule to reset its statistics.
* @return #wrtd_status
......@@ -1718,6 +1747,7 @@ wrtd_status wrtd_reset_rule_stats(wrtd_dev *wrtd,
/**
* Retrieve the name of a firmware application, based on the provided index.
*
* Complies with the IVI "Parameter style"
* for repeated capabilities (see IVI-3.4, section 12).
*
......
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