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.

c-user/clock/introduction.rst

@@ -1,36 +1,88 @@
 .. SPDX-License-Identifier: CC-BY-SA-4.0
 
+.. Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de)
 .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
 
+.. This file is part of the RTEMS quality process and was automatically
+.. generated.  If you find something that needs to be fixed or
+.. worded better please post a report or patch to an RTEMS mailing list
+.. or raise a bug report:
+..
+.. https://www.rtems.org/bugs.html
+..
+.. For information on updating and regenerating please refer to the How-To
+.. section in the Software Requirements Engineering chapter of the
+.. RTEMS Software Engineering manual.  The manual is provided as a part of
+.. a release.  For development sources please refer to the online
+.. documentation at:
+..
+.. https://docs.rtems.org
+
+.. Generated from spec:/rtems/clock/if/group
+
+.. _ClockManagerIntroduction:
+
 Introduction
 ============
 
-The clock manager provides support for time of day
-and other time related capabilities.  The directives provided by
-the clock manager are:
+.. The following list was generated from:
+.. spec:/rtems/clock/if/set
+.. spec:/rtems/clock/if/get-tod
+.. spec:/rtems/clock/if/get-tod-timeval
+.. spec:/rtems/clock/if/get-seconds-since-epoch
+.. spec:/rtems/clock/if/get-ticks-per-second
+.. spec:/rtems/clock/if/get-ticks-since-boot
+.. spec:/rtems/clock/if/get-uptime
+.. spec:/rtems/clock/if/get-uptime-timeval
+.. spec:/rtems/clock/if/get-uptime-seconds
+.. spec:/rtems/clock/if/get-uptime-nanoseconds
+.. spec:/rtems/clock/if/tick-later
+.. spec:/rtems/clock/if/tick-later-usec
+.. spec:/rtems/clock/if/tick-before
 
-- :ref:`rtems_clock_set`
+The Clock Manager provides support for time of day and other time related
+capabilities. The directives provided by the Clock Manager are:
 
-- :ref:`rtems_clock_get_tod`
+* :ref:`InterfaceRtemsClockSet` - Sets the :term:`CLOCK_REALTIME` to the time
+  of day.
 
-- :ref:`rtems_clock_get_tod_timeval`
+* :ref:`InterfaceRtemsClockGetTod` - Gets the time of day associated with the
+  current :term:`CLOCK_REALTIME`.
 
-- :ref:`rtems_clock_get_seconds_since_epoch`
+* :ref:`InterfaceRtemsClockGetTodTimeval` - Gets the seconds and microseconds
+  elapsed since the :term:`Unix epoch` and the current :term:`CLOCK_REALTIME`.
 
-- :ref:`rtems_clock_get_ticks_per_second`
+* :ref:`InterfaceRtemsClockGetSecondsSinceEpoch` - Gets the seconds elapsed
+  since the :term:`RTEMS epoch` and the current :term:`CLOCK_REALTIME`.
 
-- :ref:`rtems_clock_get_ticks_since_boot`
+* :ref:`InterfaceRtemsClockGetTicksPerSecond` - Gets the number of :term:`clock
+  ticks <clock tick>` per second configured for the application.
 
-- :ref:`rtems_clock_tick_later`
+* :ref:`InterfaceRtemsClockGetTicksSinceBoot` - Gets the number of :term:`clock
+  ticks <clock tick>` since some time point during the system initialization or
+  the last overflow of the clock tick counter.
 
-- :ref:`rtems_clock_tick_later_usec`
+* :ref:`InterfaceRtemsClockGetUptime` - Gets the seconds and nanoseconds
+  elapsed since some time point during the system initialization using
+  :term:`CLOCK_MONOTONIC`.
 
-- :ref:`rtems_clock_tick_before`
+* :ref:`InterfaceRtemsClockGetUptimeTimeval` - Gets the seconds and
+  microseconds elapsed since some time point during the system initialization
+  using :term:`CLOCK_MONOTONIC`.
 
-- :ref:`rtems_clock_get_uptime`
+* :ref:`InterfaceRtemsClockGetUptimeSeconds` - Gets the seconds elapsed since
+  some time point during the system initialization using
+  :term:`CLOCK_MONOTONIC`.
 
-- :ref:`rtems_clock_get_uptime_timeval`
+* :ref:`InterfaceRtemsClockGetUptimeNanoseconds` - Gets the nanoseconds elapsed
+  since some time point during the system initialization using
+  :term:`CLOCK_MONOTONIC`.
 
-- :ref:`rtems_clock_get_uptime_seconds`
+* :ref:`InterfaceRtemsClockTickLater` - Gets a :term:`clock tick` value which
+  is at least delta clock ticks in the future.
 
-- :ref:`rtems_clock_get_uptime_nanoseconds`
+* :ref:`InterfaceRtemsClockTickLaterUsec` - Gets a :term:`clock tick` value
+  which is at least delta microseconds in the future.
+
+* :ref:`InterfaceRtemsClockTickBefore` - Indicates if the current :term:`clock
+  tick` counter is before the ticks.

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.