[PATCH v2 12/12] c-user: Generate clock manager documentation
Frank Kühndel
frank.kuehndel at embedded-brains.de
Thu Feb 11 13:31:54 UTC 2021
Hello Sebastian,
On 2/10/21 5:28 PM, Sebastian Huber wrote:
> 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 );
A comment only: The above is a change in the signature of the function
(adding `const`). Not that I object to it - on the contrary. Yet, it may
break existing code (e.g. code which uses function pointers to
rtems_clock_set() maybe). Not sure how the project deals with such
changes in the API.
Note: You renamed this parameter to `time` but you renamed the parameter
of rtems_clock_get_tod() to `time_of_day`.
>
> -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
Note: If I see this right, there is no description for the
rtems_clock_get_tod() function and the
rtems_clock_get_seconds_since_epoch() function. In a sense a description
may not be needed as for such simple function everything is said in the
parameter description and the constraints.
> +.. 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 _______________________________________________ devel mailing
> list devel at rtems.org http://lists.rtems.org/mailman/listinfo/devel
>
--
embedded brains GmbH
Herr Frank KÜHNDEL
Dornierstr. 4
82178 Puchheim
Germany
email: frank.kuehndel at embedded-brains.de
phone: +49-89-18 94 741 - 23
fax: +49-89-18 94 741 - 08
Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier:
https://embedded-brains.de/datenschutzerklaerung/
More information about the devel
mailing list