[Tinyos-beta-commits] CVS: tinyos-1.x/beta/teps/txt tep102.txt, NONE, 1.1

[Cory Sharp]

Update of /cvsroot/tinyos/tinyos-1.x/beta/teps/txt
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv28854

Added Files:
	tep102.txt 
Log Message:
TEP 102 - Timers

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



--- NEW FILE: tep102.txt ---
============================
 Timers
============================
:TEP: 102
:Group: Core Working Group 
:Type: Documentary
:Status: Draft
:TinyOS-Version: 2.x
:Author: Cory Sharp

:Draft-Created: 22-Sep-2004
:Draft-Version: $Revision: 1.1 $
:Draft-Modified: $Date: 2005/01/19 17:37:32 $
:Draft-Discuss: TinyOS-2.0 Working List <tinyos-2.0wg at mail.millenium.berkeley.edu>

.. Note::

   This memo documents a part of TinyOS for the TinyOS Community, and
   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 both common timing
requirements in precision and resolution across common hardware
configurations.  This TEP focuses on aligning the Timer abstraction
with the three-layer Hardware Abstraction Architecture (HAA).


Introduction
====================================================================

Timer interfaces impact to a number of aspects of the operating
system:

* Low frequency alarms, synchronous, periodic and oneshot, for
user/app timers
* High frequency alarms, asynchronous, periodic and oneshot, for adc
sampling
* Stop watches, timing information
* Local time, time origin
* Time synchronization

Two fundamental properties of timers are *precision* and *resolution*.
Satisfying all possible precisions (milli, 32khz, micro, etc) and
resolutions (16-bit, 32-bit, 48-bit, 64-bit, etc) is both burdens
system developers and encumbers application programming.  To reduce
interface complexity, we assert that a variety in precision is more
beneficial than a variety in resolution.  So for simplicity, we specify
the following about timer resolution

* All exposed timer values should be unsigned 32-bit integers (uint32_t)
regardless of precision

A single timer interface common across all precisions would enable subtle
wiring errors that are hard to detect at run-time.  To prevent this, we
make timer interfaces for different precisions mutually incompatible.
But, instead of creating a wholly distinct interface for each precision,
we define generic timer interfaces parameterized by these frequency type
tags::

  typedef struct { } TMilli;
  typedef struct { } T32khz;
  typedef struct { } TMicro;
  typedef struct { } TNano; //as an example of a future extension

These tags allow a single interface specification to be common across all
precisions while making instances of them mutually incompatible in wiring.
As long as application developers are comfortable with the syntax of nesC
generics, this makes the code overall more clear.  This design pattern
further allows for classes of generic modules that are not possible using
wholly distinct interfaces per precision.

See TEP 2 for the general background on the HAA.


Quick Summary
====================================================================

Five interfaces are presented:

* TimeCount<frequency_tag>
* Alarm<frequency_tag>
* Timer<frequency_tag>
* TimerAsync<frequency_tag>
* Stopwatch<frequency_tag>

Low frequency alarms are satisfied by Timer<frequency_tag>, derived from
one or more Alarm's.  TinyOS will provide Timer<TMilli> and Timer<T32khz>
through the standard timer component TimerC.

High frequency alarms are satisfied by TimerAsync<frequency_tag>, derived
from some number of Alarm's.  TinyOS will provide TimerAsync<T32khz> and
possibly TimerAsync<TMicro> also through the standard timer component
TimerC.

Time elapsed measurements are provided by Stopwatch<frequency_tag>, which
are derived from a TimeCount.

Local time is provided by TimeCount.  The time origin is relative to when
the mote was booted.

Time synchronization and the time origin are not addressed directly in
this TEP.  It is presumed that they can be built as a nearly parallel
layer on top of this layer of timers.


Hardware differences between the current platforms
====================================================================

  a. Mica2 (ATmega128)

    i. Two 8-bit timers, each with

      * 10-bit prescaler
      * One compare register

    ii. Two 16-bit timers, each with

      * Limited prescalers
      * Three compare registers

  b. Telos/EYES (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. Both platforms have a 32kHz clock and a high frequency clock
  d. Platforms' timers are similar


Hardware Presentation Layer (HPL)
====================================================================

  a. Implementatin: Hardware-level
  b. Presentation: System dependent
  c. Stateless
  d. Expose common hardware resources via common interfaces

    i. Timers
    ii. Compares
    iii. This allows HAL's to switch between hardware resources with only
         a wiring change

  e. See for instance under tos/platform/msp430/

    i. MSP430Timer, MSP430TimerControl, MSP430Compare, MSP430Capture
    ii. MSP430TimerC, MSP430TimerM


Hardware Adaptation Layer (HAL)
====================================================================

  a. Implementaiton: System dependent
  b. Presentation: System independent
  c. Async
  d. TimeCount<frequency_tag>

    i. Get current time as a uint32_t in whatever units are specified by
      the interface tag frequency_tag
    ii. Manage overflows

      * Allows for properly deriving higher resolution counters

    iii. Interface::

      interface TimeCount<frequency_tag>
      {
	async command uint32_t get();
	async command bool isOverflowPending();
	async command bool clearOverflow();
	async event void overflow();
      }

  e. Alarm<frequency_tag>

    i. Manages a single alarm
    ii. Set is special, sets alarm delta from explicit t0 not implicit "now"

      * Avoids race condition from setting short alarms in absolute time
      * Allows for precise periodic timers, no alarm time slip

    iii. The time base of an Alarm must correspond to an appropriate TimeCount

    iv. Interface::

      interface Alarm<frequency_tag>
      {
	async command uint32_t get();
	async command bool isSet();
	async command void cancel();
	async command void set( uint32_t t0, uint32_t dt );
	async event void fired();
      }

    v. The AlarmC configuration exposes a distinct set of alarms
    *required* by standard TinyOS components.  This is necessary if the
    HIL is to be wholly independent of system implementation.  AlarmC may
    also expose additional alarms to be used by TinyOS applications. ::

      configuration AlarmC
      {
	// alarms required by standard tinyos components
	provides interface Alarm<TMilli> as AlarmTimerMilli;
	provides interface Alarm<T32khz> as AlarmTimer32khz;
	provides interface AlarmAsync<T32khz> as AlarmTimerAsync32khz;

	// extra alarms to be used by applications
	provides interface Alarm<T32khz> as Alarm32khz1;
	provides interface Alarm<T32khz> as Alarm32khz2;
	//...

	provides interface Alarm<TMicro> as AlarmMicro1;
	provides interface Alarm<TMicro> as AlarmMicro2;
	provides interface Alarm<TMicro> as AlarmMicro3;
	//...
      }

  f. Alarm downsample example.  These generic interfaces prevent, for
  instance, an Alarm<TMilli> from being wired to an Alarm<T32khz>.  And,
  because each interface isn't totally distinct (such as AlarmMilli or
  Alarm32khz), we can create a generic module to downsample one alarm to
  another::

    generic module AlarmDownsample
    ( 
      typedef to_freq_tag, 
      typedef from_freq_tag, 
      int difflog2freq
    )
    {
      provides interface Alarm<to_freq_tag> as SlowerAlarm;
      uses interface Alarm<from_freq_tag> as FasterAlarm;
    }
    implementation
    {
      components new AlarmDownsampleM(to_freq_tag,from_freq_tag,difflog2freq) as ADM;
      ADM.SlowerAlarm = SlowerAlarm;
      ADM.FasterAlarm = FasterAlarm;
    }


Hardware Interface Layer (HIL)
====================================================================

  a. Implementation: System independent
  b. Presentation: OS service
  c. Timer interface
  
    i. Synchronous
    ii. Parameterized by time precision
    iii. Provides periodic and one shot timers
    iv. May have moderate computational overhead, probably all Timers for
    a given timer precision are multiplexed from a single hardware
    resource

    v. Interface::

      interface Timer<frequency_tag>
      {
	command result_t setPeriodic( uint32_t dt );
	command result_t setOneShot( uint32_t dt );
	command result_t stop();
	command bool isSet();
	command bool isPeriodic();
	command bool isOneShot();
	command uint32_t getPeriod();
	event result_t fired();
      }

  d. TimerAsync interface
  
    i. Asynchronous
    ii. Parameterized by time precision
    iii. Provides periodic and one shot timers
    iv. Should have minimal computational overhead, probably each
    TimerAsync is based on a single hardware resource

    v. Interface::

      interface TimerAsync<frequency_tag>
      {
	async command result_t setPeriodic( uint32_t dt );
	async command result_t setOneShot( uint32_t dt );
	async command result_t stop();
	async command bool isSet();
	async command bool isPeriodic();
	async command bool isOneShot();
	async command uint32_t getPeriod();
	async event result_t fired();
      }

  e. Stopwatch interface

    i. Asynchronous
    ii. Parameterized by time precision
    iii. Provides elapsed time readings from a specified start
    iv. Indicates if an overflow occurred for the returned value
    v. Stopwatches only depend on measurements from an appropriate
    TimeCount.
    v. Interface::

      typedef struct
      {
	uint32_t value;
	bool overflow;
      } stopwatch_t;

      interface Stopwatch<frequency_tag>
      {
	async command void start();
	async command stopwatch_t read();
	async command stopwatch_t stop();
      }


Implementation
====================================================================

See the tinyos-2.x/tos/ tree.  Interfaces are in interfaces/ and
implementations are in platforms/ or chips/.


Author's Address
====================================================================

| Cory Sharp
| 410 Soda Hall
| UC Berkeley
| Berkeley, CA 94720
|
| email - cssharp at eecs.berkeley.edu