Note
This document specifies a Best Current Practices for the @@ -318,8 +313,8 @@ TinyOS Community, and requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with [TEP_1].
- Avoid the use of acronyms and abbreviations that are not well known. Try not to abbreviate "just because".
- 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)
- If you need to abbreviate a word, do so consistently. Try to be consistent with code outside your own.
@@ -392,24 +387,24 @@ documentation block.
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.
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.
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.
-
Each package should have it's own directory. It may have as many @@ -472,12 +467,12 @@ components fairly easily however.
- All nesC files must have a .nc extension. The nesC compiler requires @@ -504,8 +499,8 @@ in '_t'.
@@ -530,14 +525,14 @@ components and Atm128 for hardware abstraction layer components.
Each package may use a prefix for its component, interface and @@ -518,7 +513,7 @@ an example of a shared prefix).
- Chip-specific hardware abstraction layer components and interfaces start with the chip name, e.g., Atm128 for ATmega128.
- The Maté virtual machine uses the Mate to prefix all its names.
-- Core TinyOS names (e.g., the timer components, the Init interface) +
- Core TinyOS names (e.g., the timer components, the Init interface) do not use a prefix.
- Don't use the nesC includes statement. It does not handle macro inclusion properly. Use #include instead.
- Macros declared in an .nc file must be #define'd after the -module or configuration keyword to actually limit their scope to +module or configuration keyword to actually limit their scope to the module.
- Macros which are meant for use in multiple .nc files should be #define'd in a #include'd C header file.
@@ -552,12 +547,12 @@ can't catch.
- All C files have a .h (header) or (rarely) a .c (source) extension.
-
- Filenames associated with a component should have the same name as +
- Filenames associated with a component should have the same name as the component.
- Filenames of a package should have a name with the package prefix (if any).
@@ -565,7 +560,7 @@ prefix (if any).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:
- Minimize C code outside of nesC files. In particular: most uses of hardware specific macros in TinyOS 1.x should be replaced with nesC @@ -591,8 +586,8 @@ by underscores.
- The standard Java coding convention [Java_Coding_Convention] @@ -601,8 +596,8 @@ should be followed.
- No established conventions.
@@ -610,18 +605,18 @@ should be followed.
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.
-TinyOS defines a standard error return type, error_t, similar to Unix's error returns, except that error codes are positive:
enum {
- SUCCESS = 0,
+ SUCCESS = 0,
FAIL = 1,
ESIZE = 2, // Parameter passed in was too big.
...
@@ -643,8 +638,8 @@ the operation may be refused (i.e., the split-phase event may not be
signaled under some conditions). With such functions, the split-phase event
will be signaled iff the split-phase command returns SUCCESS.
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.
@@ -700,8 +695,8 @@ above.In the future, some tool may check that programs respect these ownership transfer rules.
TinyOS checks constraints on a program's wiring graph specified by annotations on a component's interfaces. Wiring constraints are specified by placing @atmostonce(), @atleastonce() and @exactlyonce() @@ -721,8 +716,8 @@ annotation SHOULD be used on initialisation interfaces (typically, the wire initialisation code.