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

Tue Oct 11 12:32:19 PDT 2005

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

Modified Files:
	tep102.txt 
Log Message:
Commit outstanding changes that I had sitting in my version of the TEP.
* Expand and clarify the Introduction, now calling it an Overview
* Rename startNow(dt) to start(dt) and start(t0,dt) to startAt(t0,dt)

Index: tep102.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/txt/tep102.txt,v
retrieving revision 1.15
retrieving revision 1.16
diff -C2 -d -r1.15 -r1.16
*** tep102.txt	21 Sep 2005 05:59:28 -0000	1.15
--- tep102.txt	11 Oct 2005 19:32:17 -0000	1.16
***************
*** 32,38 ****

! Introduction
  ====================================================================

  This TEP proposes all timer interfaces be parameterized by
  precision.  All precisions are in "binary" units with respect to one
--- 32,61 ----

! Overview
  ====================================================================

+ This TEP proposes a timer system which supports a set of basic
+ event-driven timing operations for common timing fidelities.
+ 
+ Fidelity is the combination of precision and width.  Examples of
+ precision are millisecond, a cycle of a 32kHz clock, and
+ microseconds.  Examples of widths are 8-bit, 16-bit, 32-bit, and
+ 64-bit.
+ 
+ The most basic behavior on time is to measure it.  This TEP defines
+ "counters" that provide a free running count of time.  "Free
+ running" means that time continues counting even if interrupts are
+ disabled or code enters an atomic section.  This is the standard and
+ expected behavior, and it means that timer code must be constructed
+ specifically with an understanding of any implications from it.
+ 
+ The next most basic behavior on time is to wait.  This TEP defines
+ "alarms" that can fire an event when a *counter* reaches a specified
+ value.  HAL level alarms can only set single events, and this TEP
+ proposes functionality to allow virtualization of a single HAL alarm.
+ 
+ The components proposed by this TEP are constructed to handle
+ overflow of the counters, which is inevitable.
+ 
  This TEP proposes all timer interfaces be parameterized by
  precision.  All precisions are in "binary" units with respect to one
***************
*** 43,65 ****
  * TMicro

! This TEP proposes these timer interfaces:

  * Alarm
  * BusyWait
- * Counter
- * LocalTime
- * Timer

! The LocalTime and Timer interfaces are used primarily by user
! applications and use a fixed width of 32-bits.
! 
! The Alarm, BusyWait, and Counter interfaces are used by the TinyOS
! timer system and advanced user components.  They are parameterized
! by precision and size.  The most common sizes are 16-bit and 32-bit.
  Some platforms will likely use 8-bit for internal implementation,
  and it is expected that some future platforms will use 64-bit.

  A number of platform independent generic components are provided by
! the TinyOS timer system:

  * AlarmToTimerC
--- 66,95 ----
  * TMicro

! These HAL interfaces are proposed:

+ * Counter
  * Alarm
  * BusyWait

! The Counter and Alarm interfaces are fundamental components to be
! implemented by each hardware platform.  A Counter is a free running
! clock, and an Alarm can schedule a single asynchronous event for
! some specified time.  These interfaces are parameterized by
! precision and size.  The most common sizes are 16-bit and 32-bit.
  Some platforms will likely use 8-bit for internal implementation,
  and it is expected that some future platforms will use 64-bit.

+ These of platform dependent HAL components MUST exist:
+ 
+ * Alarm32khzC
+ * AlarmMilliC
+ * BusyWait32khzC
+ * BusyWaitMicroC
+ * Counter32khzC
+ * CounterMilliC
+ 
  A number of platform independent generic components are provided by
! the TinyOS timer system to help derive the full HAL requirements with
! minimal source code:

  * AlarmToTimerC
***************
*** 70,88 ****
  * VirtualizeTimerC

! A number of platform dependent components MUST exist:

! * Alarm32khzC
! * AlarmMilliC
! * BusyWait32khzC
! * BusyWaitMicroC
! * Counter32khzC
! * CounterMilliC
! * TimerMilliC

! It is expected that a platform need only implement in code concise
! Alarm and Counter components expressed in native precision and
! native width.  The platform independent components may use the native
! Alarm's and Counter's to implement the platform dependent timer
! components using only configurations.

--- 100,123 ----
  * VirtualizeTimerC

! It is expected that a platform only needs to directly implement in
! code concise Counter and Alarm components expressed in the
! platform-native precision and width.  It SHOULD be possible to
! implement the remaining timer system by using only configurations and
! platform independent generic timer components.

! These HIL interfaces are proposed:

! * LocalTime
! * Timer
! 
! LocalTime and Timer are HIL versions of Counter and Alarm.
! LocalTime is a simplified version Counter in that it does not expose
! overflow.  Timer can schedule single or periodic synchronous events
! at some specified time.  The LocalTime and Timer interfaces are used
! primarily by user applications and use a fixed width of 32-bits.
! 
! This HAL component MUST also exist:
! 
! * HalTimerMilliC

***************
*** 128,132 ****
  that control the hardware subsystem.  The specifics of these interfaces 
  are dependant on the chip that contains the timer subsystem.  But certain
! guidelines and design paterns can be followed:

    HplTimer<width>   - get/set current time, overflow event, control, init
--- 163,167 ----
  that control the hardware subsystem.  The specifics of these interfaces 
  are dependant on the chip that contains the timer subsystem.  But certain
! design paterns can be followed:

    HplTimer<width>   - get/set current time, overflow event, control, init
***************
*** 200,218 ****

! HAL: Interfaces
  ====================================================================

! This TEP proposes these timer interfaces::

    interface Alarm< precision_tag, size_type >
    interface BusyWait< precision_tag, size_type >
-   interface Counter< precision_tag, size_type >
-   interface LocalTime< precision_tag >
-   interface Timer< precision_tag >
- 
- The LocalTime and Timer interfaces are used primarily by user
- applications and use a fixed width of 32-bits.  The Alarm, BusyWait,
- and Counter interfaces are used by the TinyOS timer system and
- advanced user components.

--- 235,246 ----

! HAL Interfaces
  ====================================================================

! This TEP proposes these HAL timer interfaces::

+   interface Counter< precision_tag, size_type >
    interface Alarm< precision_tag, size_type >
    interface BusyWait< precision_tag, size_type >

***************
*** 265,269 ****
    {
      // basic interface
!     async command void startNow( size_type dt );
      async command void stop();
      async event void fired();
--- 293,297 ----
    {
      // basic interface
!     async command void start( size_type dt );
      async command void stop();
      async event void fired();
***************
*** 271,280 ****
      // extended interface
      async command bool isRunning();
!     async command void start( size_type t0, size_type dt );
      async command size_type getNow();
      async command size_type getAlarm();
    }

! startNow(dt) 
    cancel any previously running alarm and set to fire in dt time units
    from the time of invocation.  The alarm will only fire once then
--- 299,308 ----
      // 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();
    }

! start(dt) 
    cancel any previously running alarm and set to fire in dt time units
    from the time of invocation.  The alarm will only fire once then
***************
*** 291,295 ****
    or has not yet fired.  FALSE is returned otherwise.

! start(t0,dt) 
    cancel any previously running alarm and set to fire at time t1 =
    t0+dt.  This form allows a delay to be anchored to some time t0
--- 319,323 ----
    or has not yet fired.  FALSE is returned otherwise.

! startAt(t0,dt) 
    cancel any previously running alarm and set to fire at time t1 =
    t0+dt.  This form allows a delay to be anchored to some time t0
***************
*** 322,325 ****
--- 350,367 ----

+ HIL Interfaces
+ ====================================================================
+ 
+ This TEP proposes these HIL timer interfaces::
+ 
+   interface LocalTime< precision_tag >
+   interface Timer< precision_tag >
+ 
+ The LocalTime and Timer interfaces are used primarily by user
+ applications and use a fixed width of 32-bits.  The Alarm, BusyWait,
+ and Counter interfaces are used by the TinyOS timer system and
+ advanced user components.
+ 
+ 
  LocalTime
  --------------------------------------------------------------------
***************
*** 350,355 ****
    {
      // basic interface
!     command void startPeriodicNow( uint32_t dt );
!     command void startOneShotNow( uint32_t dt );
      command void stop();
      event void fired();
--- 392,397 ----
    {
      // basic interface
!     command void startPeriodic( uint32_t dt );
!     command void startOneShot( uint32_t dt );
      command void stop();
      event void fired();
***************
*** 358,363 ****
      command bool isRunning();
      command bool isOneShot();
!     command void startPeriodic( uint32_t t0, uint32_t dt );
!     command void startOneShot( uint32_t t0, uint32_t dt );
      command uint32_t getNow();
      command uint32_t gett0();
--- 400,405 ----
      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();
***************
*** 365,374 ****
    }

! startPeriodicNow(dt) 
    cancel any previously running timer and set to fire in dt time units
    from the time of invocation.  The timer will fire periodically every
    dt time units until stopped.

! startOneShotNow(dt) 
    cancel any previously running timer and set to fire in dt time units
    from the time of invocation.  The timer will only fire once then
--- 407,416 ----
    }

! startPeriodic(dt) 
    cancel any previously running timer and set to fire in dt time units
    from the time of invocation.  The timer will fire periodically every
    dt time units until stopped.

! startOneShot(dt) 
    cancel any previously running timer and set to fire in dt time units
    from the time of invocation.  The timer will only fire once then
***************
*** 390,399 ****
    otherwise if the timer is a periodic timer.

! startPeriodic(t0,dt) 
    cancel any previously running timer and set to fire at time t1 =
    t0+dt.  The timer will fire periodically every dt time units until
    stopped.

! startOneShot(t0,dt) 
    cancel any previously running timer and set to fire at time t1 =
    t0+dt.  The timer will fire once then stop.
--- 432,441 ----
    otherwise if the timer is a periodic timer.

! startPeriodicAt(t0,dt) 
    cancel any previously running timer and set to fire at time t1 =
    t0+dt.  The timer will fire periodically every dt time units until
    stopped.

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

! TimerMilliC
  --------------------------------------------------------------------

! TimerMilliC MUST provide Init and Timer<TMilli> as
! TimerMilli[uint8_t num].  TimerMilliC is used by OSKI to implement
! the generic component TimerMilli that allocates a new, virtual timer
! with each instantiation.  ::

!   configuration TimerMilliC
    {
      provides interface Init;
--- 689,701 ----

! HalTimerMilliC
  --------------------------------------------------------------------

! HalTimerMilliC MUST provide Init and Timer<TMilli> as
! TimerMilli[uint8_t num].  HalTimerMilliC is used by OSKI to
! implement the generic component TimerMilliC that allocates a new,
! virtual timer with each instantiation.  ::

!   configuration HalTimerMilliC
    {
      provides interface Init;
***************
*** 766,774 ****

  | Cory Sharp
! | 410 Soda Hall
! | UC Berkeley
! | Berkeley, CA 94720
  |
! | email - cssharp at eecs.berkeley.edu
  |
  | Martin Turon
--- 808,816 ----

  | Cory Sharp
! | Moteiv Corporation
! | 2168 Shattuck Ave
! | Berkeley, CA 94704
  |
! | email - cory at moteiv.com
  |
  | Martin Turon