tep102.txt

tinyos-2.x.rar

  value of ``t0`` numerically greater than the current time (returned by
  ``getNow()``) represents a time from before the last wraparound.

startOneShotAt(t0,dt) 
  cancel any previously running timer and set to fire at time t1 =
  t0+dt.  The timer will fire once then stop.

  ``t0`` is as in ``startPeriodicAt``.

getNow() 
  return the current time in the precision and width of the timer.

gett0() 
  return the time anchor for the previously started timer or the time
  of the previous event for periodic timers.

getdt() 
  return the delay or period for the previously started timer.


3. HAL guidelines
====================================================================

Platforms SHOULD expose their relevant timing capabilities using
standard Alarm and Counter interfaces.  The design pattern presented
here defines a component naming convention to allow platform
independent access to particular Alarms and Counters if they exist
and to cause compile errors if they do not.

A platform specific hardware timer with precision ${P} and width
${W} SHOULD be exposed as these two conventional Counter and Alarm
components::

  configuration Counter${P}${W}C
  {
    provides interface Counter< T${P}, uint${W}_t >;
  }

  generic configuration Alarm${P}${W}C()
  {
    provides interface Alarm< T${P}, uint${W}_t >;
  }

Instantiating an Alarm${P}${W}C component provides a new and independent
Alarm.  If the platform presents a limited number of Alarm resources,
then allocating more Alarms in an application than are available for the
platform SHOULD produce a compile-time error.  See Appendices B and C
for an example of how to make allocatable Alarms that are each
implemented on independent hardware timers.

For example, if a platform has an 8-bit 32kHz counter and three
8-bit 32kHz alarms, then the Counter and Alarm interfaces for
${P}=32khz and ${W}=16 are::

  configuration Counter32khz8C
  {
    provides interface Counter< T32khz, uint8_t >;
  }

  generic configuration Alarm32khz8C()
  {
    provides interface Alarm< T32khz, uint8_t >;
  }

This pattern MAY be used to define components for the platform that
are mutually incompatible in a single application.  Incompatible
components SHOULD produce compile-time errors when compiled
together.


4. HIL requirements
====================================================================

The following component MUST be provided on all platforms
::

  HilTimerMilliC
  BusyWaitMicroC

Both of these components use "binary" units, i.e., 1/1024s for
HilTimerMilliC and 1/1048576s for BusyWaitMicroC. Components using
other precisions (e.g., regular, non-binary milliseconds) MAY also be
provided.

HilTimerMilliC
--------------------------------------------------------------------

::

  configuration HilTimerMilliC
  {
    provides interface Init;
    provides interface Timer<TMilli> as TimerMilli[ uint8_t num ];
    provides interface LocalTime<TMilli>;
  }

A new timer is allocated using unique(UQ_TIMER_MILLI) to obtain a
new unique timer number.  This timer number is used to index the
TimerMilli parameterised interface.  UQ_TIMER_MILLI is defined in
Timer.h.  HilTimerMilliC is used by the LocalTimeMilliC component and the
TimerMilliC generic component, both found in ``tos/system/``

BusyWaitMicroC
--------------------------------------------------------------------

::

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

BusyWaitMicroC allows applications to busy-wait for a number of
microseconds. Its use should be restricted to situations where the
delay is small and setting a timer or alarm would be impractical,
inefficient or insufficiently precise.

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.

AlarmToTimerC
--------------------------------------------------------------------

AlarmToTimerC converts a 32-bit Alarm to a Timer.  ::

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


BusyWaitCounterC
--------------------------------------------------------------------

BusyWaitCounterC uses a Counter to block until a specified amount of
time elapses.  ::

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


CounterToLocalTimeC
--------------------------------------------------------------------

CounterToLocalTimeC converts from a 32-bit Counter to LocalTime.  ::

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


TransformAlarmC
--------------------------------------------------------------------

TransformAlarmC decreases precision and/or widens an Alarm.  An
already widened Counter component is used to help.  ::

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

to_precision_tag and to_size_type describe the final precision and
final width for the provided Alarm.  from_precision_tag and
from_size_type describe the precision and width for the source
AlarmFrom.  bit_shift_right describes the bit-shift necessary to
convert from the used precision to the provided precision.

For instance to convert from an Alarm<T32khz,uint16_t> to an
Alarm<TMilli,uint32_t>, the following TransformAlarmC would be
created::

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

It is the exclusive responsibility of the developer using
TransformAlarmC to ensure that all five of its arguments are self
consistent.  No compile errors are generated if the parameters
passed to TransformAlarmC are inconsistent.


TransformCounterC
--------------------------------------------------------------------

TransformCounterC decreases precision and/or widens a Counter.  ::

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

to_precision_tag and to_size_type describe the final precision and
final width for the provided Counter.  from_precision_tag and
from_size_type describe the precision and width for the source
CounterFrom.  bit_shift_right describes the bit-shift necessary to
convert from the used precision to the provided precision.
upper_count_type describes the numeric type used to store the
additional counter bits.  upper_count_type MUST be a type with width
greater than or equal to the additional bits in to_size_type plus
bit_shift_right.

For instance to convert from a Counter<T32khz,uint16_t> to a
Counter<TMilli,uint32_t>, the following TransformCounterC would be
created::

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

VirtualizeTimerC
--------------------------------------------------------------------

VirtualizeTimerC uses a single Timer to create up to 255 virtual
timers.  ::

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

6. Implementation
====================================================================

The definition of the HIL interfaces are found in ``tinyos-2.x/tos/lib/timer``:

  * ``Alarm.nc``
  * ``BusyWait.nc``
  * ``Counter.nc``
  * ``LocalTime.nc``
  * ``Timer.h`` defines precision tags and strings for unique()
  * ``Timer.nc``

The implementation of the utility components are also found in
``tinyos-2.x/tos/lib/timer``:

  * ``AlarmToTimerC.nc``
  * ``BusyWaitCounterC.nc``
  * ``CounterToLocalTimeC.nc``
  * ``TransformAlarmC.nc``
  * ``TransformCounterC.nc``
  * ``VirtualizeAlarmC.nc``
  * ``VirtualizeTimerC.nc``

The implementation of timers for the MSP430 is in
``tinyos-2.x/tos/chips/msp430/timer``:

  * ``Alarm32khz16C.nc`` is generic and provides a new ``Alarm<T32khz,uint16_t>``
  * ``Alarm32khz32C.nc`` is generic and provides a new ``Alarm<T32khz,uint32_t>``
  * ``AlarmMilli16C.nc`` is generic and provides a new ``Alarm<TMilli,uint16_t>``
  * ``AlarmMilli32C.nc`` is generic and provides a new ``Alarm<TMilli,uint32_t>``
  * ``BusyWait32khzC.nc`` provides ``BusyWait<T32khz,uint16_t>``
  * ``BusyWaitMicroC.nc`` provides ``BusyWait<TMicro,uint16_t>``
  * ``Counter32khz16C.nc`` provides ``Counter<T32khz,uint16_t>``
  * ``Counter32khz32C.nc`` provides ``Counter<T32khz,uint32_t>``
  * ``CounterMilli16C.nc`` provides ``Counter<TMilli,uint16_t>``
  * ``CounterMilli32C.nc`` provides ``Counter<TMilli,uint32_t>``
  * ``GpioCaptureC.nc``
  * ``HilTimerMilliC.nc`` provides ``LocalTime<TMilli>`` and 
    ``Timer<TMilli> as TimerMilli[uint8_t num]``
  * ``Msp430AlarmC.nc`` is generic and converts an MSP430 timer to a 16-bit Alarm
  * ``Msp430Capture.nc`` HPL interface definition for MSP430 timer captures
  * ``Msp430ClockC.nc`` exposes MSP430 hardware clock initialization
  * ``Msp430ClockInit.nc`` HPL interface definition for hardware clock initialization
  * ``Msp430ClockP.nc`` implements MSP430 hardware clock initialization and
    calibration and startup
  * ``Msp430Compare.nc`` HPL interface definition for MSP430 timer compares
  * ``Msp430Counter32khzC.nc`` provides ``Counter<T32khz,uint16_t>`` based on
    MSP430 TimerB
  * ``Msp430CounterC.nc`` is generic and converts an Msp430Timer to a Counter
  * ``Msp430CounterMicroC.nc`` provides ``Counter<TMicro,uint16_t>`` based on
    MSP430 TimerA
  * ``Msp430Timer.h`` defines additional MSP430 timer bitmasks and structs
  * ``Msp430Timer.nc`` HPL interface definition
  * ``Msp430Timer32khzC.nc`` is generic and allocates a new 32khz hardware timer
  * ``Msp430Timer32khzMapC.nc`` exposes the MSP430 hardware timers as a
    parameterized interface allocatable using Msp430Timer32khzC
  * ``Msp430TimerC.nc`` exposes the MSP430 hardware timers
  * ``Msp430TimerCapComP.nc`` is generic and implements the HPL for MSP430
    capture/compare special function registers
  * ``Msp430TimerCommonP.nc`` maps the MSP430 timer interrupts to Msp430TimerEvents
  * ``Msp430TimerControl.nc`` HPL interface definition
  * ``Msp430TimerEvent.nc`` HPL interface definition
  * ``Msp430TimerP.nc`` is generic and implements the HPL for MSP430 timer
    special function registers

Implementation of timers for the ATmega128 and PXA27x may be found in
``tinyos-2.x/tos/chips/atm128/timer`` and
``tinyos-2.x/tos/chips/pxa27x/timer`` respectively.


7. Author's Address