[Tinyos-beta-commits] CVS: tinyos-1.x/beta/teps/html tep102.html,
1.5, 1.6
Cory Sharp
cssharp at users.sourceforge.net
Wed May 18 04:17:11 PDT 2005
Update of /cvsroot/tinyos/tinyos-1.x/beta/teps/html
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv27118
Modified Files:
tep102.html
Log Message:
Refreshed to be in sync with newly updated TEP 102.
Index: tep102.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/html/tep102.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** tep102.html 24 Mar 2005 21:21:41 -0000 1.5
--- tep102.html 18 May 2005 11:17:09 -0000 1.6
***************
*** 301,307 ****
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">22-Sep-2004</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.5</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2005-02-14</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
--- 301,307 ----
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">22-Sep-2004</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.6</td>
</tr>
! <tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2005-05-18</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
***************
*** 318,323 ****
<div class="section" id="abstract">
<h1><a name="abstract">Abstract</a></h1>
! <p>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).</p>
--- 318,323 ----
<div class="section" id="abstract">
<h1><a name="abstract">Abstract</a></h1>
! <p>This TEP proposes a Timer design that supports common timing
! requirements both in precision and width across common hardware
configurations. This TEP focuses on aligning the Timer abstraction
with the three-layer Hardware Abstraction Architecture (HAA).</p>
***************
*** 325,394 ****
<div class="section" id="introduction">
<h1><a name="introduction">Introduction</a></h1>
! <p>Timer interfaces impact to a number of aspects of the operating
! system:</p>
<ul class="simple">
! <li>Low frequency alarms, synchronous, periodic and oneshot, for
! user/app timers</li>
! <li>High frequency alarms, asynchronous, periodic and oneshot, for adc
! sampling</li>
! <li>Stop watches, timing information</li>
! <li>Local time, time origin</li>
! <li>Time synchronization</li>
</ul>
! <p>Two fundamental properties of timers are <em>precision</em> and <em>resolution</em>.
! 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</p>
<ul class="simple">
! <li>All exposed timer values should be unsigned 32-bit integers (uint32_t)
! regardless of precision</li>
</ul>
! <p>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:</p>
<pre class="literal-block">
typedef struct { } TMilli;
typedef struct { } T32khz;
typedef struct { } TMicro;
- typedef struct { } TNano; //as an example of a future extension
</pre>
! <p>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.</p>
! <p>See TEP 2 for the general background on the HAA.</p>
</div>
! <div class="section" id="quick-summary">
! <h1><a name="quick-summary">Quick Summary</a></h1>
! <p>Five interfaces are presented:</p>
<ul class="simple">
! <li>Counter<frequency_tag></li>
! <li>Alarm<frequency_tag></li>
! <li>Timer<frequency_tag></li>
! <li>TimerAsync<frequency_tag></li>
! <li>Stopwatch<frequency_tag></li>
</ul>
! <p>Low frequency alarms are satisfied by Timer<frequency_tag>, derived from
! one or more Alarm's. TinyOS will provide Timer<TMilli> through the
! standard timer component TimerC.</p>
! <p>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.</p>
! <p>Time elapsed measurements are provided by Stopwatch<frequency_tag>, which
! are derived from a Counter.</p>
! <p>Local time is provided by Counter. The time origin is relative to when
! the mote was booted.</p>
! <p>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.</p>
</div>
<div class="section" id="hardware-differences-between-the-current-platforms">
--- 325,829 ----
<div class="section" id="introduction">
<h1><a name="introduction">Introduction</a></h1>
! <p>This TEP proposes all timer interfaces be parameterized by
! precision. All precisions are in "binary" units with respect to one
! second. Precision is expressed an empty type</p>
<ul class="simple">
! <li>TMilli</li>
! <li>T32khz</li>
! <li>TMicro</li>
</ul>
! <p>This TEP proposes these timer interfaces:</p>
<ul class="simple">
! <li>Alarm</li>
! <li>BusyWait</li>
! <li>Counter</li>
! <li>LocalTime</li>
! <li>Timer</li>
</ul>
! <p>The LocalTime and Timer interfaces are used primarily by user
! applications and use a fixed width of 32-bits.</p>
! <p>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.</p>
! <p>A number of platform independent generic components are provided by
! the TinyOS timer system:</p>
! <ul class="simple">
! <li>AlarmToTimerC</li>
! <li>BusyWaitCounterC</li>
! <li>CounterToLocalTimeC</li>
! <li>TransformAlarmC</li>
! <li>TransformCounterC</li>
! <li>VirtualizeTimerC</li>
! </ul>
! <p>A number of platform dependent components MUST exist:</p>
! <ul class="simple">
! <li>Alarm32khzC</li>
! <li>AlarmMilliC</li>
! <li>BusyWait32khzC</li>
! <li>BusyWaitMicroC</li>
! <li>Counter32khzC</li>
! <li>CounterMilliC</li>
! <li>TimerMilliC</li>
! </ul>
! <p>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.</p>
! </div>
! <div class="section" id="precision-and-width">
! <h1><a name="precision-and-width">Precision and Width</a></h1>
! <p>Two fundamental properties of timers are <em>precision</em> and <em>width</em>.</p>
! <p>Examples of precision are millisecond, a cycle of a 32kHz clock, and
! microseconds. All precisions are in "binary" units with respect to
! one second. That is, one second contains 1024 binary milliseconds,
! 32768 32kHz ticks, or 1048576 microseconds. This TEP emphasizes
! millisecond and 32kHz tick precisions while reasonably accommodating
! other precisions.</p>
! <p>Examples of widths are 8-bit, 16-bit, 32-bit, and 64-bit. The width
! for timer interfaces and components SHOULD be 32-bits. That is, for
! lack of a good reason, timer interfaces should expose a 32-bit
! interface. In a number of circumstances there are good reasons not
! to expose a 32-bit interface. This TEP emphasizes 32-bit widths
! while reasonably accommodating other widths.</p>
! <p>This TEP parameterizes all interfaces by precision and some
! interfaces by width. This intentionally makes similar timer
! interfaces with different precision or width mutually incompatible.
! It also allows user code to clearly express and understand the
! precision and width for a given timer interface.</p>
! <p>Precision is expressed as an empty type -- TMilli, T32khz, and
! TMicro -- written in the standard Timer.h header like this:</p>
<pre class="literal-block">
typedef struct { } TMilli;
typedef struct { } T32khz;
typedef struct { } TMicro;
</pre>
! <p>Note that the precision names are expressed as either frequency or
! period, whichever is convenient.</p>
</div>
! <div class="section" id="interfaces">
! <h1><a name="interfaces">Interfaces</a></h1>
! <p>This TEP proposes these timer interfaces:</p>
! <pre class="literal-block">
! 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 >
! </pre>
! <p>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. by precision and size.</p>
! <div class="section" id="alarm">
! <h2><a name="alarm">Alarm</a></h2>
! <p>All commands and events of the Alarm interface are asynchronous (or
! in "interrupt context"). The Alarm interface provides a set of
! "basic" commands for common usage and provides a set of "extended"
! commands for advanced use.</p>
! <pre class="literal-block">
! interface Alarm<precision_tag,size_type>
! {
! // basic interface
! async command void startNow( size_type dt );
! async command void stop();
! async event void fired();
!
! // 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();
! }
! </pre>
! <dl class="docutils">
! <dt>startNow(dt) </dt>
! <dd>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
! stop.</dd>
! <dt>stop() </dt>
! <dd>cancel any previously running alarm.</dd>
! <dt>fired() </dt>
! <dd>signals that the alarm has occurred.</dd>
! <dt>isRunning() </dt>
! <dd>return TRUE if the alarm has been started and has not been cancelled
! or has not yet fired. FALSE is returned otherwise.</dd>
! <dt>start(t0,dt) </dt>
! <dd>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
! taken before the invocation of start. This is also the form used
! internally in the timer subsystem to allow the use of the full width
! of an alarm while being able to detect if the alarm time for a short
! alarm prematurely elapsed.</dd>
! <dt>getNow() </dt>
! <dd>return the current time in the precision and width of the alarm.</dd>
! <dt>getAlarm() </dt>
! <dd>return the time the currently running alarm will fire or the time
! that the previously running alarm was set to fire.</dd>
! </dl>
! </div>
! <div class="section" id="busywait">
! <h2><a name="busywait">BusyWait</a></h2>
! <p>The BusyWait interface replaces the TOSH_uwait macro from TinyOS
! 1.x.</p>
! <pre class="literal-block">
! interface BusyWait<precision_tag,size_type>
! {
! async command void wait( size_type dt );
! }
! </pre>
! <dl class="docutils">
! <dt>wait(dt)</dt>
! <dd>block for no less than the specified amount of time.</dd>
! </dl>
! </div>
! <div class="section" id="counter">
! <h2><a name="counter">Counter</a></h2>
! <p>The Counter interface returns the current time and provides commands
! and an event for managing overflow conditions. These overflow
! commands and events are necessary for properly deriving larger width
! Counters from smaller widths.</p>
! <pre class="literal-block">
! interface Counter<precision_tag,size_type>
! {
! async command size_type get();
! async command bool isOverflowPending();
! async command void clearOverflow();
! async event void overflow();
! }
! </pre>
! <dl class="docutils">
! <dt>get() </dt>
! <dd>return the current time.</dd>
! <dt>isOverflowPending() </dt>
! <dd>return TRUE if an overflow interrupt will occur after the outermost
! atomic block is exits. FALSE otherwise.</dd>
! <dt>clearOverflow() </dt>
! <dd>cancel the pending overflow interrupt.</dd>
! <dt>overflow() </dt>
! <dd>signals that an overflow in the current time. That is, the current
! time has wrapped around from its maximum value to zero.</dd>
! </dl>
! </div>
! <div class="section" id="localtime">
! <h2><a name="localtime">LocalTime</a></h2>
! <p>The LocalTime interface exposes a 32-bit counter without overflow
! utilities. This is primarily for application code that does not
! care about overflow conditions.</p>
! <pre class="literal-block">
! interface LocalTime<precision_tag>
! {
! async command uint32_t get();
! }
! </pre>
! <dl class="docutils">
! <dt>get() </dt>
! <dd>return the current time.</dd>
! </dl>
! </div>
! <div class="section" id="timer">
! <h2><a name="timer">Timer</a></h2>
! <p>All commands and events of the Timer interface are synchronous (or
! in "task context"). The Timer interface provides a set of "basic"
! commands for common usage and provides a set of "extended" commands
! for advanced use. The Timer interface allows for periodic events.</p>
! <pre class="literal-block">
! interface Timer<precision_tag>
! {
! // basic interface
! command void startPeriodicNow( uint32_t dt );
! command void startOneShotNow( uint32_t dt );
! command void stop();
! event void fired( uint32_t when, uint32_t numMissed );
!
! // extended interface
! 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();
! command uint32_t getdt();
! }
! </pre>
! <dl class="docutils">
! <dt>startPeriodicNow(dt) </dt>
! <dd>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.</dd>
! <dt>startOneShotNow(dt) </dt>
! <dd>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
! stop.</dd>
! <dt>stop() </dt>
! <dd>cancel any previously running timer.</dd>
! <dt>fired(when,numMissed) </dt>
! <dd>signals that the timer has occurred. The when parameter indicates
! when the timer should have fired. Because the timers fire in
! synchronous context, some time may have elapsed from "when" until
! now. For periodic timers, numMissed indicates how many events were
! outright missed and when indicates the time of the most recent
! event. For one-shot timers, numMissed is always 0 and when is the
! time of the event.</dd>
! <dt>isRunning() </dt>
! <dd>return TRUE if the timer has been started and has not been cancelled
! and has not fired for the case of one-shot timers. One a periodic
! timer is started, isRunning will return TRUE until it is cancelled.</dd>
! <dt>isOneShot() </dt>
! <dd>return TRUE if the timer is a one-shot timer. Return FALSE
! otherwise if the timer is a periodic timer.</dd>
! <dt>startPeriodic(t0,dt) </dt>
! <dd>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.</dd>
! <dt>startOneShot(t0,dt) </dt>
! <dd>cancel any previously running timer and set to fire at time t1 =
! t0+dt. The timer will fire once then stop.</dd>
! <dt>getNow() </dt>
! <dd>return the current time in the precision and width of the timer.</dd>
! <dt>gett0() </dt>
! <dd>return the time anchor for the previously started timer or the time
! of the previous event for periodic timers.</dd>
! <dt>getdt() </dt>
! <dd>return the delay or period for the previously started timer.</dd>
! </dl>
! </div>
! </div>
! <div class="section" id="platform-independent-components">
! <h1><a name="platform-independent-components">Platform independent components</a></h1>
! <p>A number of platform independent generic components are provided by
! the TinyOS timer system:</p>
<ul class="simple">
! <li>AlarmToTimerC</li>
! <li>BusyWaitCounterC</li>
! <li>CounterToLocalTimeC</li>
! <li>TransformAlarmC</li>
! <li>TransformCounterC</li>
! <li>VirtualizeTimerC</li>
</ul>
! <p>The platform independent components are used to help derive the
! platform dependent components discussed in the next section.</p>
! <div class="section" id="alarmtotimerc">
! <h2><a name="alarmtotimerc">AlarmToTimerC</a></h2>
! <p>AlarmToTimerC converts a 32-bit Alarm to a Timer.</p>
! <pre class="literal-block">
! generic component AlarmToTimerC( typedef precision_tag )
! {
! provides interface Timer<precision_tag>;
! uses interface Alarm<precision_tag,uint32_t>;
! }
! </pre>
! </div>
! <div class="section" id="busywaitcounterc">
! <h2><a name="busywaitcounterc">BusyWaitCounterC</a></h2>
! <p>BusyWaitCounterC uses a Counter to block until a specified amount of
! time elapses.</p>
! <pre class="literal-block">
! generic component BusyWaitC( typedef precision_tag,
! typedef size_type @integer() )
! {
! provides interface BusyWait<precision_tag,size_type>;
! uses interface Counter<precision_tag,size_type>;
! }
! </pre>
! </div>
! <div class="section" id="countertolocaltimec">
! <h2><a name="countertolocaltimec">CounterToLocalTimeC</a></h2>
! <p>CounterToLocalTimeC converts from a 32-bit Counter to LocalTime.</p>
! <pre class="literal-block">
! generic component CounterToLocalTimeC( precision_tag )
! {
! provides interface LocalTime<precision_tag>;
! uses interface Counter<precision_tag,uint32_t>;
! }
! </pre>
! </div>
! <div class="section" id="transformalarmc">
! <h2><a name="transformalarmc">TransformAlarmC</a></h2>
! <p>TransformAlarmC decreases precision and/or widens an Alarm. An
! already widened Counter component is used to help.</p>
! <pre class="literal-block">
! 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;
! }
! </pre>
! <p>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.</p>
! <p>For instance to convert from an Alarm<T32khz,uint16_t> to an
! Alarm<TMilli,uint32_t>, the following TransformAlarmC would be
! created:</p>
! <pre class="literal-block">
! new TransformAlarmC( TMilli, uint32_t, T32khz, uint16_t, 5 )
! </pre>
! </div>
! <div class="section" id="transformcounterc">
! <h2><a name="transformcounterc">TransformCounterC</a></h2>
! <p>TransformCounterC decreases precision and/or widens a Counter.</p>
! <pre class="literal-block">
! 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;
! }
! </pre>
! <p>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
! 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
! 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.</p>
! <p>For instance to convert from a Counter<T32khz,uint16_t> to a
! Counter<TMilli,uint32_t>, the following TransformCounterC would be
! created:</p>
! <pre class="literal-block">
! new TransformCounterC( TMilli, uint32_t, T32khz, uint16_t, 5, uint32_t )
! </pre>
! </div>
! <div class="section" id="virtualizetimerc">
! <h2><a name="virtualizetimerc">VirtualizeTimerC</a></h2>
! <p>VirtualizeTimerC uses a single Timer to create up to 255 virtual
! timers.</p>
! <pre class="literal-block">
! 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;
! }
! </pre>
! </div>
! </div>
! <div class="section" id="platform-dependent-components">
! <h1><a name="platform-dependent-components">Platform dependent components</a></h1>
! <p>A number of platform dependent components MUST exist:</p>
! <ul class="simple">
! <li>Alarm32khzC</li>
! <li>AlarmMilliC</li>
! <li>BusyWait32khzC</li>
! <li>BusyWaitMicroC</li>
! <li>Counter32khzC</li>
! <li>CounterMilliC</li>
! <li>TimerMilliC</li>
! </ul>
! <div class="section" id="alarm32khzc">
! <h2><a name="alarm32khzc">Alarm32khzC</a></h2>
! <p>Alarm32khzC MUST provide Init and Alarm<T32khz,uint32_t> as
! Alarm32khz32. The configuration MAY provide additional
! hardware-specific Alarm interfaces. Alarm32khzC is a generic
! component. Each instantiation allocates a new, distinct Alarm.
! Each instance of an Alarm32khzC MAY directly map to a hardware
! timer.</p>
! <pre class="literal-block">
! generic configuration Alarm32khzC()
! {
! provides interface Init;
! provides interface Alarm<T32khz,uint16_t> as Alarm32khz16;
! provides interface Alarm<T32khz,uint32_t> as Alarm32khz32;
! }
! </pre>
! </div>
! <div class="section" id="alarmmillic">
! <h2><a name="alarmmillic">AlarmMilliC</a></h2>
! <p>AlarmMilliC MUST provide Init and Alarm<TMilli,uint32_t> as
! AlarmMilli32. The configuration MAY provide additional
! hardware-specific Alarm interfaces. AlarmMilliC is a generic
! component. Each instantiation allocates a new, distinct Alarm.
! Each instance of an AlarmMilliC MAY directly map to a hardware
! timer.</p>
! <pre class="literal-block">
! generic configuration AlarmMilliC()
! {
! provides interface Init;
! provides interface Alarm<TMilli,uint32_t> as AlarmMilli32;
! }
! </pre>
! </div>
! <div class="section" id="busywait32khzc">
! <h2><a name="busywait32khzc">BusyWait32khzC</a></h2>
! <p>BusyWait32khzC MUST provide BusyWait<T32khz,uint16_t> as
! BusyWait32khz16. The configuration MAY provide additional
! hardware-specific BusyWait interfaces.</p>
! <pre class="literal-block">
! configuration BusyWait32khzC
! {
! provides interface BusyWait<T32khz,uint16_t> as BusyWait32khz16;
! }
! </pre>
! </div>
! <div class="section" id="busywaitmicroc">
! <h2><a name="busywaitmicroc">BusyWaitMicroC</a></h2>
! <p>BusyWaitMicroC MUST provide BusyWait<TMicro,uint16_t> as
! BusyWaitMicro16. The configuration MAY provide additional
! hardware-specific BusyWait interfaces.</p>
! <pre class="literal-block">
! configuration BusyWaitMicroC
! {
! provides interface BusyWait<TMicro,uint16_t> as BusyWaitMicro16;
! }
! </pre>
! </div>
! <div class="section" id="counter32khzc">
! <h2><a name="counter32khzc">Counter32khzC</a></h2>
! <p>Counter32khz MUST provide Counter<T32khz,uint32_t> as Counter32khz32
! and LocalTime<T32khz> as LocalTime32khz. The configuration MAY
! provide additional hardware-specific Counter interfaces.</p>
! <pre class="literal-block">
! configuration Counter32khzC
! {
! provides interface Counter<T32khz,uint32_t> as Counter32khz32;
! provides interface LocalTime<T32khz> as LocalTime32khz;
! }
! </pre>
! </div>
! <div class="section" id="countermillic">
! <h2><a name="countermillic">CounterMilliC</a></h2>
! <p>CounterMilli MUST provide Counter<TMilli,uint32_t> as CounterMilli32
! and LocalTime<TMilli> as LocalTimeMilli. The configuration MAY
! provide additional hardware-specific Counter interfaces.</p>
! <pre class="literal-block">
! configuration CounterMilliC
! {
! provides interface Counter<TMilli,uint32_t> as CounterMilli32;
! provides interface LocalTime<TMilli> as LocalTimeMilli;
! }
! </pre>
! </div>
! <div class="section" id="timermillic">
! <h2><a name="timermillic">TimerMilliC</a></h2>
! <p>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.</p>
! <pre class="literal-block">
! configuration TimerMilliC
! {
! provides interface Init;
! provides interface Timer<TMilli> as TimerMilli[ uint8_t num ];
! }
! </pre>
! </div>
</div>
<div class="section" id="hardware-differences-between-the-current-platforms">
***************
*** 440,692 ****
</blockquote>
</div>
! <div class="section" id="hardware-presentation-layer-hpl">
! <h1><a name="hardware-presentation-layer-hpl">Hardware Presentation Layer (HPL)</a></h1>
! <blockquote>
! <ol class="loweralpha simple">
! <li>Implementatin: Hardware-level</li>
! <li>Presentation: System dependent</li>
! <li>Stateless</li>
! <li>Expose common hardware resources via common interfaces</li>
! </ol>
! <blockquote>
! <ol class="lowerroman simple">
! <li>Timers</li>
! <li>Compares</li>
! <li>This allows HAL's to switch between hardware resources with only
! a wiring change</li>
! </ol>
! </blockquote>
! <ol class="loweralpha simple" start="5">
! <li>See for instance under tos/platform/msp430/</li>
! </ol>
! <blockquote>
! <ol class="lowerroman simple">
! <li>MSP430Timer, MSP430TimerControl, MSP430Compare, MSP430Capture</li>
! <li>MSP430TimerC, MSP430TimerM</li>
! </ol>
! </blockquote>
! </blockquote>
! </div>
! <div class="section" id="hardware-adaptation-layer-hal">
! <h1><a name="hardware-adaptation-layer-hal">Hardware Adaptation Layer (HAL)</a></h1>
! <blockquote>
! <ol class="loweralpha simple">
! <li>Implementaiton: System dependent</li>
! <li>Presentation: System independent</li>
! <li>Async</li>
! <li>Counter<frequency_tag></li>
! </ol>
! <blockquote>
! <ol class="lowerroman simple">
! <li>Get current time as a uint32_t in whatever units are specified by
! the interface tag frequency_tag</li>
! <li>Manage overflows</li>
! </ol>
! <blockquote>
<ul class="simple">
! <li>Allows for properly deriving higher resolution counters</li>
</ul>
! </blockquote>
! <ol class="lowerroman" start="3">
! <li><p class="first">Interface:</p>
! <pre class="literal-block">
! interface Counter<frequency_tag>
! {
! async command uint32_t get();
! async command bool isOverflowPending();
! async command bool clearOverflow();
! async event void overflow();
! }
! </pre>
! </li>
! </ol>
! </blockquote>
! <ol class="loweralpha simple" start="5">
! <li>Alarm<frequency_tag></li>
! </ol>
! <blockquote>
! <ol class="lowerroman simple">
! <li>Manages a single alarm</li>
! <li>Set is special, sets alarm delta from explicit t0 not implicit "now"</li>
! </ol>
! <blockquote>
<ul class="simple">
! <li>Avoids race condition from setting short alarms in absolute time</li>
! <li>Allows for precise periodic timers, no alarm time slip</li>
</ul>
- </blockquote>
- <ol class="lowerroman" start="3">
- <li><p class="first">The time base of an Alarm must correspond to an appropriate Counter</p>
- </li>
- <li><p class="first">Interface:</p>
- <pre class="literal-block">
- 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();
- }
- </pre>
- </li>
- </ol>
- <p>v. The AlarmC configuration exposes a distinct set of alarms
- <em>required</em> 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.</p>
- <pre class="literal-block">
- 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;
- //...
- }
- </pre>
- </blockquote>
- <p>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:</p>
- <pre class="literal-block">
- 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;
- }
- </pre>
- </blockquote>
- </div>
- <div class="section" id="hardware-interface-layer-hil">
- <h1><a name="hardware-interface-layer-hil">Hardware Interface Layer (HIL)</a></h1>
- <blockquote>
- <ol class="loweralpha simple">
- <li>Implementation: System independent</li>
- <li>Presentation: OS service</li>
- <li>Timer interface</li>
- </ol>
- <blockquote>
- <ol class="lowerroman">
- <li><p class="first">Synchronous</p>
- </li>
- <li><p class="first">Parameterized by time precision</p>
- </li>
- <li><p class="first">Provides periodic and one shot timers</p>
- </li>
- <li><p class="first">May have moderate computational overhead, probably all Timers for
- a given timer precision are multiplexed from a single hardware
- resource</p>
- </li>
- <li><p class="first">Interface:</p>
- <pre class="literal-block">
- 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 void fired();
- }
- </pre>
- </li>
- </ol>
- </blockquote>
- <ol class="loweralpha simple" start="4">
- <li>TimerAsync interface</li>
- </ol>
- <blockquote>
- <ol class="lowerroman">
- <li><p class="first">Asynchronous</p>
- </li>
- <li><p class="first">Parameterized by time precision</p>
- </li>
- <li><p class="first">Provides periodic and one shot timers</p>
- </li>
- <li><p class="first">Should have minimal computational overhead, probably each
- TimerAsync is based on a single hardware resource</p>
- </li>
- <li><p class="first">Interface:</p>
- <pre class="literal-block">
- 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 void fired();
- }
- </pre>
- </li>
- </ol>
- </blockquote>
- <ol class="loweralpha simple" start="5">
- <li>Stopwatch interface</li>
- </ol>
- <blockquote>
- <ol class="lowerroman">
- <li><p class="first">Asynchronous</p>
- </li>
- <li><p class="first">Parameterized by time precision</p>
- </li>
- <li><p class="first">Provides elapsed time readings from a specified start</p>
- </li>
- <li><p class="first">Indicates if an overflow occurred for the returned value</p>
- </li>
- <li><p class="first">Stopwatches only depend on measurements from an appropriate
- Counter.</p>
- </li>
- <li><p class="first">Interface:</p>
- <pre class="literal-block">
- 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();
- }
- </pre>
- </li>
- </ol>
- </blockquote>
- </blockquote>
</div>
! <div class="section" id="implementation">
! <h1><a name="implementation">Implementation</a></h1>
! <p>See the tinyos-2.x/tos/ tree. Interfaces are in interfaces/ and
! implementations are in platforms/ or chips/.</p>
</div>
<div class="section" id="author-s-address">
--- 875,905 ----
</blockquote>
</div>
! <div class="section" id="implementation">
! <h1><a name="implementation">Implementation</a></h1>
! <p>For platform independent headers, interfaces, and components, see</p>
<ul class="simple">
! <li>tinyos-2.x/tos/lib/timer/</li>
</ul>
! <p>For platform dependent implementations, see specific chip
! directories, such as</p>
<ul class="simple">
! <li>tinyos-2.x/tos/chips/msp430/timer/</li>
! <li>tinyos-2.x/tos/chips/ATmega128/timer/</li>
! <li>tinyos-2.x/tos/chips/pxa27a/timer/</li>
</ul>
</div>
! <div class="section" id="hints">
! <h1><a name="hints">Hints</a></h1>
! <p>In implementing Alarm32khzC.nc and AlarmMilliC.nc for the MSP430 in
! tinyos-2.x/tos/chips/msp430/timer/, see MSP430Timer32khzC.nc and
! MSP430Timer32khzMapC.nc for an example of how a set of similar
! hardware resources can be exposed through a parameterized interface
! for compile-time allocation. See how Alarm32khzC.nc and
! AlarmMilliC.nc call new MSP430Timer32khzC() to allocate a new,
! arbitrary hardware timer. Using this methodology, specific
! platforms can override MSP430Timer32khzMapC.nc to remove statically
! allocated hardware timers from the set available for compile-time
! allocation, such as the Telos platform in
! tinyos-2.x/tos/platform/telosa.</p>
</div>
<div class="section" id="author-s-address">
More information about the Tinyos-beta-commits
mailing list