David E. Culler University of California, Berkeley

1. Wireless Embedded Intrer-NetworkingFoundations of Ubiquitous Sensor NetworksTimers and System Resources David E. Culler University of California, Berkeley WEI Short Course TinyOS Timers

2. Timers • See TEP102 for complete details WEI Short Course TinyOS Timers

3. 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<precision_tag> { 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(); } WEI Short Course TinyOS Timers

4. 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 WEI Short Course TinyOS Timers

5. 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 WEI Short Course TinyOS Timers

6. 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 WEI Short Course TinyOS Timers

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

8. Local Time • get() • return the current time in specified precision. • 32-bit result, no overflows interface LocalTime<precision_tag> { async command uint32_t get(); } WEI Short Course TinyOS Timers

9. 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. WEI Short Course TinyOS Timers

10. 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(). WEI Short Course TinyOS Timers

11. 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". WEI Short Course TinyOS Timers

12. Timer Status and Control • command void stop(); • command bool isRunning(); • command bool isOneShot(); WEI Short Course TinyOS Timers

13. 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. WEI Short Course TinyOS Timers

14. Alarm Interface interface Alarm<precision_tag,size_type> { // 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(); } WEI Short Course TinyOS Timers

15. 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. WEI Short Course TinyOS Timers

16. 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. WEI Short Course TinyOS Timers

17. 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<precision_tag,size_type> { async command size_type get(); async command bool isOverflowPending(); async command void clearOverflow(); async event void overflow(); } WEI Short Course TinyOS Timers

18. 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 WEI Short Course TinyOS Timers

19. 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. WEI Short Course TinyOS Timers

20. 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. WEI Short Course TinyOS Timers

21. Virtualizing physical resources • Generic Modules • Create multiple virtual resources services by a common shared resource WEI Short Course TinyOS Timers

22. Example – multiple virtual timers #include "Timer.h" module Blink3M { uses interface Timer<TMilli> as Timer0; uses interface Timer<TMilli> as Timer1; uses interface Timer<TMilli> 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 ); } Note, not simple multiples event void Timer0.fired() { call Leds.led0Toggle(); } event void Timer1.fired() { call Leds.led1Toggle(); } event void Timer2.fired() { call Leds.led2Toggle(); } } WEI Short Course TinyOS Timers

23. 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; } WEI Short Course TinyOS Timers

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

25. Timer0 Timer0 Timer Timer TimerMilliC TimerMilliC 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 Blink3MAppC Blink3M Boot Timer0 Leds Boot Timer Leds MainC unique(UQ_TIMER_MILLI) LedsC TimerMilli TimerMilli TimerMilli TimerMilliP WEI Short Course TinyOS Timers

26. Generic Configuration tos/system/timer/TimerMilliC.nc • 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<TMilli>; } implementation { components TimerMilliP; Timer = TimerMilliP.TimerMilli[unique(UQ_TIMER_MILLI)]; } index component interface WEI Short Course TinyOS Timers

27. 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<TMilli> as TimerMilli[uint8_t id]; } implementation { … } WEI Short Course TinyOS Timers

28. Connecting to the Platform tos/system/timer/TimerMilliP.nc • 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<TMilli> as TimerMilli[uint8_t id]; } implementation { components HilTimerMilliC, MainC; MainC.SoftwareInit -> HilTimerMilliC; TimerMilli = HilTimerMilliC; } WEI Short Course TinyOS Timers

29. Mica class #include "Timer.h" configuration HilTimerMilliC { provides interface Init; provides interface Timer<TMilli> as TimerMilli[uint8_t num]; provides interface LocalTime<TMilli>; } 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 • Millisecond timer for the mica family is built on hardware timer 0, running at 1024Hz. WEI Short Course TinyOS Timers

30. Mica: Timer out of Alarms and Counters LocalTime TimerMilli init TimerMilli TimerMilli TIMER_COUNT HilTimerMilliC VirtualizeTimerC <TMilli> TimerFrom LocalTime AlarmToTimerC CounterToLocalTimeC Alarm Counter init Alarm Counter AlarmCounterMilliP WEI Short Course TinyOS Timers

31. MSP430 HIL configuration HilTimerMilliC { provides interface Init; provides interface Timer<TMilli> 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; } WEI Short Course TinyOS Timers

32. MSP430 – doing the work generic module VirtualizeTimerC(typedef precision_tag, int max_timers) { provides interface Timer<precision_tag> as Timer[uint8_t num]; uses interface Timer<precision_tag> 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; ……. WEI Short Course TinyOS Timers

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

34. 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 WEI Short Course TinyOS Timers

35. 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(); } WEI Short Course TinyOS Timers