1. June 2008 WEI Short Course TinyOS Timers 1 Wireless Embedded Intrer-Networking Foundations of Ubiquitous Sensor Networks Timers and System Resources David E. Culler University of California, Berkeley

2. June 2008WEI Short Course TinyOS Timers2 Timers See TEP102 for complete details

3. June 2008WEI Short Course TinyOS Timers3 Timer Interface (Hardware Independent) Precision: typedef struct { } TMilli; // 1024 ticks per second typedef struct { } T32khz; // 32768 ticks per second typedef struct { } TMicro; // 1048576 ticks per second interface Timer { command void startPeriodic(uint32_t dt); event void fired(); command void startOneShot(uint32_t dt); command void stop(); command bool isRunning(); command bool isOneShot(); command void startPeriodicAt(uint32_t t0, uint32_t dt); command void startOneShotAt(uint32_t t0, uint32_t dt); command uint32_t getNow(); command uint32_t gett0(); command uint32_t getdt(); }

4. June 2008WEI Short Course TinyOS Timers4 Microcontroller Timer Capabilities Most microcontrollers offer a rich timer system, with features like: –several counters, possibly of different widths, with multiple clocking options –one or more compare registers for each counter, which can trigger interrupts, changes to output pins and changes to the counter value –capture of the time of input pin changes

5. June 2008WEI Short Course TinyOS Timers5 Hardware Timer Support Atmega128 –Two 8-bit timers, each allowing »7 prescaler values (division by different powers of 2) »Timer 0 can use an external 32768Hz crystal »One compare register, with many compare actions (change output pin, clear counter, generate interrupt, etc) –Two 16-bit timers, each with »5 prescaler values »External and software clocking options »Three compare registers (again with many actions) »Input capture MSP430 –Two 16-bit timers with »One with three compare registers »One with eight compare registers »Each from distinct clock source »Each with limited prescalers

6. June 2008WEI Short Course TinyOS Timers6 Hardware Timer Support (cont) Intel PXA27x –One fixed rate (3.25MHz) 32-bit timer with »4 compare registers »Watchdog functionality –8 variable rate 32-bit timers with »1 associated compare register each »Individually selectable rates: 1/32768s, 1ms, 1s, 1us »Individually selectable sources: (32.768 external osc, 13 Mhz internal clock) –Periodic & one-shot capability –Two external sync events

7. June 2008WEI Short Course TinyOS Timers7 TinyOS Timer Subsystem Architecture Hardware Timer Support Counters Alarms Timers HPL Counters of system defined width and precision, handle overflows signal an event when specified time occurs Physical registers, Ops, comparators 32-bit counter without overflow Local Time HAL HIL Virtual timers Periodic, one-shot, phase Synchronous Asynchronous

8. June 2008WEI Short Course TinyOS Timers8 Local Time get() –return the current time in specified precision. –32-bit result, no overflows interface LocalTime { async command uint32_t get(); }

9. June 2008WEI Short Course TinyOS Timers9 Basic Timers command void startPeriodic(uint32_t dt); –Set a periodic timer to repeat every dt time units, starting from now –Fired event will be signaled every dt units (first event in dt units) command void startOneShot(uint32_t dt); –Set a single-short timer to some time units in the future from now. event void fired(); –Signal occurance of a running timer Each Timer is a distinct virtual resource (generic). Starting a timer replaces previous pending setting. Collectively they are implemented by a set of parameterized components.

10. June 2008WEI Short Course TinyOS Timers10 Time command uint32_t getNow(); –Return the current time command uint32_t gett0(); –Return the base time for the previously started timer or the time of the previous event for periodic timers. command uint32_t getdt(); –Return the interval for the previously started timer. –The next fired event will occur at gett0() + getdt().

11. June 2008WEI Short Course TinyOS Timers11 Absolute Timers command void startPeriodicAt(uint32_t t0, uint32_t dt) –Fired event will be signaled every dt units –first event at t0+dt units. »Periodic timers set in the past will get a bunch of events in succession, until the timer "catches up". command void startOneShotAt(uint32_t t0, uint32_t dt); – Set a single-short timer to time t0+dt. »Timers set in the past will fire "soon".

12. June 2008WEI Short Course TinyOS Timers12 Timer Status and Control command void stop(); command bool isRunning(); command bool isOneShot();

13. June 2008WEI Short Course TinyOS Timers13 Alarms 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 in "interrupt context"). The Alarm interface provides a set of "basic" commands for common usage and provides a set of "extended" commands for advanced use.

14. June 2008WEI Short Course TinyOS Timers14 Alarm Interface interface Alarm { // basic interface async command void start( size_type dt ); async command void stop(); async event void fired(); // extended interface async command bool isRunning(); async command void startAt( size_type t0, size_type dt ); async command size_type getNow(); async command size_type getAlarm(); }

15. June 2008WEI Short Course TinyOS Timers15 Alarms 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() –cancel any previously running alarm. fired() –signals that the alarm has occurred. isRunning() –return TRUE if the alarm has been started and has not been cancelled or has not yet fired. FALSE is returned otherwise. startAt(t0,dt) –cancel any previously running alarm and set to fire at time t1 = t0+dt. This form allows a delay to be anchored to some time t0 taken before the invocation of startAt. The timer subsystem uses this form internally, to be able to use of the full width of an alarm while also detecting when a short alarm elapses prematurely. getNow() –return the current time in the precision and width of the alarm. 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, as in startAt(getAlarm(),dt). This pattern is used within the fired() event to construct periodic alarms.

16. June 2008WEI Short Course TinyOS Timers16 Counters A Counter component will increase the width of a low-level hardware timer by wrapping the overflow event and incrementing its higher order bits. These higher order bits are considered extra state over the HPL register layer, and therefore qualify all Counters as HAL components. 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 Counters from smaller widths.

17. June 2008WEI Short Course TinyOS Timers17 Counter Interface get() –return the current time. isOverflowPending() –return TRUE if the overflow flag is set for this counter, i.e., if and only if an overflow interrupt 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. It is expected that the underlying hardware platform sets the overflow flag when appropriate. clearOverflow() –cancel the pending overflow interrupt clearing the overflow flag. overflow() –signals that an overflow in the current time. That is, the current time has wrapped around from its maximum value to zero. interface Counter { async command size_type get(); async command bool isOverflowPending(); async command void clearOverflow(); async event void overflow(); }

18. June 2008WEI Short Course TinyOS Timers18 Abstraction Architecture HPL – present capabilities of the hardware –Convenient software access to what the hardware can do –Mechanism, not policy HAL – provide useful services in a manner that is most effective for the underlying hardware platform –Allow applications the ability to optimize if they value that higher than portability –Not limited to the least common denominator HIL – provide common hardware independent services using the HAL –Expressing a powerful common subset –Range of hardware / software in implementation

19. June 2008WEI Short Course TinyOS Timers19 Philosophy Applied to Timers Small number of direct hardware supported counters and alarms –Essentially generalized interrupts –Low-latency, low jitter –Pre-empts higher level activity Create virtualized timer resources using a portion of the available hardware resources –Delivered to the application component in task (synchronous) context. –Atomic relative to other synch context handlers. –Number of virtual timers determined automatically at compile time.

20. June 2008WEI Short Course TinyOS Timers20 System Implementation Challenges Want to provide multiple dedicated virtual resources to higher levels to simplify usage –Start / stop each virtual timer independent of the others Want to implement the multiple virtual timers on a shared resource. –Multiple pending “fires”, limited physical timer registers –Set the physical timer to the next event.

21. June 2008WEI Short Course TinyOS Timers21 Virtualizing physical resources Generic Modules –Create multiple virtual resources services by a common shared resource

22. June 2008WEI Short Course TinyOS Timers22 Example – multiple virtual timers #include "Timer.h" module Blink3M { uses interface Timer as Timer0; uses interface Timer as Timer1; uses interface Timer as Timer2; uses interface Leds; uses interface Boot; } implementation { event void Boot.booted() { call Timer0.startPeriodic( 250 ); call Timer1.startPeriodic( 550 ); call Timer2.startPeriodic( 1200 ); } event void Timer0.fired() { call Leds.led0Toggle(); } event void Timer1.fired() { call Leds.led1Toggle(); } event void Timer2.fired() { call Leds.led2Toggle(); } Note, not simple multiples

23. June 2008WEI Short Course TinyOS Timers23 3 Virtual Timer Instances TimerMilliC is a generic component Instantiated multiple times configuration Blink3MAppC { } implementation { components MainC, BlinkC, LedsC; components new TimerMilliC() as Timer0; components new TimerMilliC() as Timer1; components new TimerMilliC() as Timer2; BlinkC -> MainC.Boot; BlinkC.Timer0 -> Timer0; BlinkC.Timer1 -> Timer1; BlinkC.Timer2 -> Timer2; BlinkC.Leds -> LedsC; }

24. June 2008WEI Short Course TinyOS Timers24 Instantiating Multiple Virtual Timers Blink3M BootLeds MainC Boot LedsC Leds Timer0 TimerMilliC Timer Blink3MAppC Timer0 TimerMilliC Timer Timer0 TimerMilliC Timer

25. June 2008WEI Short Course TinyOS Timers25 Providing Virtual Timers The generic configuration, TimerMilliC, obtains a unique id (at compile time) for the instance. Wires it to the indexed interface array of the resource provider Blink3M BootLeds MainC Boot LedsC Leds Timer0 TimerMilliC Timer Blink3MAppC Timer0 Timer Timer0 TimerMilliC Timer TimerMilliP TimerMilli unique(UQ_TIMER_MILLI) TimerMilli

26. June 2008WEI Short Course TinyOS Timers26 Generic Configuration Generates a unique index (key) over the UQ_TIMER_MILLI keyset. Wires the instance to that index #include "Timer.h“ generic configuration TimerMilliC() { provides interface Timer ; } implementation { components TimerMilliP; Timer = TimerMilliP.TimerMilli[unique(UQ_TIMER_MILLI)]; } tos/system/timer/TimerMilliC.nc component interface index

27. June 2008WEI Short Course TinyOS Timers27 Indexed Interface Extent parameter behaves as a compile-time constant –Size internal data structures Determined by the number of distinct wirings #include "Timer.h" configuration TimerMilliP { provides interface Timer as TimerMilli[uint8_t id]; } implementation { … }

28. June 2008WEI Short Course TinyOS Timers28 Connecting to the Platform Indexed interface, paramterized by precision Connected to Hardware Independent interface provided by the component that implements the HIL for the particular platform. #include "Timer.h" configuration TimerMilliP { provides interface Timer as TimerMilli[uint8_t id]; } implementation { components HilTimerMilliC, MainC; MainC.SoftwareInit -> HilTimerMilliC; TimerMilli = HilTimerMilliC; } tos/system/timer/TimerMilliP.nc

29. June 2008WEI Short Course TinyOS Timers29 Mica class Millisecond timer for the mica family is built on hardware timer 0, running at 1024Hz. #include "Timer.h" configuration HilTimerMilliC { provides interface Init; provides interface Timer as TimerMilli[uint8_t num]; provides interface LocalTime ; } implementation { enum { TIMER_COUNT = uniqueCount(UQ_TIMER_MILLI) }; components AlarmCounterMilliP, new AlarmToTimerC(TMilli), new VirtualizeTimerC(TMilli, TIMER_COUNT), new CounterToLocalTimeC(TMilli); Init = AlarmCounterMilliP; TimerMilli = VirtualizeTimerC; VirtualizeTimerC.TimerFrom -> AlarmToTimerC; AlarmToTimerC.Alarm -> AlarmCounterMilliP; LocalTime = CounterToLocalTimeC; CounterToLocalTimeC.Counter -> AlarmCounterMilliP; } Tos/platforms/mica/HilTimerMilliC.nc

30. June 2008WEI Short Course TinyOS Timers30 Mica: Timer out of Alarms and Counters HilTimerMilliC TimerMilli AlarmCounterMilliP AlarmToTimerC VirtualizeTimerC CounterToLocalTimeC init TIMER_COUNT TimerFrom Alarm LocalTime Counter AlarmCounter init LocalTime

31. June 2008WEI Short Course TinyOS Timers31 MSP430 HIL configuration HilTimerMilliC { provides interface Init; provides interface Timer as TimerMilli[ uint8_t num ]; } implementation { components new AlarmMilli32C(); components new AlarmToTimerC(TMilli); components new VirtualizeTimerC(TMilli, uniqueCount(UQ_TIMER_MILLI)); Init = AlarmMilli32C; TimerMilli = VirtualizeTimerC; VirtualizeTimerC.TimerFrom -> AlarmToTimerC; AlarmToTimerC.Alarm -> AlarmMilli32C; }

32. June 2008WEI Short Course TinyOS Timers32 MSP430 – doing the work generic module VirtualizeTimerC(typedef precision_tag, int max_timers) { provides interface Timer as Timer[uint8_t num]; uses interface Timer as TimerFrom; } implementation { enum { NUM_TIMERS = max_timers, END_OF_LIST = 255, }; typedef struct { uint32_t t0; uint32_t dt; bool isoneshot : 1; bool isrunning : 1; bool _reserved : 6; } Timer_t; Timer_t m_timers[NUM_TIMERS]; bool m_timers_changed; …….

33. June 2008WEI Short Course TinyOS Timers33 Additional areas of importants Resource Arbitrators Radio Stacks Sharing of Busses and Pins Platform Definition

34. June 2008WEI Short Course TinyOS Timers34 3 Classes of Resources – TEP 108 Dedicated –subsystem needs exclusive access to at all times –no sharing policy is needed –Ex: interrupts and counters –MAY be annotated with the nesC attribute @atmostonce or @exactlyonce to provide compile-time checks that their usage assumptions are not violated Virtualized –Multiple clients interact with resource as if it were dedicated –virtualized instances multiplexed on single underlying resource Shared –Multiplexing of resource is exposed to multiple clients –Ex: bus. »TelosB Flash and Radio share SPI, SPI and I2C share pins –resource arbiter is responsible for multiplexing between the different clients »Clients request access to shared resource through arbiter resource interface

35. June 2008WEI Short Course TinyOS Timers35 Resource Interface – TEP 108 interface Resource { async command error_t request(); async command error_t immediateRequest(); event void granted(); async command error_t release(); async command bool isOwner(); }