9.2. Background

9.2.1. Required Support

For the features provided by the Clock Manager to be utilized, a Clock Driver is required. The Clock Driver usually provides a clock interrupt which is serviced on each configured processor at each clock tick. In addition, the Clock Driver provides three clock sources:

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.

9.2.2. 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:

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 rtems_clock_set() directive. Some applications expect to operate on a UNIX-style date and time data structure. For example, the rtems_clock_get_tod_timeval() returns the date and time in struct timeval format.

Some directives use data structures defined by 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 CLOCK_REALTIME time points, the tv_sec member in these data structures is the number of seconds since the Unix epoch but will never be prior to the RTEMS epoch.

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 \(1 / 2^{64}\) seconds, respectively. The sbintime_t type is a signed 64-bit integer type used to represent time in units of \(1 / 2^{32}\) seconds.

9.2.3. 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 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.

9.2.4. 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 object identifier. Once activated, a sleep timer cannot be explicitly deleted. Each task may activate one and only one sleep timer at a time.

9.2.5. Timeouts

Timeouts are a special type of timer automatically created when the timeout option is used on the rtems_barrier_wait(), rtems_event_receive(), rtems_message_queue_receive(), rtems_region_get_segment(), and rtems_semaphore_obtain() 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.