tep102.txt

tinyos-2.x.rar

====================================================================
| Cory Sharp
| Moteiv Corporation
| 55 Hawthorne St, Suite 550
| San Francisco, CA 94105
|
| phone - [phone]
| email - [e-mail]
|
|
| Martin Turon
| P.O. Box 8525
| Berkeley, CA 94707
|
| phone - [phone]
| email - [e-mail]
|
|
| David Gay
| 2150 Shattuck Ave, Suite 1300
| Intel Research
| Berkeley, CA 94704
|
| phone - [phone]
| email - [e-mail]


Appendix A: Timer hardware on various microcontrollers
====================================================================

  a. Atmega128

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

    ii. Two 16-bit timers, each with

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

  b. MSP430

    i. Two 16-bit timers with

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

  c. Intel PXA27x

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

      * 4 compare registers
      * Watchdog functionality

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

    iii. Periodic & one-shot capability

    iv. 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: HplAtm128Timer0AsyncC, and HplAtm128Timer0C through
HplAtm128Timer3C. Timers 1 and 3 have three compare registers, so offer
a parameterised HplAtm128Compare interface: ::

  configuration HplAtm128Timer1C
  {
    provides {
      // 16-bit Timers
      interface HplAtm128Timer<uint16_t>   as Timer;
      interface HplAtm128TimerCtrl16       as TimerCtrl;
      interface HplAtm128Capture<uint16_t> as Capture;
      interface HplAtm128Compare<uint16_t> as Compare[uint8_t id];
    }
  }
  ...

where the ``id`` corresponds to the compare register number. The parameterised
interface is only connected for ``id`` equal to 0, 1 or 2. Attempts to use
another value cause a compile-time error. This is achieved as follows (code
from the implementation of ``HplAtm128Timer1C``) ::

  Compare[0] = HplAtm128Timer1P.CompareA; 
  Compare[1] = HplAtm128Timer1P.CompareB;
  Compare[2] = HplAtm128Timer1P.CompareC;


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;
  } ...

As a result of issues arising from using timer 0 in asynchronous mode,
the HAL also offers the following component: ::

  generic configuration Atm128AlarmAsyncC(typedef precision, int divider) {
    provides {
      interface Init @atleastonce();
      interface Alarm<precision, uint32_t>;
      interface Counter<precision, uint32_t>;
    }
  }
  ...

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

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: uses Atm128AlarmAsyncC to divide the external 32768Hz crystal
  by 32, creating a 32-bit alarm and counter. This alarm and counter is
  used to build HilTimerMilliC, using the AlarmToTimerC,
  VirtualizeTimerC and CounterToLocalTimeC utility components.

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

  32-bit microsecond Counters and Alarms, named ``CounterMicro32C`` and
  ``AlarmMicro32C``, are created from ``CounterOne16C`` and
  ``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
  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 to
  build 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.

The automatic allocation of compare registers to alarms (and
corresponding compile-time error when too many compare registers are
used) is achieved as follows.  The implementations of ``AlarmOne16C``
and ``AlarmThree16C`` use the ``Atm128AlarmC`` generic component and
wire it, using ``unique``, to one of the compare registers offered by
``HplAtm128Timer1C`` and ``HplAtm128Timer3C``::

  generic configuration AlarmOne16C()
  {
    provides interface Alarm<TOne, uint16_t>;
  }
  implementation
  {
    components HplAtm128Timer1C, InitOneP,
      new Atm128AlarmC(TOne, uint16_t, 3) as NAlarm;

    Alarm = NAlarm;
    NAlarm.HplAtm128Timer -> HplAtm128Timer1C.Timer;
    NAlarm.HplAtm128Compare -> HplAtm128Timer1C.Compare[unique(UQ_TIMER1_COMPARE)];
  }

On the fourth creation of an ``AlarmOne16C``, ``unique(UQ_TIMER1_COMPARE)``
will return 3, causing a compile-time error as discussed in Appendix B
(``HplAtm128Timer1C``'s ``Compare`` interface is only defined for values
from 0 to 2).


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:

* HilTimerMilliC: built as described above from hardware timer 0.
* 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.