diff options
Diffstat (limited to 'c-user/clock/directives.rst')
-rw-r--r-- | c-user/clock/directives.rst | 1718 |
1 files changed, 1341 insertions, 377 deletions
diff --git a/c-user/clock/directives.rst b/c-user/clock/directives.rst index 06fe38b..a6e00ca 100644 --- a/c-user/clock/directives.rst +++ b/c-user/clock/directives.rst @@ -1,549 +1,1513 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2014, 2021 embedded brains GmbH & Co. KG .. 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:: rtems_clock_set() + +.. _InterfaceRtemsClockSet: + +rtems_clock_set() +----------------- + +Sets the :term:`CLOCK_REALTIME` to the time of day. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_clock_set( const rtems_time_of_day *time_of_day ); + +.. rubric:: PARAMETERS: + +``time_of_day`` + This parameter is the time of day to set the clock. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``time_of_day`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_CLOCK` + The time of day specified by ``time_of_day`` was invalid. -.. index:: set the time of day -.. index:: rtems_clock_set +.. rubric:: NOTES: -.. _rtems_clock_set: +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. -CLOCK_SET - Set date and time +RTEMS can represent time points of the :term:`CLOCK_REALTIME` 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. Due to implementation +constraints, the time of day set by the directive shall be before +2100-01-01:00:00.000000000Z. The latest valid time of day accepted by the +POSIX `clock_settime() +<https://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_settime.html>`_ +is 2400-01-01T00:00:00.999999999Z. + +The specified time is based on the configured :term:`clock tick` rate, see the +:ref:`CONFIGURE_MICROSECONDS_PER_TICK` application configuration option. + +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. + +It is allowed to call this directive from within interrupt context, however, +this is not recommended since an arbitrary number of timers may fire. + +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. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive may change the priority of a task. This may cause the calling + task to be preempted. + +* The directive may unblock a task. This may cause the calling task to be + preempted. + +* The time of day set by the directive shall be 1988-01-01T00:00:00.000000000Z + or later. + +* The time of day set by the directive shall be before + 2100-01-01T00:00:00.000000000Z. + +.. Generated from spec:/rtems/clock/if/get-tod + +.. raw:: latex + + \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 an :ref:`InterfaceRtemsTimeOfDay` object. + 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 object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``time_of_day`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +: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-tod-timeval + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_tod_timeval() + +.. _InterfaceRtemsClockGetTodTimeval: + +rtems_clock_get_tod_timeval() ----------------------------- -CALLING SEQUENCE: - .. code-block:: c +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 `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. 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 object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``time_of_day`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +: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-realtime + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_realtime() + +.. _InterfaceRtemsClockGetRealtime: + +rtems_clock_get_realtime() +-------------------------- + +Gets the time elapsed since the :term:`Unix epoch` measured using +:term:`CLOCK_REALTIME` in seconds and nanoseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_realtime( struct timespec *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a `struct timespec + <https://en.cppreference.com/w/c/chrono/timespec>`_ object. The time + elapsed since the :term:`Unix epoch` measured using the + :term:`CLOCK_REALTIME` at some time point during the directive call will be + stored in this object. Calling the directive with a pointer equal to `NULL + <https://en.cppreference.com/w/c/types/NULL>`_ is undefined behaviour. + +.. rubric:: NOTES: + +The directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. Alternatively, the +:ref:`InterfaceRtemsClockGetRealtimeCoarse` directive may be used to get the +time in a lower resolution and with less runtime overhead. + +See :ref:`InterfaceRtemsClockGetRealtimeBintime` and +:ref:`InterfaceRtemsClockGetRealtimeTimeval` to get the time in alternative +formats. + +.. 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-realtime-bintime + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_realtime_bintime() + +.. _InterfaceRtemsClockGetRealtimeBintime: + +rtems_clock_get_realtime_bintime() +---------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` measured using +:term:`CLOCK_REALTIME` in binary time format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_realtime_bintime( struct bintime *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a ``struct bintime`` object. The time + elapsed since the :term:`Unix epoch` measured using the + :term:`CLOCK_REALTIME` at some time point during the directive call will be + stored in this object. Calling the directive with a pointer equal to `NULL + <https://en.cppreference.com/w/c/types/NULL>`_ is undefined behaviour. + +.. rubric:: NOTES: + +The directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. Alternatively, the +:ref:`InterfaceRtemsClockGetRealtimeCoarseBintime` directive may be used to get +the time in a lower resolution and with less runtime overhead. + +See :ref:`InterfaceRtemsClockGetRealtime` and +:ref:`InterfaceRtemsClockGetRealtimeTimeval` to get the time in alternative +formats. + +.. 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-realtime-timeval + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_realtime_timeval() + +.. _InterfaceRtemsClockGetRealtimeTimeval: + +rtems_clock_get_realtime_timeval() +---------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` measured using +:term:`CLOCK_REALTIME` in seconds and microseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_realtime_timeval( struct timeval *time_snapshot ); - rtems_status_code rtems_clock_set( - rtems_time_of_day *time_buffer - ); +.. rubric:: PARAMETERS: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +``time_snapshot`` + This parameter is the pointer to a `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. The time elapsed since the :term:`Unix epoch` measured using the + :term:`CLOCK_REALTIME` at some time point during the directive call will be + stored in this object. Calling the directive with a pointer equal to `NULL + <https://en.cppreference.com/w/c/types/NULL>`_ is undefined behaviour. - * - ``RTEMS_SUCCESSFUL`` - - date and time set successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``time_buffer`` is NULL - * - ``RTEMS_INVALID_CLOCK`` - - invalid time of day +.. rubric:: NOTES: -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. +The directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. Alternatively, the +:ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` directive may be used to get +the time in a lower resolution and with less runtime overhead. -NOTES: - Years before 1988 are invalid. +See :ref:`InterfaceRtemsClockGetRealtime` and +:ref:`InterfaceRtemsClockGetRealtimeBintime` to get the time in alternative +formats. - The system date and time are based on the configured tick rate (number of - microseconds in a tick). +.. rubric:: CONSTRAINTS: - 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. +The following constraints apply to this directive: - 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-realtime-coarse .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_clock_get_realtime_coarse() + +.. _InterfaceRtemsClockGetRealtimeCoarse: + +rtems_clock_get_realtime_coarse() +--------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` measured using +:term:`CLOCK_REALTIME` in coarse resolution in seconds and nanoseconds format. -.. index:: obtain the time of day -.. index:: rtems_clock_get_tod +.. rubric:: CALLING SEQUENCE: -.. _rtems_clock_get_tod: +.. code-block:: c -CLOCK_GET_TOD - Get date and time in TOD format ------------------------------------------------ + void rtems_clock_get_realtime_coarse( struct timespec *time_snapshot ); -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: PARAMETERS: - rtems_status_code rtems_clock_get_tod( - rtems_time_of_day *time_buffer - ); +``time_snapshot`` + This parameter is the pointer to a `struct timespec + <https://en.cppreference.com/w/c/chrono/timespec>`_ object. The time + elapsed since the :term:`Unix epoch` measured using the + :term:`CLOCK_REALTIME` at some time point close to the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table +.. rubric:: NOTES: - * - ``RTEMS_SUCCESSFUL`` - - current time obtained successfully - * - ``RTEMS_NOT_DEFINED`` - - system date and time is not set - * - ``RTEMS_INVALID_ADDRESS`` - - ``time_buffer`` is NULL +The directive does not access a device to get the time. It uses a recent +snapshot provided by the :term:`Clock Driver`. Alternatively, the +:ref:`InterfaceRtemsClockGetRealtime` directive may be used to get the time in +a higher resolution and with a higher runtime overhead. -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. +See :ref:`InterfaceRtemsClockGetRealtimeCoarseBintime` and +:ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` to get the time in +alternative formats. -NOTES: - This directive is callable from an ISR. +.. rubric:: CONSTRAINTS: - 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 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-realtime-coarse-bintime .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_clock_get_realtime_coarse_bintime() + +.. _InterfaceRtemsClockGetRealtimeCoarseBintime: + +rtems_clock_get_realtime_coarse_bintime() +----------------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` measured using +:term:`CLOCK_REALTIME` in coarse resolution in binary time format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_realtime_coarse_bintime( struct bintime *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a ``struct bintime`` object. The time + elapsed since the :term:`Unix epoch` measured using the + :term:`CLOCK_REALTIME` at some time point close to the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. -.. index:: obtain the time of day -.. index:: rtems_clock_get_tod_timeval +.. rubric:: NOTES: -.. _rtems_clock_get_tod_timeval: +The directive does not access a device to get the time. It uses a recent +snapshot provided by the :term:`Clock Driver`. Alternatively, the +:ref:`InterfaceRtemsClockGetRealtimeBintime` directive may be used to get the +time in a higher resolution and with a higher runtime overhead. -CLOCK_GET_TOD_TIMEVAL - Get date and time in timeval format ------------------------------------------------------------ +See :ref:`InterfaceRtemsClockGetRealtimeCoarse` and +:ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` to get the time in +alternative formats. -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-realtime-coarse-timeval .. raw:: latex - \clearpage + \clearpage -.. index:: obtain seconds since epoch -.. index:: rtems_clock_get_seconds_since_epoch +.. index:: rtems_clock_get_realtime_coarse_timeval() -.. _rtems_clock_get_seconds_since_epoch: +.. _InterfaceRtemsClockGetRealtimeCoarseTimeval: -CLOCK_GET_SECONDS_SINCE_EPOCH - Get seconds since epoch -------------------------------------------------------- +rtems_clock_get_realtime_coarse_timeval() +----------------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` measured using +:term:`CLOCK_REALTIME` in coarse resolution in seconds and microseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_realtime_coarse_timeval( struct timeval *time_snapshot ); + +.. rubric:: PARAMETERS: + +``time_snapshot`` + This parameter is the pointer to a `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. The time elapsed since the :term:`Unix epoch` measured using the + :term:`CLOCK_REALTIME` at some time point close to the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: NOTES: - rtems_status_code rtems_clock_get_seconds_since_epoch( - rtems_interval *the_interval - ); +The directive does not access a device to get the time. It uses a recent +snapshot provided by the :term:`Clock Driver`. Alternatively, the +:ref:`InterfaceRtemsClockGetRealtimeTimeval` directive may be used to get the +time in a higher resolution and with a higher runtime overhead. -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 +See :ref:`InterfaceRtemsClockGetRealtimeCoarse` and +:ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` to get the time in +alternative formats. -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-monotonic .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_clock_get_monotonic() + +.. _InterfaceRtemsClockGetMonotonic: + +rtems_clock_get_monotonic() +--------------------------- + +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in seconds and nanoseconds format. -.. 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 -------------------------------------------------- + void rtems_clock_get_monotonic( struct timespec *time_snapshot ); -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: PARAMETERS: - rtems_interval rtems_clock_get_ticks_per_second(void); +``time_snapshot`` + This parameter is the pointer to a `struct timespec + <https://en.cppreference.com/w/c/chrono/timespec>`_ object. The time + elapsed since some fixed time point in the past measured using the + :term:`CLOCK_MONOTONIC` at some time point during the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. -DIRECTIVE STATUS CODES: - NONE +.. rubric:: NOTES: -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. +The directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. Alternatively, the +:ref:`InterfaceRtemsClockGetMonotonicCoarse` directive may be used to get the +time with in a lower resolution and with less runtime overhead. -NOTES: - This directive is callable from an ISR. +See :ref:`InterfaceRtemsClockGetMonotonicBintime`, +:ref:`InterfaceRtemsClockGetMonotonicSbintime`, and +:ref:`InterfaceRtemsClockGetMonotonicTimeval` to get the time in alternative +formats. - 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-monotonic-bintime .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_clock_get_monotonic_bintime() + +.. _InterfaceRtemsClockGetMonotonicBintime: -.. index:: obtain ticks since boot -.. index:: get current ticks counter value -.. index:: rtems_clock_get_ticks_since_boot +rtems_clock_get_monotonic_bintime() +----------------------------------- -.. _rtems_clock_get_ticks_since_boot: +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in binary time format. -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); + void rtems_clock_get_monotonic_bintime( struct bintime *time_snapshot ); -DIRECTIVE STATUS CODES: - NONE +.. rubric:: PARAMETERS: -DESCRIPTION: +``time_snapshot`` + This parameter is the pointer to a ``struct bintime`` object. The time + elapsed since some fixed time point in the past measured using the + :term:`CLOCK_MONOTONIC` at some time point during the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. - 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 directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. Alternatively, the +:ref:`InterfaceRtemsClockGetMonotonicCoarseBintime` directive may be used to +get the time in a lower resolution and with less runtime overhead. - This directive is callable from an ISR. +See :ref:`InterfaceRtemsClockGetMonotonic`, +:ref:`InterfaceRtemsClockGetMonotonicSbintime`, and +:ref:`InterfaceRtemsClockGetMonotonicTimeval` to get the time in alternative +formats. - 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. + +* The directive requires a :term:`Clock Driver`. + +.. Generated from spec:/rtems/clock/if/get-monotonic-sbintime .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_clock_get_monotonic_sbintime() + +.. _InterfaceRtemsClockGetMonotonicSbintime: -.. index:: rtems_clock_tick_later +rtems_clock_get_monotonic_sbintime() +------------------------------------ -.. _rtems_clock_tick_later: +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in signed binary time format. -CLOCK_TICK_LATER - Get tick value in the future ------------------------------------------------ +.. rubric:: CALLING SEQUENCE: -CALLING SEQUENCE: - .. code-block:: c +.. code-block:: c - rtems_interval rtems_clock_tick_later( - rtems_interval delta - ); + int64_t rtems_clock_get_monotonic_sbintime( void ); -DESCRIPTION: - Returns the ticks counter value delta ticks in the future. +.. rubric:: RETURN VALUES: -NOTES: - This directive is callable from an ISR. +Returns the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` at some time point during the directive call. - This directive will not cause the running task to be preempted. +.. rubric:: NOTES: + +The directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. + +See :ref:`InterfaceRtemsClockGetMonotonic`, +:ref:`InterfaceRtemsClockGetMonotonicBintime`, and +:ref:`InterfaceRtemsClockGetMonotonicTimeval` to get the time in alternative +formats. + +.. 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-monotonic-timeval .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_clock_get_monotonic_timeval() + +.. _InterfaceRtemsClockGetMonotonicTimeval: + +rtems_clock_get_monotonic_timeval() +----------------------------------- + +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in seconds and microseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_monotonic_timeval( struct timeval *time_snapshot ); -.. index:: rtems_clock_tick_later_usec +.. rubric:: PARAMETERS: -.. _rtems_clock_tick_later_usec: +``time_snapshot`` + This parameter is the pointer to a `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. The time elapsed since some fixed time point in the past measured + using the :term:`CLOCK_MONOTONIC` at some time point during the directive + call will be stored in this object. Calling the directive with a pointer + equal to `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. -CLOCK_TICK_LATER_USEC - Get tick value in the future in microseconds --------------------------------------------------------------------- +.. rubric:: NOTES: -CALLING SEQUENCE: - .. code-block:: c +The directive accesses a device provided by the :term:`Clock Driver` to get the +time in the highest resolution available to the system. Alternatively, the +:ref:`InterfaceRtemsClockGetMonotonicCoarseTimeval` directive may be used to +get the time in a lower resolution and with less runtime overhead. - rtems_interval rtems_clock_tick_later_usec( - rtems_interval delta_in_usec - ); +See :ref:`InterfaceRtemsClockGetMonotonic`, +:ref:`InterfaceRtemsClockGetMonotonicBintime`, and +:ref:`InterfaceRtemsClockGetMonotonicSbintime` to get the time in alternative +formats. -DESCRIPTION: - Returns the ticks counter value at least delta microseconds in the future. +.. 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. +* 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-monotonic-coarse .. raw:: latex - \clearpage + \clearpage -.. index:: rtems_clock_tick_before +.. index:: rtems_clock_get_monotonic_coarse() -.. _rtems_clock_tick_before: +.. _InterfaceRtemsClockGetMonotonicCoarse: -CLOCK_TICK_BEFORE - Is tick value is before a point in time ------------------------------------------------------------ +rtems_clock_get_monotonic_coarse() +---------------------------------- -CALLING SEQUENCE: - .. code-block:: c +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in coarse resolution in seconds and nanoseconds +format. - 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_monotonic_coarse( struct timespec *time_snapshot ); - This directive will not cause the running task to be preempted. +.. rubric:: PARAMETERS: -EXAMPLE: - .. code-block:: c +``time_snapshot`` + This parameter is the pointer to a `struct timespec + <https://en.cppreference.com/w/c/chrono/timespec>`_ object. The time + elapsed since some fixed time point in the past measured using the + :term:`CLOCK_MONOTONIC` at some time point close to the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. - 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:: NOTES: + +The directive does not access a device to get the time. It uses a recent +snapshot provided by the :term:`Clock Driver`. Alternatively, the +:ref:`InterfaceRtemsClockGetMonotonic` directive may be used to get the time in +a higher resolution and with a higher runtime overhead. + +See :ref:`InterfaceRtemsClockGetMonotonicCoarseBintime` and +:ref:`InterfaceRtemsClockGetMonotonicCoarseTimeval` to get the time in +alternative formats. + +.. 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-monotonic-coarse-bintime .. raw:: latex - \clearpage + \clearpage -.. index:: clock get uptime -.. index:: uptime -.. index:: rtems_clock_get_uptime +.. index:: rtems_clock_get_monotonic_coarse_bintime() -.. _rtems_clock_get_uptime: +.. _InterfaceRtemsClockGetMonotonicCoarseBintime: -CLOCK_GET_UPTIME - Get the time since boot +rtems_clock_get_monotonic_coarse_bintime() ------------------------------------------ -CALLING SEQUENCE: - .. code-block:: c +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in coarse resolution in binary time format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c - rtems_status_code rtems_clock_get_uptime( - struct timespec *uptime - ); + void rtems_clock_get_monotonic_coarse_bintime( struct bintime *time_snapshot ); -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-table - * - ``RTEMS_SUCCESSFUL`` - - clock tick processed successfully - * - ``RTEMS_INVALID_ADDRESS`` - - ``time_buffer`` is ``NULL`` +.. rubric:: PARAMETERS: -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. +``time_snapshot`` + This parameter is the pointer to a ``struct bintime`` object. The time + elapsed since some fixed time point in the past measured using the + :term:`CLOCK_MONOTONIC` at some time point close to the directive call will + be stored in this object. Calling the directive with a pointer equal to + `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. -NOTES: - This directive may be called from an ISR. +.. rubric:: NOTES: + +The directive does not access a device to get the time. It uses a recent +snapshot provided by the :term:`Clock Driver`. Alternatively, the +:ref:`InterfaceRtemsClockGetMonotonicBintime` directive may be used to get the +time in a higher resolution and with a higher runtime overhead. + +See :ref:`InterfaceRtemsClockGetMonotonicCoarse` and +:ref:`InterfaceRtemsClockGetMonotonicCoarseTimeval` to get the time in +alternative formats. + +.. 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-monotonic-coarse-timeval .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_clock_get_monotonic_coarse_timeval() + +.. _InterfaceRtemsClockGetMonotonicCoarseTimeval: + +rtems_clock_get_monotonic_coarse_timeval() +------------------------------------------ + +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in coarse resolution in seconds and microseconds +format. + +.. rubric:: CALLING SEQUENCE: -.. index:: clock get uptime interval -.. index:: uptime -.. index:: rtems_clock_get_uptime_timeval +.. code-block:: c -.. _rtems_clock_get_uptime_timeval: + void rtems_clock_get_monotonic_coarse_timeval( struct timeval *time_snapshot ); -CLOCK_GET_UPTIME_TIMEVAL - Get the time since boot in timeval format --------------------------------------------------------------------- +.. rubric:: PARAMETERS: -CALLING SEQUENCE: - .. code-block:: c +``time_snapshot`` + This parameter is the pointer to a `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. The time elapsed since some fixed time point in the past measured + using the :term:`CLOCK_MONOTONIC` at some time point close to the directive + call will be stored in this object. Calling the directive with a pointer + equal to `NULL <https://en.cppreference.com/w/c/types/NULL>`_ is undefined + behaviour. - void rtems_clock_get_uptime_timeval( - struct timeval *uptime - ); +.. rubric:: NOTES: -DIRECTIVE STATUS CODES: - NONE +The directive does not access a device to get the time. It uses a recent +snapshot provided by the :term:`Clock Driver`. Alternatively, the +:ref:`InterfaceRtemsClockGetMonotonicTimeval` directive may be used to get the +time in a higher resolution and with a higher runtime overhead. -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. +See :ref:`InterfaceRtemsClockGetMonotonicCoarse` and +:ref:`InterfaceRtemsClockGetMonotonicCoarseBintime` to get the time in +alternative formats. -NOTES: - This directive may be called from an ISR. +.. 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-boot-time .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_clock_get_boot_time() + +.. _InterfaceRtemsClockGetBootTime: + +rtems_clock_get_boot_time() +--------------------------- + +Gets the time elapsed since the :term:`Unix epoch` at some time point during +system initialization in seconds and nanoseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_boot_time( struct timespec *boot_time ); + +.. rubric:: PARAMETERS: + +``boot_time`` + This parameter is the pointer to a `struct timespec + <https://en.cppreference.com/w/c/chrono/timespec>`_ object. The time + elapsed since the :term:`Unix epoch` at some time point during system + initialization call will be stored in this object. Calling the directive + with a pointer equal to `NULL + <https://en.cppreference.com/w/c/types/NULL>`_ is undefined behaviour. -.. index:: clock get uptime seconds -.. index:: uptime -.. index:: rtems_clock_get_uptime_seconds +.. rubric:: NOTES: -.. _rtems_clock_get_uptime_seconds: +See :ref:`InterfaceRtemsClockGetBootTimeBintime` and +:ref:`InterfaceRtemsClockGetBootTimeTimeval` to get the boot time in +alternative formats. Setting the :term:`CLOCK_REALTIME` will also set the boot +time. -CLOCK_GET_UPTIME_SECONDS - Get the seconds since boot ------------------------------------------------------ +.. rubric:: CONSTRAINTS: -CALLING SEQUENCE: - .. code-block:: c +The following constraints apply to this directive: - time_t rtems_clock_get_uptime_seconds(void); +* The directive may be called from within any runtime context. -DIRECTIVE STATUS CODES: - The system uptime in seconds. +* The directive will not cause the calling task to be preempted. -DESCRIPTION: - This directive returns the seconds since the system was booted. +* The directive requires a :term:`Clock Driver`. -NOTES: - This directive may be called from an ISR. +.. Generated from spec:/rtems/clock/if/get-boot-time-bintime .. raw:: latex - \clearpage + \clearpage -.. index:: clock get nanoseconds uptime -.. index:: uptime -.. index:: rtems_clock_get_uptime_nanoseconds +.. index:: rtems_clock_get_boot_time_bintime() -.. _rtems_clock_get_uptime_nanoseconds: +.. _InterfaceRtemsClockGetBootTimeBintime: -CLOCK_GET_UPTIME_NANOSECONDS - Get the nanoseconds since boot -------------------------------------------------------------- +rtems_clock_get_boot_time_bintime() +----------------------------------- -CALLING SEQUENCE: - .. code-block:: c +Gets the time elapsed since the :term:`Unix epoch` at some time point during +system initialization in binary time format. - uint64_t rtems_clock_get_uptime_nanoseconds(void); +.. rubric:: CALLING SEQUENCE: -DIRECTIVE STATUS CODES: - The system uptime in nanoseconds. +.. code-block:: c -DESCRIPTION: - This directive returns the nanoseconds since the system was booted. + void rtems_clock_get_boot_time_bintime( struct bintime *boot_time ); -NOTES: - This directive may be called from an ISR. +.. rubric:: PARAMETERS: -Removed Directives -================== +``boot_time`` + This parameter is the pointer to a ``struct bintime`` object. The time + elapsed since the :term:`Unix epoch` at some time point during system + initialization call will be stored in this object. Calling the directive + with a pointer equal to `NULL + <https://en.cppreference.com/w/c/types/NULL>`_ is undefined behaviour. + +.. rubric:: NOTES: + +See :ref:`InterfaceRtemsClockGetBootTime` and +:ref:`InterfaceRtemsClockGetBootTimeTimeval` to get the boot time in +alternative formats. Setting the :term:`CLOCK_REALTIME` will also set the boot +time. + +.. 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-boot-time-timeval .. raw:: latex - \clearpage + \clearpage -.. _rtems_clock_get: +.. index:: rtems_clock_get_boot_time_timeval() -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. +.. _InterfaceRtemsClockGetBootTimeTimeval: + +rtems_clock_get_boot_time_timeval() +----------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` at some time point during +system initialization in seconds and microseconds format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_boot_time_timeval( struct timeval *boot_time ); + +.. rubric:: PARAMETERS: + +``boot_time`` + This parameter is the pointer to a `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. The time elapsed since the :term:`Unix epoch` at some time point + during system initialization call will be stored in this object. Calling + the directive with a pointer equal to `NULL + <https://en.cppreference.com/w/c/types/NULL>`_ is undefined behaviour. + +.. rubric:: NOTES: + +See :ref:`InterfaceRtemsClockGetBootTime` and +:ref:`InterfaceRtemsClockGetBootTimeBintime` to get the boot time in +alternative formats. Setting the :term:`CLOCK_REALTIME` will also set the boot +time. + +.. 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-seconds-since-epoch + +.. raw:: latex + + \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`. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_clock_get_seconds_since_epoch( + rtems_interval *seconds_since_rtems_epoch + ); + +.. rubric:: PARAMETERS: + +``seconds_since_rtems_epoch`` + This parameter is the pointer to an :ref:`InterfaceRtemsInterval` object. + 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 object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``seconds_since_rtems_epoch`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +: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 + +.. index:: rtems_clock_get_ticks_per_second() + +.. _InterfaceRtemsClockGetTicksPerSecond: + +rtems_clock_get_ticks_per_second() +---------------------------------- + +Gets the number of :term:`clock ticks <clock tick>` per second configured for +the application. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_interval rtems_clock_get_ticks_per_second( void ); + +.. rubric:: RETURN VALUES: + +Returns the number of clock ticks per second configured for this application. + +.. rubric:: NOTES: + +The number of clock ticks per second is defined indirectly by the +:ref:`CONFIGURE_MICROSECONDS_PER_TICK` configuration option. + +.. 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-ticks-since-boot + +.. raw:: latex + + \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. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_interval rtems_clock_get_ticks_since_boot( void ); + +.. rubric:: RETURN VALUES: + +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. + +.. rubric:: NOTES: + +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. + +.. 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 + +.. 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`. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_clock_get_uptime( struct timespec *uptime ); + +.. rubric:: PARAMETERS: + +``uptime`` + This parameter is the pointer to a `struct timespec + <https://en.cppreference.com/w/c/chrono/timespec>`_ object. 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 object. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +: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 + +.. index:: rtems_clock_get_uptime_timeval() + +.. _InterfaceRtemsClockGetUptimeTimeval: + +rtems_clock_get_uptime_timeval() +-------------------------------- + +Gets the seconds and microseconds elapsed since some time point during the +system initialization using :term:`CLOCK_MONOTONIC`. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_uptime_timeval( struct timeval *uptime ); + +.. rubric:: PARAMETERS: + +``uptime`` + This parameter is the pointer to a `struct timeval + <https://pubs.opengroup.org/onlinepubs/009695399/basedefs/sys/time.h.html>`_ + object. 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 object. The pointer shall + be valid, otherwise the behaviour is undefined. + +.. 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 + +.. index:: rtems_clock_get_uptime_seconds() + +.. _InterfaceRtemsClockGetUptimeSeconds: + +rtems_clock_get_uptime_seconds() +-------------------------------- + +Gets the seconds elapsed since some time point during the system initialization +using :term:`CLOCK_MONOTONIC`. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + time_t rtems_clock_get_uptime_seconds( void ); + +.. rubric:: RETURN VALUES: + +Returns the seconds elapsed since some time point during the system +initialization and some point during the directive call using +:term:`CLOCK_MONOTONIC`. + +.. 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-nanoseconds + +.. raw:: latex + + \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`. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + uint64_t rtems_clock_get_uptime_nanoseconds( void ); + +.. rubric:: RETURN VALUES: + +Returns the nanoseconds elapsed since some time point during the system +initialization and some point during the directive call using +:term:`CLOCK_MONOTONIC`. + +.. 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-later + +.. raw:: latex + + \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: + +.. code-block:: c + + rtems_interval rtems_clock_tick_later( rtems_interval delta ); + +.. rubric:: PARAMETERS: + +``delta`` + This parameter is the delta value in clock ticks. + +.. rubric:: RETURN VALUES: + +Returns a :term:`clock tick` counter value which is at least ``delta`` clock +ticks 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-later-usec + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_tick_later_usec() + +.. _InterfaceRtemsClockTickLaterUsec: + +rtems_clock_tick_later_usec() +----------------------------- + +Gets a :term:`clock tick` value which is at least delta microseconds in the +future. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_interval rtems_clock_tick_later_usec( rtems_interval delta_in_usec ); + +.. rubric:: PARAMETERS: + +``delta_in_usec`` + This parameter is the delta value in microseconds. + +.. rubric:: RETURN VALUES: + +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 + +.. 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`. |