diff options
Diffstat (limited to 'c-user/clock/directives.rst')
-rw-r--r-- | c-user/clock/directives.rst | 874 |
1 files changed, 492 insertions, 382 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`. |