diff options
| -rw-r--r-- | c-user/clock/directives.rst | 874 | ||||
| -rw-r--r-- | c-user/clock/introduction.rst | 84 | ||||
| -rw-r--r-- | c-user/glossary.rst | 53 |
3 files changed, 613 insertions, 398 deletions
diff --git a/c-user/clock/directives.rst b/c-user/clock/directives.rst index 06fe38b..a13b5ef 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 of day. - 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_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_of_day`` + This parameter is the time of day 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_of_day`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. -.. raw:: latex +:c:macro:`RTEMS_INVALID_CLOCK` + The time of day specified by ``time_of_day`` was invalid. - \clearpage +.. rubric:: NOTES: -.. index:: obtain the time of day -.. index:: rtems_clock_get_tod +The date, time, and ticks specified by ``time_of_day`` are all range-checked, +and an error is returned if any one is out of its valid range. -.. _rtems_clock_get_tod: +RTEMS can represent time points of this clock in nanoseconds ranging from +1988-01-01T00:00:00.000000000Z to 2514-05-31T01:53:03.999999999Z. The future +uptime of the system shall be in this range, otherwise the system behaviour is +undefined. -CLOCK_GET_TOD - Get date and time in TOD format ------------------------------------------------ +The specified time is based on the configured :term:`clock tick` rate, see the +:ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration option. -CALLING SEQUENCE: - .. code-block:: c +Setting the time forward will fire all :term:`CLOCK_REALTIME` timers which are +scheduled at a time point before or at the time set by the directive. This may +unblock tasks, which may preempt the calling task. User-provided timer routines +will execute in the context of the caller. - rtems_status_code rtems_clock_get_tod( - rtems_time_of_day *time_buffer - ); +It is allowed to call this directive from within interrupt context, however, +this is not recommended since an arbitrary number of timers may fire. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +The directive shall be called at least once to enable the service of +:term:`CLOCK_REALTIME` related directives. If the clock is not set at least +once, they may return an error status. - * - ``RTEMS_SUCCESSFUL`` - - current time obtained successfully - * - ``RTEMS_NOT_DEFINED`` - - system date and time is not set - * - ``RTEMS_INVALID_ADDRESS`` - - ``time_buffer`` is NULL +.. rubric:: CONSTRAINTS: -DESCRIPTION: - This directive obtains the system date and time. If the date and time has - not been set with a previous call to ``rtems_clock_set``, then the - ``RTEMS_NOT_DEFINED`` status code is returned. +The following constraints apply to this directive: -NOTES: - This directive is callable from an ISR. +* The directive may be called from within any runtime context. - This directive will not cause the running task to be preempted. - Re-initializing RTEMS causes the system date and time to be reset to an - uninitialized state. Another call to ``rtems_clock_set`` is required to - re-initialize the system date and time to application specific - specifications. +* The directive may change the priority of another task which may preempt the + calling task. + +* The directive may unblock another task which may preempt the calling task. + +.. Generated from spec:/rtems/clock/if/get-tod .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_clock_get_tod() + +.. _InterfaceRtemsClockGetTod: + +rtems_clock_get_tod() +--------------------- + +Gets the time of day associated with the current :term:`CLOCK_REALTIME`. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_clock_get_tod( rtems_time_of_day *time_of_day ); + +.. rubric:: PARAMETERS: + +``time_of_day`` + This parameter is the pointer to a RTEMS time of day variable. When the + directive call is successful, the time of day associated with the + :term:`CLOCK_REALTIME` at some point during the directive call will be + stored in this variable. + +.. rubric:: RETURN VALUES: -.. index:: obtain the time of day -.. index:: rtems_clock_get_tod_timeval +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. -.. _rtems_clock_get_tod_timeval: +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``time_of_day`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. -CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format ------------------------------------------------------------ +:c:macro:`RTEMS_NOT_DEFINED` + The :term:`CLOCK_REALTIME` was not set. It can be set with + :ref:`InterfaceRtemsClockSet`. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: CONSTRAINTS: - rtems_status_code rtems_clock_get_tod_interval( - struct timeval *time - ); +The following constraints apply to this directive: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - current time obtained successfully - * - ``RTEMS_NOT_DEFINED`` - - system date and time is not set - * - ``RTEMS_INVALID_ADDRESS`` - - ``time`` is NULL +* The directive may be called from within any runtime context. -DESCRIPTION: - This directive obtains the system date and time in POSIX ``struct timeval`` - format. If the date and time has not been set with a previous call to - ``rtems_clock_set``, then the ``RTEMS_NOT_DEFINED`` status code is - returned. +* The directive will not cause the calling task to be preempted. -NOTES: - This directive is callable from an ISR. +* The directive requires a :term:`Clock Driver`. - This directive will not cause the running task to be preempted. - Re-initializing RTEMS causes the system date and time to be reset to an - uninitialized state. Another call to ``rtems_clock_set`` is required to - re-initialize the system date and time to application specific - specifications. +.. Generated from spec:/rtems/clock/if/get-tod-timeval .. raw:: latex - \clearpage + \clearpage -.. index:: obtain seconds since epoch -.. index:: rtems_clock_get_seconds_since_epoch +.. index:: rtems_clock_get_tod_timeval() -.. _rtems_clock_get_seconds_since_epoch: +.. _InterfaceRtemsClockGetTodTimeval: -CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch -------------------------------------------------------- +rtems_clock_get_tod_timeval() +----------------------------- + +Gets the seconds and microseconds elapsed since the :term:`Unix epoch` and the +current :term:`CLOCK_REALTIME`. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_clock_get_tod_timeval( struct timeval *time_of_day ); + +.. rubric:: PARAMETERS: + +``time_of_day`` + 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_of_day`` 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..ad4b14c 100644 --- a/c-user/clock/introduction.rst +++ b/c-user/clock/introduction.rst @@ -1,36 +1,88 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de) .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/clock/if/group + +.. _ClockManagerIntroduction: + Introduction ============ -The clock manager provides support for time of day -and other time related capabilities. The directives provided by -the clock manager are: +.. The following list was generated from: +.. spec:/rtems/clock/if/set +.. spec:/rtems/clock/if/get-tod +.. spec:/rtems/clock/if/get-tod-timeval +.. spec:/rtems/clock/if/get-seconds-since-epoch +.. spec:/rtems/clock/if/get-ticks-per-second +.. spec:/rtems/clock/if/get-ticks-since-boot +.. spec:/rtems/clock/if/get-uptime +.. spec:/rtems/clock/if/get-uptime-timeval +.. spec:/rtems/clock/if/get-uptime-seconds +.. spec:/rtems/clock/if/get-uptime-nanoseconds +.. spec:/rtems/clock/if/tick-later +.. spec:/rtems/clock/if/tick-later-usec +.. spec:/rtems/clock/if/tick-before + +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 + of day. -- :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. |