![[Burning Cog]](../../../icons/pyromaniac.png){kind=icon}
Introduction
The TimerManager module provides an abstraction of the hardware timers. It is used by the Kernel in order to provide the monotonic timer used for the system clock, interval timer, monotonic timer, and system timed events. The module also provides an interface to allow other hardware timers to be controlled by other components. Timers may run off independant clock sources and so may have different granularity and ranges of rates at which they may generate interrupts.
Each hardware implementation has an independant TimerManager module implementation specific to the timers which are available to the operating system.
Overview
The number of timers provided by the hardware can be read using SWI TimerManager_ReturnNumber. Timers may be claimed and released by components using SWI TimerManager_Claim and SWI TimerManager_Release. The rate at which a timer is running can be modified after it has been claimed by using SWI TimerManager_SetRate. The relationship between timer rates and external measurements can be obtained by using SWI TimerManager_Convert.
Technical details
A number of timers may be provided by a TimerManager hardware device driver. These timers can be claimed by a single client at any time. The timer's rate may be defined in a number of different forms, to allow clients to specify the rate in the most natural manner. Not all timers may support the exact rate requested, so clients should expect to handle different forms of timers.
Timers are numbered from 0, and timer 0 is reserved for use by the Kernel as the monotonic timer.
Measurement format
Many of the SWIs take a number of flags to indicate the measurement format of the timer. The measurement format flags take the form of 8 bits:
| Bit(s) | Meaning | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0-2 |
Unit scaler:
| |||||||||||||||||||
| 3 | Reserved, must be zero | |||||||||||||||||||
| 4-5 |
Measurement type:
| |||||||||||||||||||
| 6-7 | Reserved, must be zero | |||||||||||||||||||
For example, to request a frequency of 100 Hz one could use a measurement type of 1, a scaler of 4 (scale by 1) and a value of 100. Alternatively, this could be represented as a period of 1/100th second by using a measurement type of 2, a scaler of 3 (scale by 1/1000) and a value of 10.
For SWIs which take an input rate the measurement format flags are held in the bits 0-7 of the SWI flags.
For SWIs which return a rate the measurement format flags are held in bits 8-15 of the SWI flags.
SWI calls
| R0 | = | Flags (must be 0) |
| R0 | = | Number of timers available |
This SWI is used to find the number of timers available to the operating system. Timers are numbered from 0, so the maximum timer number that may be used is the value returned - 1.
| R0 | = | Flags:
| ||||||||||||
| R1 | = | Timer number | ||||||||||||
| R2 | = | Timer rate, using the measurement format from bits 0-7 | ||||||||||||
| R3 | = | Pointer to function to call on interrupt | ||||||||||||
| R4 | = | Value to pass in R12 to interrupt function | ||||||||||||
| R2 | = | Actual timer rate, using the measurement format from bits 8-15, or 0 if the rate cannot be represented |
This SWI is used to claim a timer for dedicated use by a client. Only a single client may claim a timer; subsequent claims will return an error. The timer specified will be set to the rate given and interrupts will call the routine specified. The interrupt routine may corrupt R0-R3 but should preserve all other registers.
An error will be returned if the input measurement format in R0 bits 0-7 is not valid or cannot be provided by the timer.
If the meaurement format used for return in R0 bits 8-15 is invalid the value returned in R2 will be 0, but no error will be raised. The return value is provided as a convenience.
| R0 | = | Flags (must be zero) |
| R1 | = | Timer number |
This SWI is used to release a previously claimed timer. The IRQ will no longer cause the specified routine to be called.
| R0 | = | Flags:
| ||||||||||||
| R1 | = | Timer number | ||||||||||||
| R2 | = | Timer rate, using the measurement format from bits 0-7 | ||||||||||||
| R2 | = | Actual timer rate, using the measurement format from bits 8-15, or 0 if the rate cannot be represented |
This SWI is used to change the rate used by a timer. Only timers which have been claimed can have their rate changed; unclaimed timers will return an error. The timer specified will be set to the rate given.
An error will be returned if the input measurement format in R0 bits 0-7 is not valid or cannot be provided by the timer.
If the meaurement format used for return in R0 bits 8-15 is invalid the value returned in R2 will be 0, but no error will be raised. The return value is provided as a convenience.
| R0 | = | Flags:
| ||||||||||||
| R1 | = | Timer number | ||||||||||||
| R2 | = | Timer rate, using the measurement format from bits 0-7 | ||||||||||||
| R2 | = | Timer rate in form specified by R0 bits 8-15 |
This SWI is used to convert between timer rate formats. The values converted will be checked to ensure that the timer is capable of those rates.
An error will be returned if the input measurement format in R0 bits 0-7 is not valid or cannot be provided by the timer.
An error will be returned if the meaurement format used for return in R0 bits 8-15 is invalid.