Timers

@@ -297,7 +298,6 @@ ul.auto-toc {

Cory Sharp, Martin Turon, David Gay

Note

This memo documents a part of TinyOS for the TinyOS Community, and @@ -305,15 +305,15 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1.

Abstract

This TEP proposes a Timer design that supports common timing requirements both in precision and width across common hardware configurations. This TEP focuses on aligning the Timer abstraction with the three-layer Hardware Abstraction Architecture (HAA).

1. Introduction

Most microcontrollers offer a rich timer system, with features like:

several counters, possibly of different widths, with multiple clocking options

2. Interfaces

guidelines on how each microcontroller's HAL SHOULD expose its timer hardware in terms of the above interfaces (3. HAL guidelines)
what components a microcontroller's timer HIL MUST implement +
what components a microcontroller's timer HIL MUST implement (4. HIL requirements)
a set of utility components whose use simplifies building the components specified by the HAL guidelines and HIL requirements (5. Utility components)

This TEP ends with appendices documenting, as an example, the mica2 timer subsystem implementation.

2. Interfaces

Before presenting the interfaces (2.2), we start with a general discussion of the issues of precision, width and accuracy in timer interfaces (2.1).

2.1 Precision, Width and Accuracy

Three fundamental properties of timers are precision, width and accuracy.

Examples of precision are millisecond, a cycle of a 32kHz clock, and @@ -359,7 +359,7 @@ units with respect to one second. That is, one second contains 1024 binary milliseconds, 32768 32kHz ticks, or 1048576 microseconds. This TEP emphasizes millisecond and 32kHz tick precisions while reasonably accommodating other precisions. The use of "binary" units -is motivated by the common availability of hardware clocks driven +is motivated by the common availability of hardware clocks driven by a 32768Hz crystal.

Examples of widths are 8-bit, 16-bit, 32-bit, and 64-bit. The width for timer interfaces and components SHOULD be 32-bits. This TEP @@ -392,8 +392,8 @@ typedef struct { int notUsed; } TMicro; // 1048576 ticks per second

Note that the precision names are expressed as either frequency or period, whichever is convenient.

2.2 Timer interfaces

This TEP proposes these timer interfaces:

 interface Counter< precision_tag, size_type >
@@ -407,8 +407,8 @@ applications and use a fixed width of 32-bits.  The Alarm, BusyWait,
 and Counter interfaces are used by the TinyOS timer system and
 advanced user components.

Counter

The Counter interface returns the current time and provides commands and an event for managing overflow conditions. These overflow commands and events are necessary for properly deriving larger width @@ -423,22 +423,22 @@ interface Counter<precision_tag,size_type> }

get()
get(): return the current time.
isOverflowPending()
isOverflowPending(): return TRUE if the overflow flag is set for this counter, i.e., if and only if an overflow event will occur after the outermost atomic block exits. Return FALSE otherwise. This command only returns the state of the overflow flag and causes no side effect.
clearOverflow()
clearOverflow(): cancel the pending overflow event clearing the overflow flag.
overflow()
overflow(): signals that an overflow in the current time. That is, the current time has wrapped around from its maximum value to zero.

Alarm

Alarm components are extensions of Counters that signal an event when their compare register detects the alarm time has been hit. All commands and events of the Alarm interface are asynchronous (or @@ -461,15 +461,15 @@ interface Alarm<precision_tag,size_type> }

start(dt)
start(dt): cancel any previously running alarm and set to fire in dt time units from the time of invocation. The alarm will only fire once then stop.
stop()
stop(): cancel any previously running alarm.
fired()
fired(): signals that the alarm has expired.
isRunning()
isRunning(): return TRUE if the alarm has been started and has not been cancelled or has not yet fired. FALSE is returned otherwise.

@@ -485,9 +485,9 @@ numerically greater than the current time (returned by -getNow() +getNow() return the current time in the precision and width of the alarm. -getAlarm() +getAlarm() return the time the currently running alarm will fire or the time that the previously running alarm was set to fire. getAlarm can be used with startAt to set an alarm from the previous alarm time, @@ -495,8 +495,8 @@ as in startAt(getAlarm(),dt). This pattern is used within the fired() event to construct periodic alarms.

- -BusyWait + +BusyWait The BusyWait interface allows for very short synchronous delays. BusyWait should be used sparingly and when an Alarm would not be reasonably efficient or accurate. The BusyWait interface replaces @@ -516,8 +516,8 @@ interface BusyWait<precision_tag,size_type> block until at least dt time units have elapsed - -LocalTime + +LocalTime The LocalTime interface exposes a 32-bit counter without overflow utilities. This is primarily for application code that does not care about overflow conditions. @@ -528,12 +528,12 @@ interface LocalTime<precision_tag> } -get() +get() return the current time. - -Timer + +Timer All commands and events of the Timer interface are synchronous (or in "task context"). The Timer interface provides a set of "basic" commands for common usage and provides a set of "extended" commands @@ -558,26 +558,26 @@ interface Timer<precision_tag> } -startPeriodic(dt) +startPeriodic(dt) cancel any previously running timer and set to fire in dt time units from the time of invocation. The timer will fire periodically every dt time units until stopped. -startOneShot(dt) +startOneShot(dt) cancel any previously running timer and set to fire in dt time units from the time of invocation. The timer will only fire once then stop. -stop() +stop() cancel any previously running timer. fired() signals that the timer has expired (one-shot) or repeated (periodic). -isRunning() +isRunning() return TRUE if the timer has been started and has not been cancelled and has not fired for the case of one-shot timers. Once a periodic timer is started, isRunning will return TRUE until it is cancelled. -isOneShot() +isOneShot() return TRUE if the timer is a one-shot timer. Return FALSE otherwise if the timer is a periodic timer. -startPeriodicAt(t0,dt) +startPeriodicAt(t0,dt) cancel any previously running timer and set to fire at time t1 = t0+dt. The timer will fire periodically every dt time units until stopped. @@ -585,23 +585,23 @@ stopped. value of t0 numerically greater than the current time (returned by getNow()) represents a time from before the last wraparound. -startOneShotAt(t0,dt) +startOneShotAt(t0,dt) cancel any previously running timer and set to fire at time t1 = t0+dt. The timer will fire once then stop. t0 is as in startPeriodicAt. -getNow() +getNow() return the current time in the precision and width of the timer. -gett0() +gett0() return the time anchor for the previously started timer or the time of the previous event for periodic timers. -getdt() +getdt() return the delay or period for the previously started timer. - -3. HAL guidelines + +3. HAL guidelines Platforms SHOULD expose their relevant timing capabilities using standard Alarm and Counter interfaces. The design pattern presented here defines a component naming convention to allow platform @@ -646,8 +646,8 @@ are mutually incompatible in a single application. Incompatible components SHOULD produce compile-time errors when compiled together. - -4. HIL requirements + +4. HIL requirements The following component MUST be provided on all platforms HilTimerMilliC @@ -657,8 +657,8 @@ BusyWaitMicroC HilTimerMilliC and 1/1048576s for BusyWaitMicroC. Components using other precisions (e.g., regular, non-binary milliseconds) MAY also be provided. - -HilTimerMilliC + +HilTimerMilliC configuration HilTimerMilliC { @@ -673,8 +673,8 @@ TimerMilli parameterised interface. UQ_TIMER_MILLI is defined in Timer.h. HilTimerMilliC is used by the LocalTimeMilliC component and the TimerMilliC generic component, both found in tos/system/ - -BusyWaitMicroC + +BusyWaitMicroC configuration BusyWaitMicroC { @@ -687,8 +687,8 @@ delay is small and setting a timer or alarm would be impractical, inefficient or insufficiently precise. - -5. Utility components + +5. Utility components A number of platform independent generic components are provided to help implementers and advanced users of the TinyOS timer system: @@ -701,8 +701,8 @@ help implementers and advanced users of the TinyOS timer system: Appendices B and C show how these can be used to help implement the timer HAL and HIL. - -AlarmToTimerC + +AlarmToTimerC AlarmToTimerC converts a 32-bit Alarm to a Timer. generic component AlarmToTimerC( typedef precision_tag ) @@ -712,8 +712,8 @@ generic component AlarmToTimerC( typedef precision_tag ) } - -BusyWaitCounterC + +BusyWaitCounterC BusyWaitCounterC uses a Counter to block until a specified amount of time elapses. @@ -725,8 +725,8 @@ generic component BusyWaitC( typedef precision_tag, } - -CounterToLocalTimeC + +CounterToLocalTimeC CounterToLocalTimeC converts from a 32-bit Counter to LocalTime. generic component CounterToLocalTimeC( precision_tag ) @@ -736,12 +736,12 @@ generic component CounterToLocalTimeC( precision_tag ) } - -TransformAlarmC + +TransformAlarmC TransformAlarmC decreases precision and/or widens an Alarm. An already widened Counter component is used to help. -generic component TransformAlarmC( +generic component TransformAlarmC( typedef to_precision_tag, typedef to_size_type @integer(), typedef from_precision_tag, @@ -769,8 +769,8 @@ TransformAlarmC to ensure that all five of its arguments are self consistent. No compile errors are generated if the parameters passed to TransformAlarmC are inconsistent. - -TransformCounterC + +TransformCounterC TransformCounterC decreases precision and/or widens a Counter. generic component TransformCounterC( @@ -801,8 +801,8 @@ created: new TransformCounterC( TMilli, uint32_t, T32khz, uint16_t, 5, uint32_t ) - -VirtualizeTimerC + +VirtualizeTimerC VirtualizeTimerC uses a single Timer to create up to 255 virtual timers. @@ -815,8 +815,8 @@ generic component VirtualizeTimerC( typedef precision_tag, int max_timers ) - -6. Implementation + +6. Implementation The definition of the HIL interfaces are found in tinyos-2.x/tos/lib/timer: @@ -856,7 +856,7 @@ generic component VirtualizeTimerC( typedef precision_tag, int max_timers ) CounterMilli16C.nc provides Counter<TMilli,uint16_t> CounterMilli32C.nc provides Counter<TMilli,uint32_t> GpioCaptureC.nc -HilTimerMilliC.nc provides LocalTime<TMilli> and + HilTimerMilliC.nc provides LocalTime<TMilli> and Timer<TMilli> as TimerMilli[uint8_t num] Msp430AlarmC.nc is generic and converts an MSP430 timer to a 16-bit Alarm Msp430Capture.nc HPL interface definition for MSP430 timer captures @@ -889,8 +889,8 @@ special function registers tinyos-2.x/tos/chips/atm128/timer and tinyos-2.x/tos/chips/pxa27x/timer respectively. - -7. Author's Address + +7. Author's Address Cory Sharp Moteiv Corporation @@ -918,8 +918,8 @@ special function registers email - david.e.gay@intel.com - -Appendix A: Timer hardware on various microcontrollers + +Appendix A: Timer hardware on various microcontrollers Atmega128 @@ -995,8 +995,8 @@ output pin, clear counter, generate interrupt, etc) - -Appendix B: a microcontroller: Atmega 128 timer subsystem + +Appendix B: a microcontroller: Atmega 128 timer subsystem The Atmega128 exposes its four timers through a common set of interfaces: @@ -1026,7 +1026,7 @@ interface HplAtm128Timer<timer_size> async command bool isOn(); //<! Is overflow interrupt on? /// Clock initialization interface - async command void off(); //<! Turn off the clock + async command void off(); //<! Turn off the clock async command void setScale( uint8_t scale); //<! Turn on the clock async command uint8_t getScale(); //<! Get prescaler setting } @@ -1057,7 +1057,7 @@ interface HplAtm128Capture<size_type> /// Interrupt signals async event void captured(size_type t); //<! Signalled on capture int - /// Interrupt flag utilites: Bit level set/clr + /// Interrupt flag utilites: Bit level set/clr async command void reset(); //<! Clear the capture interrupt flag async command void start(); //<! Enable the capture interrupt async command void stop(); //<! Turn off capture interrupts @@ -1089,7 +1089,7 @@ interface is only connected for i another value cause a compile-time error. This is achieved as follows (code from the implementation of HplAtm128Timer1C) -Compare[0] = HplAtm128Timer1P.CompareA; +Compare[0] = HplAtm128Timer1P.CompareA; Compare[1] = HplAtm128Timer1P.CompareB; Compare[2] = HplAtm128Timer1P.CompareC; @@ -1133,8 +1133,8 @@ generic configuration Atm128AlarmAsyncC(typedef precision, int divider) { which builds a 32-bit alarm and timer over timer 0. divider is used to initialise the timer0 scaling factor. - -Appendix C: a mote: Mica family timer subsystem + +Appendix C: a mote: Mica family timer subsystem Members of the mica family (mica2, mica2dot, micaz) use the Atmega128 microprocessor and have external crystals at 4 or 7.37MHz. Additionally, they can be run from an internal oscillator at 1, 2, 4, or 8 MHz. The @@ -1157,13 +1157,13 @@ VirtualizeTimerC and CounterToLocalTimeC utility components. Timer 1: the 16-bit hardware timer 1 is set to run at 1MHz if possible. However, the set of dividers for timer 1 is limited to 1, 8, 64, 256 and 1024. So, when clocked at 2 or 4MHz, a divider of 1 is -selected and timer 1 runs at 2 or 4MHz. To reflect this fact, the +selected and timer 1 runs at 2 or 4MHz. To reflect this fact, the HAL components exposing timer 1 are named CounterOne16C and AlarmOne16C (rather than the CounterMicro16C AlarmMicro16C as suggested in Section 3). 32-bit microsecond Counters and Alarms, named CounterMicro32C and AlarmMicro32C, are created from CounterOne16C and -AlarmOne16C using the TransformAlarmC and TransformCounterC +AlarmOne16C using the TransformAlarmC and TransformCounterC utility components. Three compare registers are available on timer1, so up to three instances of AlarmOne16C and/or AlarmMicro32C can be created. The timing @@ -1179,7 +1179,7 @@ accuracy depends on how the mote is clocked: Timer 3: the 16-bit hardware timer 3 is set to run at a rate close to 32768Hz, if possible. As with timer 1, the limited set of dividers makes this impossible at some clock frequencies, so the 16-bit timer 3 HAL -components are named CounterThree16C and AlarmThree16C. As +components are named CounterThree16C and AlarmThree16C. As with timer 1, the rate of timer 3 is adjusted in software to build 32-bit counter and 32-bit alarms, giving components Counter32khz32C and Alarm32khz32C. As with timer 1, three compare diff --git a/doc/html/tep115.html b/doc/html/tep115.html index d425c9ed..de3c6547 100644 --- a/doc/html/tep115.html +++ b/doc/html/tep115.html @@ -3,7 +3,7 @@ - + Power Management of Non-Virtualised Devices