[PATCH v2 12/12] c-user: Generate clock manager documentation
Sebastian Huber
sebastian.huber at embedded-brains.de
Wed Feb 10 16:28:09 UTC 2021
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/directives.rst | 874 +++++++++++++++++++---------------
c-user/clock/introduction.rst | 83 +++-
c-user/glossary.rst | 53 +++
3 files changed, 612 insertions(+), 398 deletions(-)
diff --git a/c-user/clock/directives.rst b/c-user/clock/directives.rst
index 06fe38b..55af03b 100644
--- a/c-user/clock/directives.rst
+++ b/c-user/clock/directives.rst
@@ -1,549 +1,659 @@
.. 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
+
+.. _ClockManagerDirectives:
+
Directives
==========
-This section details the clock manager's directives. A subsection is dedicated
-to each of this manager's directives and describes the calling sequence,
-related constants, usage, and status codes.
+This section details the directives of the Clock Manager. A subsection is
+dedicated to each of this manager's directives and lists the calling sequence,
+parameters, description, return values, and notes of the directive.
+
+.. Generated from spec:/rtems/clock/if/set
.. raw:: latex
- \clearpage
+ \clearpage
-.. index:: set the time of day
-.. index:: rtems_clock_set
+.. index:: rtems_clock_set()
-.. _rtems_clock_set:
+.. _InterfaceRtemsClockSet:
-CLOCK_SET - Set date and time
------------------------------
+rtems_clock_set()
+-----------------
-CALLING SEQUENCE:
- .. code-block:: c
+Sets the :term:`CLOCK_REALTIME` to the time.
- rtems_status_code rtems_clock_set(
- rtems_time_of_day *time_buffer
- );
+.. rubric:: CALLING SEQUENCE:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+.. code-block:: c
- * - ``RTEMS_SUCCESSFUL``
- - date and time set successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``time_buffer`` is NULL
- * - ``RTEMS_INVALID_CLOCK``
- - invalid time of day
+ rtems_status_code rtems_clock_set( const rtems_time_of_day *time );
-DESCRIPTION:
- This directive sets the system date and time. The date, time, and ticks in
- the time_buffer structure are all range-checked, and an error is returned
- if any one is out of its valid range.
+.. rubric:: PARAMETERS:
-NOTES:
- Years before 1988 are invalid.
+``time``
+ This parameter is the time to set the clock.
- The system date and time are based on the configured tick rate (number of
- microseconds in a tick).
+.. rubric:: RETURN VALUES:
- Setting the time forward may cause a higher priority task, blocked waiting
- on a specific time, to be made ready. In this case, the calling task will
- be preempted after the next clock tick.
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
- Re-initializing RTEMS causes the system date and time to be reset to an
- uninitialized state. Another call to ``rtems_clock_set`` is required to
- re-initialize the system date and time to application specific
- specifications.
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``time`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
-.. raw:: latex
+:c:macro:`RTEMS_INVALID_CLOCK`
+ The time point specified by ``time`` was invalid.
- \clearpage
+.. rubric:: NOTES:
-.. index:: obtain the time of day
-.. index:: rtems_clock_get_tod
+The date, time, and ticks specified by ``time`` are all range-checked, and an
+error is returned if any one is out of its valid range.
-.. _rtems_clock_get_tod:
+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. The future
+uptime of the system shall be in this range, otherwise the system behaviour is
+undefined.
-CLOCK_GET_TOD - Get date and time in TOD format
------------------------------------------------
+The specified time is based on the configured :term:`clock tick` rate, see the
+:ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration option.
-CALLING SEQUENCE:
- .. code-block:: c
+Setting the time forward will fire all :term:`CLOCK_REALTIME` timers which are
+scheduled at a time point before or at the time set by the directive. This may
+unblock tasks, which may preempt the calling task. User-provided timer routines
+will execute in the context of the caller.
- rtems_status_code rtems_clock_get_tod(
- rtems_time_of_day *time_buffer
- );
+It is allowed to call this directive from within interrupt context, however,
+this is not recommended since an arbitrary number of timers may fire.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
+The directive shall be called at least once to enable the service of
+:term:`CLOCK_REALTIME` related directives. If the clock is not set at least
+once, they may return an error status.
- * - ``RTEMS_SUCCESSFUL``
- - current time obtained successfully
- * - ``RTEMS_NOT_DEFINED``
- - system date and time is not set
- * - ``RTEMS_INVALID_ADDRESS``
- - ``time_buffer`` is NULL
+.. rubric:: CONSTRAINTS:
-DESCRIPTION:
- This directive obtains the system date and time. If the date and time has
- not been set with a previous call to ``rtems_clock_set``, then the
- ``RTEMS_NOT_DEFINED`` status code is returned.
+The following constraints apply to this directive:
-NOTES:
- This directive is callable from an ISR.
+* The directive may be called from within any runtime context.
- This directive will not cause the running task to be preempted.
- Re-initializing RTEMS causes the system date and time to be reset to an
- uninitialized state. Another call to ``rtems_clock_set`` is required to
- re-initialize the system date and time to application specific
- specifications.
+* The directive may change the priority of another task which may preempt the
+ calling task.
+
+* The directive may unblock another task which may preempt the calling task.
+
+.. Generated from spec:/rtems/clock/if/get-tod
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_clock_get_tod()
+
+.. _InterfaceRtemsClockGetTod:
+
+rtems_clock_get_tod()
+---------------------
+
+Gets the time of day associated with the current :term:`CLOCK_REALTIME`.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_clock_get_tod( rtems_time_of_day *time_of_day );
+
+.. rubric:: PARAMETERS:
+
+``time_of_day``
+ This parameter is the pointer to a RTEMS time of day variable. When the
+ directive call is successful, the time of day associated with the
+ :term:`CLOCK_REALTIME` at some point during the directive call will be
+ stored in this variable.
+
+.. rubric:: RETURN VALUES:
-.. index:: obtain the time of day
-.. index:: rtems_clock_get_tod_timeval
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
-.. _rtems_clock_get_tod_timeval:
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``time_of_day`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
-CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format
------------------------------------------------------------
+:c:macro:`RTEMS_NOT_DEFINED`
+ The :term:`CLOCK_REALTIME` was not set. It can be set with
+ :ref:`InterfaceRtemsClockSet`.
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: CONSTRAINTS:
- rtems_status_code rtems_clock_get_tod_interval(
- struct timeval *time
- );
+The following constraints apply to this directive:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
- * - ``RTEMS_SUCCESSFUL``
- - current time obtained successfully
- * - ``RTEMS_NOT_DEFINED``
- - system date and time is not set
- * - ``RTEMS_INVALID_ADDRESS``
- - ``time`` is NULL
+* The directive may be called from within any runtime context.
-DESCRIPTION:
- This directive obtains the system date and time in POSIX ``struct timeval``
- format. If the date and time has not been set with a previous call to
- ``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` status code is
- returned.
+* The directive will not cause the calling task to be preempted.
-NOTES:
- This directive is callable from an ISR.
+* The directive requires a :term:`Clock Driver`.
- This directive will not cause the running task to be preempted.
- Re-initializing RTEMS causes the system date and time to be reset to an
- uninitialized state. Another call to ``rtems_clock_set`` is required to
- re-initialize the system date and time to application specific
- specifications.
+.. Generated from spec:/rtems/clock/if/get-tod-timeval
.. raw:: latex
- \clearpage
+ \clearpage
-.. index:: obtain seconds since epoch
-.. index:: rtems_clock_get_seconds_since_epoch
+.. index:: rtems_clock_get_tod_timeval()
-.. _rtems_clock_get_seconds_since_epoch:
+.. _InterfaceRtemsClockGetTodTimeval:
-CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch
--------------------------------------------------------
+rtems_clock_get_tod_timeval()
+-----------------------------
+
+Gets the seconds and microseconds elapsed since the :term:`Unix epoch` and the
+current :term:`CLOCK_REALTIME`.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ rtems_status_code rtems_clock_get_tod_timeval( struct timeval *time );
+
+.. rubric:: PARAMETERS:
+
+``time``
+ This parameter is the pointer to a timeval structure variable. When the
+ directive call is successful, the seconds and microseconds elapsed since
+ the :term:`Unix epoch` and the :term:`CLOCK_REALTIME` at some point during
+ the directive call will be stored in this variable.
+
+.. rubric:: RETURN VALUES:
-CALLING SEQUENCE:
- .. code-block:: c
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
- rtems_status_code rtems_clock_get_seconds_since_epoch(
- rtems_interval *the_interval
- );
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``time`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
- * - ``RTEMS_SUCCESSFUL``
- - current time obtained successfully
- * - ``RTEMS_NOT_DEFINED``
- - system date and time is not set
- * - ``RTEMS_INVALID_ADDRESS``
- - ``the_interval`` is NULL
+:c:macro:`RTEMS_NOT_DEFINED`
+ The :term:`CLOCK_REALTIME` was not set. It can be set with
+ :ref:`InterfaceRtemsClockSet`.
-DESCRIPTION:
- This directive returns the number of seconds since the RTEMS epoch and the
- current system date and time. If the date and time has not been set with a
- previous call to ``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` status
- code is returned.
+.. rubric:: CONSTRAINTS:
-NOTES:
- This directive is callable from an ISR.
+The following constraints apply to this directive:
- This directive will not cause the running task to be preempted.
- Re-initializing RTEMS causes the system date and time to be reset to an
- uninitialized state. Another call to ``rtems_clock_set`` is required to
- re-initialize the system date and time to application specific
- specifications.
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+* The directive requires a :term:`Clock Driver`.
+
+.. Generated from spec:/rtems/clock/if/get-seconds-since-epoch
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_clock_get_seconds_since_epoch()
+
+.. _InterfaceRtemsClockGetSecondsSinceEpoch:
+
+rtems_clock_get_seconds_since_epoch()
+-------------------------------------
+
+Gets the seconds elapsed since the :term:`RTEMS epoch` and the current
+:term:`CLOCK_REALTIME`.
-.. index:: obtain seconds since epoch
-.. index:: rtems_clock_get_ticks_per_second
+.. rubric:: CALLING SEQUENCE:
-.. _rtems_clock_get_ticks_per_second:
+.. code-block:: c
-CLOCK_GET_TICKS_PER_SECOND - Get ticks per second
--------------------------------------------------
+ rtems_status_code rtems_clock_get_seconds_since_epoch(
+ rtems_interval *seconds_since_rtems_epoch
+ );
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: PARAMETERS:
- rtems_interval rtems_clock_get_ticks_per_second(void);
+``seconds_since_rtems_epoch``
+ This parameter is the pointer to an interval variable. When the directive
+ call is successful, the seconds elapsed since the :term:`RTEMS epoch` and
+ the :term:`CLOCK_REALTIME` at some point during the directive call will be
+ stored in this variable.
-DIRECTIVE STATUS CODES:
- NONE
+.. rubric:: RETURN VALUES:
-DESCRIPTION:
- This directive returns the number of clock ticks per second. This is
- strictly based upon the microseconds per clock tick that the application
- has configured.
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
-NOTES:
- This directive is callable from an ISR.
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``seconds_since_rtems_epoch`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
- This directive will not cause the running task to be preempted.
+:c:macro:`RTEMS_NOT_DEFINED`
+ The :term:`CLOCK_REALTIME` was not set. It can be set with
+ :ref:`InterfaceRtemsClockSet`.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+* The directive requires a :term:`Clock Driver`.
+
+.. Generated from spec:/rtems/clock/if/get-ticks-per-second
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_clock_get_ticks_per_second()
+
+.. _InterfaceRtemsClockGetTicksPerSecond:
-.. index:: obtain ticks since boot
-.. index:: get current ticks counter value
-.. index:: rtems_clock_get_ticks_since_boot
+rtems_clock_get_ticks_per_second()
+----------------------------------
-.. _rtems_clock_get_ticks_since_boot:
+Gets the number of :term:`clock ticks <clock tick>` per second configured for
+the application.
-CLOCK_GET_TICKS_SINCE_BOOT - Get current ticks counter value
-------------------------------------------------------------
+.. rubric:: CALLING SEQUENCE:
-CALLING SEQUENCE:
- .. code-block:: c
+.. code-block:: c
- rtems_interval rtems_clock_get_ticks_since_boot(void);
+ rtems_interval rtems_clock_get_ticks_per_second( void );
-DIRECTIVE STATUS CODES:
- NONE
+.. rubric:: RETURN VALUES:
-DESCRIPTION:
+Returns the number of clock ticks per second configured for this application.
- This directive returns the current tick counter value. With a 1ms clock
- tick, this counter overflows after 50 days since boot. This is the
- historical measure of uptime in an RTEMS system. The newer service
- ``rtems_clock_get_uptime`` is another and potentially more accurate way of
- obtaining similar information.
+.. rubric:: NOTES:
-NOTES:
+The number of clock ticks per second is defined indirectly by the
+:ref:`CONFIGURE_MICROSECONDS_PER_TICK` configuration option.
- This directive is callable from an ISR.
+.. rubric:: CONSTRAINTS:
- This directive will not cause the running task to be preempted.
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/clock/if/get-ticks-since-boot
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_clock_get_ticks_since_boot()
+
+.. _InterfaceRtemsClockGetTicksSinceBoot:
+
+rtems_clock_get_ticks_since_boot()
+----------------------------------
+
+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.
-.. index:: rtems_clock_tick_later
+.. rubric:: CALLING SEQUENCE:
-.. _rtems_clock_tick_later:
+.. code-block:: c
-CLOCK_TICK_LATER - Get tick value in the future
------------------------------------------------
+ rtems_interval rtems_clock_get_ticks_since_boot( void );
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: RETURN VALUES:
- rtems_interval rtems_clock_tick_later(
- rtems_interval delta
- );
+Returns 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.
-DESCRIPTION:
- Returns the ticks counter value delta ticks in the future.
+.. rubric:: NOTES:
-NOTES:
- This directive is callable from an ISR.
+With a 1ms clock tick, this counter overflows after 50 days since boot. This
+is the historical measure of uptime in an RTEMS system. The newer service
+:ref:`InterfaceRtemsClockGetUptime` is another and potentially more accurate
+way of obtaining similar information.
- This directive will not cause the running task to be preempted.
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+.. Generated from spec:/rtems/clock/if/get-uptime
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_clock_get_uptime()
+
+.. _InterfaceRtemsClockGetUptime:
+
+rtems_clock_get_uptime()
+------------------------
+
+Gets the seconds and nanoseconds elapsed since some time point during the
+system initialization using :term:`CLOCK_MONOTONIC`.
-.. index:: rtems_clock_tick_later_usec
+.. rubric:: CALLING SEQUENCE:
-.. _rtems_clock_tick_later_usec:
+.. code-block:: c
-CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds
---------------------------------------------------------------------
+ rtems_status_code rtems_clock_get_uptime( struct timespec *uptime );
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: PARAMETERS:
- rtems_interval rtems_clock_tick_later_usec(
- rtems_interval delta_in_usec
- );
+``uptime``
+ This parameter is the pointer to a timeval structure variable. When the
+ directive call is successful, the seconds and nanoseconds elapsed since
+ some time point during the system initialization and some point during the
+ directive call using :term:`CLOCK_MONOTONIC` will be stored in this
+ variable.
-DESCRIPTION:
- Returns the ticks counter value at least delta microseconds in the future.
+.. rubric:: RETURN VALUES:
-NOTES:
- This directive is callable from an ISR.
+:c:macro:`RTEMS_SUCCESSFUL`
+ The requested operation was successful.
- This directive will not cause the running task to be preempted.
+:c:macro:`RTEMS_INVALID_ADDRESS`
+ The ``uptime`` parameter was `NULL
+ <https://en.cppreference.com/w/c/types/NULL>`_.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+* The directive requires a :term:`Clock Driver`.
+
+.. Generated from spec:/rtems/clock/if/get-uptime-timeval
.. raw:: latex
- \clearpage
+ \clearpage
-.. index:: rtems_clock_tick_before
+.. index:: rtems_clock_get_uptime_timeval()
-.. _rtems_clock_tick_before:
+.. _InterfaceRtemsClockGetUptimeTimeval:
-CLOCK_TICK_BEFORE - Is tick value is before a point in time
------------------------------------------------------------
+rtems_clock_get_uptime_timeval()
+--------------------------------
-CALLING SEQUENCE:
- .. code-block:: c
+Gets the seconds and microseconds elapsed since some time point during the
+system initialization using :term:`CLOCK_MONOTONIC`.
- rtems_interval rtems_clock_tick_before(
- rtems_interval tick
- );
+.. rubric:: CALLING SEQUENCE:
-DESCRIPTION:
- Returns true if the current ticks counter value indicates a time before the
- time specified by the tick value and false otherwise.
+.. code-block:: c
-NOTES:
- This directive is callable from an ISR.
+ void rtems_clock_get_uptime_timeval( struct timeval *uptime );
- This directive will not cause the running task to be preempted.
+.. rubric:: PARAMETERS:
-EXAMPLE:
- .. code-block:: c
+``uptime``
+ This parameter is the pointer to a timeval structure variable. The seconds
+ and microseconds elapsed since some time point during the system
+ initialization and some point during the directive call using
+ :term:`CLOCK_MONOTONIC` will be stored in this variable. The pointer shall
+ be valid, otherwise the behaviour is undefined.
- status busy( void )
- {
- rtems_interval timeout = rtems_clock_tick_later_usec( 10000 );
- do {
- if ( ok() ) {
- return success;
- }
- } while ( rtems_clock_tick_before( timeout ) );
- return timeout;
- }
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+* The directive requires a :term:`Clock Driver`.
+
+.. Generated from spec:/rtems/clock/if/get-uptime-seconds
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_clock_get_uptime_seconds()
+
+.. _InterfaceRtemsClockGetUptimeSeconds:
+
+rtems_clock_get_uptime_seconds()
+--------------------------------
-.. index:: clock get uptime
-.. index:: uptime
-.. index:: rtems_clock_get_uptime
+Gets the seconds elapsed since some time point during the system initialization
+using :term:`CLOCK_MONOTONIC`.
-.. _rtems_clock_get_uptime:
+.. rubric:: CALLING SEQUENCE:
-CLOCK_GET_UPTIME - Get the time since boot
-------------------------------------------
+.. code-block:: c
-CALLING SEQUENCE:
- .. code-block:: c
+ time_t rtems_clock_get_uptime_seconds( void );
- rtems_status_code rtems_clock_get_uptime(
- struct timespec *uptime
- );
+.. rubric:: RETURN VALUES:
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
- * - ``RTEMS_SUCCESSFUL``
- - clock tick processed successfully
- * - ``RTEMS_INVALID_ADDRESS``
- - ``time_buffer`` is ``NULL``
+Returns the seconds elapsed since some time point during the system
+initialization and some point during the directive call using
+:term:`CLOCK_MONOTONIC`.
-DESCRIPTION:
- This directive returns the seconds and nanoseconds since the system was
- booted. If the BSP supports nanosecond clock accuracy, the time reported
- will probably be different on every call.
+.. rubric:: CONSTRAINTS:
-NOTES:
- This directive may be called from an ISR.
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+* The directive requires a :term:`Clock Driver`.
+
+.. Generated from spec:/rtems/clock/if/get-uptime-nanoseconds
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_clock_get_uptime_nanoseconds()
+
+.. _InterfaceRtemsClockGetUptimeNanoseconds:
+
+rtems_clock_get_uptime_nanoseconds()
+------------------------------------
+
+Gets the nanoseconds elapsed since some time point during the system
+initialization using :term:`CLOCK_MONOTONIC`.
-.. index:: clock get uptime interval
-.. index:: uptime
-.. index:: rtems_clock_get_uptime_timeval
+.. rubric:: CALLING SEQUENCE:
-.. _rtems_clock_get_uptime_timeval:
+.. code-block:: c
-CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format
---------------------------------------------------------------------
+ uint64_t rtems_clock_get_uptime_nanoseconds( void );
-CALLING SEQUENCE:
- .. code-block:: c
+.. rubric:: RETURN VALUES:
- void rtems_clock_get_uptime_timeval(
- struct timeval *uptime
- );
+Returns the nanoseconds elapsed since some time point during the system
+initialization and some point during the directive call using
+:term:`CLOCK_MONOTONIC`.
-DIRECTIVE STATUS CODES:
- NONE
+.. rubric:: CONSTRAINTS:
-DESCRIPTION:
- This directive returns the seconds and microseconds since the system was
- booted. If the BSP supports nanosecond clock accuracy, the time reported
- will probably be different on every call.
+The following constraints apply to this directive:
-NOTES:
- This directive may be called from an ISR.
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+* The directive requires a :term:`Clock Driver`.
+
+.. Generated from spec:/rtems/clock/if/tick-later
.. raw:: latex
- \clearpage
+ \clearpage
+
+.. index:: rtems_clock_tick_later()
+
+.. _InterfaceRtemsClockTickLater:
+
+rtems_clock_tick_later()
+------------------------
+
+Gets a :term:`clock tick` value which is at least delta clock ticks in the
+future.
+
+.. rubric:: CALLING SEQUENCE:
-.. index:: clock get uptime seconds
-.. index:: uptime
-.. index:: rtems_clock_get_uptime_seconds
+.. code-block:: c
-.. _rtems_clock_get_uptime_seconds:
+ rtems_interval rtems_clock_tick_later( rtems_interval delta );
-CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot
------------------------------------------------------
+.. rubric:: PARAMETERS:
-CALLING SEQUENCE:
- .. code-block:: c
+``delta``
+ This parameter is the delta value in clock ticks.
- time_t rtems_clock_get_uptime_seconds(void);
+.. rubric:: RETURN VALUES:
-DIRECTIVE STATUS CODES:
- The system uptime in seconds.
+Returns a :term:`clock tick` counter value which is at least ``delta`` clock
+ticks in the future.
-DESCRIPTION:
- This directive returns the seconds since the system was booted.
+.. rubric:: CONSTRAINTS:
-NOTES:
- This directive may be called from an ISR.
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+* The directive requires a :term:`Clock Driver`.
+
+.. Generated from spec:/rtems/clock/if/tick-later-usec
.. raw:: latex
- \clearpage
+ \clearpage
-.. index:: clock get nanoseconds uptime
-.. index:: uptime
-.. index:: rtems_clock_get_uptime_nanoseconds
+.. index:: rtems_clock_tick_later_usec()
+
+.. _InterfaceRtemsClockTickLaterUsec:
+
+rtems_clock_tick_later_usec()
+-----------------------------
-.. _rtems_clock_get_uptime_nanoseconds:
+Gets a :term:`clock tick` value which is at least delta microseconds in the
+future.
-CLOCK_GET_UPTIME_NANOSECONDS - Get the nanoseconds since boot
--------------------------------------------------------------
+.. rubric:: CALLING SEQUENCE:
-CALLING SEQUENCE:
- .. code-block:: c
+.. code-block:: c
- uint64_t rtems_clock_get_uptime_nanoseconds(void);
+ rtems_interval rtems_clock_tick_later_usec( rtems_interval delta_in_usec );
-DIRECTIVE STATUS CODES:
- The system uptime in nanoseconds.
+.. rubric:: PARAMETERS:
-DESCRIPTION:
- This directive returns the nanoseconds since the system was booted.
+``delta_in_usec``
+ This parameter is the delta value in microseconds.
-NOTES:
- This directive may be called from an ISR.
+.. rubric:: RETURN VALUES:
-Removed Directives
-==================
+Returns a :term:`clock tick` counter value which is at least ``delta_in_usec``
+microseconds in the future.
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+* The directive requires a :term:`Clock Driver`.
+
+.. Generated from spec:/rtems/clock/if/tick-before
.. raw:: latex
- \clearpage
-
-.. _rtems_clock_get:
-
-CLOCK_GET - Get date and time information
------------------------------------------
-.. index:: obtain the time of day
-.. index:: rtems_clock_get
-
-.. warning::
-
- This directive was removed in RTEMS 5.1. See also
- :ref:`ClockManagerAdviceClockGet`.
-
-CALLING SEQUENCE:
- .. code-block:: c
-
- rtems_status_code rtems_clock_get(
- rtems_clock_get_options option,
- void *time_buffer
- );
-
-DIRECTIVE STATUS CODES:
- .. list-table::
- :class: rtems-table
-
- * - ``RTEMS_SUCCESSFUL``
- - current time obtained successfully
- * - ``RTEMS_NOT_DEFINED``
- - system date and time is not set
- * - ``RTEMS_INVALID_ADDRESS``
- - ``time_buffer`` is NULL
-
-DESCRIPTION:
- This directive obtains the system date and time. If the caller is
- attempting to obtain the date and time (i.e. option is set to either
- ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH``, ``RTEMS_CLOCK_GET_TOD``, or
- ``RTEMS_CLOCK_GET_TIME_VALUE``) and the date and time has not been set with
- a previous call to ``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED``
- status code is returned. The caller can always obtain the number of ticks
- per second (option is ``RTEMS_CLOCK_GET_TICKS_PER_SECOND``) and the number
- of ticks since the executive was initialized option is
- ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT``).
-
- The ``option`` argument may taken on any value of the enumerated type
- ``rtems_clock_get_options``. The data type expected for ``time_buffer`` is
- based on the value of ``option`` as indicated below:
-
- .. index:: rtems_clock_get_options
-
- +-----------------------------------------+---------------------------+
- | Option | Return type |
- +=========================================+===========================+
- | ``RTEMS_CLOCK_GET_TOD`` | ``(rtems_time_of_day *)`` |
- +-----------------------------------------+---------------------------+
- | ``RTEMS_CLOCK_GET_SECONDS_SINCE_EPOCH`` | ``(rtems_interval *)`` |
- +-----------------------------------------+---------------------------+
- | ``RTEMS_CLOCK_GET_TICKS_SINCE_BOOT`` | ``(rtems_interval *)`` |
- +-----------------------------------------+---------------------------+
- |``RTEMS_CLOCK_GET_TICKS_PER_SECOND`` | ``(rtems_interval *)`` |
- +-----------------------------------------+---------------------------+
- | ``RTEMS_CLOCK_GET_TIME_VALUE`` | ``(struct timeval *)`` |
- +-----------------------------------------+---------------------------+
-
-NOTES:
- This directive is callable from an ISR.
-
- This directive will not cause the running task to be preempted.
- Re-initializing RTEMS causes the system date and time to be reset to an
- uninitialized state. Another call to ``rtems_clock_set`` is required to
- re-initialize the system date and time to application specific
- specifications.
+ \clearpage
+
+.. index:: rtems_clock_tick_before()
+
+.. _InterfaceRtemsClockTickBefore:
+
+rtems_clock_tick_before()
+-------------------------
+
+Indicates if the current :term:`clock tick` counter is before the ticks.
+
+.. rubric:: CALLING SEQUENCE:
+
+.. code-block:: c
+
+ bool rtems_clock_tick_before( rtems_interval ticks );
+
+.. rubric:: PARAMETERS:
+
+``ticks``
+ This parameter is the ticks value to check.
+
+.. rubric:: RETURN VALUES:
+
+Returns true, if current :term:`clock tick` counter indicates a time before the
+time in ticks, otherwise returns false.
+
+.. rubric:: NOTES:
+
+This directive can be used to write busy loops with a timeout.
+
+.. code-block:: c
+ :linenos:
+
+ status busy( void )
+ {
+ rtems_interval timeout;
+
+ timeout = rtems_clock_tick_later_usec( 10000 );
+
+ do {
+ if ( ok() ) {
+ return success;
+ }
+ } while ( rtems_clock_tick_before( timeout ) );
+
+ return timeout;
+ }
+
+.. rubric:: CONSTRAINTS:
+
+The following constraints apply to this directive:
+
+* The directive may be called from within any runtime context.
+
+* The directive will not cause the calling task to be preempted.
+
+* The directive requires a :term:`Clock Driver`.
diff --git a/c-user/clock/introduction.rst b/c-user/clock/introduction.rst
index e952d7d..2bad4e1 100644
--- a/c-user/clock/introduction.rst
+++ b/c-user/clock/introduction.rst
@@ -1,36 +1,87 @@
.. 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
+
+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_set`
+* :ref:`InterfaceRtemsClockSet` - Sets the :term:`CLOCK_REALTIME` to the time.
-- :ref:`rtems_clock_get_tod`
+* :ref:`InterfaceRtemsClockGetTod` - Gets the time of day associated with the
+ current :term:`CLOCK_REALTIME`.
-- :ref:`rtems_clock_get_tod_timeval`
+* :ref:`InterfaceRtemsClockGetTodTimeval` - Gets the seconds and microseconds
+ elapsed since the :term:`Unix epoch` and the current :term:`CLOCK_REALTIME`.
-- :ref:`rtems_clock_get_seconds_since_epoch`
+* :ref:`InterfaceRtemsClockGetSecondsSinceEpoch` - Gets the seconds elapsed
+ since the :term:`RTEMS epoch` and the current :term:`CLOCK_REALTIME`.
-- :ref:`rtems_clock_get_ticks_per_second`
+* :ref:`InterfaceRtemsClockGetTicksPerSecond` - Gets the number of :term:`clock
+ ticks <clock tick>` per second configured for the application.
-- :ref:`rtems_clock_get_ticks_since_boot`
+* :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`
+* :ref:`InterfaceRtemsClockGetUptime` - Gets the seconds and nanoseconds
+ elapsed since some time point during the system initialization using
+ :term:`CLOCK_MONOTONIC`.
-- :ref:`rtems_clock_tick_later_usec`
+* :ref:`InterfaceRtemsClockGetUptimeTimeval` - Gets the seconds and
+ microseconds elapsed since some time point during the system initialization
+ using :term:`CLOCK_MONOTONIC`.
-- :ref:`rtems_clock_tick_before`
+* :ref:`InterfaceRtemsClockGetUptimeSeconds` - Gets the seconds elapsed since
+ some time point during the system initialization using
+ :term:`CLOCK_MONOTONIC`.
-- :ref:`rtems_clock_get_uptime`
+* :ref:`InterfaceRtemsClockGetUptimeNanoseconds` - Gets the nanoseconds elapsed
+ since some time point during the system initialization using
+ :term:`CLOCK_MONOTONIC`.
-- :ref:`rtems_clock_get_uptime_timeval`
+* :ref:`InterfaceRtemsClockTickLater` - Gets a :term:`clock tick` value which
+ is at least delta clock ticks in the future.
-- :ref:`rtems_clock_get_uptime_seconds`
+* :ref:`InterfaceRtemsClockTickLaterUsec` - Gets a :term:`clock tick` value
+ which is at least delta microseconds in the future.
-- :ref:`rtems_clock_get_uptime_nanoseconds`
+* :ref:`InterfaceRtemsClockTickBefore` - Indicates if the current :term:`clock
+ tick` counter is before the ticks.
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.
--
2.26.2
More information about the devel
mailing list