<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" />
<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" />
<title>Coding Standard</title>
<meta name="author" content="Ion Yannopoulos, David Gay" />
<style type="text/css">
<title>Coding Standard</title>
<meta name="author" content="Ion Yannopoulos, David Gay" />
<style type="text/css">
<h1 class="title">Coding Standard</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<h1 class="title">Coding Standard</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This document specifies a Best Current Practices for the
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This document specifies a Best Current Practices for the
improvements. Distribution of this memo is unlimited. This memo
is in full compliance with <a class="citation-reference" href="#tep-1" id="id1" name="id1">[TEP_1]</a>.</p>
</div>
improvements. Distribution of this memo is unlimited. This memo
is in full compliance with <a class="citation-reference" href="#tep-1" id="id1" name="id1">[TEP_1]</a>.</p>
</div>
-<div class="contents topic" id="contents">
-<p class="topic-title first"><a name="contents">Contents</a></p>
+<div class="contents topic">
+<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
<ul class="auto-toc simple">
<li><a class="reference" href="#introduction" id="id7" name="id7">1 Introduction</a></li>
<li><a class="reference" href="#general-conventions" id="id8" name="id8">2 General Conventions</a><ul class="auto-toc">
<ul class="auto-toc simple">
<li><a class="reference" href="#introduction" id="id7" name="id7">1 Introduction</a></li>
<li><a class="reference" href="#general-conventions" id="id8" name="id8">2 General Conventions</a><ul class="auto-toc">
below, be consistent in how you do so. If you add any new conventions to
your code, note it in a README.</p>
</div>
below, be consistent in how you do so. If you add any new conventions to
your code, note it in a README.</p>
</div>
-<div class="section" id="general-conventions">
-<h1><a class="toc-backref" href="#id8" name="general-conventions">2 General Conventions</a></h1>
-<div class="section" id="general">
-<h2><a class="toc-backref" href="#id9" name="general">2.1 General</a></h2>
+<div class="section">
+<h1><a class="toc-backref" href="#id8" id="general-conventions" name="general-conventions">2 General Conventions</a></h1>
+<div class="section">
+<h2><a class="toc-backref" href="#id9" id="general" name="general">2.1 General</a></h2>
<blockquote>
<ul class="simple">
<li>Avoid the use of acronyms and abbreviations that are not well known.
Try not to abbreviate "just because".</li>
<li>Acronyms should be capitalized (as in Java), i.e., Adc, not ADC.
<blockquote>
<ul class="simple">
<li>Avoid the use of acronyms and abbreviations that are not well known.
Try not to abbreviate "just because".</li>
<li>Acronyms should be capitalized (as in Java), i.e., Adc, not ADC.
messages, not Am)</li>
<li>If you need to abbreviate a word, do so consistently. Try to be
consistent with code outside your own.</li>
messages, not Am)</li>
<li>If you need to abbreviate a word, do so consistently. Try to be
consistent with code outside your own.</li>
<p>For the purposes of this document a package is a collection of related
source and other files, in whatever languages are needed. A package is
a logical grouping. It may or may not correspond to a physical grouping
such as a single directory. In TinyOS a package is most often a
directory with zero or more subdirectories.</p>
<p>nesC and C do not currently provide any package support, thus names
<p>For the purposes of this document a package is a collection of related
source and other files, in whatever languages are needed. A package is
a logical grouping. It may or may not correspond to a physical grouping
such as a single directory. In TinyOS a package is most often a
directory with zero or more subdirectories.</p>
<p>nesC and C do not currently provide any package support, thus names
See the examples below.</p>
<p>In a package, we distinguish between public components (intended to
be used and wired outside the package) and private components (only
used and wired within the package). This distinction is not enforced
by nesC.</p>
See the examples below.</p>
<p>In a package, we distinguish between public components (intended to
be used and wired outside the package) and private components (only
used and wired within the package). This distinction is not enforced
by nesC.</p>
-<div class="section" id="language-conventions">
-<h1><a class="toc-backref" href="#id12" name="language-conventions">4 Language Conventions</a></h1>
-<div class="section" id="nesc-convention">
-<h2><a class="toc-backref" href="#id13" name="nesc-convention">4.1 nesC convention</a></h2>
-<div class="section" id="names">
-<h3><a class="toc-backref" href="#id14" name="names">4.1.1 Names</a></h3>
+<div class="section">
+<h1><a class="toc-backref" href="#id12" id="language-conventions" name="language-conventions">4 Language Conventions</a></h1>
+<div class="section">
+<h2><a class="toc-backref" href="#id13" id="nesc-convention" name="nesc-convention">4.1 nesC convention</a></h2>
+<div class="section">
+<h3><a class="toc-backref" href="#id14" id="names" name="names">4.1.1 Names</a></h3>
<li>Chip-specific hardware abstraction layer components and interfaces
start with the chip name, e.g., Atm128 for ATmega128.</li>
<li>The Maté virtual machine uses the Mate to prefix all its names.</li>
<li>Chip-specific hardware abstraction layer components and interfaces
start with the chip name, e.g., Atm128 for ATmega128.</li>
<li>The Maté virtual machine uses the Mate to prefix all its names.</li>
<blockquote>
<ul class="simple">
<li>Don't use the nesC <cite>includes</cite> statement. It does not handle macro
inclusion properly. Use <cite>#include</cite> instead.</li>
<li>Macros declared in an <cite>.nc</cite> file must be <cite>#define</cite>'d after the
<blockquote>
<ul class="simple">
<li>Don't use the nesC <cite>includes</cite> statement. It does not handle macro
inclusion properly. Use <cite>#include</cite> instead.</li>
<li>Macros declared in an <cite>.nc</cite> file must be <cite>#define</cite>'d after the
the module.</li>
<li>Macros which are meant for use in multiple <cite>.nc</cite> files should be
<cite>#define</cite>'d in a <cite>#include</cite>'d C header file.</li>
the module.</li>
<li>Macros which are meant for use in multiple <cite>.nc</cite> files should be
<cite>#define</cite>'d in a <cite>#include</cite>'d C header file.</li>
-should also use it for all types, tags, functions, variables,
+should also use it for all types, tags, functions, variables,
constants and macros. This leads naturally to:<ul>
<li>Minimize C code outside of nesC files. In particular: most uses of
hardware specific macros in TinyOS 1.x should be replaced with nesC
constants and macros. This leads naturally to:<ul>
<li>Minimize C code outside of nesC files. In particular: most uses of
hardware specific macros in TinyOS 1.x should be replaced with nesC
<p>TinyOS also follows a number of higher-level programming conventions,
mostly designed to provide a consistent "look" to TinyOS interfaces and
components, and to increase software reliability.</p>
<p>TinyOS also follows a number of higher-level programming conventions,
mostly designed to provide a consistent "look" to TinyOS interfaces and
components, and to increase software reliability.</p>
<p>TinyOS defines a standard error return type, <tt class="docutils literal"><span class="pre">error_t</span></tt>, similar to Unix's
error returns, except that error codes are positive:</p>
<pre class="literal-block">
enum {
<p>TinyOS defines a standard error return type, <tt class="docutils literal"><span class="pre">error_t</span></tt>, similar to Unix's
error returns, except that error codes are positive:</p>
<pre class="literal-block">
enum {
signaled under some conditions). With such functions, the split-phase event
will be signaled iff the split-phase command returns <tt class="docutils literal"><span class="pre">SUCCESS</span></tt>.</p>
</div>
signaled under some conditions). With such functions, the split-phase event
will be signaled iff the split-phase command returns <tt class="docutils literal"><span class="pre">SUCCESS</span></tt>.</p>
</div>
-<div class="section" id="passing-pointers-between-components">
-<h2><a class="toc-backref" href="#id22" name="passing-pointers-between-components">5.2 Passing pointers between components</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id22" id="passing-pointers-between-components" name="passing-pointers-between-components">5.2 Passing pointers between components</a></h2>
<p>Sharing data across components can easily lead to bugs such as data races,
overwriting data, etc. To minimise the likelyhood of these occurrences,
we discourage the use of pointers in TinyOS interfaces.</p>
<p>Sharing data across components can easily lead to bugs such as data races,
overwriting data, etc. To minimise the likelyhood of these occurrences,
we discourage the use of pointers in TinyOS interfaces.</p>
<p>TinyOS checks constraints on a program's wiring graph specified by
annotations on a component's interfaces. Wiring constraints are specified
by placing <tt class="docutils literal"><span class="pre">@atmostonce()</span></tt>, <tt class="docutils literal"><span class="pre">@atleastonce()</span></tt> and <tt class="docutils literal"><span class="pre">@exactlyonce()</span></tt>
<p>TinyOS checks constraints on a program's wiring graph specified by
annotations on a component's interfaces. Wiring constraints are specified
by placing <tt class="docutils literal"><span class="pre">@atmostonce()</span></tt>, <tt class="docutils literal"><span class="pre">@atleastonce()</span></tt> and <tt class="docutils literal"><span class="pre">@exactlyonce()</span></tt>
<table class="docutils citation" frame="void" id="tep-1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<table class="docutils citation" frame="void" id="tep-1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">