diff options
Diffstat (limited to 'c-user/clock')
| -rw-r--r-- | c-user/clock/background.rst | 85 | ||||
| -rw-r--r-- | c-user/clock/directives.rst | 858 | ||||
| -rw-r--r-- | c-user/clock/index.rst | 2 | ||||
| -rw-r--r-- | c-user/clock/introduction.rst | 83 | ||||
| -rw-r--r-- | c-user/clock/removed-directives.rst | 2 |
5 files changed, 987 insertions, 43 deletions
diff --git a/c-user/clock/background.rst b/c-user/clock/background.rst index 64e8311..11a3cb5 100644 --- a/c-user/clock/background.rst +++ b/c-user/clock/background.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2021 embedded brains GmbH & Co. KG .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) Background @@ -8,20 +9,28 @@ Background Required Support ---------------- -For the features provided by the clock manager to be utilized, periodic timer -interrupts are required. Therefore, a real-time clock or hardware timer is -necessary to create the timer interrupts. The clock tick directive -is normally called by the timer ISR to announce to RTEMS that a system clock -tick has occurred. Elapsed time is measured in ticks. A tick is defined to be -an integral number of microseconds which is specified by the user in the -Configuration Table. +For the features provided by the Clock Manager to be utilized, a :term:`Clock +Driver` is required. The Clock Driver usually provides a clock interrupt which +is serviced on each configured processor at each :term:`clock tick`. In +addition, the Clock Driver provides three clock sources: + +* clock tick + +* :term:`CLOCK_REALTIME` + +* :term:`CLOCK_MONOTONIC` + +The time of these clock sources advances at each clock tick. This yields the +time of the clock sources in a coarse resolution. To get the time of the +``CLOCK_REALTIME`` or ``CLOCK_MONOTONIC`` clock sources in a higher resolution, +the Clock Driver may use a clock device to get the time between clock ticks. .. _Time and Date Data Structures: Time and Date Data Structures ----------------------------- -The clock facilities of the clock manager operate upon calendar time. These +The clock facilities of the Clock Manager operate upon calendar time. These directives utilize the following date and time structure for the native time and date format: @@ -29,7 +38,7 @@ and date format: .. code-block:: c - struct rtems_tod_control { + typedef struct { uint32_t year; /* greater than 1987 */ uint32_t month; /* 1 - 12 */ uint32_t day; /* 1 - 31 */ @@ -37,20 +46,34 @@ and date format: uint32_t minute; /* 0 - 59 */ uint32_t second; /* 0 - 59 */ uint32_t ticks; /* elapsed between seconds */ - }; - typedef struct rtems_tod_control rtems_time_of_day; + } rtems_time_of_day; The native date and time format is the only format supported when setting the -system date and time using the ``rtems_clock_set`` directive. Some +system date and time using the :ref:`InterfaceRtemsClockSet` directive. Some applications expect to operate on a *UNIX-style* date and time data structure. -The ``rtems_clock_get_tod_timeval`` always returns the date and time in -``struct timeval`` format. - -The ``struct timeval`` data structure has two fields: ``tv_sec`` and -``tv_usec`` which are seconds and microseconds, respectively. The ``tv_sec`` -field in this data structure is the number of seconds since the POSIX epoch of -*January 1, 1970* but will never be prior to the RTEMS epoch of *January 1, -1988*. +For example, the :ref:`InterfaceRtemsClockGetTodTimeval` returns the date and +time in ``struct timeval`` format. + +.. index:: struct timeval +.. index:: struct timespec + +Some directives use data structures defined by :term:`POSIX`. The ``struct +timeval`` data structure has two members: ``tv_sec`` and ``tv_usec`` which are +seconds and microseconds, respectively. The ``struct timespec`` data structure +has two members: ``tv_sec`` and ``tv_nsec`` which are seconds and nanoseconds, +respectively. For :term:`CLOCK_REALTIME` time points, the ``tv_sec`` member in +these data structures is the number of seconds since the :term:`Unix epoch` but +will never be prior to the :term:`RTEMS epoch`. + +.. index:: struct bintime +.. index:: sbintime_t + +The ``struct bintime`` and ``sbintime_t`` time formats used by some directives +originate in FreeBSD. The ``struct bintime`` data structure which represents +time in a binary time format has two members: ``sec`` and ``frac`` which are +seconds and fractions of a second in units of :math:`1 / 2^{64}` seconds, +respectively. The ``sbintime_t`` type is a signed 64-bit integer type used to +represent time in units of :math:`1 / 2^{32}` seconds. .. index:: timeslicing @@ -64,8 +87,9 @@ scheduling algorithm. The length of time allocated to each task is known as the quantum or timeslice. The system's timeslice is defined as an integral number of ticks, and is -specified in the Configuration Table. The timeslice is defined for the entire -system of tasks, but timeslicing is enabled and disabled on a per task basis. +specified by the :ref:`CONFIGURE_TICKS_PER_TIMESLICE` application configuration +option. The timeslice is defined for the entire system of tasks, but +timeslicing is enabled and disabled on a per task basis. The clock tick directives implement timeslicing by decrementing the running task's time-remaining counter when both timeslicing and preemption are @@ -79,10 +103,10 @@ Delays A sleep timer allows a task to delay for a given interval or up until a given time, and then wake and continue execution. This type of timer is created -automatically by the ``rtems_task_wake_after`` and ``rtems_task_wake_when`` -directives and, as a result, does not have an RTEMS ID. Once activated, a -sleep timer cannot be explicitly deleted. Each task may activate one and only -one sleep timer at a time. +automatically by the :ref:`InterfaceRtemsTaskWakeAfter` and +:ref:`InterfaceRtemsTaskWakeWhen` directives and, as a result, does not have an +object identifier. Once activated, a sleep timer cannot be explicitly deleted. +Each task may activate one and only one sleep timer at a time. .. index:: timeouts @@ -90,7 +114,8 @@ Timeouts -------- Timeouts are a special type of timer automatically created when the timeout -option is used on the ``rtems_message_queue_receive``, ``rtems_event_receive``, -``rtems_semaphore_obtain`` and ``rtems_region_get_segment`` directives. Each -task may have one and only one timeout active at a time. When a timeout -expires, it unblocks the task with a timeout status code. +option is used on the :ref:`InterfaceRtemsBarrierWait`, +:ref:`InterfaceRtemsEventReceive`, :ref:`InterfaceRtemsMessageQueueReceive`, +:ref:`InterfaceRtemsRegionGetSegment`, and :ref:`InterfaceRtemsSemaphoreObtain` +directives. Each task may have one and only one timeout active at a time. +When a timeout expires, it unblocks the task with a timeout status code. diff --git a/c-user/clock/directives.rst b/c-user/clock/directives.rst index 1a65abf..a6e00ca 100644 --- a/c-user/clock/directives.rst +++ b/c-user/clock/directives.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. 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 @@ -137,7 +137,7 @@ Gets the time of day associated with the current :term:`CLOCK_REALTIME`. .. rubric:: PARAMETERS: ``time_of_day`` - This parameter is the pointer to an :c:type:`rtems_time_of_day` object. + 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. @@ -220,6 +220,845 @@ The following constraints apply to this directive: * 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 ); + +.. 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 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:`InterfaceRtemsClockGetRealtimeCoarseTimeval` directive may be used to get +the time in a lower resolution and with less runtime overhead. + +See :ref:`InterfaceRtemsClockGetRealtime` and +:ref:`InterfaceRtemsClockGetRealtimeBintime` 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-coarse + +.. raw:: latex + + \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. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_realtime_coarse( 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 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. + +.. 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:`InterfaceRtemsClockGetRealtime` directive may be used to get the time in +a higher resolution and with a higher runtime overhead. + +See :ref:`InterfaceRtemsClockGetRealtimeCoarseBintime` and +:ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` 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-coarse-bintime + +.. raw:: latex + + \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. + +.. 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:`InterfaceRtemsClockGetRealtimeBintime` directive may be used to get the +time in a higher resolution and with a higher runtime overhead. + +See :ref:`InterfaceRtemsClockGetRealtimeCoarse` and +:ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` 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-coarse-timeval + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_realtime_coarse_timeval() + +.. _InterfaceRtemsClockGetRealtimeCoarseTimeval: + +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. + +.. 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:`InterfaceRtemsClockGetRealtimeTimeval` directive may be used to get the +time in a higher resolution and with a higher runtime overhead. + +See :ref:`InterfaceRtemsClockGetRealtimeCoarse` and +:ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` 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 + +.. raw:: latex + + \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. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_monotonic( 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 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. + +.. 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:`InterfaceRtemsClockGetMonotonicCoarse` directive may be used to get the +time with in a lower resolution and with less runtime overhead. + +See :ref:`InterfaceRtemsClockGetMonotonicBintime`, +:ref:`InterfaceRtemsClockGetMonotonicSbintime`, 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-bintime + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_monotonic_bintime() + +.. _InterfaceRtemsClockGetMonotonicBintime: + +rtems_clock_get_monotonic_bintime() +----------------------------------- + +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in binary time format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_monotonic_bintime( struct bintime *time_snapshot ); + +.. rubric:: PARAMETERS: + +``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. + +.. 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:`InterfaceRtemsClockGetMonotonicCoarseBintime` directive may be used to +get the time in a lower resolution and with less runtime overhead. + +See :ref:`InterfaceRtemsClockGetMonotonic`, +:ref:`InterfaceRtemsClockGetMonotonicSbintime`, 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-sbintime + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_monotonic_sbintime() + +.. _InterfaceRtemsClockGetMonotonicSbintime: + +rtems_clock_get_monotonic_sbintime() +------------------------------------ + +Gets the time elapsed since some fixed time point in the past measured using +the :term:`CLOCK_MONOTONIC` in signed binary time format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + int64_t rtems_clock_get_monotonic_sbintime( void ); + +.. rubric:: RETURN VALUES: + +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. + +.. 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 + +.. 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 ); + +.. 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 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. + +.. 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:`InterfaceRtemsClockGetMonotonicCoarseTimeval` directive may be used to +get the time in a lower resolution and with less runtime overhead. + +See :ref:`InterfaceRtemsClockGetMonotonic`, +:ref:`InterfaceRtemsClockGetMonotonicBintime`, and +:ref:`InterfaceRtemsClockGetMonotonicSbintime` 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 + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_monotonic_coarse() + +.. _InterfaceRtemsClockGetMonotonicCoarse: + +rtems_clock_get_monotonic_coarse() +---------------------------------- + +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. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_monotonic_coarse( 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 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. + +.. 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 + +.. index:: rtems_clock_get_monotonic_coarse_bintime() + +.. _InterfaceRtemsClockGetMonotonicCoarseBintime: + +rtems_clock_get_monotonic_coarse_bintime() +------------------------------------------ + +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 + + void rtems_clock_get_monotonic_coarse_bintime( struct bintime *time_snapshot ); + +.. rubric:: PARAMETERS: + +``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. + +.. 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 + +.. 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: + +.. code-block:: c + + void rtems_clock_get_monotonic_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 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. + +.. 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:`InterfaceRtemsClockGetMonotonicTimeval` directive may be used to get the +time in a higher resolution and with a higher runtime overhead. + +See :ref:`InterfaceRtemsClockGetMonotonicCoarse` and +:ref:`InterfaceRtemsClockGetMonotonicCoarseBintime` 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-boot-time + +.. raw:: latex + + \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. + +.. rubric:: NOTES: + +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. + +.. 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-bintime + +.. raw:: latex + + \clearpage + +.. index:: rtems_clock_get_boot_time_bintime() + +.. _InterfaceRtemsClockGetBootTimeBintime: + +rtems_clock_get_boot_time_bintime() +----------------------------------- + +Gets the time elapsed since the :term:`Unix epoch` at some time point during +system initialization in binary time format. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + void rtems_clock_get_boot_time_bintime( struct bintime *boot_time ); + +.. rubric:: PARAMETERS: + +``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 + +.. index:: rtems_clock_get_boot_time_timeval() + +.. _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 @@ -247,8 +1086,8 @@ Gets the seconds elapsed since the :term:`RTEMS epoch` and the current .. rubric:: PARAMETERS: ``seconds_since_rtems_epoch`` - This parameter is the pointer to an :c:type:`rtems_interval` object. When - the directive call is successful, the seconds elapsed since the + 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. @@ -383,12 +1222,11 @@ system initialization using :term:`CLOCK_MONOTONIC`. .. rubric:: PARAMETERS: ``uptime`` - 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 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. + 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: diff --git a/c-user/clock/index.rst b/c-user/clock/index.rst index d84a37a..cf41998 100644 --- a/c-user/clock/index.rst +++ b/c-user/clock/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. index:: clock diff --git a/c-user/clock/introduction.rst b/c-user/clock/introduction.rst index ad4b14c..6ba814b 100644 --- a/c-user/clock/introduction.rst +++ b/c-user/clock/introduction.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2014, 2021 embedded brains GmbH (http://www.embedded-brains.de) +.. 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 @@ -29,6 +29,22 @@ Introduction .. spec:/rtems/clock/if/set .. spec:/rtems/clock/if/get-tod .. spec:/rtems/clock/if/get-tod-timeval +.. spec:/rtems/clock/if/get-realtime +.. spec:/rtems/clock/if/get-realtime-bintime +.. spec:/rtems/clock/if/get-realtime-timeval +.. spec:/rtems/clock/if/get-realtime-coarse +.. spec:/rtems/clock/if/get-realtime-coarse-bintime +.. spec:/rtems/clock/if/get-realtime-coarse-timeval +.. spec:/rtems/clock/if/get-monotonic +.. spec:/rtems/clock/if/get-monotonic-bintime +.. spec:/rtems/clock/if/get-monotonic-sbintime +.. spec:/rtems/clock/if/get-monotonic-timeval +.. spec:/rtems/clock/if/get-monotonic-coarse +.. spec:/rtems/clock/if/get-monotonic-coarse-bintime +.. spec:/rtems/clock/if/get-monotonic-coarse-timeval +.. spec:/rtems/clock/if/get-boot-time +.. spec:/rtems/clock/if/get-boot-time-bintime +.. spec:/rtems/clock/if/get-boot-time-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 @@ -52,6 +68,71 @@ capabilities. The directives provided by the Clock Manager are: * :ref:`InterfaceRtemsClockGetTodTimeval` - Gets the seconds and microseconds elapsed since the :term:`Unix epoch` and the current :term:`CLOCK_REALTIME`. +* :ref:`InterfaceRtemsClockGetRealtime` - Gets the time elapsed since the + :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in seconds and + nanoseconds format. + +* :ref:`InterfaceRtemsClockGetRealtimeBintime` - Gets the time elapsed since + the :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in binary time + format. + +* :ref:`InterfaceRtemsClockGetRealtimeTimeval` - Gets the time elapsed since + the :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in seconds and + microseconds format. + +* :ref:`InterfaceRtemsClockGetRealtimeCoarse` - Gets the time elapsed since the + :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in coarse resolution + in seconds and nanoseconds format. + +* :ref:`InterfaceRtemsClockGetRealtimeCoarseBintime` - Gets the time elapsed + since the :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in coarse + resolution in binary time format. + +* :ref:`InterfaceRtemsClockGetRealtimeCoarseTimeval` - Gets the time elapsed + since the :term:`Unix epoch` measured using :term:`CLOCK_REALTIME` in coarse + resolution in seconds and microseconds format. + +* :ref:`InterfaceRtemsClockGetMonotonic` - Gets the time elapsed since some + fixed time point in the past measured using the :term:`CLOCK_MONOTONIC` in + seconds and nanoseconds format. + +* :ref:`InterfaceRtemsClockGetMonotonicBintime` - Gets the time elapsed since + some fixed time point in the past measured using the :term:`CLOCK_MONOTONIC` + in binary time format. + +* :ref:`InterfaceRtemsClockGetMonotonicSbintime` - Gets the time elapsed since + some fixed time point in the past measured using the :term:`CLOCK_MONOTONIC` + in signed binary time format. + +* :ref:`InterfaceRtemsClockGetMonotonicTimeval` - Gets the time elapsed since + some fixed time point in the past measured using the :term:`CLOCK_MONOTONIC` + in seconds and microseconds format. + +* :ref:`InterfaceRtemsClockGetMonotonicCoarse` - 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. + +* :ref:`InterfaceRtemsClockGetMonotonicCoarseBintime` - 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. + +* :ref:`InterfaceRtemsClockGetMonotonicCoarseTimeval` - 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. + +* :ref:`InterfaceRtemsClockGetBootTime` - Gets the time elapsed since the + :term:`Unix epoch` at some time point during system initialization in seconds + and nanoseconds format. + +* :ref:`InterfaceRtemsClockGetBootTimeBintime` - Gets the time elapsed since + the :term:`Unix epoch` at some time point during system initialization in + binary time format. + +* :ref:`InterfaceRtemsClockGetBootTimeTimeval` - Gets the time elapsed since + the :term:`Unix epoch` at some time point during system initialization in + seconds and microseconds format. + * :ref:`InterfaceRtemsClockGetSecondsSinceEpoch` - Gets the seconds elapsed since the :term:`RTEMS epoch` and the current :term:`CLOCK_REALTIME`. diff --git a/c-user/clock/removed-directives.rst b/c-user/clock/removed-directives.rst index d7fd775..66be74e 100644 --- a/c-user/clock/removed-directives.rst +++ b/c-user/clock/removed-directives.rst @@ -14,7 +14,7 @@ Removed Directives CLOCK_GET - Get date and time information ----------------------------------------- .. index:: obtain the time of day -.. index:: rtems_clock_get +.. index:: rtems_clock_get() .. warning:: |