dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
<tr class="field"><th class="docinfo-name">Type:</th><td class="field-body">Documentary</td>
</tr>
<tr><th class="docinfo-name">Status:</th>
-<td>Draft</td></tr>
+<td>Final</td></tr>
<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">2.x</td>
</tr>
<tr><th class="docinfo-name">Author:</th>
<td>Cory Sharp, Martin Turon, David Gay</td></tr>
-<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.3</td>
-</tr>
-<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-09-06</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>
-</tr>
</tbody>
</table>
<div class="note">
discussion of the issues of precision, width and accuracy in
timer interfaces (2.1).</p>
<div class="section">
-<h2><a id="precision-width-and-accuracy" name="precision-width-and-accuracy">2.1 Precision, Width and Accuracy.</a></h2>
+<h2><a id="precision-width-and-accuracy" name="precision-width-and-accuracy">2.1 Precision, Width and Accuracy</a></h2>
<p>Three fundamental properties of timers are <em>precision</em>, <em>width</em> and
<em>accuracy</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>
+microseconds. All precisions presented in this TEP 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. The use of "binary" units
+is motivated by the common availability of hardware clocks driven
+by a 32768Hz crystal.</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>
+for timer interfaces and components SHOULD be 32-bits. This TEP
+emphasizes 32-bit widths while reasonably accommodating other widths -
+a particular platform may have good reasons not to expose a 32-bit
+interface.</p>
<p>Accuracy reflects how closely a component conforms to the precision it
claims to provide. Accuracy is affected by issues such as clock drift (much
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
+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
appropriate documentation. However, the accuracy MUST remain reasonable:
It also allows user code to clearly express and understand the
precision and width for a given timer interface. Accuracy is not
reflected in the interface type.</p>
-<p>Precision is expressed as an empty type -- TMilli, T32khz, and
+<p>Precision is expressed as a dummy 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;
+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
</pre>
<p>Note that the precision names are expressed as either frequency or
period, whichever is convenient.</p>
</div>
<div class="section">
<h2><a id="counter" name="counter">Counter</a></h2>
-<p>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
+<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>
<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>
+<dd>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.</dd>
<dt>clearOverflow()</dt>
-<dd>cancel the pending overflow interrupt.</dd>
+<dd>cancel the pending overflow event clearing the overflow flag.</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>
<div class="section">
<h2><a id="alarm" name="alarm">Alarm</a></h2>
<p>Alarm components are extensions of Counters that signal an event
-when their Compare register detects the alarm time has been hit.
+when their compare register detects the alarm time has been hit.
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"
<dt>stop()</dt>
<dd>cancel any previously running alarm.</dd>
<dt>fired()</dt>
-<dd>signals that the alarm has occurred.</dd>
+<dd>signals that the alarm has expired.</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>startAt(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>
+</dl>
+<p>startAt(t0,dt)</p>
+<blockquote>
+<p>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 startAt. The timer subsystem uses this form
+internally, to be able to use of the full width of an alarm while also
+detecting when a short alarm elapses prematurely.</p>
+<p>The time <tt class="docutils literal"><span class="pre">t0</span></tt> is always assumed to be in the past. A value of <tt class="docutils literal"><span class="pre">t0</span></tt>
+numerically greater than the current time (returned by <tt class="docutils literal"><span class="pre">getNow()</span></tt>)
+represents a time from before the last wraparound.</p>
+</blockquote>
+<dl class="docutils">
<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>
+that the previously running alarm was set to fire. getAlarm can
+be used with startAt to set an alarm from the previous alarm time,
+as in startAt(getAlarm(),dt). This pattern is used within the
+fired() event to construct periodic alarms.</dd>
</dl>
</div>
<div class="section">
<h2><a id="busywait" name="busywait">BusyWait</a></h2>
-<p>The BusyWait interface replaces the TOSH_uwait macro from TinyOS
-1.x.</p>
+<p>The BusyWait interface allows for very short synchronous delays.
+BusyWait should be used sparingly and when an Alarm would not be
+reasonably efficient or accurate. The BusyWait interface replaces
+the TOSH_uwait macro from TinyOS 1.x.</p>
+<p>BusyWait blocks for no less than the specified amount of time. No
+explicit upper bound is imposed on the enacted delay, though it is
+expected that the underlying implementation spins in a busy loop until
+the specified amount of time has elapsed.</p>
<pre class="literal-block">
interface BusyWait<precision_tag,size_type>
{
</pre>
<dl class="docutils">
<dt>wait(dt)</dt>
-<dd>block for no less than the specified amount of time.</dd>
+<dd>block until at least dt time units have elapsed</dd>
</dl>
</div>
<div class="section">
<dt>stop()</dt>
<dd>cancel any previously running timer.</dd>
<dt>fired()</dt>
-<dd>signals that the timer has occurred.</dd>
+<dd>signals that the timer has expired (one-shot) or repeated (periodic).</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
+and has not fired for the case of one-shot timers. Once 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>startPeriodicAt(t0,dt)</dt>
-<dd>cancel any previously running timer and set to fire at time t1 =
+<dd><p class="first">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>
+stopped.</p>
+<p class="last">As with alarms, the time <tt class="docutils literal"><span class="pre">t0</span></tt> is always assumed to be in the past. A
+value of <tt class="docutils literal"><span class="pre">t0</span></tt> numerically greater than the current time (returned by
+<tt class="docutils literal"><span class="pre">getNow()</span></tt>) represents a time from before the last wraparound.</p>
+</dd>
<dt>startOneShotAt(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>
+<dd><p class="first">cancel any previously running timer and set to fire at time t1 =
+t0+dt. The timer will fire once then stop.</p>
+<p class="last"><tt class="docutils literal"><span class="pre">t0</span></tt> is as in <tt class="docutils literal"><span class="pre">startPeriodicAt</span></tt>.</p>
+</dd>
<dt>getNow()</dt>
<dd>return the current time in the precision and width of the timer.</dd>
<dt>gett0()</dt>
</div>
<div class="section">
<h1><a id="hal-guidelines" name="hal-guidelines">3. HAL guidelines</a></h1>
-<p>Platforms typically select a clocking option for each of their
-hardware counters, based on their hardware design (e.g., the mica
-family of motes all run their hardware timer 0 at 32kHz, and the micaz
-mote runs its timer 1 at cpu frequency/256). Platforms SHOULD expose
-the timing functionality of these timers using the Alarm and Counter
-interfaces, in the fashion described below. Platforms MAY expose the
-same hardware timer with different frequencies - use of conflicting
-frequences in the same program SHOULD produce compile-time
-errors.</p>
-<p>A hardware timer with precision <em>P</em> and width <em>W</em> SHOULD be exposed as a
-several components:</p>
+<p>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.</p>
+<p>A platform specific hardware timer with precision ${P} and width
+${W} SHOULD be exposed as these two conventional Counter and Alarm
+components:</p>
<pre class="literal-block">
-configuration CounterPWC {
- provides interface Counter<TP, uintW_t>;
-} ...
-generic configuration AlarmPWC {
- provides interface Alarm<TP,uintW_t>;
-} ...
+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 >;
+}
</pre>
-<p>and, except if <em>W</em> is 32:</p>
+<p>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.</p>
+<p>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:</p>
<pre class="literal-block">
-configuration CounterP32C {
- provides interface Counter<TP, uint32_t>;
-} ...
-generic configuration AlarmP32C {
- provides interface Alarm<TP,uint32_t>;
-} ...
+configuration Counter32khz8C
+{
+ provides interface Counter< T32khz, uint8_t >;
+}
+
+generic configuration Alarm32khz8C()
+{
+ provides interface Alarm< T32khz, uint8_t >;
+}
</pre>
-<p>Instantiating the Alarm... components provides a new Alarm independent
-of all prior instantiations. Instantiating such a component "consumes"
-a compare register from the corresponding hardware timer; when no more
-compare registers are available, instantiation SHOULD produce a
-compile-time error (see Appendix B for an example of how to achieve
-this).</p>
-<p>For example, the micaz platform includes an AlarmMilli8C and
-AlarmMilli32C components for timer 0 (one instantiation allowed), and
-Alarm32kHz16C and Alarm32kHz32C for timer 1 (three instantiations
-allowed).</p>
+<p>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.</p>
</div>
<div class="section">
<h1><a id="hil-requirements" name="hil-requirements">4. HIL requirements</a></h1>
-<dl class="docutils">
-<dt>The following component MUST be provided on all platforms::</dt>
-<dd>TimerMilliC
-BusyWaitMicroC</dd>
-</dl>
+<p>The following component MUST be provided on all platforms</p>
+<pre class="literal-block">
+HilTimerMilliC
+BusyWaitMicroC
+</pre>
+<p>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.</p>
<div class="section">
-<h2><a id="timermillic" name="timermillic">TimerMilliC</a></h2>
+<h2><a id="hiltimermillic" name="hiltimermillic">HilTimerMilliC</a></h2>
<pre class="literal-block">
-#define TIMERMILLIC_SERVICE ...
-configuration TimerMilliC
+configuration HilTimerMilliC
{
provides interface Init;
- provides interface Timer<TMilli>[uint8_t num];
+ provides interface Timer<TMilli> as TimerMilli[ uint8_t num ];
provides interface LocalTime<TMilli>;
}
</pre>
-<p>A timer is allocated using unique(TIMERMILLIC_SERVICE) to obtain a new
-unique timer number. This timer number is used to index the TimerMilli
-parameterised interface.</p>
+<p>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 <tt class="docutils literal"><span class="pre">tos/system/</span></tt></p>
</div>
<div class="section">
<h2><a id="busywaitmicroc" name="busywaitmicroc">BusyWaitMicroC</a></h2>
}
</pre>
<p>BusyWaitMicroC allows applications to busy-wait for a number of
-microseconds. It's use should be restricted to situations where the
+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.</p>
</div>
<pre class="literal-block">
new TransformAlarmC( TMilli, uint32_t, T32khz, uint16_t, 5 )
</pre>
+<p>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.</p>
</div>
<div class="section">
<h2><a id="transformcounterc" name="transformcounterc">TransformCounterC</a></h2>
<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
+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
</div>
</div>
<div class="section">
-<h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
+<h1><a id="implementation" name="implementation">6. Implementation</a></h1>
+<p>The definition of the HIL interfaces are found in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/timer</span></tt>:</p>
+<blockquote>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">Alarm.nc</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">BusyWait.nc</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">Counter.nc</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">LocalTime.nc</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">Timer.h</span></tt> defines precision tags and strings for unique()</li>
+<li><tt class="docutils literal"><span class="pre">Timer.nc</span></tt></li>
+</ul>
+</blockquote>
+<p>The implementation of the utility components are also found in
+<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/lib/timer</span></tt>:</p>
+<blockquote>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">AlarmToTimerC.nc</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">BusyWaitCounterC.nc</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">CounterToLocalTimeC.nc</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">TransformAlarmC.nc</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">TransformCounterC.nc</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">VirtualizeAlarmC.nc</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">VirtualizeTimerC.nc</span></tt></li>
+</ul>
+</blockquote>
+<p>The implementation of timers for the MSP430 is in
+<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/msp430/timer</span></tt>:</p>
+<blockquote>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">Alarm32khz16C.nc</span></tt> is generic and provides a new <tt class="docutils literal"><span class="pre">Alarm<T32khz,uint16_t></span></tt></li>
+<li><tt class="docutils literal"><span class="pre">Alarm32khz32C.nc</span></tt> is generic and provides a new <tt class="docutils literal"><span class="pre">Alarm<T32khz,uint32_t></span></tt></li>
+<li><tt class="docutils literal"><span class="pre">AlarmMilli16C.nc</span></tt> is generic and provides a new <tt class="docutils literal"><span class="pre">Alarm<TMilli,uint16_t></span></tt></li>
+<li><tt class="docutils literal"><span class="pre">AlarmMilli32C.nc</span></tt> is generic and provides a new <tt class="docutils literal"><span class="pre">Alarm<TMilli,uint32_t></span></tt></li>
+<li><tt class="docutils literal"><span class="pre">BusyWait32khzC.nc</span></tt> provides <tt class="docutils literal"><span class="pre">BusyWait<T32khz,uint16_t></span></tt></li>
+<li><tt class="docutils literal"><span class="pre">BusyWaitMicroC.nc</span></tt> provides <tt class="docutils literal"><span class="pre">BusyWait<TMicro,uint16_t></span></tt></li>
+<li><tt class="docutils literal"><span class="pre">Counter32khz16C.nc</span></tt> provides <tt class="docutils literal"><span class="pre">Counter<T32khz,uint16_t></span></tt></li>
+<li><tt class="docutils literal"><span class="pre">Counter32khz32C.nc</span></tt> provides <tt class="docutils literal"><span class="pre">Counter<T32khz,uint32_t></span></tt></li>
+<li><tt class="docutils literal"><span class="pre">CounterMilli16C.nc</span></tt> provides <tt class="docutils literal"><span class="pre">Counter<TMilli,uint16_t></span></tt></li>
+<li><tt class="docutils literal"><span class="pre">CounterMilli32C.nc</span></tt> provides <tt class="docutils literal"><span class="pre">Counter<TMilli,uint32_t></span></tt></li>
+<li><tt class="docutils literal"><span class="pre">GpioCaptureC.nc</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">HilTimerMilliC.nc</span></tt> provides <tt class="docutils literal"><span class="pre">LocalTime<TMilli></span></tt> and
+<tt class="docutils literal"><span class="pre">Timer<TMilli></span> <span class="pre">as</span> <span class="pre">TimerMilli[uint8_t</span> <span class="pre">num]</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">Msp430AlarmC.nc</span></tt> is generic and converts an MSP430 timer to a 16-bit Alarm</li>
+<li><tt class="docutils literal"><span class="pre">Msp430Capture.nc</span></tt> HPL interface definition for MSP430 timer captures</li>
+<li><tt class="docutils literal"><span class="pre">Msp430ClockC.nc</span></tt> exposes MSP430 hardware clock initialization</li>
+<li><tt class="docutils literal"><span class="pre">Msp430ClockInit.nc</span></tt> HPL interface definition for hardware clock initialization</li>
+<li><tt class="docutils literal"><span class="pre">Msp430ClockP.nc</span></tt> implements MSP430 hardware clock initialization and
+calibration and startup</li>
+<li><tt class="docutils literal"><span class="pre">Msp430Compare.nc</span></tt> HPL interface definition for MSP430 timer compares</li>
+<li><tt class="docutils literal"><span class="pre">Msp430Counter32khzC.nc</span></tt> provides <tt class="docutils literal"><span class="pre">Counter<T32khz,uint16_t></span></tt> based on
+MSP430 TimerB</li>
+<li><tt class="docutils literal"><span class="pre">Msp430CounterC.nc</span></tt> is generic and converts an Msp430Timer to a Counter</li>
+<li><tt class="docutils literal"><span class="pre">Msp430CounterMicroC.nc</span></tt> provides <tt class="docutils literal"><span class="pre">Counter<TMicro,uint16_t></span></tt> based on
+MSP430 TimerA</li>
+<li><tt class="docutils literal"><span class="pre">Msp430Timer.h</span></tt> defines additional MSP430 timer bitmasks and structs</li>
+<li><tt class="docutils literal"><span class="pre">Msp430Timer.nc</span></tt> HPL interface definition</li>
+<li><tt class="docutils literal"><span class="pre">Msp430Timer32khzC.nc</span></tt> is generic and allocates a new 32khz hardware timer</li>
+<li><tt class="docutils literal"><span class="pre">Msp430Timer32khzMapC.nc</span></tt> exposes the MSP430 hardware timers as a
+parameterized interface allocatable using Msp430Timer32khzC</li>
+<li><tt class="docutils literal"><span class="pre">Msp430TimerC.nc</span></tt> exposes the MSP430 hardware timers</li>
+<li><tt class="docutils literal"><span class="pre">Msp430TimerCapComP.nc</span></tt> is generic and implements the HPL for MSP430
+capture/compare special function registers</li>
+<li><tt class="docutils literal"><span class="pre">Msp430TimerCommonP.nc</span></tt> maps the MSP430 timer interrupts to Msp430TimerEvents</li>
+<li><tt class="docutils literal"><span class="pre">Msp430TimerControl.nc</span></tt> HPL interface definition</li>
+<li><tt class="docutils literal"><span class="pre">Msp430TimerEvent.nc</span></tt> HPL interface definition</li>
+<li><tt class="docutils literal"><span class="pre">Msp430TimerP.nc</span></tt> is generic and implements the HPL for MSP430 timer
+special function registers</li>
+</ul>
+</blockquote>
+<p>Implementation of timers for the ATmega128 and PXA27x may be found in
+<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/atm128/timer</span></tt> and
+<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/pxa27x/timer</span></tt> respectively.</p>
+</div>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">7. Author's Address</a></h1>
<div class="line-block">
<div class="line">Cory Sharp</div>
<div class="line">Moteiv Corporation</div>
<div class="line">55 Hawthorne St, Suite 550</div>
<div class="line">San Francisco, CA 94105</div>
<div class="line"><br /></div>
+<div class="line">phone - +1 415 692 0963</div>
<div class="line">email - <a class="reference" href="mailto:cory@moteiv.com">cory@moteiv.com</a></div>
<div class="line"><br /></div>
<div class="line"><br /></div>
async command void setEdge(bool up); //<! True = detect rising edge
}
</pre>
-<p>These interfaces are provided by four components, corresponding to
-each hardware timer: HplAtm128Timer0C through HplAtm128Timer3C.</p>
+<p>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:</p>
+<pre class="literal-block">
+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];
+ }
+}
+...
+</pre>
+<p>where the <tt class="docutils literal"><span class="pre">id</span></tt> corresponds to the compare register number. The parameterised
+interface is only connected for <tt class="docutils literal"><span class="pre">id</span></tt> 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 <tt class="docutils literal"><span class="pre">HplAtm128Timer1C</span></tt>)</p>
+<pre class="literal-block">
+Compare[0] = HplAtm128Timer1P.CompareA;
+Compare[1] = HplAtm128Timer1P.CompareB;
+Compare[2] = HplAtm128Timer1P.CompareC;
+</pre>
<p>The Atmega128 chip components do not define a HAL, as the timer
configuration choices (frequencies, use of input capture or compare output,
etc) are platform-specific. Instead, it provides a few generic components
uses interface HplTimer<timer_size> as Timer;
} ...
</pre>
+<p>As a result of issues arising from using timer 0 in asynchronous mode,
+the HAL also offers the following component:</p>
+<pre class="literal-block">
+generic configuration Atm128AlarmAsyncC(typedef precision, int divider) {
+ provides {
+ interface Init @atleastonce();
+ interface Alarm<precision, uint32_t>;
+ interface Counter<precision, uint32_t>;
+ }
+}
+...
+</pre>
+<p>which builds a 32-bit alarm and timer over timer 0. divider is used
+to initialise the timer0 scaling factor.</p>
</div>
<div class="section">
<h1><a id="appendix-c-a-mote-mica-family-timer-subsystem" name="appendix-c-a-mote-mica-family-timer-subsystem">Appendix C: a mote: Mica family timer subsystem</a></h1>
<p>The mica family configures its four timers in part based on the value
of this MHZ symbol:</p>
<ul>
-<li><p class="first">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.</p>
+<li><p class="first">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.</p>
+<p>Timing accuracy is as good as the external crystal.</p>
</li>
<li><p class="first">Timer 1: the 16-bit hardware timer 1 is set to run at 1MHz if possible.
However, the set of dividers for timer 1 is limited to 1, 8,
HAL components exposing timer 1 are named <tt class="docutils literal"><span class="pre">CounterOne16C</span></tt> and
<tt class="docutils literal"><span class="pre">AlarmOne16C</span></tt> (rather than the <tt class="docutils literal"><span class="pre">CounterMicro16C</span></tt> <tt class="docutils literal"><span class="pre">AlarmMicro16C</span></tt>
as suggested in Section 3).</p>
-<p>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 <em>are</em> named <tt class="docutils literal"><span class="pre">CounterMicro32C</span></tt> and <tt class="docutils literal"><span class="pre">AlarmMicro32C</span></tt>.</p>
+<p>32-bit microsecond Counters and Alarms, named <tt class="docutils literal"><span class="pre">CounterMicro32C</span></tt> and
+<tt class="docutils literal"><span class="pre">AlarmMicro32C</span></tt>, are created from <tt class="docutils literal"><span class="pre">CounterOne16C</span></tt> and
+<tt class="docutils literal"><span class="pre">AlarmOne16C</span></tt> using the TransformAlarmC and TransformCounterC
+utility components.</p>
<p>Three compare registers are available on timer1, so up to three instances
of <tt class="docutils literal"><span class="pre">AlarmOne16C</span></tt> and/or <tt class="docutils literal"><span class="pre">AlarmMicro32C</span></tt> can be created. The timing
accuracy depends on how the mote is clocked:</p>
32768Hz, if possible. As with timer 1, the limited set of dividers makes
this impossible at some clock frequencies, so the 16-bit timer 3 HAL
components are named <tt class="docutils literal"><span class="pre">CounterThree16C</span></tt> and <tt class="docutils literal"><span class="pre">AlarmThree16C</span></tt>. 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
+with timer 1, the rate of timer 3 is adjusted in software to
+build 32-bit counter and 32-bit alarms, giving components
<tt class="docutils literal"><span class="pre">Counter32khz32C</span></tt> and <tt class="docutils literal"><span class="pre">Alarm32khz32C</span></tt>. As with timer 1, three compare
registers, hence up to three instances of <tt class="docutils literal"><span class="pre">Alarm32khz32C</span></tt> and/or
<tt class="docutils literal"><span class="pre">AlarmThree16C</span></tt> are available.</p>
~28.8kHz.</p>
</li>
</ul>
+<p>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 <tt class="docutils literal"><span class="pre">AlarmOne16C</span></tt>
+and <tt class="docutils literal"><span class="pre">AlarmThree16C</span></tt> use the <tt class="docutils literal"><span class="pre">Atm128AlarmC</span></tt> generic component and
+wire it, using <tt class="docutils literal"><span class="pre">unique</span></tt>, to one of the compare registers offered by
+<tt class="docutils literal"><span class="pre">HplAtm128Timer1C</span></tt> and <tt class="docutils literal"><span class="pre">HplAtm128Timer3C</span></tt>:</p>
+<pre class="literal-block">
+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)];
+}
+</pre>
+<p>On the fourth creation of an <tt class="docutils literal"><span class="pre">AlarmOne16C</span></tt>, <tt class="docutils literal"><span class="pre">unique(UQ_TIMER1_COMPARE)</span></tt>
+will return 3, causing a compile-time error as discussed in Appendix B
+(<tt class="docutils literal"><span class="pre">HplAtm128Timer1C</span></tt>'s <tt class="docutils literal"><span class="pre">Compare</span></tt> interface is only defined for values
+from 0 to 2).</p>
<p>When an Atmega128 is in any power-saving mode, hardware timers 1, 2 and 3
stop counting. The default Atmega128 power management <em>will</em> enter these
power-saving modes even when timers 1 and 3 are enabled, so time as
will not enter power-saving modes.</p>
<p>The mica family HIL components are built as follows:</p>
<ul class="simple">
-<li>TimerMilliC: built using AlarmMilli32C (consuming its single compare
-register)</li>
+<li>HilTimerMilliC: built as described above from hardware timer 0.</li>
<li>BusyWaitMicroC: implemented using a simple software busy-wait loop which
waits for <tt class="docutils literal"><span class="pre">MHZ</span></tt> cycles per requested microsecond. Accuracy is the same as
Timer 1.</li>
projects / tinyos-2.x.git / blobdiff