[doc] wip

87509f75 · Dimitris Lampridis · e0b366cb · 87509f75 · 87509f75 · 87509f75
Commit 87509f75 authored Jul 08, 2019 by Dimitris Lampridis
5 changed files
--- a/doc/basic_concepts.rst
+++ b/doc/basic_concepts.rst
@@ -72,8 +72,8 @@ All other Event IDs are considered to refer to network :ref:`messages <message>`

 .. _timestamp:

-Timestamp
---------
+Event Timestamp
+---------------

 Every :ref:`event` has an associated Timestamp.

@@ -94,6 +94,16 @@ nanoseconds (where every "tick" represents 2\ :sup:`-16`\ ns).
   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``.

+.. _event_log:
+
+Event Log
+=========
+
+The Event Log records information about all received and transmitted :ref:`Events <event>`, as well
+as information regarding any discarded :ref:`event`, along with the reason for discarding it.
+
+The Event Log has a limited storage buffer. Newer entries will overwrite older, unread ones.
+
 .. _local_channel:

 Local Channel

--- a/doc/usage_clib.rst
+++ b/doc/usage_clib.rst
@@ -3,6 +3,19 @@
 C Library
 =========

+The WRTD C Library is the standard, most flexible way of accessing a WRTD Node. The library itself is modelled
+after `IVI`_ and `LXI`_ (see also :ref:`lxi`).
+
+The following specifications are relevant to and used by WRTD:
+
+* `IVI-3.1 Driver Architecture Specification`_
+* `IVI-3.2 Inherent Capabilities Specification`_
+* `IVI-3.4 API Style Guide`_
+* `IVI-3.15 IviLxiSync Specification`_
+* `LXI Core Specification`_
+* `LXI Event Messaging Extended Function`_
+
+The remainder of this section presents the provided API, split in
 .. _api_error:

 Error Handling API
@@ -28,21 +41,38 @@ Functions
 +++++++++

 .. doxygenfunction:: wrtd_get_error
+
+.. doxygenfunction:: wrtd_error_message
 .. code-block:: c
+   :caption: Error handling
+   :name: lst-get_error

   #include <libwrtd.h>

   int main(void) {
           wrtd_dev *wrtd;
           wrtd_status status, err_code;
+           char status_str[256];
           char *err_msg;
           int buf_size;

           status = wrtd_init("MT01", false, NULL, &wrtd);
+           if (status != WRTD_SUCCESS) {
+                   /* use wrtd_error_message because wrtd_init failed
+                      and the wrtd pointer is not valid. */
+                   wrtd_error_message(wrtd, status, status_str);
+                   printf("ERROR: %d, %s\n", status, status_str);
+                   return status;
+           }

+           status = wrtd_get_attr_bool(wrtd, WRTD_GLOBAL_REP_CAP_ID,
+                                       WRTD_ATTR_EVENT_LOG_EMPTY);
           if (status != WRTD_SUCCESS) {
+                   /* query the necessary buffer size for the error message */
                   buf_size = wrtd_get_error(wrtd, NULL, 0, NULL);
+                   /* allocate the buffer */
                   err_msg = calloc(sizeof(char), buf_size);
+                   /* retrieve the error code and message */
                   wrtd_get_error(wrtd, &err_code, buf_size, err_msg)
                   printf("ERROR: %d, %s\n", err_code, err_msg);
                   return status;
@@ -53,28 +83,11 @@ Functions
           return 0;
   }

-.. doxygenfunction:: wrtd_error_message
-.. code-block:: c
-
-   #include <libwrtd.h>
-
-   int main(void) {
-           wrtd_dev *wrtd;
-           wrtd_status status;
-           char err_msg[256];
+.. important::

-           status = wrtd_init("MT01", false, NULL, &wrtd);
-
-           if (status != WRTD_SUCCESS) {
-                   wrtd_error_message(wrtd, status, err_msg);
-                   printf("ERROR: %d, %s\n", status, err_msg);
-                   return status;
-           }
-
-           wrtd_close(wrtd);
-
-           return 0;
-   }
+   In the remaining code examples we omit error checking on purpose, to simplify the
+   examples. However, in a real application, users should always check the status code of every call
+   to a WRTD function, like in :numref:`lst-get_error`.

 .. _api_init:

@@ -95,6 +108,7 @@ library functions can be used after that.
 .. doxygenfunction:: wrtd_close
 .. doxygenfunction:: wrtd_reset
 .. code-block:: c
+   :caption: Opening and closing a connection to a Node.

   #include <libwrtd.h>

@@ -119,6 +133,9 @@ library functions can be used after that.
 Attribute Handling API
 ----------------------

+The Attribute Handling API defines the available :ref:`api_attr_id` and the :ref:`api_attr_func` for
+accessing them.
+
 Attributes can be of type ``bool``, ``int32``, ``string``, or ``tstamp`` (:cpp:class:`wrtd_tstamp`).

 Access can be ``RW`` (read/write), ``RO`` (read-only) or ``WO`` (write-only).
@@ -142,6 +159,22 @@ When using one of the above functions to access a "global" :ref:`attribute`, the
 parameter should be set to :c:macro:`WRTD_GLOBAL_REP_CAP_ID`.

 .. doxygendefine:: WRTD_GLOBAL_REP_CAP_ID
+.. code-block:: c
+   :caption: Accessing a "global" :ref:`attribute`.
+
+   #include <libwrtd.h>
+
+   int main(void) {
+           wrtd_dev *wrtd;
+           wrtd_status status;
+
+           status = wrtd_init("MT01", false, NULL, &wrtd);
+
+           status = wrtd_get_attr_bool(wrtd, WRTD_GLOBAL_REP_CAP_ID,
+                                       WRTD_ATTR_EVENT_LOG_EMPTY);
+
+           wrtd_close(wrtd);
+   }

 .. _api_attr_id:

@@ -164,26 +197,136 @@ Functions
 .. doxygenfunction:: wrtd_set_attr_string
 .. doxygenfunction:: wrtd_get_attr_string

-.. doxygenstruct:: wrtd_tstamp
-                   :members:
 .. doxygenfunction:: wrtd_set_attr_tstamp
 .. doxygenfunction:: wrtd_get_attr_tstamp

+.. code-block:: c
+   :caption: Accessing various types of :ref:`attributes <attribute>`.
+
+   #include <libwrtd.h>
+
+   int main(void) {
+           wrtd_dev *wrtd;
+           wrtd_status status;
+           wrtd_tstamp ts;
+           bool log_empty;
+
+           status = wrtd_init("MT01", false, NULL, &wrtd);
+
+           /* check if the event log is empty (global attribute) */
+           status = wrtd_get_attr_bool(wrtd, WRTD_GLOBAL_REP_CAP_ID,
+                                       WRTD_ATTR_EVENT_LOG_EMPTY, &log_empty);
+
+           /* add a rule with name "rule1" */
+           status = wrtd_add_rule(wrtd, "rule1");
+
+           /* set the repeat count for "rule1 */
+           status = wrtd_set_attr_int32(wrtd, "rule1",
+                                        WRTD_ATTR_RULE_REPEAT_COUNT, 5);
+
+           /* set the source for "rule1" to local channel input 1 */
+           status = wrtd_set_attr_string(wrtd, "rule1",
+                                         WRTD_ATTR_RULE_SOURCE, "LC-I1");
+
+           /* get the delay configured for "rule1" */
+           status = wrtd_get_attr_tstamp(wrtd, "rule1",
+                                         WRTD_ATTR_RULE_DELAY, &ts");
+
+           wrtd_close(wrtd);
+   }
+
+.. important::
+
+   :cpp:func:`wrtd_get_attr_tstamp` and :cpp:func:`wrtd_set_attr_tstamp` allow getting and setting
+   of timestamp :ref:`attributes <attribute>`. Within the C library, a timestamp is represented as a
+   C struct:
+
+   .. doxygenstruct:: wrtd_tstamp
+                      :members:
+
+   Note that the above internal representation is slightly different than the official
+   :ref:`definition of a timestamp <timestamp>`. In particular, the seconds counter is 16-bits
+   shorter and the fractional nanosecond counter is 16 bits longer (and every "tick" represents 2\
+   :sup:`-32`\ ns). Both of these changes help the underlying firmware to operate faster. When WRTD
+   sends (or receives) a message, it will always use the official :ref:`definition of a timestamp
+   <timestamp>` and convert it automatically to the above internal representation when necessary.
+
 .. _api_log:

 Event Logging API
 -----------------

-.. doxygendefine:: WRTD_LOG_ENTRY_SIZE
+The Event Logging API provides functions for accessing the :ref:`event_log`.

 .. doxygenfunction:: wrtd_clear_event_log_entries
 .. doxygenfunction:: wrtd_get_next_event_log_entry
+.. code-block:: c
+   :caption: Accessing the :ref:`event_log`.
+   :name: lst-event_log
+
+   #include <libwrtd.h>
+
+   int main(void) {
+           wrtd_dev *wrtd;
+           char *log_msg;
+           int buf_size;
+
+           status = wrtd_init("MT01", false, NULL, &wrtd);
+
+           /* clear the event log */
+           status = wrtd_clean_event_log_entries(wrtd);
+
+           /* query the size of the next event log message */
+           buf_size = wrtd_get_next_event_log_entry(wrtd, 0, NULL);
+
+           /* allocate the buffer for the log message */
+           log_msg = calloc(sizeof(char), buf_size);
+
+           /* retrieve the next event log message */
+           status = wrtd_get_next_event_log_entry(wrtd, buf_size, log_msg);
+
+           wrtd_close(wrtd);
+
+           return 0;
+   }
+
+.. hint::
+
+   If you want to be sure that the buffer that you pass to :cpp:func:`wrtd_get_next_event_log_entry`
+   is large enough, without having to resort to querying like in :numref:`lst-event_log`, you can
+   always allocate a buffer of :c:macro:`WRTD_LOG_ENTRY_SIZE`. WRTD guarantees that all event log
+   entries shall not exceed this size.
+
+   .. doxygendefine:: WRTD_LOG_ENTRY_SIZE
+   .. code-block:: c
+      :caption: Accessing the :ref:`event_log` with a pre-defined buffer size
+
+      #include <libwrtd.h>
+
+      int main(void) {
+              wrtd_dev *wrtd;
+              char log_msg[WRTD_LOG_ENTRY_SIZE];
+
+              status = wrtd_init("MT01", false, NULL, &wrtd);
+
+              /* retrieve the next event log message */
+              status = wrtd_get_next_event_log_entry(wrtd, WRTD_LOG_ENTRY_SIZE, log_msg);
+
+              wrtd_close(wrtd);
+
+              return 0;
+      }

 .. _api_alarm:

 Alarms API
 ----------

+The Alarms API provides functions for adding, removing and indexing :ref:`Alarms <alarm>`.
+
+Configuration of an Alarm happens by setting the relevant :ref:`Attributes <attribute>` via the
+:ref:`api_attr`.
+
 .. doxygenfunction:: wrtd_add_alarm
 .. doxygenfunction:: wrtd_disable_all_alarms
 .. doxygenfunction:: wrtd_remove_alarm
@@ -195,6 +338,11 @@ Alarms API
 Rules API
 ---------

+The Rules API provides functions for adding, removing and indexing :ref:`Rules <rule>`.
+
+Configuration of a Rule happens by setting the relevant :ref:`Attributes <attribute>` via the
+:ref:`api_attr`.
+
 .. doxygenfunction:: wrtd_add_rule
 .. doxygenfunction:: wrtd_disable_all_rules
 .. doxygenfunction:: wrtd_remove_rule
@@ -208,3 +356,19 @@ Applications API
 ----------------

 .. doxygenfunction:: wrtd_get_fw_name
+
+.. _IVI: http://ivifoundation.org
+
+.. _LXI: http://www.lxistandard.org
+
+.. _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: http://www.lxistandard.org/members/Adopted%20Specifications/Latest%20Version%20of%20Standards_/LXI%20Standard%201.5%20Specifications/LXI%20Event%20Messaging%20Extended%20Function.pdf
+
+.. _IVI-3.15 IviLxiSync Specification: http://www.ivifoundation.org/downloads/Architecture%20Specifications/IVI-3.15_LxiSync_2018-08-23.pdf
+
+.. _IVI-3.1 Driver Architecture Specification: http://www.ivifoundation.org/downloads/Architecture%20Specifications/IVIspecstopost10-22-2018/IVI-3.1_Architecture_2018-10-19.pdf
+
+.. _IVI-3.2 Inherent Capabilities Specification: http://www.ivifoundation.org/downloads/Architecture%20Specifications/IVI-3.2_Inherent_Capabilities_2017-02-07.pdf
+
+.. _IVI-3.4 API Style Guide: http://www.ivifoundation.org/downloads/Architecture%20Specifications/IVIspecstopost10-22-2018/IVI-3.4_APIStyleGuide_2018-10-19.pdf
--- a/doc/usage_index.rst
+++ b/doc/usage_index.rst
@@ -4,8 +4,14 @@
 Usage
 -----

+There are three options offered for accessing a WRTD Node (in decreasing order of flexibility and complexity):
+
+* By writing your own application using the provided :ref:`clib`.
+* By writing your own application using the provided :ref:`pywrap`.
+* By using the provided :ref:`tools`.
+
 .. toctree::
-   :maxdepth: 2
+   :hidden:

   usage_clib
   usage_pywrap

--- a/software/lib/libwrtd.c
+++ b/software/lib/libwrtd.c
@@ -734,7 +734,9 @@ wrtd_status wrtd_set_attr_string(wrtd_dev *wrtd,
 * @param[in]  id         ID (#wrtd_attr) of concerned attribute.
 * @param[in]  value_buffer_size Size of pre-allocated `value` buffer.
 * @param[out] value      Retrieved attribute value.
- * @return #wrtd_status. See also IVI-3.2, section 3.1.2.1.
+ * @return #wrtd_status. However, if the buffer size parameter is 0, then this function returns
+ * instead a positive value, indicating the minimum buffer size necessary to fit the full message.
+ * See also IVI-3.2, section 3.1.2.1.
 */
 wrtd_status wrtd_get_attr_string(wrtd_dev *wrtd,
                                 const char *rep_cap_id,
@@ -983,7 +985,9 @@ wrtd_status wrtd_get_attr_tstamp(wrtd_dev *wrtd,
 * @param[in]  wrtd        Device token.
 * @param[in]  log_entry_buffer_size Size of pre-allocated `log_entry` buffer.
 * @param[out] log_entry Buffer to store the log message string.
- * @return #wrtd_status. See also IVI-3.2, section 3.1.2.1.
+ * @return #wrtd_status. However, if the buffer size parameter is 0, then this function returns
+ * instead a positive value, indicating the minimum buffer size necessary to fit the full message.
+ * See also IVI-3.2, section 3.1.2.1.
 */
 wrtd_status wrtd_get_next_event_log_entry(wrtd_dev *wrtd,
                                          int32_t log_entry_buffer_size,

--- a/software/lib/libwrtd.h
+++ b/software/lib/libwrtd.h
@@ -30,7 +30,7 @@ typedef enum wrtd_status {
        /** No error. */
        WRTD_SUCCESS = 0,

-        /** Same as *IVI_INHERENT_ERROR_BASE* */
+        /** Same as *IVI_INHERENT_ERROR_BASE*. */
        __WRTD_ERROR_BASE = 0xBFFA0000,
        /** Invalid/unknown attribute. */
        WRTD_ERROR_INVALID_ATTRIBUTE      = __WRTD_ERROR_BASE + 0x0C,
@@ -55,25 +55,25 @@ typedef enum wrtd_status {
        /** Incorrect repeated capability selector. */
        WRTD_ERROR_BADLY_FORMED_SELECTOR  = __WRTD_ERROR_BASE + 0x66,

-        /** Same as *IVI_LXISYNC_ERROR_BASE* */
+        /** Same as *IVI_LXISYNC_ERROR_BASE*. */
        __WRTD_LXISYNC_ERROR_BASE = 0xBFFA3000,
        /** The alarm already exists. */
        WRTD_ERROR_ALARM_EXISTS           = __WRTD_LXISYNC_ERROR_BASE + 0x07,
        /** The specified alarm has not been defined. */
        WRTD_ERROR_ALARM_DOES_NOT_EXIST   = __WRTD_LXISYNC_ERROR_BASE + 0x08,

-        /** Same as *IVI_VENDOR_SPECIFIC_ERROR_BASE* */
+        /** Same as *IVI_VENDOR_SPECIFIC_ERROR_BASE*. */
        __WRTD_SPECIFIC_ERROR_BASE = 0xBFFA6000,
-        /** Version mismatch */
+        /** Version mismatch. */
        WRTD_ERROR_VERSION_MISMATCH       = __WRTD_SPECIFIC_ERROR_BASE + 0x00,
-        /** Internal error */
+        /** Internal error. */
        WRTD_ERROR_INTERNAL               = __WRTD_SPECIFIC_ERROR_BASE + 0x01,
-        /** Unknown event log type/reason */
+        /** Unknown event log type/reason. */
        WRTD_ERROR_UNKNOWN_LOG_TYPE       = __WRTD_SPECIFIC_ERROR_BASE + 0x02,
        /** Resource is not disabled and cannot be changed.  */
        WRTD_ERROR_RESOURCE_ACTIVE        = __WRTD_SPECIFIC_ERROR_BASE + 0x03,
        /** Attempt to access a global attribute without
-            using the global attribute selector */
+            using the global attribute selector. */
        WRTD_ERROR_ATTR_GLOBAL            = __WRTD_SPECIFIC_ERROR_BASE + 0x04,
        /** The device has no more resources to allocate. */
        WRTD_ERROR_OUT_OF_RESOURCES       = __WRTD_SPECIFIC_ERROR_BASE + 0x05,
@@ -82,7 +82,7 @@ typedef enum wrtd_status {
        /** The specified rule has not been defined. */
        WRTD_ERROR_RULE_DOES_NOT_EXIST    = __WRTD_SPECIFIC_ERROR_BASE + 0x07,

-        /** always last entry in this enum */
+        /** Always last entry in this enum. */
        __WRTD_ERROR_MAX_NUMBER,
 } wrtd_status;