doc: wip

bc19c9e1 · Dimitris Lampridis · a575fbae · bc19c9e1 · bc19c9e1 · bc19c9e1
Commit bc19c9e1 authored Jul 04, 2019 by Dimitris Lampridis
Hide whitespace changes
Inline Side-by-side

Showing with 140 additions and 42 deletions

basic_concepts.rst doc/basic_concepts.rst +71 -13

ref_nodes.rst doc/ref_nodes.rst +4 -0

usage.rst doc/usage.rst +7 -1

libwrtd.c software/lib/libwrtd.c +58 -28

No files found.
--- a/doc/basic_concepts.rst
+++ b/doc/basic_concepts.rst
@@ -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
+functionality, but each one with its own settings (:ref:`Attributes <attribute>`).
-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:
+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
+Similar to a :ref:`Rule`, an Alarm is a :ref:`rep_cap` instance inside a :ref:`node`
-other characters (always limited to 16 characters, including null-termination).
+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

--- a/doc/ref_nodes.rst
+++ b/doc/ref_nodes.rst
@@ -4,8 +4,12 @@
 Reference Nodes
 ---------------
+.. _spec150t_ref_adc:
 SPEC150T-based FMC-ADC
 ======================
+.. _svec_ref_tdc_fd:
 SVEC-based TDC+FDELAY
 =====================
--- a/doc/usage.rst
+++ b/doc/usage.rst
@@ -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
 -----
--- a/software/lib/libwrtd.c
+++ b/software/lib/libwrtd.c
@@ -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
+ * Retrieve and clear the last error from the device.
- * GetError function.
+ *
+ * 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
+ * Convert a #wrtd_status error code to a string.
- * ErrorMessage function.
+ *
+ * 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
+ * Set an attribute of type `bool`.
- * SetAttribute family of functions.
+ *
+ * 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
+ * Get an attribute of type `bool`.
- * GetAttribute family of functions.
+ *
+ * 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
+ * Set an attribute of type `int32`.
- * SetAttribute family of functions.
+ *
+ * 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
+ * Get an attribute of type `int32`.
- * GetAttribute family of functions.
+ *
+ * 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
+ * Set an attribute of type `string`.
- * SetAttribute family of functions.
+ *
+ * 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
+ * Get an attribute of type `string`.
- * GetAttribute family of functions.
+ *
+ * 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
+ * Set an attribute of type `timestamp`.
- * SetAttribute family of functions.
+ *
+ * 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
+ * Get an attribute of type `timestamp`.
- * GetAttribute family of functions.
+ *
+ * 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
+ * Retrieve and clear the last entry from the Event Log.
- * GetNextEventLogEntry function (from IVI-3.15).
+ *
+ * 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
+ * Clear all entries from the Event Log.
- * ClearEventLog function (from IVI-3.15).
+ *
+ * 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).
 *