const ITimer.ANY |
 |
Const used to specify any timer
enum ITimer.PeriodType |
 |
Timer period units
enum PeriodType {
PeriodType_MICROSECS,
// period in microsecs
PeriodType_COUNTS
// period in counts
};
VALUES
PeriodType_MICROSECS
Period value is in microseconds.
PeriodType_COUNTS
Period value is in counts.
enum ITimer.RunMode |
 |
Timer Run Modes
enum RunMode {
RunMode_CONTINUOUS,
// periodic and continuous
RunMode_ONESHOT,
// one-shot
RunMode_DYNAMIC
// dynamically reprogrammed (available on subset of devices)
};
VALUES
RunMode_CONTINUOUS
Timer is periodic and runs continuously.
RunMode_ONESHOT
Timer runs for a single period value and stops.
RunMode_DYNAMIC
Timer is dynamically reprogrammed for the next required tick. This mode
is intended only for use by the Clock module when it is operating in
TickMode_DYNAMIC; it is not applicable for user-created Timer instances.
The behavior is similar to RunMode_ONESHOT, but the timer will be reprogrammed
and restarted automatically by the Clock module upon each timer interrupt.
enum ITimer.StartMode |
 |
Timer Start Modes
enum StartMode {
StartMode_AUTO,
// timer starts automatically
StartMode_USER
// timer will be started by user
};
VALUES
StartMode_AUTO
Statically created/constructed Timers will be started in BIOS_start().
Dynamically created Timers will start at create() time. This includes
timers created before BIOS_start().
StartMode_USER
Timer will be started by the user using start().
enum ITimer.Status |
 |
Timer Status
enum Status {
Status_INUSE,
// timer in use
Status_FREE
// timer is free
};
VALUES
Status_INUSE
Timer is in use. A timer is marked in use from the time it gets
created to the time it gets deleted.
Status_FREE
Timer is free and can be acquired using create.
typedef ITimer.FuncPtr |
 |
Timer tick function prototype
typedef Void (*FuncPtr)(UArg);
metaonly config ITimer.common$ // module-wide |
 |
Common module configuration parameters
DETAILS
All modules have this configuration parameter. Its name contains the '$'
character to ensure it does not conflict with configuration parameters
declared by the module. This allows new configuration parameters to be
added in the future without any chance of breaking existing modules.
ITimer.getNumTimers() // module-wide |
 |
Returns number of timer peripherals on the platform
RETURNS
Number of timer peripherals.
ITimer.getStatus() // module-wide |
 |
Returns timer status (free or in use)
RETURNS
timer status
DETAILS
Thread safety should be observed when using
getStatus.
For example, to protect against preemption surround the query of
timer status with
Hwi_disable() and
Hwi_restore() calls:
// disable interrupts to avoid another thread claiming this timer
key = Hwi_disable();
status = Timer_getStatus(timerId);
...
Hwi_restore(key);
config ITimer.Params.arg // instance |
 |
Argument for tick function
DETAILS
Default is null.
config ITimer.Params.extFreq // instance |
 |
Timer frequency
DETAILS
This parameter is meaningfull only on platforms where the timer's
input clock can be changed. If value is left at zero, then input clock
to the timer clock is assumed.
This value is used to convert timer ticks to real time units; seconds,
milliseconds, etc.
config ITimer.Params.period // instance |
 |
Period of a tick
config UInt32 period = 0;
DETAILS
The period can be specified in timer counts or microseconds
and its default value is 0.
The implementation of ITimer will support a period of UInt32
timer counts and use pre-scalars if necessary.
config ITimer.Params.periodType // instance |
 |
Period type
DETAILS
Default is PeriodType_MICROSECS
config ITimer.Params.runMode // instance |
 |
Timer run mode
DETAILS
config ITimer.Params.startMode // instance |
 |
Timer start mode
DETAILS
Static Instance Creation |
 |
// Create an instance-object
ARGUMENTS
id
Timer id ranging from 0 to a platform specific value,
or ANY
tickFxn
function that runs upon timer expiry.
DETAILS
Create could fail if timer peripheral is unavailable. To
request any available timer use
ANY as the id.
TimerId's are logical ids. The family-specific implementations
map the ids to physical peripherals.
ITimer.getCount() // instance |
 |
Read timer counter register
RETURNS
timer counter value
DETAILS
Thread safety may be a concern when using
getCount, to avoid
using a stale count value. For example, to protect against preemption
surround the query of timer count with
Hwi_disable() and
Hwi_restore() calls:
// disable interrupts to read current timer count
key = Hwi_disable();
currentCount = Timer_getCount();
...
Hwi_restore(key);
ITimer.getFreq() // instance |
 |
Return timer frequency in Hz
ARGUMENTS
freq
frequency in Hz
DETAILS
This is the effective frequency of the clock incrementing the timer
counter register after all scaling factors are taken into account.
(including pre-scalars).
ITimer.getFunc() // instance |
 |
Get Timer function and arg
ARGUMENTS
arg
pointer for returning Timer's function argument
RETURNS
Timer's function
ITimer.getPeriod() // instance |
 |
Get timer period in timer counts
RETURNS
period in timer counts
ITimer.setFunc() // instance |
 |
Overwrite Timer function and arg
ARGUMENTS
fxn
pointer to function
arg
argument to function
DETAILS
Replaces a Timer object's tickFxn function originally
provided in
create.
ITimer.setPeriod() // instance |
 |
Set timer period specified in timer counts
Void setPeriod(UInt32 period);
ARGUMENTS
period
period in timer counts
DETAILS
Timer_setPeriod() invokes Timer_stop() prior to setting the period
and leaves the timer in the stopped state.
To dynamically change the period of a timer you must
protect against re-entrancy by disabling interrupts.
Use the following call sequence to guarantee proper results:
// disable interrupts if an interrupt could lead to
// another call to Timer_start().
key = Hwi_disable();
Timer_setPeriod(period);
Timer_start();
Hwi_restore(key);
ITimer implementation must support UInt32 and use pre-scalars whenever
necessary
SIDE EFFECTS
Calls Timer_stop(), and disables the timer's interrupt.
ITimer.setPeriodMicroSecs() // instance |
 |
Set timer period specified in microseconds
Bool setPeriodMicroSecs(UInt32 microsecs);
ARGUMENTS
period
period in microseconds
DETAILS
A best-effort method will be used to set the period register.
There might be a slight rounding error based on resolution of timer
period register. If the timer frequency cannot support the requested
period, i.e. the timer period register cannot support the requested
period, then this function returns false.
Timer_setPeriodMicroSecs() invokes Timer_stop() prior to setting
the period and leaves the timer in the stopped state.
To dynamically change the period of a timer you must
protect against re-entrancy by disabling interrupts.
Use the following call sequence to guarantee proper results:
// disable interrupts if an interrupt could lead to
// another call to Timer_start().
key = Hwi_disable();
Timer_setPeriodMicroSecs(period);
Timer_start();
Hwi_restore(key);
ITimer.start() // instance |
 |
Reload and start the timer
DETAILS
Thread safety must be observed when using the
start
and
stop APIs to avoid possible miss-
configuration of the timers and unintended behaviors.
To protect against re-entrancy, surround the start/stop invocations
with
Hwi_disable() and
Hwi_restore() calls:
// disable interrupts if an interrupt could lead to
// another call to Timer_start().
key = Hwi_disable();
Timer_stop();
...
Timer_start();
Hwi_restore(key);
CONSTRAINTS
Timer_start() should not be called if the timer has already been
started.
SIDE EFFECTS
Enables the timer's interrupt.
ITimer.stop() // instance |
 |
Stop the timer
DETAILS
Thread safety must be observed when using the
start
and
stop APIs to avoid possible miss-
configuration of the timers and unintended behaviors.
To protect against re-entrancy, surround the start/stop invocations
with
Hwi_disable() and
Hwi_restore() calls:
// disable interrupts if an interrupt could lead to
// another call to Timer_start().
key = Hwi_disable();
Timer_stop();
...
Timer_start();
Hwi_restore(key);
SIDE EFFECTS
Disables the timer's interrupt.