Pyromaniac

Pyromaniac PRM: Hardware timer device driver (TimerManager)

Pyromaniac PRM: Hardware timer device driver (TimerManager)

RISC OS PyromaniacHardware timer device driver (TimerManager)

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:

ValueMeaning
0Invalid
1Scaled by 1/1000000000
2Scaled by 1/1000000
3Scaled by 1/1000
4Scaled by 1
5Scaled by 1000
6Scaled by 1000000
7Scaled by 1000000000

3Reserved, must be zero
4-5

Measurement type:

ValueMeaning
0Native ticks
1Frequency (interrupts per second)
2Period (in seconds)
3Invalid

6-7Reserved, 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

TimerManager_ReturnNumberSWI &58B80
Return number of supported timers
R0=Flags (must be 0)
R0=Number of timers available
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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.

TimerManager_ClaimSWI &58B81
Claim a hardware timer
R0=

Flags:

Bit(s)Meaning
0-7Measurement format for the timer rate
8-15Measurement format for the returned timer rate
16-31Reserved, must be zero

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
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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.

TimerManager_ReleaseSWI &58B82
Release a hardware timer
R0=Flags (must be zero)
R1=Timer number
None
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

This SWI is used to release a previously claimed timer. The IRQ will no longer cause the specified routine to be called.

TimerManager_SetRateSWI &58B83
Change the rate used by a hardware timer
R0=

Flags:

Bit(s)Meaning
0-7Measurement format for the timer rate
8-15Measurement format for the returned timer rate
16-31Reserved, must be zero

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
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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.

TimerManager_ConvertSWI &58B84
Convert between rate formats used by a hardware timer
R0=

Flags:

Bit(s)Meaning
0-7Measurement format for the timer rate
8-15Measurement format for the returned timer rate
16-31Reserved, must be zero

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
Interrupts are undefined
Fast interrupts are enabled
Processor is in SVC mode
SWI is not re-entrant

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.