1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
|
.. SPDX-License-Identifier: CC-BY-SA-4.0
.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de)
.. 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.
|
