diff options
Diffstat (limited to 'c-user/clock/background.rst')
-rw-r--r-- | c-user/clock/background.rst | 121 |
1 files changed, 121 insertions, 0 deletions
diff --git a/c-user/clock/background.rst b/c-user/clock/background.rst new file mode 100644 index 0000000..11a3cb5 --- /dev/null +++ b/c-user/clock/background.rst @@ -0,0 +1,121 @@ +.. 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 +========== + +Required Support +---------------- + +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 +directives utilize the following date and time structure for the native time +and date format: + +.. index:: rtems_time_of_day + +.. code-block:: c + + typedef struct { + uint32_t year; /* greater than 1987 */ + uint32_t month; /* 1 - 12 */ + uint32_t day; /* 1 - 31 */ + uint32_t hour; /* 0 - 23 */ + uint32_t minute; /* 0 - 59 */ + uint32_t second; /* 0 - 59 */ + uint32_t ticks; /* elapsed between seconds */ + } rtems_time_of_day; + +The native date and time format is the only format supported when setting the +system date and time using the :ref:`InterfaceRtemsClockSet` directive. Some +applications expect to operate on a *UNIX-style* date and time data structure. +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 + +Clock Tick and Timeslicing +-------------------------- + +Timeslicing is a task scheduling discipline in which tasks of equal priority +are executed for a specific period of time before control of the CPU is passed +to another task. It is also sometimes referred to as the automatic round-robin +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 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 +enabled. If the task's timeslice has expired, then that task will be preempted +if there exists a ready task of equal priority. + +.. index:: delays + +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 :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 + +Timeouts +-------- + +Timeouts are a special type of timer automatically created when the timeout +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. |