1============================
2The Timer driver (bare-bone)
3============================
4
5The Timer driver provides means for delayed and periodical function invocation.
6
7A timer task is a piece of code (function) executed at a specific time or periodically by the timer after the task has
8been added to the timers task queue. The execution delay or period is set in ticks, where one tick is defined as a
9configurable number of clock cycles in the hardware timer. Changing the number of clock cycles in a tick automatically
10changes execution delays and periods for all tasks in the timers task queue.
11
12A task has two operation modes, single-shot or repeating mode. In single-shot mode the task is removed from the task queue
13and then is executed once, in repeating mode the task reschedules itself automatically after it has executed based on
14the period set in the task configuration.
15In single-shot mode a task is removed from the task queue before its callback is invoked. It allows an application to
16reuse the memory of expired task in the callback.
17
18Each instance of the Timer driver supports infinite amount of timer tasks, only limited by the amount of RAM available.
19
20Features
21--------
22* Initialization and de-initialization
23* Starting and stopping
24* Timer tasks - periodical invocation of functions
25* Changing and obtaining of the period of a timer
26
27Applications
28------------
29* Delayed and periodical function execution for middle-ware stacks and applications.
30
31Dependencies
32------------
33* Each instance of the driver requires separate hardware timer capable of generating periodic interrupt.
34
35Concurrency
36-----------
37The Timer driver is an interrupt driven driver.This means that the interrupt that triggers a task may occur during
38the process of adding or removing a task via the driver's API. In such case the interrupt processing is postponed
39until the task adding or removing is complete.
40
41The task queue is not protected from the access by interrupts not used by the driver. Due to this
42it is not recommended to add or remove a task from such interrupts: in case if a higher priority interrupt supersedes
43the driver's interrupt, adding or removing a task may cause unpredictable behavior of the driver.
44
45Limitations
46-----------
47* The driver is designed to work outside of an operating system environment, the task queue is therefore processed in interrupt context which may delay execution of other interrupts.
48* If there are a lot of frequently called interrupts with the priority higher than the driver's one, it may cause delay for triggering of a task.
49
50Knows issues and workarounds
51----------------------------
52Not applicable
53