diff options
Diffstat (limited to 'c-user/clock/background.rst')
| -rw-r--r-- | c-user/clock/background.rst | 85 |
1 files changed, 55 insertions, 30 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. |