<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.3.6: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>Coding Standard</title>
<meta name="author" content="Ion Yannopoulos, David Gay" />
<style type="text/css">
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 }
</style>
</head>
<body>
+<div class="document" id="coding-standard">
<h1 class="title">Coding Standard</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
</tr>
</tbody>
</table>
-<div class="document" id="coding-standard">
<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>
-<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">
<li><a class="reference" href="#citations" id="id24" name="id24">6 Citations</a></li>
</ul>
</div>
-<div class="section" id="introduction">
-<h1><a class="toc-backref" href="#id7" name="introduction">1 Introduction</a></h1>
+<div class="section">
+<h1><a class="toc-backref" href="#id7" id="introduction" name="introduction">1 Introduction</a></h1>
<dl class="docutils">
<dt>The purpose of a naming convention is twofold:</dt>
<dd><ul class="first last simple">
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.
-Exception: 2-letter acronyms should be all caps (e.g., AM for active
+Exception: 2-letter acronyms should be all caps (e.g., AM for active
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>
</blockquote>
</div>
</div>
-<div class="section" id="packages">
-<h1><a class="toc-backref" href="#id10" name="packages">3 Packages</a></h1>
+<div class="section">
+<h1><a class="toc-backref" href="#id10" id="packages" name="packages">3 Packages</a></h1>
<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
-of types and components in different packages might accidentally
+of types and components in different packages might accidentally
clash. To make this less likely, judiciously use prefixes on groups
-of related files (often, but not always, part of a single package).
+of related files (often, but not always, part of a single package).
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="directory-structure">
-<h2><a class="toc-backref" href="#id11" name="directory-structure">3.1 Directory structure</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id11" id="directory-structure" name="directory-structure">3.1 Directory structure</a></h2>
<blockquote>
<ul>
<li><p class="first">Each package should have it's own directory. It may have as many
</blockquote>
</div>
</div>
-<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>
<blockquote>
<ul class="simple">
<li>All nesC files must have a <cite>.nc</cite> extension. The nesC compiler requires
</ul>
</blockquote>
</div>
-<div class="section" id="id5">
-<h3><a class="toc-backref" href="#id15" name="id5">4.1.2 Packages</a></h3>
+<div class="section">
+<h3><a class="toc-backref" href="#id15" id="id5" name="id5">4.1.2 Packages</a></h3>
<blockquote>
<ul>
<li><p class="first">Each package may use a prefix for its component, interface and
<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>Core TinyOS names (e.g., the timer components, the Init interface)
+<li>Core TinyOS names (e.g., the timer components, the Init interface)
do not use a prefix.</li>
</ul>
</blockquote>
</ul>
</blockquote>
</div>
-<div class="section" id="preprocessor">
-<h3><a class="toc-backref" href="#id16" name="preprocessor">4.1.3 Preprocessor</a></h3>
+<div class="section">
+<h3><a class="toc-backref" href="#id16" id="preprocessor" name="preprocessor">4.1.3 Preprocessor</a></h3>
<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
-<cite>module</cite> or <cite>configuration</cite> keyword to actually limit their scope to
+<cite>module</cite> or <cite>configuration</cite> keyword to actually limit their scope to
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>
</blockquote>
</div>
</div>
-<div class="section" id="c-convention">
-<h2><a class="toc-backref" href="#id17" name="c-convention">4.2 C Convention</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id17" id="c-convention" name="c-convention">4.2 C Convention</a></h2>
<blockquote>
<ul class="simple">
<li>All C files have a .h (header) or (rarely) a .c (source) extension.<ul>
-<li>Filenames associated with a component should have the same name as
+<li>Filenames associated with a component should have the same name as
the component.</li>
<li>Filenames of a package should have a name with the package
prefix (if any).</li>
</ul>
</li>
<li>C does not protect names in any way. If a package uses a prefix, it
-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
</ul>
</blockquote>
</div>
-<div class="section" id="java-convention">
-<h2><a class="toc-backref" href="#id18" name="java-convention">4.3 Java convention</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id18" id="java-convention" name="java-convention">4.3 Java convention</a></h2>
<blockquote>
<ul class="simple">
<li>The standard Java coding convention <a class="citation-reference" href="#java-coding-convention" id="id6" name="id6">[Java_Coding_Convention]</a>
</ul>
</blockquote>
</div>
-<div class="section" id="other-languages">
-<h2><a class="toc-backref" href="#id19" name="other-languages">4.4 Other languages</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id19" id="other-languages" name="other-languages">4.4 Other languages</a></h2>
<blockquote>
<ul class="simple">
<li>No established conventions.</li>
</blockquote>
</div>
</div>
-<div class="section" id="tinyos-conventions">
-<h1><a class="toc-backref" href="#id20" name="tinyos-conventions">5 TinyOS Conventions</a></h1>
+<div class="section">
+<h1><a class="toc-backref" href="#id20" id="tinyos-conventions" name="tinyos-conventions">5 TinyOS Conventions</a></h1>
<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>
-<div class="section" id="error-returns">
-<h2><a class="toc-backref" href="#id21" name="error-returns">5.1 Error returns</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id21" id="error-returns" name="error-returns">5.1 Error returns</a></h2>
<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 {
- SUCCESS = 0,
+ SUCCESS = 0,
FAIL = 1,
ESIZE = 2, // Parameter passed in was too big.
...
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>In the future, some tool may check that programs respect these ownership
transfer rules.</p>
</div>
-<div class="section" id="usage-of-wiring-annotations">
-<h2><a class="toc-backref" href="#id23" name="usage-of-wiring-annotations">5.3 Usage of wiring annotations</a></h2>
+<div class="section">
+<h2><a class="toc-backref" href="#id23" id="usage-of-wiring-annotations" name="usage-of-wiring-annotations">5.3 Usage of wiring annotations</a></h2>
<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>
wire initialisation code.</p>
</div>
</div>
-<div class="section" id="citations">
-<h1><a class="toc-backref" href="#id24" name="citations">6 Citations</a></h1>
+<div class="section">
+<h1><a class="toc-backref" href="#id24" id="citations" name="citations">6 Citations</a></h1>
<table class="docutils citation" frame="void" id="tep-1" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
projects / tinyos-2.x.git / blobdiff