# Kernel Timer

## Overview

The RW Kernel provides:

- A time reference (absolute time counter)
- Timer services to start and stop the timer

Timers are implemented by means of a reserved queue of delayed messages. Timer messages do not have parameters.

IMPORTANT: Kernel timer functions (ke_timer_*) must not be used in an interrupt context. Do not call them within any interrupt service routines. The kernel timer is not interrupt-safe.

## Time Definition

Time is defined as duration; the minimum step is a multiple of 1 ms.

## Timer Object

The structure of the timer message contains:

- *next: Pointer on the next timer
- id: Message identifier
- task: Destination task identifier
- time: Duration

## Timer Setting

The "Timer Setting Flow" figure shows the flow for setting up timer messages.

Figure: Timer Setting Flow

## Time Primitives

### Timer Set

Set a timer.

#### Prototype:

void ke_timer_set(ke_msg_id_t const timer_id, ke_task_id_t const task, uint32_t const delay);

#### Parameters:

Table: Timer Set Parameters
Type | Parameters | Description
--- | --- | ---
ke_msg_id_t | timer_id | Timer identifier
ke_task_id_t | task_id | Task identifier
uint32_t | delay | Timer duration (multiple of 1ms; maximum is 41,943,039 ms)

#### Return:

None

#### Description:

The function first cancels the timer if it exists; then it creates a new one.

When the timer expires, a message is sent to the task provided as argument, with the timer id as message id.

### Timer Clear

Remove a registered timer.

#### Prototype:

void ke_timer_clear(ke_msg_id_t const timer_id, ke_task_id_t const task);

#### Parameters:

Table: Timer Clear Parameters
Type | Parameters | Description
--- | --- | ---
ke_msg_id_t | timer_id | Timer identifier
ke_task_id_t | task_id | Task identifier

#### Return:

None

#### Description:

This function searches for the timer element identified by its timer and task identifiers. If found, it is stopped and freed; otherwise an error message is returned.

### Timer Activity

Check if a requested timer is active.

#### Prototype:

bool ke_timer_active(ke_msg_id_t const timer_id, ke_task_id_t const task);

#### Parameters:

Table: Timer Activity Parameters
Type | Parameters | Description
--- | --- | ---
ke_msg_id_t | timer_id | Timer identifier
ke_task_id_t | task_id | Task identifier

#### Return:

TRUE if the timer identified by Timer ID is active for the Task ID; FALSE otherwise

#### Description:

This function pops the first timer from the timer queue and notifies the appropriate task by sending a kernel message. If the timer is periodic, it is set again; if it is one-shot, the timer is freed. The function also checks the next timers, and processes them if they have expired or are about to expire. The "Timer Expiry Flow" figure shows the process flow for handling expired timers.

### Timer Adjust

Adjust all kernel timers by specified adjustment delay.

#### Prototype:

void ke_timer_adjust_all(uint32_t delay);

#### Parameters:

Table: Timer Adjust Parameters
Type | Parameters | Description
--- | --- | ---
uint16_t | delay | Adjustment delay is a multiple of 1 ms

#### Return:

None

#### Description:

This function updates all timers to align to a new SYSCLK after a system clock adjustment.

### Timer Expiry

The "Timer Expiry Flow" figure shows the flow of timer messages when the timer expires.

Figure: Timer Expiry Flow