<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.6: http://docutils.sourceforge.net/" />
<title>Timers</title>
<meta name="author" content="Cory Sharp, Martin Turon, David Gay" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="timers">
<h1 class="title">Timers</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<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 class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.7</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-09-06</td>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-12-12</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="document" id="timers">
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This memo documents a part of TinyOS for the TinyOS Community, and
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
+<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>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>Most microcontrollers offer a rich timer system, with features like:</p>
<ul class="simple">
<li>several counters, possibly of different widths, with multiple clocking options</li>
platform-independent fashion. Instead, following the principles of the
HAA[_tep2], each microcontroller should expose all this functionality
via components and interfaces at the HPL and, where appropriate, HAL levels.
-However, two aspects of timers are sufficiently common and important
+However, two aspects of timers are sufficiently common and important
that they should be made available in a well-defined way: measuring time,
and triggering (possibly repeating) events at specific times. The rest
of this TEP specifies:</p>
events (<a class="reference" href="#interfaces">2. Interfaces</a>)</li>
<li>guidelines on how each microcontroller's HAL SHOULD expose its timer hardware
in terms of the above interfaces (<a class="reference" href="#hal-guidelines">3. HAL guidelines</a>)</li>
-<li>what components a microcontroller's timer HIL MUST implement
+<li>what components a microcontroller's timer HIL MUST implement
(<a class="reference" href="#hil-requirements">4. HIL requirements</a>)</li>
<li>a set of utility components whose use simplifies building the components
specified by the HAL guidelines and HIL requirements (<a class="reference" href="#utility-components">5. Utility components</a>)</li>
<p>This TEP ends with appendices documenting, as an example, the mica2
timer subsystem implementation.</p>
</div>
-<div class="section">
-<h1><a id="interfaces" name="interfaces">2. Interfaces</a></h1>
+<div class="section" id="interfaces">
+<h1><a name="interfaces">2. Interfaces</a></h1>
<p>Before presenting the interfaces (2.2), we start with a general
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>
+<div class="section" id="precision-width-and-accuracy">
+<h2><a 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.</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
<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;
+typedef struct { } TMilli; // 1024 ticks per second
+typedef struct { } T32khz; // 32768 ticks per second
+typedef struct { } 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="timer-interfaces" name="timer-interfaces">2.2 Timer interfaces</a></h2>
+<div class="section" id="timer-interfaces">
+<h2><a name="timer-interfaces">2.2 Timer interfaces</a></h2>
<p>This TEP proposes these timer interfaces:</p>
<pre class="literal-block">
interface Counter< precision_tag, size_type >
and Counter interfaces are used by the TinyOS timer system and
advanced user components.</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
+<div class="section" id="counter">
+<h2><a 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.
}
</pre>
<dl class="docutils">
-<dt>get()</dt>
+<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>
+<dt>isOverflowPending() </dt>
+<dd>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.</dd>
+<dt>clearOverflow() </dt>
+<dd>cancel the pending overflow interrupt 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>
</dl>
</div>
-<div class="section">
-<h2><a id="alarm" name="alarm">Alarm</a></h2>
+<div class="section" id="alarm">
+<h2><a 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"
}
</pre>
<dl class="docutils">
-<dt>start(dt)</dt>
+<dt>start(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>
+<dt>stop() </dt>
<dd>cancel any previously running alarm.</dd>
-<dt>fired()</dt>
+<dt>fired() </dt>
<dd>signals that the alarm has occurred.</dd>
-<dt>isRunning()</dt>
+<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>
-<dt>getNow()</dt>
+</dl>
+<p>startAt(t0,dt)</p>
+<blockquote>
+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.</blockquote>
+<dl class="docutils">
+<dt>getNow() </dt>
<dd>return the current time in the precision and width of the alarm.</dd>
-<dt>getAlarm()</dt>
+<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>
+<div class="section" id="busywait">
+<h2><a name="busywait">BusyWait</a></h2>
+<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 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">
-<h2><a id="localtime" name="localtime">LocalTime</a></h2>
+<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>
<dl class="docutils">
-<dt>get()</dt>
+<dt>get() </dt>
<dd>return the current time.</dd>
</dl>
</div>
-<div class="section">
-<h2><a id="timer" name="timer">Timer</a></h2>
+<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
}
</pre>
<dl class="docutils">
-<dt>startPeriodic(dt)</dt>
+<dt>startPeriodic(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>startOneShot(dt)</dt>
+<dt>startOneShot(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>
+<dt>stop() </dt>
<dd>cancel any previously running timer.</dd>
<dt>fired()</dt>
<dd>signals that the timer has occurred.</dd>
-<dt>isRunning()</dt>
+<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>
+<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>
+<dt>startPeriodicAt(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>startOneShotAt(t0,dt)</dt>
+<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>
-<dt>getNow()</dt>
+<dt>getNow() </dt>
<dd>return the current time in the precision and width of the timer.</dd>
-<dt>gett0()</dt>
+<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>
+<dt>getdt() </dt>
<dd>return the delay or period for the previously started timer.</dd>
</dl>
</div>
</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>
+<div class="section" id="hal-guidelines">
+<h1><a name="hal-guidelines">3. HAL guidelines</a></h1>
+<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 Appendix B 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 defined components for the platform that
+are mutually incompatible in 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>
+<div class="section" id="hil-requirements">
+<h1><a name="hil-requirements">4. HIL requirements</a></h1>
<dl class="docutils">
<dt>The following component MUST be provided on all platforms::</dt>
-<dd>TimerMilliC
+<dd>HilTimerMilliC
BusyWaitMicroC</dd>
</dl>
-<div class="section">
-<h2><a id="timermillic" name="timermillic">TimerMilliC</a></h2>
+<div class="section" id="hiltimermillic">
+<h2><a 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 LocalTime<TMilli>;
+ provides interface Timer<TMilli> as TimerMilli[ uint8_t num ];
}
</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 generic component
+TimerMilliC 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>
+<div class="section" id="busywaitmicroc">
+<h2><a name="busywaitmicroc">BusyWaitMicroC</a></h2>
<pre class="literal-block">
configuration BusyWaitMicroC
{
}
</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>
</div>
-<div class="section">
-<h1><a id="utility-components" name="utility-components">5. Utility components</a></h1>
+<div class="section" id="utility-components">
+<h1><a name="utility-components">5. Utility components</a></h1>
<p>A number of platform independent generic components are provided to
help implementers and advanced users of the TinyOS timer system:</p>
<ul class="simple">
</ul>
<p>Appendices B and C show how these can be used to help implement
the timer HAL and HIL.</p>
-<div class="section">
-<h2><a id="alarmtotimerc" name="alarmtotimerc">AlarmToTimerC</a></h2>
+<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 )
}
</pre>
</div>
-<div class="section">
-<h2><a id="busywaitcounterc" name="busywaitcounterc">BusyWaitCounterC</a></h2>
+<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">
}
</pre>
</div>
-<div class="section">
-<h2><a id="countertolocaltimec" name="countertolocaltimec">CounterToLocalTimeC</a></h2>
+<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 )
}
</pre>
</div>
-<div class="section">
-<h2><a id="transformalarmc" name="transformalarmc">TransformAlarmC</a></h2>
+<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(
+generic component TransformAlarmC(
typedef to_precision_tag,
typedef to_size_type @integer(),
typedef from_precision_tag,
<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>
+<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(
new TransformCounterC( TMilli, uint32_t, T32khz, uint16_t, 5, uint32_t )
</pre>
</div>
-<div class="section">
-<h2><a id="virtualizetimerc" name="virtualizetimerc">VirtualizeTimerC</a></h2>
+<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">
</pre>
</div>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
+<div class="section" id="implementation">
+<h1><a 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">TransformAlarmCounterC.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">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>
+</div>
+<div class="section" id="author-s-address">
+<h1><a 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>
<div class="line">email - <a class="reference" href="mailto:david.e.gay@intel.com">david.e.gay@intel.com</a></div>
</div>
</div>
-<div class="section">
-<h1><a id="appendix-a-timer-hardware-on-various-microcontrollers" name="appendix-a-timer-hardware-on-various-microcontrollers">Appendix A: Timer hardware on various microcontrollers</a></h1>
+<div class="section" id="appendix-a-timer-hardware-on-various-microcontrollers">
+<h1><a name="appendix-a-timer-hardware-on-various-microcontrollers">Appendix A: Timer hardware on various microcontrollers</a></h1>
<blockquote>
<ol class="loweralpha simple">
<li>Atmega128</li>
</blockquote>
</blockquote>
</div>
-<div class="section">
-<h1><a id="appendix-b-a-microcontroller-atmega-128-timer-subsystem" name="appendix-b-a-microcontroller-atmega-128-timer-subsystem">Appendix B: a microcontroller: Atmega 128 timer subsystem</a></h1>
+<div class="section" id="appendix-b-a-microcontroller-atmega-128-timer-subsystem">
+<h1><a name="appendix-b-a-microcontroller-atmega-128-timer-subsystem">Appendix B: a microcontroller: Atmega 128 timer subsystem</a></h1>
<p>The Atmega128 exposes its four timers through a common set of interfaces:</p>
<blockquote>
<ul class="simple">
async command bool isOn(); //<! Is overflow interrupt on?
/// Clock initialization interface
- async command void off(); //<! Turn off the clock
+ async command void off(); //<! Turn off the clock
async command void setScale( uint8_t scale); //<! Turn on the clock
async command uint8_t getScale(); //<! Get prescaler setting
}
/// Interrupt signals
async event void captured(size_type t); //<! Signalled on capture int
- /// Interrupt flag utilites: Bit level set/clr
+ /// Interrupt flag utilites: Bit level set/clr
async command void reset(); //<! Clear the capture interrupt flag
async command void start(); //<! Enable the capture interrupt
async command void stop(); //<! Turn off capture interrupts
} ...
</pre>
</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>
+<div class="section" id="appendix-c-a-mote-mica-family-timer-subsystem">
+<h1><a name="appendix-c-a-mote-mica-family-timer-subsystem">Appendix C: a mote: Mica family timer subsystem</a></h1>
<p>Members of the mica family (mica2, mica2dot, micaz) use the Atmega128
microprocessor and have external crystals at 4 or 7.37MHz. Additionally,
they can be run from an internal oscillator at 1, 2, 4, or 8 MHz. The
<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,
64, 256 and 1024. So, when clocked at 2 or 4MHz, a divider of 1 is
-selected and timer 1 runs at 2 or 4MHz. To reflect this fact, the
+selected and timer 1 runs at 2 or 4MHz. To reflect this fact, the
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>
<li><p class="first">Timer 3: the 16-bit hardware timer 3 is set to run at a rate close to
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
+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
<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
projects / tinyos-2.x.git / blobdiff