[Tinyos-2-commits] CVS: tinyos-2.x/doc/txt tep102.txt,1.7,1.8

Wed May 23 14:33:49 PDT 2007

Update of /cvsroot/tinyos/tinyos-2.x/doc/txt
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv13492

Modified Files:
	tep102.txt 
Log Message:
updates for clarification and LocalTime

Index: tep102.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep102.txt,v
retrieving revision 1.7
retrieving revision 1.8
diff -C2 -d -r1.7 -r1.8
*** tep102.txt	12 Dec 2006 18:22:54 -0000	1.7
--- tep102.txt	23 May 2007 21:33:47 -0000	1.8
***************
*** 72,76 ****
  timer interfaces (2.1).

! 2.1 Precision, Width and Accuracy.
  --------------------------------------------------------------------

--- 72,76 ----
  timer interfaces (2.1).

! 2.1 Precision, Width and Accuracy
  --------------------------------------------------------------------

***************
*** 83,87 ****
  binary milliseconds, 32768 32kHz ticks, or 1048576 microseconds.
  This TEP emphasizes millisecond and 32kHz tick precisions while
! reasonably accommodating other precisions.

  Examples of widths are 8-bit, 16-bit, 32-bit, and 64-bit.  The width
--- 83,89 ----
  binary milliseconds, 32768 32kHz ticks, or 1048576 microseconds.
  This TEP emphasizes millisecond and 32kHz tick precisions while
! reasonably accommodating other precisions. The use of "binary" units
! is motivated by the common availability of hardware clocks driven 
! by a 32768Hz crystal.

  Examples of widths are 8-bit, 16-bit, 32-bit, and 64-bit.  The width
***************
*** 96,100 ****
  higher for internal vs crystal oscillators) and hardware limitations. As an
  example of hardware limitations, a mica2 clocked at 7.37MHz cannot offer an
! exact microsecond timer -- the closest it can come is 7.37MHz/8. Rather
  than introduce a plethora of precisions, we believe it is often best to
  pick the existing precision closest to what can be provided, along with
--- 98,102 ----
  higher for internal vs crystal oscillators) and hardware limitations. As an
  example of hardware limitations, a mica2 clocked at 7.37MHz cannot offer an
! exact binary microsecond timer -- the closest it can come is 7.37MHz/8. Rather
  than introduce a plethora of precisions, we believe it is often best to
  pick the existing precision closest to what can be provided, along with
***************
*** 110,119 ****
  reflected in the interface type.

! Precision is expressed as an empty type -- TMilli, T32khz, and
  TMicro -- written in the standard Timer.h header like this::

!   typedef struct { } TMilli; // 1024 ticks per second
!   typedef struct { } T32khz; // 32768 ticks per second
!   typedef struct { } TMicro; // 1048576 ticks per second

  Note that the precision names are expressed as either frequency or
--- 112,121 ----
  reflected in the interface type.

! Precision is expressed as a dummy type -- TMilli, T32khz, and
  TMicro -- written in the standard Timer.h header like this::

!   typedef struct { int notUsed; } TMilli; // 1024 ticks per second
!   typedef struct { int notUsed; } T32khz; // 32768 ticks per second
!   typedef struct { int notUsed; } TMicro; // 1048576 ticks per second

  Note that the precision names are expressed as either frequency or
***************
*** 139,146 ****
  --------------------------------------------------------------------

- 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
--- 141,144 ----
***************
*** 161,172 ****
  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() 
--- 159,168 ----
  isOverflowPending() 
    return TRUE if the overflow flag is set for this counter, i.e., if and
!   only if an overflow event 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.  

  clearOverflow() 
!   cancel the pending overflow event clearing the overflow flag.

  overflow() 
***************
*** 222,225 ****
--- 218,225 ----
    detecting when a short alarm elapses prematurely.

+   The time ``t0`` is always assumed to be in the past. A value of ``t0``
+   numerically greater than the current time (returned by ``getNow()``)
+   represents a time from before the last wraparound.
+ 
  getNow() 
    return the current time in the precision and width of the alarm.
***************
*** 328,335 ****
--- 328,341 ----
    stopped.

+   As with alarms, the time ``t0`` is always assumed to be in the past. A
+   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.
***************
*** 366,375 ****
    }

! 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 Appendix B 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
--- 372,381 ----
    }

! 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
***************
*** 409,412 ****
--- 415,419 ----
      provides interface Init;
      provides interface Timer<TMilli> as TimerMilli[ uint8_t num ];
+     provides interface LocalTime<TMilli>;
    }

***************
*** 414,419 ****
  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 generic component
! TimerMilliC found in ``tos/system/``.

  BusyWaitMicroC
--- 421,426 ----
  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
***************
*** 542,546 ****
  final width for the provided Counter.  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.
  upper_count_type describes the numeric type used to store the
--- 549,553 ----
  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
***************
*** 555,559 ****
    new TransformCounterC( TMilli, uint32_t, T32khz, uint16_t, 5, uint32_t )

- 
  VirtualizeTimerC
  --------------------------------------------------------------------
--- 562,565 ----
***************
*** 588,592 ****
    * ``CounterToLocalTimeC.nc``
    * ``TransformAlarmC.nc``
-   * ``TransformAlarmCounterC.nc``
    * ``TransformCounterC.nc``
    * ``VirtualizeAlarmC.nc``
--- 594,597 ----
***************
*** 780,785 ****
    }

! 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
--- 785,814 ----
    }

! 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
***************
*** 808,811 ****
--- 837,856 ----
    } ...

+ 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
  ====================================================================
***************
*** 826,832 ****
  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.
--- 871,879 ----
  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.
***************
*** 838,844 ****
    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
--- 885,892 ----
    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
***************
*** 855,860 ****
    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
--- 903,908 ----
    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
***************
*** 865,868 ****
--- 913,943 ----
    ~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
***************
*** 874,879 ****
  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
--- 949,953 ----
  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