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@rtems.org http://lists.rtems.org/mailman/listinfo/devel > -- embedded brains GmbH Herr Frank KÜHNDEL Dornierstr. 4 82178 Puchheim Germany email: frank.kuehn...@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/ _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
