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
• 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

The interested reader can refer to Appendix A for a brief overview of the timer hardware on some current TinyOS platforms.

TinyOS does not attempt to capture all this diversity in a platform-independent fashion. Instead, following the principles of the HAA[_tep2], each microcontroller should expose all this functionality via components and interfaces at the HPL and, where appropriate, HAL levels. However, two aspects of timers are sufficiently common and important that they should be made available in a well-defined way: measuring time, and triggering (possibly repeating) events at specific times. The rest of this TEP specifies:

• a set of platform-independent interfaces for counting time and triggering events (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 (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).

typedef struct { } TMilli;
typedef struct { } T32khz;
typedef struct { } TMicro;

interface Counter< precision_tag, size_type >
interface Alarm< precision_tag, size_type >
interface BusyWait< precision_tag, size_type >
interface LocalTime< precision_tag >
interface Timer< precision_tag >

interface Counter<precision_tag,size_type>
{
  async command size_type get();
  async command bool isOverflowPending();
  async command void clearOverflow();
  async event void overflow();
}

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();
}

interface BusyWait<precision_tag,size_type>
{
  async command void wait( size_type dt );
}

interface LocalTime<precision_tag>
{
  async command uint32_t get();
}

interface Timer<precision_tag>
{
  // basic interface
  command void startPeriodic( uint32_t dt );
  command void startOneShot( uint32_t dt );
  command void stop();
  event void fired();

  // extended interface
  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();
}

3. HAL guidelines

Platforms typically select a clocking option for each of their hardware counters, based on their hardware design (e.g., the mica family of motes all run their hardware timer 0 at 32kHz, and the micaz mote runs its timer 1 at cpu frequency/256). Platforms SHOULD expose the timing functionality of these timers using the Alarm and Counter interfaces, in the fashion described below. Platforms MAY expose the same hardware timer with different frequencies - use of conflicting frequences in the same program SHOULD produce compile-time errors.

A hardware timer with precision P and width W SHOULD be exposed as a several components:

configuration CounterPWC {
  provides interface Counter<TP, uintW_t>;
} ...
generic configuration AlarmPWC {
  provides interface Alarm<TP,uintW_t>;
} ...

and, except if W is 32:

configuration CounterP32C {
  provides interface Counter<TP, uint32_t>;
} ...
generic configuration AlarmP32C {
  provides interface Alarm<TP,uint32_t>;
} ...

Instantiating the Alarm... components provides a new Alarm independent of all prior instantiations. Instantiating such a component "consumes" a compare register from the corresponding hardware timer; when no more compare registers are available, instantiation SHOULD produce a compile-time error (see Appendix B for an example of how to achieve this).

For example, the micaz platform includes an AlarmMilli8C and AlarmMilli32C components for timer 0 (one instantiation allowed), and Alarm32kHz16C and Alarm32kHz32C for timer 1 (three instantiations allowed).

4. HIL requirements

The following component MUST be provided on all platforms::

TimerMilliC BusyWaitMicroC

#define TIMERMILLIC_SERVICE ...
configuration TimerMilliC
{
  provides interface Init;
  provides interface Timer<TMilli>[uint8_t num];
  provides interface LocalTime<TMilli>;
}

configuration BusyWaitMicroC
{
  provides interface BusyWait<TMicro,uint16_t>;
}

5. Utility components

A number of platform independent generic components are provided to help implementers and advanced users of the TinyOS timer system:

• AlarmToTimerC
• BusyWaitCounterC
• CounterToLocalTimeC
• TransformAlarmC
• TransformCounterC
• VirtualizeTimerC

Appendices B and C show how these can be used to help implement the timer HAL and HIL.

generic component AlarmToTimerC( typedef precision_tag )
{
  provides interface Timer<precision_tag>;
  uses interface Alarm<precision_tag,uint32_t>;
}

generic component BusyWaitC( typedef precision_tag,
  typedef size_type @integer() )
{
  provides interface BusyWait<precision_tag,size_type>;
  uses interface Counter<precision_tag,size_type>;
}

generic component CounterToLocalTimeC( precision_tag )
{
  provides interface LocalTime<precision_tag>;
  uses interface Counter<precision_tag,uint32_t>;
}

generic component TransformAlarmC(
  typedef to_precision_tag,
  typedef to_size_type @integer(),
  typedef from_precision_tag,
  typedef from_size_type @integer(),
  uint8_t bit_shift_right )
{
  provides interface Alarm<to_precision_tag,to_size_type> as Alarm;
  uses interface Counter<to_precision_tag,to_size_type> as Counter;
  uses interface Alarm<from_precision_tag,from_size_type> as AlarmFrom;
}

new TransformAlarmC( TMilli, uint32_t, T32khz, uint16_t, 5 )

generic component TransformCounterC(
  typedef to_precision_tag,
  typedef to_size_type @integer(),
  typedef from_precision_tag,
  typedef from_size_type @integer(),
  uint8_t bit_shift_right,
  typedef upper_count_type @integer() )
{
  provides interface Counter<to_precision_tag,to_size_type> as Counter;
  uses interface Counter<from_precision_tag,from_size_type> as CounterFrom;
}

new TransformCounterC( TMilli, uint32_t, T32khz, uint16_t, 5, uint32_t )

generic component VirtualizeTimerC( typedef precision_tag, int max_timers )
{
  provides interface Init;
  provides interface Timer<precision_tag> as Timer[ uint8_t num ];
  uses interface Timer<precision_tag> as TimerFrom;
}

Appendix A: Timer hardware on various microcontrollers

1. Atmega128

1. 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)

2. Two 16-bit timers, each with

• 5 prescaler values
• External and software clocking options
• Three compare registers (again with many actions)
• Input capture

2. MSP430

1. Two 16-bit timers with

• One with three compare registers
• One with eight compare registers
• Each from distinct clock source
• Each with limited prescalers

3. Intel PXA27x

1. One fixed rate (3.25MHz) 32-bit timer with

• 4 compare registers
• Watchdog functionality

2. 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)

3. Periodic & one-shot capability
4. Two external sync events

Appendix B: a microcontroller: Atmega 128 timer subsystem

The Atmega128 exposes its four timers through a common set of interfaces:

• HplTimer<width> - get/set current time, overflow event, control, init
• HplCompare<width> - get/set compare time, fired event, control
• HplCapture<width> - get/set capture time, captured event, control, config

Parameterising these interfaces by width allows reusing the same interfaces for the 8 and 16-bit timers. This simplifies building reusable higher level components which are independent of timer width.

interface HplAtm128Timer<timer_size>
{
  /// Timer value register: Direct access
  async command timer_size get();
  async command void       set( timer_size t );

  /// Interrupt signals
  async event void overflow();        //<! Signalled on overflow interrupt

  /// Interrupt flag utilites: Bit level set/clr
  async command void reset(); //<! Clear the overflow interrupt flag
  async command void start(); //<! Enable the overflow interrupt
  async command void stop();  //<! Turn off overflow interrupts
  async command bool test();  //<! Did overflow interrupt occur?
  async command bool isOn();  //<! Is overflow interrupt on?

  /// Clock initialization interface
  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
}

interface HplAtm128Compare<size_type>
{
  /// Compare value register: Direct access
  async command size_type get();
  async command void      set(size_type t);

  /// Interrupt signals
  async event void fired();           //<! Signalled on compare interrupt

  /// Interrupt flag utilites: Bit level set/clr
  async command void reset();         //<! Clear the compare interrupt flag
  async command void start();         //<! Enable the compare interrupt
  async command void stop();          //<! Turn off comparee interrupts
  async command bool test();          //<! Did compare interrupt occur?
  async command bool isOn();          //<! Is compare interrupt on?
}

interface HplAtm128Capture<size_type>
{
  /// Capture value register: Direct access
  async command size_type get();
  async command void      set(size_type t);

  /// Interrupt signals
  async event void captured(size_type t);  //<! Signalled on capture int

  /// 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
  async command bool test();           //<! Did capture interrupt occur?
  async command bool isOn();           //<! Is capture interrupt on?

  async command void setEdge(bool up); //<! True = detect rising edge
}

These interfaces are provided by four components, corresponding to each hardware timer: HplAtm128Timer0C through HplAtm128Timer3C.

The Atmega128 chip components do not define a HAL, as the timer configuration choices (frequencies, use of input capture or compare output, etc) are platform-specific. Instead, it provides a few generic components for converting the HPL interfaces into platform-independent interfaces. These generic components include appropriate configuration parameters (e.g., prescaler values):

generic module Atm128AlarmC(typedef frequency_tag,
                            typedef timer_size @integer(),
                            uint8_t prescaler,
                            int mindt)
{
  provides interface Init;
  provides interface Alarm<frequency_tag, timer_size> as Alarm;
  uses interface HplTimer<timer_size>;
  uses interface HplCompare<timer_size>;
} ...

generic module Atm128CounterC(typedef frequency_tag,
                              typedef timer_size @integer())
{
  provides interface Counter<frequency_tag,timer_size> as Counter;
  uses interface HplTimer<timer_size> as Timer;
} ...

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 internal oscillator is less precise, but allows for much faster startup from power-down and power-save modes (6 clocks vs 16000 clocks). Finally, power consumption is lower at the lower frequencies.

The mica family members support operation at all these frequencies via a MHZ preprocessor symbol, which can be defined to 1, 2, 4, or 8. If undefined, it defaults to a platform-dependent value (4 for mica2dot, 8 for mica2 and micaz).

The mica family configures its four timers in part based on the value of this MHZ symbol:

• Timer 0: divides the external 32768Hz crystal by 32 to build AlarmMilli8C and AlarmMilli32C (see Section 3). As timer 0 has a single compare register, these can only be instantiated once. Timing accuracy is as good as the external crystal.

• 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 HAL components exposing timer 1 are named CounterOne16C and AlarmOne16C (rather than the CounterMicro16C AlarmMicro16C as suggested in Section 3).

  When building the 32-bit counter and 32-bit alarms, the rate of timer 1 is adjusted in software to 1MHz. Thus the 32-bit HAL components for timer are named CounterMicro32C and AlarmMicro32C.

  Three compare registers are available on timer1, so up to three instances of AlarmOne16C and/or AlarmMicro32C can be created. The timing accuracy depends on how the mote is clocked:

  • internal clock: depends on how well the clock is calibrated
  • external 7.37MHz crystal: times will be off by ~8.6%
  • external 4MHz crystal: times will be as accurate as the crystal

• Timer 2: this timer is not currently exposed by the HAL.

• 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 with timer 1, the rate of timer 3 is adjusted in software when building the 32-bit counter and 32-bit alarms, giving components Counter32khz32C and Alarm32khz32C. As with timer 1, three compare registers, hence up to three instances of Alarm32khz32C and/or AlarmThree16C are available.

  At 1, 2, 4 and 8MHz, Counter32khz32C and Alarm32khz32C run at 31.25kHz (plus clock rate inaccuracy). At 7.37MHz, they run at ~28.8kHz.

When an Atmega128 is in any power-saving mode, hardware timers 1, 2 and 3 stop counting. The default Atmega128 power management will enter these power-saving modes even when timers 1 and 3 are enabled, so time as measured by timers 1 and 3 does not represent real time. However, if any alarms built on timers 1 or 3 are active, the Atmega128 power management will not enter power-saving modes.

The mica family HIL components are built as follows:

• TimerMilliC: built using AlarmMilli32C (consuming its single compare register)
• BusyWaitMicroC: implemented using a simple software busy-wait loop which waits for MHZ cycles per requested microsecond. Accuracy is the same as Timer 1.

Finally, the mica family motes measure their clock rate at boot time, based on the external 32768Hz crystal. The results of this clock rate measurement are made available via the cyclesPerJiffy command of the Atm128Calibrate interface of the MeasureClockC component. This command reports the number of cycles per 1/32768s. Please see this interface definition for other useful commands for more accurate timing.