c-user: Generate clock manager documentation

The documentation is a consolidation of the comments in Doxygen markup
and the documentation sources in Sphinx markup.  The documentation was
transfered to interface specification items.  The documentation source
files were generated from the items by a script.

Update #3993.

1 files changed, 53 insertions, 0 deletions

diff --git a/c-user/glossary.rst b/c-user/glossary.rst
index 65e1fd7..8aa1266 100644
--- a/c-user/glossary.rst
+++ b/c-user/glossary.rst
@@ -121,6 +121,39 @@ Glossary
         of elements.  It differs from an array in that it is not limited to a
         predefined size.
 
+    Clock Driver
+        The Clock Driver is a driver which provides the :term:`clock tick` and a
+        time counter.  The time counter is used to drive the :term:`CLOCK_REALTIME`
+        and :term:`CLOCK_MONOTONIC`.  The Clock Driver can be initialized by the
+        application with the :ref:`CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER` and
+        :ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration options.
+
+    clock tick
+        The clock tick is a coarse time measure provided by RTEMS.  The
+        :term:`Clock Driver` emits clock ticks at rate specified by the
+        :ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration option.  In
+        contrast to :term:`CLOCK_REALTIME` and :term:`CLOCK_MONOTONIC`, the clock
+        tick rate is not affected by incremental adjustments.
+
+    CLOCK_MONOTONIC
+        The CLOCK_MONOTONIC is a clock provided by RTEMS which measures the time
+        since an unspecified starting point.  In contrast to :term:`CLOCK_REALTIME`,
+        this clock cannot be set.  It may be affected by incremental adjustments for
+        example carried out by the :term:`NTP` or the use of a :term:`PPS` signal.
+        See also :term:`CLOCK_REALTIME`, :term:`clock tick`, and
+        :term:`Clock Driver`.
+
+    CLOCK_REALTIME
+        The CLOCK_REALTIME is a clock provided by RTEMS which measures the real time
+        (also known as wall-clock time).  It is defined by :term:`POSIX`.  In
+        particular, every day is treated as if it contains exactly 86400 seconds and
+        leap seconds are ignored.  This clock can be set by the application which may
+        result in time jumps.  It may be affected by incremental adjustments for
+        example carried out by the :term:`NTP` or the use of a :term:`PPS` signal.
+        RTEMS can represent time points of this clock in nanoseconds ranging from
+        1988-01-01T00:00:00.000000000Z to 2514-05-31T01:53:03.999999999Z.  See also
+        :term:`CLOCK_MONOTONIC`, :term:`clock tick`, and :term:`Clock Driver`.
+
     cluster
         We have clustered scheduling in case the set of processors of a system is
         partitioned into non-empty pairwise disjoint subsets.  These subsets are
@@ -458,6 +491,10 @@ Glossary
     non-existent
         The state occupied by an uncreated or deleted task.
 
+    NTP
+        This term is an acronym for
+        `Network Time Protocol <https://en.wikipedia.org/wiki/Network_Time_Protocol>`_.
+
     NUMA
         This term is an acronym for Non-Uniform Memory Access.
 
@@ -527,9 +564,17 @@ Glossary
         A term used to describe the ease with which software can be rehosted on
         another computer.
 
+    POSIX
+        This term is an acronym for
+        `Portable Operating System Interface <https://en.wikipedia.org/wiki/POSIX>`_.
+
     posting
         The act of sending an event, message, semaphore, or signal to a task.
 
+    PPS
+        This term is an acronym for
+        `Pulse-Per-Second <https://en.wikipedia.org/wiki/Pulse-per-second_signal>`_.
+
     preempt
         The act of forcing a task to relinquish the processor and dispatching to
         another task.
@@ -650,6 +695,10 @@ Glossary
     RTEMS
         This term is an acronym for Real-Time Executive for Multiprocessor Systems.
 
+    RTEMS epoch
+        The RTEMS epoch is a point in time.  It is 1988-01-01T00:00:00Z in
+        `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ time format.
+
     running
         The state of a rate monotonic timer while it is being used to delineate a
         period.  The timer exits this state by either expiring or being canceled.
@@ -910,6 +959,10 @@ Glossary
     TTAS
         This term is an acronym for Test and Test-And-Set.
 
+    Unix epoch
+        The Unix epoch is a point in time.  It is 1970-01-01T00:00:00Z in
+        `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ time format.
+
     User Extension Table
         A table which contains the entry points for each user extensions.