--- /dev/null
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<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/" />
+<title>Timers</title>
+<meta name="author" content="Cory Sharp, Martin Turon, David Gay" />
+<style type="text/css">
+
+/*
+:Author: David Goodger
+:Contact: goodger@users.sourceforge.net
+:date: $Date$
+:version: $Revision$
+:copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+*/
+body {
+ font-family: Times;
+ font-size: 16px;
+}
+
+.first {
+ margin-top: 0 ! important }
+
+.last {
+ margin-bottom: 0 ! important }
+
+.hidden {
+ display: none }
+
+a.toc-backref {
+ text-decoration: none ;
+ color: black }
+
+blockquote.epigraph {
+ margin: 2em 5em ; }
+
+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 }
+
+div.abstract p.topic-title {
+ font-weight: bold ;
+ text-align: center }
+
+div.attention, div.caution, div.danger, div.error, div.hint,
+div.important, div.note, div.tip, div.warning, div.admonition {
+ margin: 2em ;
+ border: medium outset ;
+ padding: 1em }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+ color: red ;
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.hint p.admonition-title, div.important p.admonition-title,
+div.note p.admonition-title, div.tip p.admonition-title,
+div.admonition p.admonition-title {
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.dedication {
+ margin: 2em 5em ;
+ text-align: center ;
+ font-style: italic }
+
+div.dedication p.topic-title {
+ font-weight: bold ;
+ font-style: normal }
+
+div.figure {
+ margin-left: 2em }
+
+div.footer, div.header {
+ font-size: smaller }
+
+div.line-block {
+ display: block ;
+ margin-top: 1em ;
+ margin-bottom: 1em }
+
+div.line-block div.line-block {
+ margin-top: 0 ;
+ margin-bottom: 0 ;
+ margin-left: 1.5em }
+
+div.sidebar {
+ margin-left: 1em ;
+ border: medium outset ;
+ padding: 0em 1em ;
+ background-color: #ffffee ;
+ width: 40% ;
+ float: right ;
+ clear: right }
+
+div.sidebar p.rubric {
+ font-family: sans-serif ;
+ font-size: medium }
+
+div.system-messages {
+ margin: 5em }
+
+div.system-messages h1 {
+ color: red }
+
+div.system-message {
+ border: medium outset ;
+ padding: 1em }
+
+div.system-message p.system-message-title {
+ color: red ;
+ font-weight: bold }
+
+div.topic {
+ margin: 2em }
+
+h1 {
+ font-family: Arial, sans-serif;
+ font-size: 20px;
+}
+
+h1.title {
+ text-align: center;
+ font-size: 32px;
+}
+
+h2 {
+ font-size: 16px;
+ font-family: Arial, sans-serif;
+}
+
+h2.subtitle {
+ text-align: center }
+
+h3 {
+ font-size: 12px;
+ font-family: Arial, sans-serif;
+}
+
+hr {
+ width: 75% }
+
+ol.simple, ul.simple {
+ margin-bottom: 1em }
+
+ol.arabic {
+ list-style: decimal }
+
+ol.loweralpha {
+ list-style: lower-alpha }
+
+ol.upperalpha {
+ list-style: upper-alpha }
+
+ol.lowerroman {
+ list-style: lower-roman }
+
+ol.upperroman {
+ list-style: upper-roman }
+
+p.attribution {
+ text-align: right ;
+ margin-left: 50% }
+
+p.caption {
+ font-style: italic }
+
+p.credits {
+ font-style: italic ;
+ font-size: smaller }
+
+p.label {
+ white-space: nowrap }
+
+p.rubric {
+ font-weight: bold ;
+ font-size: larger ;
+ color: maroon ;
+ text-align: center }
+
+p.sidebar-title {
+ font-family: sans-serif ;
+ font-weight: bold ;
+ font-size: larger }
+
+p.sidebar-subtitle {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+p.topic-title {
+ font-weight: bold }
+
+pre.address {
+ margin-bottom: 0 ;
+ margin-top: 0 ;
+ font-family: serif ;
+ font-size: 100% }
+
+pre.line-block {
+ font-family: serif ;
+ font-size: 100% }
+
+pre.literal-block, pre.doctest-block {
+ margin-left: 2em ;
+ margin-right: 2em ;
+ background-color: #eeeeee;
+ border-color: #000000;
+ border-width: thin;
+ font-size: 14px
+}
+
+span.classifier {
+ font-family: sans-serif ;
+ font-style: oblique }
+
+span.classifier-delimiter {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+span.interpreted {
+ font-family: sans-serif }
+
+span.option {
+ white-space: nowrap }
+
+span.option-argument {
+ font-style: italic }
+
+span.pre {
+ white-space: pre }
+
+span.problematic {
+ color: red }
+
+table {
+ margin-top: 0.5em ;
+ margin-bottom: 0.5em }
+
+table.citation {
+ border-left: solid thin gray ;
+ padding-left: 0.5ex }
+
+table.docinfo {
+ margin: 2em 4em;
+}
+
+table.footnote {
+ border-left: solid thin black ;
+ padding-left: 0.5ex }
+
+td, th {
+ padding-left: 0.5em ;
+ padding-right: 0.5em ;
+ vertical-align: top }
+
+th.docinfo-name, th.field-name {
+ font-weight: bold ;
+ text-align: left ;
+ white-space: nowrap;
+ }
+
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
+ font-size: 100% }
+
+tt {}
+
+ul.auto-toc {
+ list-style-type: none }
+
+</style>
+</head>
+<body>
+<div class="document" id="timers">
+<h1 class="title">Timers</h1>
+<table class="docinfo" frame="void" rules="none">
+<col class="docinfo-name" />
+<col class="docinfo-content" />
+<tbody valign="top">
+<tr class="field"><th class="docinfo-name">TEP:</th><td class="field-body">102</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Group:</th><td class="field-body">Core Working Group</td>
+</tr>
+<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>
+<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.1.2.4</td>
+</tr>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-06-16</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">
+<p class="first admonition-title">Note</p>
+<p class="last">This memo documents a part of TinyOS for the TinyOS Community, and
+requests discussion and suggestions for improvements. Distribution
+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>
+<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>
+<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>
+<li>one or more compare registers for each counter, which can trigger
+interrupts, changes to output pins and changes to the counter value</li>
+<li>capture of the time of input pin changes</li>
+</ul>
+<p>The interested reader can refer to Appendix A for a brief overview of
+the timer hardware on some current TinyOS platforms.</p>
+<p>TinyOS does not attempt to capture all this diversity in a
+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
+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>
+<ul class="simple">
+<li>a set of platform-independent interfaces for counting time and triggering
+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
+(<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>
+</ul>
+<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>
+<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>
+<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>
+<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>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
+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:
+for instance, it would be inappropriate to claim that a millisecond timer
+is a 32kHz timer.</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. Accuracy is not
+reflected in the interface type.</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">
+<h2><a id="timer-interfaces" 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 >
+interface Alarm< precision_tag, size_type >
+interface BusyWait< 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.</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
+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">
+<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.
+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 start( size_type dt );
+ async command void stop();
+ async event void fired();
+
+ // extended interface
+ async command bool isRunning();
+ async command void startAt( size_type t0, size_type dt );
+ async command size_type getNow();
+ async command size_type getAlarm();
+}
+</pre>
+<dl class="docutils">
+<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>
+<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>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>
+<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">
+<h2><a id="busywait" 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">
+<h2><a id="localtime" 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">
+<h2><a id="timer" 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 startPeriodic( uint32_t dt );
+ command void startOneShot( uint32_t dt );
+ command void stop();
+ event void fired();
+
+ // extended interface
+ command bool isRunning();
+ command bool isOneShot();
+ command void startPeriodicAt( uint32_t t0, uint32_t dt );
+ command void startOneShotAt( uint32_t t0, uint32_t dt );
+ command uint32_t getNow();
+ command uint32_t gett0();
+ command uint32_t getdt();
+}
+</pre>
+<dl class="docutils">
+<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>
+<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()</dt>
+<dd>signals that the timer has occurred.</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>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>
+<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">
+<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>
+<pre class="literal-block">
+configuration CounterPWC {
+ provides interface Counter<TP, uintW_t>;
+} ...
+generic configuration AlarmPWC {
+ provides interface Alarm<TP,uintW_t>;
+} ...
+</pre>
+<p>and, except if <em>W</em> is 32:</p>
+<pre class="literal-block">
+configuration CounterP32C {
+ provides interface Counter<TP, uint32_t>;
+} ...
+generic configuration AlarmP32C {
+ provides interface Alarm<TP,uint32_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>
+</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>
+<div class="section">
+<h2><a id="timermillic" name="timermillic">TimerMilliC</a></h2>
+<pre class="literal-block">
+#define TIMERMILLIC_SERVICE ...
+configuration TimerMilliC
+{
+ provides interface Init;
+ provides interface Timer<TMilli>[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>
+</div>
+<div class="section">
+<h2><a id="busywaitmicroc" name="busywaitmicroc">BusyWaitMicroC</a></h2>
+<pre class="literal-block">
+configuration BusyWaitMicroC
+{
+ provides interface BusyWait<TMicro,uint16_t>;
+}
+</pre>
+<p>BusyWaitMicroC allows applications to busy-wait for a number of
+microseconds. It's 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>
+<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">
+<li>AlarmToTimerC</li>
+<li>BusyWaitCounterC</li>
+<li>CounterToLocalTimeC</li>
+<li>TransformAlarmC</li>
+<li>TransformCounterC</li>
+<li>VirtualizeTimerC</li>
+</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>
+<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">
+<h2><a id="busywaitcounterc" 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">
+<h2><a id="countertolocaltimec" 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">
+<h2><a id="transformalarmc" 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">
+<h2><a id="transformcounterc" 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">
+<h2><a id="virtualizetimerc" 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">
+<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>
+<blockquote>
+<ol class="loweralpha simple">
+<li>Atmega128</li>
+</ol>
+<blockquote>
+<ol class="lowerroman simple">
+<li>Two 8-bit timers, each allowing</li>
+</ol>
+<blockquote>
+<ul class="simple">
+<li>7 prescaler values (division by different powers of 2)</li>
+<li>Timer 0 can use an external 32768Hz crystal</li>
+<li>One compare register, with many compare actions (change
+output pin, clear counter, generate interrupt, etc)</li>
+</ul>
+</blockquote>
+<ol class="lowerroman simple" start="2">
+<li>Two 16-bit timers, each with</li>
+</ol>
+<blockquote>
+<ul class="simple">
+<li>5 prescaler values</li>
+<li>External and software clocking options</li>
+<li>Three compare registers (again with many actions)</li>
+<li>Input capture</li>
+</ul>
+</blockquote>
+</blockquote>
+<ol class="loweralpha simple" start="2">
+<li>MSP430</li>
+</ol>
+<blockquote>
+<ol class="lowerroman simple">
+<li>Two 16-bit timers with</li>
+</ol>
+<blockquote>
+<ul class="simple">
+<li>One with three compare registers</li>
+<li>One with eight compare registers</li>
+<li>Each from distinct clock source</li>
+<li>Each with limited prescalers</li>
+</ul>
+</blockquote>
+</blockquote>
+<ol class="loweralpha simple" start="3">
+<li>Intel PXA27x</li>
+</ol>
+<blockquote>
+<ol class="lowerroman simple">
+<li>One fixed rate (3.25MHz) 32-bit timer with</li>
+</ol>
+<blockquote>
+<ul class="simple">
+<li>4 compare registers</li>
+<li>Watchdog functionality</li>
+</ul>
+</blockquote>
+<ol class="lowerroman simple" start="2">
+<li>8 variable rate 32-bit timers with</li>
+</ol>
+<blockquote>
+<ul class="simple">
+<li>1 associated compare register each</li>
+<li>Individually selectable rates: 1/32768s, 1ms, 1s, 1us</li>
+<li>Individually selectable sources: (32.768 external osc,
+13 Mhz internal clock)</li>
+</ul>
+</blockquote>
+<ol class="lowerroman simple" start="3">
+<li>Periodic & one-shot capability</li>
+<li>Two external sync events</li>
+</ol>
+</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>
+<p>The Atmega128 exposes its four timers through a common set of interfaces:</p>
+<blockquote>
+<ul class="simple">
+<li>HplTimer<width> - get/set current time, overflow event, control, init</li>
+<li>HplCompare<width> - get/set compare time, fired event, control</li>
+<li>HplCapture<width> - get/set capture time, captured event, control, config</li>
+</ul>
+</blockquote>
+<p>Parameterising these interfaces by width allows reusing the same interfaces
+for the 8 and 16-bit timers. This simplifies building reusable higher level
+components which are independent of timer width.</p>
+<pre class="literal-block">
+interface HplAtm128Timer<timer_size>
+{
+ /// Timer value register: Direct access
+ async command timer_size get();
+ async command void set( timer_size t );
+
+ /// Interrupt signals
+ async event void overflow(); //<! Signalled on overflow interrupt
+
+ /// Interrupt flag utilites: Bit level set/clr
+ async command void reset(); //<! Clear the overflow interrupt flag
+ async command void start(); //<! Enable the overflow interrupt
+ async command void stop(); //<! Turn off overflow interrupts
+ async command bool test(); //<! Did overflow interrupt occur?
+ async command bool isOn(); //<! Is overflow interrupt on?
+
+ /// Clock initialization interface
+ 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
+}
+
+interface HplAtm128Compare<size_type>
+{
+ /// Compare value register: Direct access
+ async command size_type get();
+ async command void set(size_type t);
+
+ /// Interrupt signals
+ async event void fired(); //<! Signalled on compare interrupt
+
+ /// Interrupt flag utilites: Bit level set/clr
+ async command void reset(); //<! Clear the compare interrupt flag
+ async command void start(); //<! Enable the compare interrupt
+ async command void stop(); //<! Turn off comparee interrupts
+ async command bool test(); //<! Did compare interrupt occur?
+ async command bool isOn(); //<! Is compare interrupt on?
+}
+
+interface HplAtm128Capture<size_type>
+{
+ /// Capture value register: Direct access
+ async command size_type get();
+ async command void set(size_type t);
+
+ /// Interrupt signals
+ async event void captured(size_type t); //<! Signalled on capture int
+
+ /// 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
+ async command bool test(); //<! Did capture interrupt occur?
+ async command bool isOn(); //<! Is capture interrupt on?
+
+ 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>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
+for converting the HPL interfaces into platform-independent interfaces.
+These generic components include appropriate configuration parameters
+(e.g., prescaler values):</p>
+<pre class="literal-block">
+generic module Atm128AlarmC(typedef frequency_tag,
+ typedef timer_size @integer(),
+ uint8_t prescaler,
+ int mindt)
+{
+ provides interface Init;
+ provides interface Alarm<frequency_tag, timer_size> as Alarm;
+ uses interface HplTimer<timer_size>;
+ uses interface HplCompare<timer_size>;
+} ...
+
+generic module Atm128CounterC(typedef frequency_tag,
+ typedef timer_size @integer())
+{
+ provides interface Counter<frequency_tag,timer_size> as Counter;
+ uses interface HplTimer<timer_size> as Timer;
+} ...
+</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>
+<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
+internal oscillator is less precise, but allows for much faster startup
+from power-down and power-save modes (6 clocks vs 16000 clocks). Finally,
+power consumption is lower at the lower frequencies.</p>
+<p>The mica family members support operation at all these frequencies via
+a <tt class="docutils literal"><span class="pre">MHZ</span></tt> preprocessor symbol, which can be defined to 1, 2, 4, or 8.
+If undefined, it defaults to a platform-dependent value (4 for mica2dot,
+8 for mica2 and micaz).</p>
+<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>
+<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
+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>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>
+<ul class="simple">
+<li>internal clock: depends on how well the clock is calibrated</li>
+<li>external 7.37MHz crystal: times will be off by ~8.6%</li>
+<li>external 4MHz crystal: times will be as accurate as the crystal</li>
+</ul>
+</li>
+<li><p class="first">Timer 2: this timer is not currently exposed by the HAL.</p>
+</li>
+<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
+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
+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>
+<p>At 1, 2, 4 and 8MHz, <tt class="docutils literal"><span class="pre">Counter32khz32C</span></tt> and <tt class="docutils literal"><span class="pre">Alarm32khz32C</span></tt> run
+at 31.25kHz (plus clock rate inaccuracy). At 7.37MHz, they run at
+~28.8kHz.</p>
+</li>
+</ul>
+<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
+measured by timers 1 and 3 does <em>not</em> represent real time. However, if any
+alarms built on timers 1 or 3 are active, the Atmega128 power management
+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>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>
+</ul>
+<p>Finally, the mica family motes measure their clock rate at boot time, based
+on the external 32768Hz crystal. The results of this clock rate measurement
+are made available via the <tt class="docutils literal"><span class="pre">cyclesPerJiffy</span></tt> command of the
+<tt class="docutils literal"><span class="pre">Atm128Calibrate</span></tt> interface of the <tt class="docutils literal"><span class="pre">MeasureClockC</span></tt> component. This
+command reports the number of cycles per 1/32768s. Please see this interface
+definition for other useful commands for more accurate timing.</p>
+</div>
+</div>
+</body>
+</html>
projects / tinyos-2.x.git / blobdiff