[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