Philip Levis
Draft-Created:	18-Oct-2004
Draft-Version:	1.1.2.5
Draft-Version:	1.5
Draft-Modified:	2006-10-19
Draft-Modified:	2006-12-12
Draft-Discuss:	TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>

Cory Sharp, Martin Turon, David Gay
Draft-Created:	22-Sep-2004
Draft-Version:	1.1.2.9
Draft-Version:	1.7
Draft-Modified:	2006-10-18
Draft-Modified:	2006-12-12
Draft-Discuss:	TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>

Final
TinyOS-Version:	2.x
Authors:	Kevin Klues - Philip Levis - David Gay - David Culler - Vlado Handziski
Author:	Kevin Klues
Author:	Philip Levis
Author:	David Gay
Author:	David Culler
Author:	Vlado Handziski

Philip Levis
Draft-Created:	20-Jun-2005
Draft-Version:	1.1.2.2
Draft-Version:	1.5
Draft-Modified:	2006-02-08
Draft-Modified:	2006-12-12
Draft-Discuss:	TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>

Robert Szewczyk, Philip Levis, Martin Turon, Lama Nachman, Philip Buonadonna, Vlado Handziski
Draft-Created:	19-Sep-2005
Draft-Version:	1.6
Draft-Version:	1.7
Draft-Modified:	2006-12-20
Draft-Modified:	2007-01-10
Draft-Discuss:	TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>

Gilman Tolle, Philip Levis, and David Gay
Draft-Created:	30-Oct-2005
Draft-Version:	1.6
Draft-Version:	1.7
Draft-Modified:	2006-12-12
Draft-Modified:	2007-01-10
Draft-Discuss:	TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>

Draft-Modified:	2007-02-21
Draft-Discuss:	TinyOS Developer List +
Draft-Discuss:	TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>

Philip Levis
Draft-Created:	10-Dec-2004
Draft-Version:	1.9
Draft-Version:	1.10
Draft-Modified:	2007-03-21
Draft-Modified:	2007-03-28
Draft-Discuss:	TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>

Phil Buonadonna, Jonathan Hui
Draft-Created:	23-Jan-2006
Draft-Version:	1.1.2.9
Draft-Version:	1.5
Draft-Modified:	2006-09-30
Draft-Modified:	2006-12-12
Draft-Discuss:	TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>

Philip Levis and Gilman Tolle
Draft-Created:	10-Dec-2004
Draft-Version:	1.1.2.3
Draft-Version:	1.6
Draft-Modified:	2006-06-20
Draft-Modified:	2006-12-12
Draft-Discuss:	TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>

Draft
TinyOS-Version:	All
Authors:	Philippe Bonnet - David Culler - Deborah Estrin - Ramesh Govindan - Mike Horton - Jeonghoon Kang - Philip Levis - Lama Nachman - Jack Stankovic - Rob Szewczyk - Matt Welsh - Adam Wolisz
Author:	Philippe Bonnet
Author:	David Culler
Author:	Deborah Estrin
Author:	Ramesh Govindan
Author:	Mike Horton
Author:	Jeonghoon Kang
Author:	Philip Levis
Author:	Lama Nachman
Author:	Jack Stankovic
Author:	Rob Szewczyk
Author:	Matt Welsh
Author:	Adam Wolisz
Draft-Created:	17-April-2006
Draft-Version:	1.1.2.5
Draft-Version:	1.5
Draft-Modified:	2006-10-25
Draft-Modified:	2006-12-12
Draft-Discuss:	TinyOS Alliance <tinyos-alliance at mail.millennium.berkeley.edu>

Jonathan Hui, Philip Levis, and David Moss
Draft-Created:	2-Feb-2007
Draft-Version:	1.1
Draft-Version:	1.2
Draft-Modified:	2007-04-03
Draft-Modified:	2007-04-09
Draft-Discuss:	TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>

David Moss, Jonathan Hui, Philip Levis, and Jung Il Choi
Draft-Created:	5-Mar-2007
Draft-Version:	1.1
Draft-Version:	1.3
Draft-Modified:	2007-03-23
Draft-Modified:	2007-04-20
Draft-Discuss:	TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>

TinyOS 2.0 Overview

@@ -295,14 +294,15 @@ ul.auto-toc {

Oct 30 2006

Note

This document gives a brief overview of TinyOS 2.0, highlighting how and where it departs from 1.1 and 1.0. Further detail on these changes is detailed in TEP (TinyOS Enhancement Proposal) documents.

1. Introduction

TinyOS 2.0 is a clean slate redesign and re-implementation of TinyOS. Its development was motivated by our belief that many aspects of 1.x strain to meet requirements and uses that were not foreseen @@ -323,8 +323,8 @@ the scheduler, booting and initialization. Further detail on each of these can be found in TEPs (TinyOS Enhancement Proposals), which document and describe these abstractions.

2. Platforms/Hardware Abstraction

Platforms exist in the tos/platforms subdirectory. In TinyOS 2.0, a platform is a collection of chips and some glue code that connects them together. For example, the mica2 platform is the CC1000 radio @@ -377,8 +377,8 @@ the following platforms:

The btnode3 platform is not included in the RPM.

3. Scheduler

As with TinyOS 1.x, TinyOS 2.0 scheduler has a non-preemptive FIFO policy. However, tasks in 2.0 operate slightly differently than in 1.x.

@@ -406,8 +406,8 @@ however, or the scheduler will break all nesC's static concurrency analysis. Details on the new scheduler and how to extend it can be found in TEP 106: Schedulers and Tasks[TEP106].

4. Booting/Initialization

TinyOS 2.0 has a different boot sequence than 1.x. The 1.x interface StdControl has been split into two interfaces: Init and StdControl. The latter only has two commands: start and stop. @@ -420,13 +420,13 @@ handles this event and start services accordingly. Details on the new boot sequence can be found in TEP 107: TinyOS 2.x Boot Sequence[TEP107].

5. Virtualization

TinyOS 2.0 is written with nesC 1.2, which introduces the concept of a 'generic' or instantiable component. Generic modules allow TinyOS to have reusable data structures, such as bit vectors and queues, which simplify development. More importantly, generic -configurations allow services to encapsulate complex wiring +configurations allow services to encapsulate complex wiring relationships for clients that need them.

In practice, this means that many basic TinyOS services are now virtualized. Rather than wire to a component with a parameterized @@ -436,8 +436,8 @@ service component does all of the wiring underneath (e.g., in the case of timers, to a unique) automatically, reducing wiring mistakes and simplifying use of the abstraction.

6. Timers

TinyOS 2.0 provides a much richer set of timer interfaces than 1.x. Experience has shown that timers are one of the most critical abstractions a mote OS can provide, and so 2.0 expands the fidelity @@ -447,7 +447,7 @@ timers, and the timer system may provide one or two high-precision timers that fire asynchronously (they have the async keyword). Components can query their timers for how much time remainins before they fire, and can start timers in the future (e.g., -'start firing a timer at 1Hz starting 31ms from now'). TEP 102: +'start firing a timer at 1Hz starting 31ms from now'). TEP 102: Timers[TEP102] defines what HIL components a platform must provide in order to support standard TinyOS timers. Platforms are required to provide millisecond granularity timers, and can provide @@ -464,8 +464,8 @@ components App, new TimerMilliC(); App.Timer -> TimerMilliC;

7. Communication

In TinyOS 2.0, the message buffer type is message_t, and it is a buffer that is large enough to hold a packet from any of a node's communication interfaces. The structure itself is completely opaque: @@ -486,8 +486,8 @@ active message layer as ActiveMessageC.

communication. Instead, a component should wire to SerialActiveMessageC, which provides active message communication over the serial port.

Active message communication is virtualized through four generic -components, which take the AM type as a parameter: AMSenderC, +

Active message communication is virtualized through four generic +components, which take the AM type as a parameter: AMSenderC, AMReceiverC, AMSnooperC, and AMSnoopingReceiverC. AMSenderC is virtualized in that the call to send() does not fail if some other component is sending (as it does with GenericComm in 1.x). Instead, @@ -495,9 +495,9 @@ it fails only if that particular AMSenderC already has a packet outstanding or if the radio is not in a sending state. Underneath, the active message system queues and sends these outstanding packets. This is different than the QueuedSendC approach of 1.x, in which there -is an N-deep queue that is shared among all senders. With N AMSenderC +is an N-deep queue that is shared among all senders. With N AMSenderC components, there is an N-deep queue where each sender has a single -reserved entry. This means that each AMSenderC receives +reserved entry. This means that each AMSenderC receives 1/n of the available post-MAC transmission opportunities, where n is the number of AMSenderC components with outstanding packets. In the worst case, n is the number of components; even when every @@ -510,8 +510,8 @@ found in TEP 116: Packet Protocols[TEP116

8. Sensors

In TinyOS 2.0, named sensor components comprise the HIL of a platform's sensors. TEP 114 describes a set of HIL data acquisition interfaces, such as Read, ReadStream, and Get, which sensors @@ -529,8 +529,8 @@ the organization of sensor boards can be found in TEP 109: Sensorboards[TEP109], and the details of the HIL sensor interfaces can be found in TEP 114: Source and Sink Independent Drivers[TEP114].

9. Error Codes

The standard TinyOS 1.x return code is result_t, whose value is either SUCCESS (a non-zero value) or FAIL (a zero value). While this makes conditionals on calls very easy to write (e.g., if (call @@ -542,7 +542,7 @@ commands and events define which error codes they may return and why.

different in 2.0. Calls that were once: if (call X.y()) { - busy = TRUE; + busy = TRUE; } now have their meanings reversed. In 1.x, the busy statement will execute @@ -554,30 +554,30 @@ if (call X.y() == SUCCESS) { }

-

-10. Arbitration + +10. Arbitration While basic abstractions, such as packet communication and timers, -can be virtualized, experiences with 1.x showed that some cannot +can be virtualized, experiences with 1.x showed that some cannot without either adding significant complexity or limiting the system. The most pressing example of this is a shared bus on a microcontroller. Many different systems -- sensors, storage, the radio -- might need to use the bus at the same time, so some way of arbitrating access is needed. -To support these kinds of abstractions, TinyOS 2.0 introduces + To support these kinds of abstractions, TinyOS 2.0 introduces the Resource interface, which components use to request and -acquire shared resources, and arbiters, which provide a policy for +acquire shared resources, and arbiters, which provide a policy for arbitrating access between multiple clients. For some abstractions, the arbiter also provides a power management policy, as it can tell when the system is no longer needed and can be safely turned off. TEP 108: Resource Arbitration[TEP108] describes the Resource interface and how arbiters work. -

-11. Power Management + +11. Power Management Power management in 2.0 is divided into two parts: the power state of the microcontroller and the power state of devices. The former, discussed in TEP 112: Microcontroller Power Management[TEP112], -is computed in a chip-specific manner by examining which devices +is computed in a chip-specific manner by examining which devices and interrupt souces are active. The latter, discussed in TEP 115: Power Management of Non-Virtualised Devices{TEP115], is handled through resource abiters. Fully virtualized services have their @@ -585,29 +585,29 @@ own, individual power management policies. TinyOS 2.0 provides low-power stacks for the CC1000 (mica2) and CC2420 (micaz, telosb, imote2) radios. Both use a low-power listening apporach, where transmitters send long preambles or -repeatedly send packets and receivers wake up periodically to -sense the channel to hear if there is a packet being +repeatedly send packets and receivers wake up periodically to +sense the channel to hear if there is a packet being transmitted. The low-power stack CC1000 is standard, while the CC2420 stack is experimental. That is, the default CC1000 -stack (chips/cc1000) has low-power-listening, while the default +stack (chips/cc1000) has low-power-listening, while the default CC2420 stack (chips/cc2420) does not. To use the low-power CC2420 stack, you must include chips/cc2420_lpl in your application Makefile. -

-12. Network Protocols -TinyOS 2.0 provides simple reference implementations of two of + +12. Network Protocols +TinyOS 2.0 provides simple reference implementations of two of the most basic protocols used in mote networks: dissemination -and collection. Dissemination reliably delivers small (fewer +and collection. Dissemination reliably delivers small (fewer than 20 byte) data items to every node in a network, while collection builds a routing tree rooted at a sink node. Together, these two protocols enable a wide range of data collection applications. Collection has advanced significantly since the -most recent beta release; experimental tests in multiple +most recent beta release; experimental tests in multiple network conditions have seen very high (>98%) deliver rates as long as the network is not saturated. -

-13. Conclusion + +13. Conclusion TinyOS 2.0 represents the next step of TinyOS development. Building on user experiences over the past few years, it has taken the basic TinyOS architecture and pushed it forward in several directions, @@ -616,19 +616,19 @@ still under active development: future prereleases will include non-volatile storage, basic multihop protocols (collection routing, dissemination), and further power management abstractions. -

-14. Acknowledgments + +14. Acknowledgments TinyOS 2.0 is the result of a lot of hard work from a lot of people, -including (but not limited to) David Gay, Philip Levis, Cory Sharp, -Vlado Handziski, Jan Hauer, Kevin Klues, Joe Polastre, Jonathan Hui, -Prabal Dutta, -Gilman Tolle, Martin Turon, Phil Buonodonna, Ben Greenstein, David Culler, -Kristin Wright, Ion Yannopoulos, Henri Dubois-Ferriere, Jan Beutel, +including (but not limited to) David Gay, Philip Levis, Cory Sharp, +Vlado Handziski, Jan Hauer, Kevin Klues, Joe Polastre, Jonathan Hui, +Prabal Dutta, +Gilman Tolle, Martin Turon, Phil Buonodonna, Ben Greenstein, David Culler, +Kristin Wright, Ion Yannopoulos, Henri Dubois-Ferriere, Jan Beutel, Robert Szewczyk, Rodrigo Fonseca, Kyle Jamieson, Omprakash Gnawali, David Moss, and Kristin Wright. -

-15. Author's Address + +15. Author's Address Philip Levis 358 Gates @@ -641,8 +641,8 @@ David Moss, and Kristin Wright. email - pal@cs.stanford.edu -

-16. Citations +

+16. Citations diff --git a/doc/html/porting.html b/doc/html/porting.html index be841068..dfc638f3 100644 --- a/doc/html/porting.html +++ b/doc/html/porting.html @@ -3,7 +3,7 @@ - +Porting TinyOS 1.x Code to TinyOS 2.0 @@ -284,7 +284,6 @@ ul.auto-toc { - Porting TinyOS 1.x Code to TinyOS 2.0 @@ -296,17 +295,18 @@ ul.auto-toc { October 26 2006 + Note -This document provides a few important points that describe + This document provides a few important points that describe major steps required for porting TinyOS 1.x code to TinyOS 2.0. It is based on Tahir Azim's experience porting Beacon Vector Routing (BVR[1]) from TinyOS 1.x to T2. This document is not a complete porting guide, but the hope is that it will provide some help or guidance. - -1. Porting Points + +1. Porting Points As these observations come from porting a network protocol, they are rather protocol-centric and do not consider other abstractions such as storage. We hope to add such points in the future. @@ -322,7 +322,7 @@ if (call Packet...) { In TinyOS 2.x, SUCCESS is equal to a zero error code, while other error codes are non-zero. So calls like this should be changed to make sure they test the result for equality with SUCCESS: -if (call Packet... () == SUCCESS ) { +if (call Packet... () == SUCCESS ) { //SUCCESS!: do this... } @@ -342,8 +342,8 @@ if (call Packet... () == SUCCESS ) { - -2. Author's Address + +2. Author's Address Tahir Azim 358 Gates Hall @@ -364,8 +364,8 @@ if (call Packet... () == SUCCESS ) { email - pal@cs.stanford.edu - -3. Citations + +3. Citations diff --git a/doc/html/tep1.html b/doc/html/tep1.html index 4222ee20..2d2068b5 100644 --- a/doc/html/tep1.html +++ b/doc/html/tep1.html @@ -3,7 +3,7 @@ - +TEP Structure and Keywords - TEP Structure and Keywords @@ -303,28 +302,29 @@ ul.auto-toc { - + - + Philip Levis Draft-Created: 18-Oct-2004 Draft-Version: 1.1.2.5 Draft-Version: 1.5 Draft-Modified: 2006-10-19 Draft-Modified: 2006-12-12 Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu> + Note This document specifies a Best Current Practices for the TinyOS Community, and requests discussion and suggestions for improvements. Distribution of this memo is unlimited. - -Abstract + +Abstract This memo describes the structure all TinyOS Extension Proposal (TEP) documents follow, and defines the meaning of several key words in those documents. - -1. Introduction + +1. Introduction In order to simplify management, reading, and tracking development, all TinyOS Extension Proposals (TEPs) MUST have a particular structure. Additionally, to simplify development and improve @@ -332,40 +332,40 @@ implementation interoperability, all TEPs MUST observe the meaning of several key words that specify levels of compliance. This document describes and follows both. - -2. Keywords + +2. Keywords The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in TEP 1. Note that the force of these words is modified by the requirement level of the document in which they are used. - -2.1 MUST + +2.1 MUST MUST: This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification. - -2.2 MUST NOT + +2.2 MUST NOT MUST NOT: This phrase, or the phrase "SHALL NOT", mean that the definition is an absolute prohibition of the specification. - -2.3 SHOULD + +2.3 SHOULD SHOULD: This word, or the adjective "RECOMMENDED", mean that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course. - -2.4 SHOULD NOT + +2.4 SHOULD NOT SHOULD NOT: This phrase, or the phrase "NOT RECOMMENDED" mean that there may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label. - -2.5 MAY + +2.5 MAY MAY: This word, or the adjective "OPTIONAL", mean that an item is truly optional. One implementer may choose to include the item because a particular application requires it or because the @@ -378,8 +378,8 @@ does include a particular option MUST be prepared to interoperate with another implementation which does not include the option (except, of course, for the feature the option provides.) - -2.6 Guidance in the use of these Imperatives + +2.6 Guidance in the use of these Imperatives Imperatives of the type defined in this memo must be used with care and sparingly. In particular, they MUST only be used where it is actually required for interoperation or to limit behavior which has @@ -389,21 +389,21 @@ on implementors where the method is not required for interoperability. - -3. TEP Structure + +3. TEP Structure TEPs have two major parts, a header and a body. The header states -document metadata, for management and status. The body contains the +document metadata, for management and status. The body contains the content of the proposal. -All TEPs MUST follow the TEP docutils template, and conform to -reStructuredText standards [1], to enable translation from + All TEPs MUST follow the TEP docutils template, and conform to +reStructuredText standards [1], to enable translation from reStructuredText to HTML and Latex. - -3.1 TEP Header + +3.1 TEP Header The TEP header has several fields which MUST be included, as well as others which MAY be included. The first six header fields MUST be included in all TEPs, in the order stated here. The first field is "TEP," and specifies the TEP number of the -document. A TEP's number is unique.. This document is TEP 1. The +document. A TEP's number is unique.. This document is TEP 1. The TEP type (discussed below) determines how a number is assigned to it. Generally, when a document is ready to be a TEP, it is assigned the smallest available number. @@ -421,7 +421,7 @@ authors. Developers desiring to add code (or TEPs) to TinyOS SHOULD follow all current BCPs. Documentary TEPs describe a system or protocol that exists; a documentary TEP MUST reference an implementation that a reader can -easily obtain. Documentary TEPs simplify interoperability when +easily obtain. Documentary TEPs simplify interoperability when needed, and document TinyOS service implementations. Informational TEPs provide information that is of interest to the community. Informational TEPs include data gathered on radio behavior, @@ -430,12 +430,12 @@ organizational and logistic information, or experiences which could help the community achieve its goals. Experimental TEPs describe a completely experimental approach to a problem, which are outside the TinyOS core and will not necessarily -become part of it. Unlike Documentary TEPs, Experimental TEPs may +become part of it. Unlike Documentary TEPs, Experimental TEPs may describe systems that do not have a reference implementation. The fourth field is "Status," which specifies the status of the TEP. A TEP status can either be "Draft," which means it is a work in -progress, "Final," which means it is complete and will not change. -Once a TEP has the status "Final," its body MUST NOT change. +progress, "Final," which means it is complete and will not change. +Once a TEP has the status "Final," its body MUST NOT change. The values of its header fields MUST NOT change. The header of a Final TEP MAY have an "Obsoleted By" field added. The "Obsoletes" field is a backward pointer to an earlier TEP which @@ -463,7 +463,7 @@ here (see Section 3.2). There is an optional field, "Extends." The "Extends" field refers to another TEP. The purpose of this field is to denote when a TEP represents an addition to an existing TEP. Meeting the requirements of a TEP with an -Extends field requires also meeting the requirements of all TEPs listed +Extends field requires also meeting the requirements of all TEPs listed in the Extends field. If a TEP is a Draft, then four additional fields MUST be included: Draft-Created, Draft-Modified, Draft-Version, and Draft-Discuss. @@ -474,8 +474,8 @@ made. Draft-Discuss specifies the email address of a mailing list where the draft is being discussed. Final and Obsolete TEPs MUST NOT have these fields, which are for Drafts only. - -3.2 TEP Body + +3.2 TEP Body The first element of the TEP body MUST be the title of the document. A TEP SHOULD follow the title with an Abstract, which gives a brief overview of the content of the TEP. Longer TEPs MAY, after the @@ -493,17 +493,17 @@ entitled "Author's Address" or "Author's Addresses" MUST con detailed author contact information. - -4. Reference + +4. Reference The reference use of this document is TEP 1 (itself). - -5. Acknowledgments + +5. Acknowledgments The definitions of the compliance terms are a direct copy of definitions taken from IETF RFC 2119. - -6. Author's Address + +6. Author's Address Philip Levis 467 Soda Hall @@ -515,8 +515,8 @@ definitions taken from IETF RFC 2119. email - pal@cs.berkeley.edu - -7. Citations + +7. Citations diff --git a/doc/html/tep101.html b/doc/html/tep101.html index 48aa1ac7..f022ddfd 100644 --- a/doc/html/tep101.html +++ b/doc/html/tep101.html @@ -3,7 +3,7 @@ - +Analog-to-Digital Converters (ADCs) - Analog-to-Digital Converters (ADCs) @@ -303,6 +302,7 @@ ul.auto-toc { Jan-Hinrich Hauer, Philip Levis, Vlado Handziski, David Gay + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -310,15 +310,15 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with [TEP1]. - -Abstract + +Abstract This TEP proposes a hardware abstraction for analog-to-digital converters (ADCs) in TinyOS 2.x, which is aligned to the three-layer Hardware Abstraction Architecture (HAA) specified in [TEP2]. It describes some design principles and documents the set of hardware-independent interfaces to an ADC. - -1. Introduction + +1. Introduction Analog-to-digital converters (ADCs) are devices that convert analog input signals to discrete digital output signals, typically voltage to a binary number. The interested reader can refer to Appendix A for a brief overview of @@ -421,31 +421,31 @@ provides access to the hardware registers (see the set of standard TinyOS interfaces for collecting ADC conversion results and for configuring an ADC (2. Interfaces) -guidelines on how an ADC's HAL should expose chip-specific + guidelines on how an ADC's HAL should expose chip-specific interfaces (3. HAL guidelines) what components an ADC's HIL MUST implement (4. HIL requirements) -guidelines on how the HIL should be implemented + guidelines on how the HIL should be implemented (5. HIL guidelines) a section pointing to current implementations (6. Implementation) This TEP ends with appendices documenting, as an example, the ADC implementation for the TI MSP430 MCU. - -2. Interfaces + +2. Interfaces This TEP proposes the AdcConfigure interface for ADC hardware configuration and the Read, ReadStream and ReadNow interfaces to acquire conversion results. The Read and ReadStream interfaces are documented in [TEP114] and the ReadNow interface is documented in this TEP. A Read[Now|Stream] interface is always provided in conjunction with a AdcConfigure interface. - -Interface for configuring the ADC hardware + +Interface for configuring the ADC hardware The AdcConfigure interface is defined as follows: -interface AdcConfigure< config_type > +interface AdcConfigure< config_type > { - async command config_type getConfiguration(); + async command config_type getConfiguration(); } This interface is used by the ADC stack to retrieve the hardware configuration @@ -468,8 +468,8 @@ The rationale is that the ADC HIL implementation does not have to store an ADC configuration per client - instead the ADC client can, for example, store its configuration in program memory. - -Interfaces for acquiring conversion results + +Interfaces for acquiring conversion results This TEP proposes to adopt the following two source-independent data collection interfaces from [TEP114] for the collection of ADC conversion results on the level of HIL: @@ -488,24 +488,24 @@ requirements). As the resolution of conversion results is chip-specific, th size_type parameter reflects an upper bound for the chip-specific resolution of the conversion results - the actual resolution may be smaller (e.g. uint16_t for a 12-bit ADC). - -Read + +Read The Read interface can be used to sample an ADC channel once and return a single conversion result as an uninterpreted value. The Read interface is documented in [TEP114]. - -ReadStream + +ReadStream The ReadStream interface can be used to sample an ADC channel multiple times with a specified sampling period. The ReadStream interface is documented in [TEP114] . - -ReadNow + +ReadNow The ReadNow interface is intended for split-phase low-latency reading of small values: -interface ReadNow<val_t> +interface ReadNow<val_t> { async command error_t read(); async event void readDone( error_t result, val_t val ); @@ -525,16 +525,16 @@ component. - -3. HAL guidelines + +3. HAL guidelines As explained in 1. Introduction the HAL exposes the full capabilities of the ADC hardware. Therefore only chip- and platform-dependent clients can wire to the HAL. Although the HAL is chip-specific, both, in terms of implementation and representation, its design should follow the guidelines described in this section to facilitate the mapping to the HIL representation. Appendix B shows the signature of the HAL for the MSP430. - -Resource reservation + +Resource reservation As the ADC hardware is a shared resource that is usually multiplexed between several clients some form of access arbitration is necessary. The HAL should therefore provide a parameterized Resource interface, instantiate a @@ -543,8 +543,8 @@ arbiter as described in Resource interface are the topic of [TEP108]. - -Configuration and sampling + +Configuration and sampling As the ADC hardware is a shared resource the HAL should support hardware configuration and sampling per client (although per-port configuration is possible, it is not recommended, because it forces all clients to use the same @@ -566,8 +566,8 @@ configuration data is passed as a pointer, the HAL component MUST NOT reference it after the return of the respective command. Appendix B shows the HAL interfaces for the MSP430. - -HAL virtualization + +HAL virtualization In order to hide wiring complexities and/or export only a subset of all ADC functions generic ADC wrapper components may be provided on the level of HAL. Such components can also be used to ensure that a sampling interface is always @@ -575,14 +575,14 @@ provided with a Resource - -4. HIL requirements + +4. HIL requirements The following generic components MUST be provided on all platforms that have an ADC: -AdcReadClientC -AdcReadNowClientC -AdcReadStreamClientC +AdcReadClientC +AdcReadNowClientC +AdcReadStreamClientC These components provide virtualized access to the HIL of an ADC. They are instantiated by an ADC client and provide/use the four interfaces described in @@ -592,8 +592,8 @@ TEP does not address the issue of how to deal with multiple ADCs on the same platform (the question of how to deal with multiple devices of the same class is a general one in TinyOS 2.x). Appendix C shows the AdcReadClientC for the MSP430. - -AdcReadClientC + +AdcReadClientC generic configuration AdcReadClientC() { provides { @@ -615,8 +615,8 @@ command. Note that both, size_ty placeholders and will be instantiated by the respective HIL implementation (for an example, see the AdcReadClientC for the MSP430 in Appendix C). - -AdcReadNowClientC + +AdcReadNowClientC generic configuration AdcReadNowClientC() { provides { @@ -647,8 +647,8 @@ to dynamically "pull" the client's ADC settings when it translates the instantiated by the respective HIL implementation (for an example how this is done for the AdcReadClientC see Appendix C). - -AdcReadStreamClientC + +AdcReadStreamClientC generic configuration AdcReadStreamClientC() { provides { @@ -668,8 +668,8 @@ will be instantiated by the respective HIL implementation (for an example how this is done for the AdcReadClientC see Appendix C). - -5. HIL guidelines + +5. HIL guidelines The HIL implementation of an ADC stack has two main tasks: it translates a Read, ReadNow or ReadStream request to a chip-specific HAL sampling command and it abstracts from the Resource interface (the latter only for @@ -699,18 +699,18 @@ check ownership of the client through the ReadNow client. - -6. Implementation - -TestAdc application + +6. Implementation + +TestAdc application An ADC HIL test application can be found in tinyos-2.x/apps/tests/TestAdc. Note that this application instantiates generic DemoSensorC, DemoSensorStreamC and DemoSensorNowC components (see [TEP114]) and assumes that these components are actually wired to an ADC HIL. Please refer to tinyos-2.x/apps/tests/TestAdc/README.txt for more information. - -HAA on the MSP430 and Atmega 128 + +HAA on the MSP430 and Atmega 128 The implementation of the ADC12 stack on the MSP430 can be found in tinyos-2.x/tos/chips/msp430/adc12: @@ -730,7 +730,7 @@ HAL virtualization components are explained in HplAtm128AdcC.nc is the HPL implementation Atm128AdcP.nc is the HAL implementation -AdcP.nc, WireAdcP.nc and the library components for arbitrating + AdcP.nc, WireAdcP.nc and the library components for arbitrating 'Read', 'ReadNow' and 'ReadStream', ArbitratedReadC and ArbitratedReadStreamC (in tinyos-2.x/tos/system), realize the HIL @@ -740,8 +740,8 @@ the HIL - -Appendix A: Hardware differences between platforms + +Appendix A: Hardware differences between platforms The following table compares the characteristics of two microcontrollers commonly used in TinyOS platforms: @@ -751,9 +751,9 @@ commonly used in TinyOS platforms: - - - + + + @@ -870,8 +870,8 @@ sequence conversion Atmel Atmega 128 TI MSP430 ADC12 Atmel Atmega 128 TI MSP430 ADC12 - -Appendix B: a HAL representation: MSP430 ADC12 + +Appendix B: a HAL representation: MSP430 ADC12 This section shows the HAL signature for the ADC12 of the TI MSP430 MCU. It reflects the four MSP430 ADC12 conversion modes as it lets a client sample an ADC channel once ("Single-channel-single-conversion") or repeatedly @@ -882,41 +882,41 @@ interrupt after multiple samples and thus enable high-frequency sampling. The DMAExtension interface is used to reset the state machine when the DMA is responsible for data transfer (managed in an exterior component): -configuration Msp430Adc12P -{ +configuration Msp430Adc12P +{ provides { - interface Resource[uint8_t id]; - interface Msp430Adc12SingleChannel as SingleChannel[uint8_t id]; + interface Resource[uint8_t id]; + interface Msp430Adc12SingleChannel as SingleChannel[uint8_t id]; interface AsyncStdControl as DMAExtension[uint8_t id]; } } -interface Msp430Adc12SingleChannel -{ +interface Msp430Adc12SingleChannel +{ async command error_t configureSingle(const msp430adc12_channel_config_t *config); async command error_t configureSingleRepeat(const msp430adc12_channel_config_t *config, uint16_t jiffies); async command error_t configureMultiple( const msp430adc12_channel_config_t *config, uint16_t buffer[], uint16_t numSamples, uint16_t jiffies); async command error_t configureMultipleRepeat(const msp430adc12_channel_config_t *config, uint16_t buffer[], uint8_t numSamples, uint16_t jiffies); async command error_t getData(); async event error_t singleDataReady(uint16_t data); - async event uint16_t* multipleDataReady(uint16_t buffer[], uint16_t numSamples); + async event uint16_t* multipleDataReady(uint16_t buffer[], uint16_t numSamples); } -typedef struct -{ - unsigned int inch: 4; // input channel - unsigned int sref: 3; // reference voltage - unsigned int ref2_5v: 1; // reference voltage level - unsigned int adc12ssel: 2; // clock source sample-hold-time - unsigned int adc12div: 3; // clock divider sample-hold-time +typedef struct +{ + unsigned int inch: 4; // input channel + unsigned int sref: 3; // reference voltage + unsigned int ref2_5v: 1; // reference voltage level + unsigned int adc12ssel: 2; // clock source sample-hold-time + unsigned int adc12div: 3; // clock divider sample-hold-time unsigned int sht: 4; // sample-hold-time - unsigned int sampcon_ssel: 2; // clock source sampcon signal + unsigned int sampcon_ssel: 2; // clock source sampcon signal unsigned int sampcon_id: 2; // clock divider sampcon signal } msp430adc12_channel_config_t; - -Appendix C: a HIL representation: MSP430 ADC12 + +Appendix C: a HIL representation: MSP430 ADC12 The signature of the AdcReadClientC component for the MSP430 ADC12 is as follows: diff --git a/doc/html/tep102.html b/doc/html/tep102.html index ce4a3bde..48f1aff2 100644 --- a/doc/html/tep102.html +++ b/doc/html/tep102.html @@ -3,7 +3,7 @@ - + Timers - Timers @@ -303,14 +302,15 @@ ul.auto-toc { - + - + Cory Sharp, Martin Turon, David Gay Draft-Created: 22-Sep-2004 Draft-Version: 1.1.2.9 Draft-Version: 1.7 Draft-Modified: 2006-10-18 Draft-Modified: 2006-12-12 Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu> + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -318,15 +318,15 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract + +Abstract 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). - -1. Introduction + +1. Introduction Most microcontrollers offer a rich timer system, with features like: several counters, possibly of different widths, with multiple clocking options @@ -340,7 +340,7 @@ the timer hardware on some current TinyOS platforms. 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: @@ -349,7 +349,7 @@ of this TEP specifies: events (2. Interfaces) guidelines on how each microcontroller's HAL SHOULD expose its timer hardware in terms of the above interfaces (3. HAL guidelines) -what components a microcontroller's timer HIL MUST implement + what components a microcontroller's timer HIL MUST implement (4. HIL requirements) a set of utility components whose use simplifies building the components specified by the HAL guidelines and HIL requirements (5. Utility components) @@ -357,13 +357,13 @@ specified by the HAL guidelines and HIL requirements (This TEP ends with appendices documenting, as an example, the mica2 timer subsystem implementation. - -2. Interfaces + +2. Interfaces 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). - -2.1 Precision, Width and Accuracy. + +2.1 Precision, Width and Accuracy. Three fundamental properties of timers are precision, width and accuracy. Examples of precision are millisecond, a cycle of a 32kHz clock, and @@ -404,8 +404,8 @@ typedef struct { } TMicro; // 1048576 ticks per second Note that the precision names are expressed as either frequency or period, whichever is convenient. - -2.2 Timer interfaces + +2.2 Timer interfaces This TEP proposes these timer interfaces: interface Counter< precision_tag, size_type > @@ -419,9 +419,9 @@ 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. - -Counter -A Counter component will increase the width of a low-level hardware timer + +Counter +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. @@ -439,24 +439,24 @@ interface Counter<precision_tag,size_type> } -get() +get() return the current time. -isOverflowPending() +isOverflowPending() 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. -clearOverflow() +clearOverflow() cancel the pending overflow interrupt clearing the overflow flag. -overflow() +overflow() signals that an overflow in the current time. That is, the current time has wrapped around from its maximum value to zero. - -Alarm + +Alarm 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 @@ -479,15 +479,15 @@ interface Alarm<precision_tag,size_type> } -start(dt) +start(dt) 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. -stop() +stop() cancel any previously running alarm. -fired() +fired() signals that the alarm has occurred. -isRunning() +isRunning() return TRUE if the alarm has been started and has not been cancelled or has not yet fired. FALSE is returned otherwise. @@ -499,9 +499,9 @@ 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. -getNow() +getNow() return the current time in the precision and width of the alarm. -getAlarm() +getAlarm() return the time the currently running alarm will fire or the time that the previously running alarm was set to fire. getAlarm can be used with startAt to set an alarm from the previous alarm time, @@ -509,8 +509,8 @@ as in startAt(getAlarm(),dt). This pattern is used within the fired() event to construct periodic alarms. - -BusyWait + +BusyWait 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 @@ -530,8 +530,8 @@ interface BusyWait<precision_tag,size_type> block until at least dt time units have elapsed - -LocalTime + +LocalTime The LocalTime interface exposes a 32-bit counter without overflow utilities. This is primarily for application code that does not care about overflow conditions. @@ -542,12 +542,12 @@ interface LocalTime<precision_tag> } -get() +get() return the current time. - -Timer + +Timer 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 @@ -572,44 +572,44 @@ interface Timer<precision_tag> } -startPeriodic(dt) +startPeriodic(dt) 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. -startOneShot(dt) +startOneShot(dt) 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. -stop() +stop() cancel any previously running timer. fired() signals that the timer has occurred. -isRunning() +isRunning() 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. -isOneShot() +isOneShot() return TRUE if the timer is a one-shot timer. Return FALSE otherwise if the timer is a periodic timer. -startPeriodicAt(t0,dt) +startPeriodicAt(t0,dt) 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. -startOneShotAt(t0,dt) +startOneShotAt(t0,dt) cancel any previously running timer and set to fire at time t1 = t0+dt. The timer will fire once then stop. -getNow() +getNow() return the current time in the precision and width of the timer. -gett0() +gett0() return the time anchor for the previously started timer or the time of the previous event for periodic timers. -getdt() +getdt() return the delay or period for the previously started timer. - -3. HAL guidelines + +3. HAL guidelines 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 @@ -654,15 +654,15 @@ are mutually incompatible in single application. Incompatible components SHOULD produce compile-time errors when compiled together. - -4. HIL requirements + +4. HIL requirements The following component MUST be provided on all platforms:: HilTimerMilliC BusyWaitMicroC - -HilTimerMilliC + +HilTimerMilliC configuration HilTimerMilliC { @@ -676,8 +676,8 @@ TimerMilli parameterised interface. UQ_TIMER_MILLI is defined in Timer.h. HilTimerMilliC is used by the generic component TimerMilliC found in tos/system/. - -BusyWaitMicroC + +BusyWaitMicroC configuration BusyWaitMicroC { @@ -690,8 +690,8 @@ delay is small and setting a timer or alarm would be impractical, inefficient or insufficiently precise. - -5. Utility components + +5. Utility components A number of platform independent generic components are provided to help implementers and advanced users of the TinyOS timer system: @@ -704,8 +704,8 @@ help implementers and advanced users of the TinyOS timer system: Appendices B and C show how these can be used to help implement the timer HAL and HIL. - -AlarmToTimerC + +AlarmToTimerC AlarmToTimerC converts a 32-bit Alarm to a Timer. generic component AlarmToTimerC( typedef precision_tag ) @@ -715,8 +715,8 @@ generic component AlarmToTimerC( typedef precision_tag ) } - -BusyWaitCounterC + +BusyWaitCounterC BusyWaitCounterC uses a Counter to block until a specified amount of time elapses. @@ -728,8 +728,8 @@ generic component BusyWaitC( typedef precision_tag, } - -CounterToLocalTimeC + +CounterToLocalTimeC CounterToLocalTimeC converts from a 32-bit Counter to LocalTime. generic component CounterToLocalTimeC( precision_tag ) @@ -739,12 +739,12 @@ generic component CounterToLocalTimeC( precision_tag ) } - -TransformAlarmC + +TransformAlarmC TransformAlarmC decreases precision and/or widens an Alarm. An already widened Counter component is used to help. -generic component TransformAlarmC( +generic component TransformAlarmC( typedef to_precision_tag, typedef to_size_type @integer(), typedef from_precision_tag, @@ -772,8 +772,8 @@ 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. - -TransformCounterC + +TransformCounterC TransformCounterC decreases precision and/or widens a Counter. generic component TransformCounterC( @@ -804,8 +804,8 @@ created: new TransformCounterC( TMilli, uint32_t, T32khz, uint16_t, 5, uint32_t ) - -VirtualizeTimerC + +VirtualizeTimerC VirtualizeTimerC uses a single Timer to create up to 255 virtual timers. @@ -818,8 +818,8 @@ generic component VirtualizeTimerC( typedef precision_tag, int max_timers ) - -6. Implementation + +6. Implementation The definition of the HIL interfaces are found in tinyos-2.x/tos/lib/timer: @@ -889,8 +889,8 @@ special function registers - -7. Author's Address + +7. Author's Address Cory Sharp Moteiv Corporation @@ -918,8 +918,8 @@ special function registers email - david.e.gay@intel.com - -Appendix A: Timer hardware on various microcontrollers + +Appendix A: Timer hardware on various microcontrollers Atmega128 @@ -995,8 +995,8 @@ output pin, clear counter, generate interrupt, etc) - -Appendix B: a microcontroller: Atmega 128 timer subsystem + +Appendix B: a microcontroller: Atmega 128 timer subsystem The Atmega128 exposes its four timers through a common set of interfaces: @@ -1026,7 +1026,7 @@ interface HplAtm128Timer<timer_size> 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 } @@ -1057,7 +1057,7 @@ interface HplAtm128Capture<size_type> /// 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 @@ -1095,8 +1095,8 @@ generic module Atm128CounterC(typedef frequency_tag, } ... - -Appendix C: a mote: Mica family timer subsystem + +Appendix C: a mote: Mica family timer subsystem 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 @@ -1118,7 +1118,7 @@ Timing accuracy is as good as the external crystal. 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 CounterOne16C and AlarmOne16C (rather than the CounterMicro16C AlarmMicro16C as suggested in Section 3). @@ -1139,7 +1139,7 @@ accuracy depends on how the mote is clocked: 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 CounterThree16C and AlarmThree16C. As +components are named CounterThree16C and AlarmThree16C. 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 Counter32khz32C and Alarm32khz32C. As with timer 1, three compare diff --git a/doc/html/tep103.html b/doc/html/tep103.html index b1c9de14..82fc95b3 100644 --- a/doc/html/tep103.html +++ b/doc/html/tep103.html @@ -3,7 +3,7 @@ - + Permanent Data Storage (Flash) - Permanent Data Storage (Flash) @@ -303,6 +302,7 @@ ul.auto-toc { David Gay, Jonathan Hui + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -310,14 +310,14 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract + +Abstract This memo documents a set of hardware-independent interfaces to non-volatile storage for TinyOS 2.x. It describes some design principles for the HPL and HAL layers of various flash chips. - -1. Introduction + +1. Introduction Flash chips are a form of EEPROM (electrically-erasable, programmable read-only memory), distinguished by a fast erase capability. However, erases can only be done in large units (from 256B to 128kB depending on the @@ -338,12 +338,12 @@ significantly different tradeoffs than other flash chips: -X -NOR +X +NOR (ex: ST M25P40, Intel PXA27x) -AT45DB - +AT45DB + NAND (ex: Samsung K9K1G08R0B) @@ -444,8 +444,8 @@ reimplemented for these other chips, in part because it does not support some applications (e.g., network reprogramming) very well. - -2. Storage in TinyOS 2.x + +2. Storage in TinyOS 2.x One approach to hiding the differences between different flash chips is to provide a disk-like, block interface (with, e.g., 512B blocks). This is the approach taken by compact flash cards. However, in the context of TinyOS, @@ -503,8 +503,8 @@ this framework. flash chips (Section 3), then describes the flash volumes and storage abstractions in detail (Section 4). - -3. HPL/HAL/HIL Architecture + +3. HPL/HAL/HIL Architecture The flash chip architecture follows the three-layer Hardware Abstraction Architecture (HAA), with each chip providing a presentation layer (HPL, Section 3.1), adaptation layer (HAL, Section 3.2) and @@ -515,8 +515,8 @@ family with a similar interface, the HAA SHOULD support all family members by relying, e.g., on platform-provided configuration information. Appendix A shows example HPL and HAL specifications for the AT45DB and ST M25P chip families. - -3.1 Hardware Presentation Layer (HPL) + +3.1 Hardware Presentation Layer (HPL) The flash HPL has a chip-dependent, platform-independent interface. The implementation of this HPL is platform-dependent. The flash HPL SHOULD be stateless. @@ -528,8 +528,8 @@ directory. If the flash chip implementation supports a family of flash chips, this directory MAY also contain a file describing the particular flash chip found on the platform. - -3.2 Hardware Adaptation Layer (HAL) + +3.2 Hardware Adaptation Layer (HAL) The flash HAL has a chip-dependent, platform-independent interface and implementation. Flash families with a common HPL SHOULD have a common HAL. Flash HAL's SHOULD expose a Resource interface and automatically @@ -538,8 +538,8 @@ provide a way to access the volume information specified by the programmer (see Section 3). This allows users to build new flash abstractions that interact cleanly with the rest of the flash system. - -3.3 Hardware Interface Layer (HIL) + +3.3 Hardware Interface Layer (HIL) Each flash chip MUST support at least one of the storage abstractions described in Section 4. These abstractions SHOULD be presented in components named ChipAbstractionC, e.g., At45dbLogStorageC. @@ -553,13 +553,13 @@ SHOULD redirect uses of Abstracti chip, based on the requested volume. - -4. Non-Volatile Storage Abstractions + +4. Non-Volatile Storage Abstractions The HIL implementations are platform-independent, but chip (family) dependent. They implement the three storage abstractions and volume structure discussed in the introduction. - -4.1. Volumes + +4.1. Volumes The division of the flash chip into fixed-size volumes is specified by an XML file that is placed in the application's directory (where one types 'make'). The XML file specifies the allocation as follows: @@ -597,8 +597,8 @@ components new BlockStorageC(VOLUME_DELUGE0); compile-time error since the symbol will be undefined. A volume MUST NOT be used with more than one storage abstraction instance. - -4.2 Large objects + +4.2 Large objects The motivating example for large objects is the transmission or long-term storage of large pieces of data. For instance, programs in a network-reprogramming system, or large data-packets in a reliable @@ -647,8 +647,8 @@ integrity of the BlockStorage data, but such support can easily be built by using the computeCrc command and storing the result in a well-defined location, and checking this CRC when desired. - -4.3 Logging + +4.3 Logging Event and result logging is a common requirement in sensor networks. Such logging should be reliable (a mote crash should not lose data). It should also be easy to extract data from the log, @@ -735,8 +735,8 @@ a single record. However, the guarantee that only whole records are lost is sufficient to ensure that applications do not to have worry about incomplete or inconsistent log entries. - -4.4 Small objects: + +4.4 Small objects: Sensor network applications need to store configuration data, e.g., mote identity, radio frequency, sample rates, etc. Such data is not large, but losing it may lead to a mote misbehaving or losing contact with the @@ -783,13 +783,13 @@ in the small object. definitions. - -5. Implementations + +5. Implementations An AT45DB implementation can be found in tinyos-2.x/tos/chips/at45db. An ST M25P implementation can be found in tinyos-2.x/tos/chips/stm25p. - -6. Authors' Addresses + +6. Authors' Addresses David Gay 2150 Shattuck Ave, Suite 1300 @@ -809,8 +809,8 @@ definitions. email - jhui@archedrock.com - -7. Citations + +7. Citations @@ -825,10 +825,10 @@ motes. (version 1.0)." - -Appendix A. HAA for some existing flash chips - -A.1 AT45DB + +Appendix A. HAA for some existing flash chips + +A.1 AT45DB The Atmel AT45DB family HPL is: configuration HplAt45dbC { @@ -878,8 +878,8 @@ copy. It also includes flush and sync operations to manage the cache. The At45dbVolume interface has operations to report volume size and map volume-relative pages to absolute pages. - -A.2 ST M25P + +A.2 ST M25P The ST M25P family HPL is: configuration Stm25pSpiC { @@ -912,13 +912,13 @@ volume-relative addresses. Clients of the ST M25P HAL must implement the obtain the volume id of each of its clients. - -Appendix B. Storage interfaces + +Appendix B. Storage interfaces These interfaces are presented briefly here for reference; please refer to the TinyOS documentation for a full description of the commands, events and their parameters. - -B.1 BlockStorage interfaces + +B.1 BlockStorage interfaces The BlockStorage interfaces are: interface BlockRead { @@ -947,8 +947,8 @@ interface BlockWrite { } - -B.2 ConfigStorage interfaces + +B.2 ConfigStorage interfaces The ConfigStorage interfaces are: interface Mount { @@ -973,8 +973,8 @@ interface ConfigStorage { } - -B.3 LogStorage interfaces + +B.3 LogStorage interfaces The LogStorage interfaces are: interface LogRead { diff --git a/doc/html/tep106.html b/doc/html/tep106.html index c50832f1..b7f83537 100644 --- a/doc/html/tep106.html +++ b/doc/html/tep106.html @@ -3,7 +3,7 @@ - + Schedulers and Tasks - Schedulers and Tasks @@ -303,6 +302,7 @@ ul.auto-toc { Philip Levis and Cory Sharp + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -310,13 +310,13 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract + +Abstract This memo documents the structure and implementation of tasks and task schedulers in TinyOS 2.x. - -1. Introduction + +1. Introduction TinyOS has two basic computational abstractions: asynchronous events and tasks. Early versions of TinyOS provided a single type of task -- parameter free -- and only a FIFO scheduling policy. While changing @@ -328,8 +328,8 @@ available. TinyOS 2.0 takes both approaches, and this memo documents the structure of how it does so as well as a simple mechanism that greatly increases system dependability. - -2. Tasks and the Scheduler in TinyOS 1.x + +2. Tasks and the Scheduler in TinyOS 1.x Tasks in TinyOS are a form of deferred procedure call (DPC) [1], which enable a program to defer a computation or operation until a later time. TinyOS tasks run to completion and do not pre-empt one @@ -340,8 +340,8 @@ are atomic with respect to other tasks task declarations and post expressions: task void computeTask() { - // Code here -} + // Code here +} and: @@ -398,28 +398,28 @@ application component does not try to send another packet until it knows the one it is sending completes (so it can re-use the buffer). As the sendDone() event was lost, this does not occur, and the application stops sending network traffic. -The solution to this particular problem in TinyOS 1.x is to signal -sendDone() in the radio send complete interrupt if the post fails: -this violates the sync/async boundary, but the justification is that -a possible rare race condition is better than certain failure. + The solution to this particular problem in TinyOS 1.x is to signal +sendDone() in the radio send complete interrupt if the post fails: +this violates the sync/async boundary, but the justification is that +a possible rare race condition is better than certain failure. Another solution would be to use an interrupt source to periodically retry posting the task; while this does not break the sync/async -boundary, until the post succeeds the system cannot send packets. +boundary, until the post succeeds the system cannot send packets. The TinyOS 1.x model prevents it from doing any better. - -3. Tasks in TinyOS 2.x + +3. Tasks in TinyOS 2.x The semantics of tasks in TinyOS 2.x are different than those in 1.x. This change is based on experiences with the limitations and run time errors that the 1.x model introduces. In TinyOS 2.x, a basic post will -only fail if and only if the task has already been posted and has not -started execution. A task can always run, but can only have one +only fail if and only if the task has already been posted and has not +started execution. A task can always run, but can only have one outstanding post at any time. 2.x achieves these semantics by allocating one byte of state per task (the assumption is that there will be fewer than 255 -tasks in the system). While a very large number of tasks could make +tasks in the system). While a very large number of tasks could make this overhead noticable, it is not significant in practice. -If a component needs to post a task several times, then the end of +If a component needs to post a task several times, then the end of the task logic can repost itself as need be. For example, one can do this: @@ -429,7 +429,7 @@ task void processTask() { // do work if (moreToProcess) { post processTask(); - } + } } These semantics prevent several problems, such as the inability to @@ -447,15 +447,15 @@ and an event, run. Th up to the interface. For example, a task interface that allows a task to take an integer parameter could look like this: -interface TaskParameter { - async error_t command postTask(uint16_t param); - event void runTask(uint16_t param); -} +interface TaskParameter { + async error_t command postTask(uint16_t param); + event void runTask(uint16_t param); +} Using this task interface, a component could post a task with a uint16_t parameter. When the scheduler runs the task, it will signal the runTask event with the passed parameter, which contains -the task's logic. Note, however, that this does not save any RAM: +the task's logic. Note, however, that this does not save any RAM: the scheduler must have RAM allocated for the parameter. Furthermore, as there can only be one copy of a task outstanding at any time, it is just as simple to store the variable in the component. E.g., @@ -475,7 +475,7 @@ uint16_t param; post parameterTask(); ... task void parameterTask() { - // use param + // use param } The principal difference between the simplest code for these @@ -490,8 +490,8 @@ if (post myTask() == SUCCESS) { } - -4. The Scheduler in TinyOS 2.x + +4. The Scheduler in TinyOS 2.x In TinyOS 2.x, the scheduler is a TinyOS component. Every scheduler MUST support nesC tasks. It MAY also support any number of additional task interfaces. The scheduler component is resonsible for @@ -507,29 +507,29 @@ function to obtain a unique identifier, which the scheduler uses to dispatch tasks. For example, the standard TinyOS scheduler has this signature: -module SchedulerBasicP { - provides interface Scheduler; - provides interface TaskBasic[uint8_t taskID]; - uses interface McuSleep; -} +module SchedulerBasicP { + provides interface Scheduler; + provides interface TaskBasic[uint8_t taskID]; + uses interface McuSleep; +} A scheduler MUST provide a parameterized TaskBasic interface. If a call to TaskBasic.postTask() returns SUCCESS, the scheduler MUST run it -eventually, so that starvation is not a concern. The scheduler MUST +eventually, so that starvation is not a concern. The scheduler MUST return SUCCESS to a TaskBasic.postTask() operation unless it is not the first call to TaskBasic.postTask() since -that task's TaskBasic.runTask() event has been signaled. The +that task's TaskBasic.runTask() event has been signaled. The McuSleep interface is used for microcontroller power management; its workings are explained in TEP 112 [3]. -A scheduler MUST provide the Scheduler interface. + A scheduler MUST provide the Scheduler interface. The Scheduler interface has commands for initialization and running tasks, and is used by TinyOS to execute tasks: -interface Scheduler { - command void init(); - command bool runNextTask(bool sleep); - command void taskLoop(); -} +interface Scheduler { + command void init(); + command bool runNextTask(bool sleep); + command void taskLoop(); +} The init() command initializes the task queue and scheduler data structures. runNextTask() MUST run to completion whatever task the @@ -549,17 +549,17 @@ within the scheduler improves the efficiency of the task loop, in terms of the assembly generated by the TinyOS toolchain. This is the TaskBasic interface: -interface TaskBasic { - async command error_t postTask(); - void event runTask(); -} +interface TaskBasic { + async command error_t postTask(); + void event runTask(); +} When a component declares a task with the task keyword in nesC, it is implicitly declaring that it uses an instance of the TaskBasic interface: the task body is the runTask event. When a component uses the post keyword, it calls the postTask command. Each TaskBasic MUST be -wired to the scheduler with a unique identifier as its parameter. -The parameter MUST be obtained with the unique function in nesC, +wired to the scheduler with a unique identifier as its parameter. +The parameter MUST be obtained with the unique function in nesC, with a key of "TinySchedulerC.TaskBasic". The nesC compiler automatically does this wiring when the task and post keywords are used. @@ -572,8 +572,8 @@ components MUST NOT assume a FIFO policy. If two tasks must run in a particular temporal order, this order should be enforced by the earlier task posting the later task. - -5. Replacing the Scheduler + +5. Replacing the Scheduler The TinyOS scheduler is presented as a component named TinySchedulerC. The default TinyOS scheduler implementation is a module named SchedulerBasicP; the default scheduler component is a configuration @@ -586,41 +586,41 @@ scheduler implementations MUST provide a parameterize TaskBasic interface, as SchedulerBasicP does; this supports nesC post statements and task declarations and enables TinyOS core systems to operate properly. Generally, TinyOS core code needs to be able to run unchanged -with new scheduler implementations. All scheduler +with new scheduler implementations. All scheduler implementations MUST provide the Scheduler interface. For example, imagine a hypothetical scheduler that provides earliest deadline first tasks, which are provided through the TaskEdf interface: -interface TaskEdf { - async command error_t postTask(uint16_t deadlineMs); - event void runTask(); -} +interface TaskEdf { + async command error_t postTask(uint16_t deadlineMs); + event void runTask(); +} The scheduler implementation is named SchedulerEdfP, and provides both TaskBasic and TaskEdf interfaces: -module SchedulerEdfP { - provides interface Scheduler; - provides interface TaskBasic[uint8_t taskID]; - provides interface TaskEdf[uint8_t taskID]; -} +module SchedulerEdfP { + provides interface Scheduler; + provides interface TaskBasic[uint8_t taskID]; + provides interface TaskEdf[uint8_t taskID]; +} An application that wants to use SchedulerEdfP instead of SchedulerBasicP includes a configuration named TinySchedulerC, which exports all of SchedulerEdfP's interfaces: -configuration TinySchedulerC { - provides interface Scheduler; - provides interface TaskBasic[uint8_t taskID]; - provides interface TaskEdf[uint8_t taskID]; -} -implementation { - components SchedulerEdfP; - Scheduler = SchedulerEdf; - TaskBasic = SchedulerEdfP; - TaskEDF = SchedulerEdfP; -} +configuration TinySchedulerC { + provides interface Scheduler; + provides interface TaskBasic[uint8_t taskID]; + provides interface TaskEdf[uint8_t taskID]; +} +implementation { + components SchedulerEdfP; + Scheduler = SchedulerEdf; + TaskBasic = SchedulerEdfP; + TaskEDF = SchedulerEdfP; +} For a module to have an earliest deadline first task, it uses the TaskEdf interface. Its configuration SHOULD wire it to TinySchedulerC. @@ -634,14 +634,14 @@ is to #define it. For example, TaskEdf.nc might include: In this example, the module SomethingP requires two EDF tasks: -configuration SomethingC { - ... -} -implementation { - components SomethingP, TinySchedulerC; - SomethingP.SendTask -> TinySchedulerC.TaskEdf[unique(UQ_TASK_EDF)]; - SomethingP.SenseTask -> TinySchedulerC.TaskEdf[unique(UQ_TASK_EDF)]; -} +configuration SomethingC { + ... +} +implementation { + components SomethingP, TinySchedulerC; + SomethingP.SendTask -> TinySchedulerC.TaskEdf[unique(UQ_TASK_EDF)]; + SomethingP.SenseTask -> TinySchedulerC.TaskEdf[unique(UQ_TASK_EDF)]; +} The module SomethingP also has a basic task. The nesC compiler automatically transforms task keywords into BasicTask interfaces and @@ -651,55 +651,55 @@ interface. A component SHOULD use the keywords whenever possible, and it MUST NOT mix the two syntaxes for a given task. This is an example implementation of SomethingP that uses keywords for basic tasks: -module SomethingP { - uses interface TaskEdf as SendTask - uses interface TaskEdf as SenseTask -} -implementation { - // The TaskBasic, written with keywords - task void cleanupTask() { ... some logic ... } - event void SendTask.runTask() { ... some logic ... } - event void SenseTask.runTask() { ... some logic ... } - - void internal_function() { - call SenseTask.postTask(20); - call SendTask.postTask(100); - post cleanupTask(); - } -} +module SomethingP { + uses interface TaskEdf as SendTask + uses interface TaskEdf as SenseTask +} +implementation { + // The TaskBasic, written with keywords + task void cleanupTask() { ... some logic ... } + event void SendTask.runTask() { ... some logic ... } + event void SenseTask.runTask() { ... some logic ... } + + void internal_function() { + call SenseTask.postTask(20); + call SendTask.postTask(100); + post cleanupTask(); + } +} The requirement that basic tasks not be subject to starvation requires that a scheduler supporting EDF tasks must ensure that basic tasks run eventually even if there is an unending stream of short deadline tasks to run. Quantifying "eventually" is difficult, -but a 1% share of the MCU cycles (or invocations) is a reasonable +but a 1% share of the MCU cycles (or invocations) is a reasonable approximation. If the scheduler provides two instances of the same task interface, -their unique keys are based on the name of the interface as the +their unique keys are based on the name of the interface as the scheduler presents it (the "as" keyword). For example, imagine a scheduler which provides two instances of TaskBasic: standard tasks and high-priority tasks. The scheduler usually selects a task for the high priority queue before the standard queue: -configuration TinySchedulerC { - provides interface Scheduler; - provides interface TaskBasic[uint8_t taskID]; - provides interface TaskBasic[uint8_t taskID] as TaskHighPriority; -} +configuration TinySchedulerC { + provides interface Scheduler; + provides interface TaskBasic[uint8_t taskID]; + provides interface TaskBasic[uint8_t taskID] as TaskHighPriority; +} It cannot always select a high priority task because that could -starve basic tasks. A component that uses a high priority task would +starve basic tasks. A component that uses a high priority task would wire to TaskHighPriority with the key "TinySchedulerC.TaskHighPriority": -configuration SomethingElseC {} -implementation { - components TinySchedulerC as Sched, SomethingElseP; - SomethingElseP.RetransmitTask -> Sched.TaskHighPriority[unique("TinySchedulerC.TaskHighPriority")]; -} +configuration SomethingElseC {} +implementation { + components TinySchedulerC as Sched, SomethingElseP; + SomethingElseP.RetransmitTask -> Sched.TaskHighPriority[unique("TinySchedulerC.TaskHighPriority")]; +} - -6. Implementation + +6. Implementation The following files in tinyos-2.x/tos/system contain the reference implementations of the scheduler: @@ -713,15 +713,15 @@ that wires SchedulerBasicP to McuSleepC http://csl.stanford.edu/~pal/tinyos/edf-sched.tgz. - -7. Author's Address + +7. Author's Address Philip Levis 358 Gates Hall Stanford University Stanford, CA 94305 -phone - +1 650 725 9046 +phone - +1 650 725 9046 email - pal@cs.stanford.edu Cory Sharp @@ -732,12 +732,12 @@ at the URL http://csl.stanford.ed email - cssharp@eecs.berkeley.edu - -8. Citations + +8. Citations - @@ -759,8 +759,8 @@ Programming Language Design and Implementation (PLDI). [1] Erik Cota-Robles and James P. Held. "A Comparison of Windows + [1] Erik Cota-Robles and James P. Held. "A Comparison of Windows Driver Model Latency Performance on Windows NT and Windows 98." In Proceedings of the Third Symposium on Operating System Design and Implementation (OSDI). - -Appendix A: Changing the Scheduler + +Appendix A: Changing the Scheduler The nesC compiler transforms the post and task keywords into nesC interfaces, wirings, and calls. By default, the statement: @@ -771,7 +771,7 @@ implementation { task x() { ... post x(); - } + } } diff --git a/doc/html/tep107.html b/doc/html/tep107.html index ae4e210d..77316a12 100644 --- a/doc/html/tep107.html +++ b/doc/html/tep107.html @@ -3,7 +3,7 @@ - + TinyOS 2.x Boot Sequence - TinyOS 2.x Boot Sequence @@ -303,6 +302,7 @@ ul.auto-toc { Philip Levis + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -310,13 +310,13 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract + +Abstract This memo documents the structure and implementation of the mote boot sequence in TinyOS 2.x. - -1. Introduction + +1. Introduction TinyOS has a set of calling conventions and semantics in its boot sequence. Earlier versions of TinyOS used an interface named "StdControl" to take care of system initialization and starting @@ -330,8 +330,8 @@ initialization, one for starting and stopping components, and one for notification that the mote has booted. This memo describes the TinyOS boot sequence and reasons for its semantics. - -2. TinyOS 1.x Boot Sequence + +2. TinyOS 1.x Boot Sequence The TinyOS 1.x boot sequence is uniform across most mote platforms (TOSSIM has a very different boot sequence, as it is a PC program). The module RealMain implements main(), and has the following @@ -351,11 +351,11 @@ int main() __attribute__ ((C, spontaneous)) { call hardwareInit(); call Pot.init(10); TOSH_sched_init(); - + call StdControl.init(); call StdControl.start(); __nesc_enable_interrupt(); - + while(1) { TOSH_run_task(); } @@ -386,8 +386,8 @@ start/stop model. In this case, some components can't operate properly until the radio starts, but main has no mechanism for waiting for the radio start completion event. - -3. TinyOS 2.x Boot Interfaces + +3. TinyOS 2.x Boot Interfaces The TinyOS 2.x boot sequence uses three interfaces: @@ -408,7 +408,7 @@ range of components need to be interleaved effectively, initialization is a sequential, synchronous operation: no component can be started until initialization is complete. If a particular component's initialization requires waiting for interrupts or other asynchronous -events, then it must explicitly wait for them (e.g., +events, then it must explicitly wait for them (e.g., with a spin loop), MUST NOT return until complete. Otherwise the system may start before initialization is complete. The Scheduler interface is for initializing and controlling task @@ -421,8 +421,8 @@ interface Boot { } - -4. TinyOS 2.x Boot Sequence + +4. TinyOS 2.x Boot Sequence The module RealMainP implements the standard TinyOS 2.x boot sequence. The configuration MainC wires some of RealMainP's interfaces to components that implement standard abstractions and exports the others @@ -457,8 +457,8 @@ implementation { default event void Boot.booted() { } } - -4.1 Initialization + +4.1 Initialization The first step in the boot sequence is initializing the system: atomic { @@ -475,11 +475,11 @@ places the system into an executable state. This function MUST NOT include operations besides those which are absolutely necessary for further code, such as scheduler initialization, to execute. Examples of platform_bootstrap() operations are configuring the memory -system and setting the processor mode. Generally, platform_bootstrap() +system and setting the processor mode. Generally, platform_bootstrap() is an empty function. TinyOS's top-level include file, tos.h, includes a default implementation of this function which does nothing. If a platform needs to replace the default, it SHOULD put it in a platform's -platform.h file as a #define. The implementation of tos.h +platform.h file as a #define. The implementation of tos.h supports this: /* This platform_bootstrap macro exists in accordance with TEP @@ -499,7 +499,7 @@ configuration MainC { uses interface Init as SoftwareInit; } implementation { - components PlatformC, RealMainP, TinySchedulerC; + components PlatformC, RealMainP, TinySchedulerC; RealMainP.Scheduler -> TinySchedulerC; RealMainP.PlatformInit -> PlatformC; @@ -531,7 +531,7 @@ through PlatformC meet some or all of the following criteria: The initialization is a prerequisite for common services in the system. Three example operations that often belong in PlatformInit are I/O pin -configuration, clock calibration, and LED configuration. I/O pin +configuration, clock calibration, and LED configuration. I/O pin configuration meets the first two criteria. It should always be performed (regardless of what components the OS uses) for low-power reasons: incorrectly configured pins can draw current and prevent the MCU from @@ -540,13 +540,13 @@ all three criteria. LED configuration is a special case: while it nominally meets all three criteria, the most important one is the third: as LEDs are often needed during SoftwareInit initialization, they must be set up before it is invoked. -Note that not all code which meets some of these criteria is wired through -PlatformC. In particular, criterion 1 is typically necessary but not + Note that not all code which meets some of these criteria is wired through +PlatformC. In particular, criterion 1 is typically necessary but not sufficient to require PlatformC. For example, a timer system that configures overflow and capture settings or a UART stack that sets the baud rate and transmission options can often be wired to SoftwareInit. They are encapsulated abstractions which will not be invoked or -started until the boot event, and only need to be configured if the +started until the boot event, and only need to be configured if the system includes their functionality. Components whose initialization does not directly depend on hardware resources SHOULD wire to MainC.SoftwareInit. If a component requires a @@ -569,7 +569,7 @@ configuration TimerMilliP { implementation { components HilTimerMilliC, MainC; MainC.SoftwareInit -> HilTimerMilliC; - TimerMilli = HilTimerMilliC; + TimerMilli = HilTimerMilliC; } Rather than require an application to wire HilTimerMilliC to MainC, @@ -577,8 +577,8 @@ TimerMilliP does it automatically. When a component instantiates a TimerMilliC, that names TimerMilliP, which will automatically make sure that the timer system is initialized when TinyOS boots. - -4.2 Interrupts in Initialization + +4.2 Interrupts in Initialization Interrupts are not enabled until all calls to Init.init have returned. If a component's initialization needs to handle interrupts, it can do one of three things: @@ -605,7 +605,7 @@ flag) or to catch a brief edge transition. In these cases, a component can handle an interrupt in the boot sequence only if doing so will not cause any other component to handle an interrupt. As they have all been written assuming that interrupts are not enabled until after Init -completes, making one of them handle an interrupt could cause it to +completes, making one of them handle an interrupt could cause it to fail. Depending on what capabilities the hardware provides, there are several ways to meet these requirements. The simplest is to push these @@ -620,22 +620,22 @@ initialized unless it has initialized them, and MUST NOT call any functional interfaces on any components that might be shared or interact with shared resources. Components MAY call functions on other components that are completely internal to the subsystem. -For example, a networking layer can call queue operations to +For example, a networking layer can call queue operations to initialize its queue, but a link layer must not send commands over an SPI bus. An HAA component MAY make other calls to initialize hardware state. A component that is not part of an HAA SHOULD NOT call Init.init() on other components unless it needs to enforce a temporal ordering on initialization. -If a component A depends on another component, B, -which needs to be initialized, then A SHOULD wire B's Init directly + If a component A depends on another component, B, +which needs to be initialized, then A SHOULD wire B's Init directly to the boot sequence, unless there is a temporal ordering requirement to the initialization. The purpose of this convention is to simplify component initialization and the initialization sequence. - -5. Implementation + +5. Implementation The following files in tinyos-2.x/tos/system contain the reference implementations of the TinyOS boot sequence: @@ -646,8 +646,8 @@ PlatformC and TinySchedulerC - -6. Author's Address + +6. Author's Address Philip Levis 467 Soda Hall @@ -659,8 +659,8 @@ PlatformC and TinySchedulerC email - pal@cs.berkeley.edu - -7. Citations + +7. Citations diff --git a/doc/html/tep108.html b/doc/html/tep108.html index 84dc1cf2..e4c7083a 100644 --- a/doc/html/tep108.html +++ b/doc/html/tep108.html @@ -3,9 +3,13 @@ - +Resource Arbitration - + + + + + - Resource Arbitration @@ -299,14 +302,19 @@ ul.auto-toc { - - + + + + + + + + + + Final TinyOS-Version: 2.x Authors: Kevin Klues - Philip Levis - David Gay - David Culler - Vlado Handziski Author: Kevin Klues Author: Philip Levis Author: David Gay Author: David Culler Author: Vlado Handziski + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -314,14 +322,14 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract + +Abstract This memo documents the general resource sharing mechanisms for TinyOS 2.x. These mechanisms are used to allow multiple software components to arbitrate access to shared abstractions. - -1. Introduction + +1. Introduction TinyOS 1.x has two mechanisms for managing shared resources: virtualization and completion events. A virtualized resource appears as an independent instance of an abstraction, such as the Timer @@ -333,19 +341,19 @@ programs need the control provided by a physical abstraction. For example, components in 1.x share a single communication stack, GenericComm. GenericComm can only handle one outgoing packet at a time. If a component tries to send a packet when GenericComm is -already busy, then the call returns FAIL. The component needs a way to +already busy, then the call returns FAIL. The component needs a way to tell when GenericComm is free so it can retry. TinyOS 1.x provides the mechanism of a global completion event which is signaled whenever a packet send completes. Interested components can handle this event and retry. -This approach to physical (rather than virtualized) abstractions + This approach to physical (rather than virtualized) abstractions has several drawbacks: If you need to make several requests, you have to handle the -possibility of a request returning FAIL at any point. This complicates +possibility of a request returning FAIL at any point. This complicates implementations by adding internal states. You have no control over the timing of a sequence of operations. One -example of when this can be a problem is timing-sensitive use of an +example of when this can be a problem is timing-sensitive use of an A/D converter. You need a way to pre-reserve the use of the ADC so that its operations can be run at the exact moment they are desired. If a hardware resource supports reservation, you cannot express this @@ -356,7 +364,7 @@ but it is not clear how to use this in TinyOS 1.x's I2C abstraction. monitoring an abstraction's availability for the purpose of retries, nor very clear documentation of which requests could happen simultaneously. -It should be clear that a single approach to resource sharing is not appropriate + It should be clear that a single approach to resource sharing is not appropriate for all circumstances. For instance, requiring explicit reservation of a resource allows programs to have better timing guarantees for access to an A/D converter. If a program does not need precise timing guarantees, however (e.g., @@ -366,10 +374,10 @@ nicely using virtualization. The following section introduces the concept of resource classes in order to address this issue. The sharing policy used by a particular resource abstraction is dictated by the resource class it belongs to. - -2. Resource Classes -TinyOS 2.x distinguishes between three kinds of abstractions: -dedicated, virtualized, and shared. Components offer resource + +2. Resource Classes +TinyOS 2.x distinguishes between three kinds of abstractions: +dedicated, virtualized, and shared. Components offer resource sharing mechanisms appropriate to their goals and level of abstraction. Note @@ -379,45 +387,45 @@ inevitably requires state. Depending on their expected use, HPL abstractions can either be dedicated or shared. For example, while hardware timers are rarely multiplexed between multiple components, buses almost always are. -This can be seen on the MSP430 microcontroller, where the compare and -counter registers are implemented as dedicated resources, and the USARTs +This can be seen on the MSP430 microcontroller, where the compare and +counter registers are implemented as dedicated resources, and the USARTs are shared ones. - -2.1 Dedicated + +2.1 Dedicated An abstraction is dedicated if it is a resource -which a subsystem needs exclusive access to at all times. -In this class of resources, no sharing policy is needed since only +which a subsystem needs exclusive access to at all times. +In this class of resources, no sharing policy is needed since only a single component ever requires use of the resource. Examples of dedicated abstractions include interrupts and counters. -Dedicated abstractions MAY be annotated with the nesC attribute + Dedicated abstractions MAY be annotated with the nesC attribute @atmostonce or @exactlyonce to provide compile-time checks that their usage assumptions are not violated. -Please refer to Appendix A for an example of how a dedicated -resource might be represented, including the use of + Please refer to Appendix A for an example of how a dedicated +resource might be represented, including the use of the nesC @exactlyonce attribute. - -2.2 Virtualized + +2.2 Virtualized Virtual abstractions hide multiple clients from each other -through software virtualization. Every client of a virtualized resource +through software virtualization. Every client of a virtualized resource interacts with it as if it were a dedicated resource, with all virtualized instances being multiplexed on top of a single underlying resource. Because the virtualization is done in software, there is no upper bound on the number of clients using the abstraction, barring memory or efficiency constraints. -As virtualization usually requires keeping state that scales with the number -of virtualized instances, virtualized resources often use the Service Instance +As virtualization usually requires keeping state that scales with the number +of virtualized instances, virtualized resources often use the Service Instance pattern [3], which is based on a parameterized interface. -Virtualization generally provides a very simple interface to its clients. -This simplicity comes at the cost of reduced efficiency and an inability to + Virtualization generally provides a very simple interface to its clients. +This simplicity comes at the cost of reduced efficiency and an inability to precisely control the underlying resource. For example, a virtualized -timer resource introduces CPU overhead from dispatching and maintaining -each individual virtual timer, as well as introducing jitter whenever two -timers happen to fire at the same time. Please refer to Appendix A for an +timer resource introduces CPU overhead from dispatching and maintaining +each individual virtual timer, as well as introducing jitter whenever two +timers happen to fire at the same time. Please refer to Appendix A for an example of how such a virtualized timer resource might be implemented. - -2.3 Shared + +2.3 Shared Dedicated abstractions are useful when a resource is always controlled by a single component. Virtualized abstractions are useful when clients are willing to pay a bit of overhead and sacrifice @@ -426,7 +434,7 @@ situations, however, when many clients need precise control of a resource. Clearly, they can't all have such control at the same time: some degree of multiplexing is needed. A motivating example of a shared resource is a bus. -The bus may have multiple peripherals on it, corresponding to +The bus may have multiple peripherals on it, corresponding to different subsystems. For example, on the Telos platform the flash chip (storage) and the radio (network) share a bus. The storage and network stacks need exclusive access to the bus when using it, @@ -434,38 +442,38 @@ but they also need to share it with the other subsystem. In this case, virtualization is problematic, as the radio stack needs to be able to perform a series of operations in quick succession without having to reacquire the bus in each case. Having the bus be a -shared resource allows the radio stack to send a series of operations -to the radio atomically, without having to buffer them all up +shared resource allows the radio stack to send a series of operations +to the radio atomically, without having to buffer them all up in memory beforehand (introducing memory pressure in the process). In TinyOS 2.x, a resource arbiter is responsible for multiplexing -between the different clients of a shared resource. It determines -which client has access to the resource at which time. While a client -holds a resource, it has complete and unfettered control. Arbiters assume -that clients are cooperative, only acquiring the resource when needed -and holding on to it no longer than necessary. Clients explicitly +between the different clients of a shared resource. It determines +which client has access to the resource at which time. While a client +holds a resource, it has complete and unfettered control. Arbiters assume +that clients are cooperative, only acquiring the resource when needed +and holding on to it no longer than necessary. Clients explicitly release resources: there is no way for an arbiter to forcibly reclaim it. -The following section is dedicated to describing the arbiter and its +The following section is dedicated to describing the arbiter and its interfaces. - -3. Resource Arbiters + +3. Resource Arbiters Every shared resource has an arbiter to manage which client can use the resource at any given time. Because an arbiter is a centralized place that knows whether the resource is in use, it can also provide information useful for a variety of other services, such as power management. An arbiter MUST provide a parameterized Resource interface as well as an instance of the ArbiterInfo interface. The Resource -interface is instantiated by different clients wanting to gain access to a -resource. The ArbiterInfo interface is used by components that wish to -retrieve global information about the status of a resource (i.e. if it is in -use, who is using it, etc.). An arbiter SHOULD also provide a parameterized -ResourceRequested interface and use a parameterized ResourceConfigure interface. -It MAY also provide an instance of the ResourceDefaultOwner interface or -any additional interfaces specific to the particular arbitration policy +interface is instantiated by different clients wanting to gain access to a +resource. The ArbiterInfo interface is used by components that wish to +retrieve global information about the status of a resource (i.e. if it is in +use, who is using it, etc.). An arbiter SHOULD also provide a parameterized +ResourceRequested interface and use a parameterized ResourceConfigure interface. +It MAY also provide an instance of the ResourceDefaultOwner interface or +any additional interfaces specific to the particular arbitration policy being implemented. Each of these interfaces is explained in greater detail below: -Resource ArbiterInfo ResourceRequested ResourceDefaultOwner +Resource ArbiterInfo ResourceRequested ResourceDefaultOwner | | | | | | | | | \|/ \|/ | @@ -473,13 +481,13 @@ Resource ArbiterInfo ResourceRequested ResourceDefaultOwner |--------------| Arbiter |----------------------| /---------------\ | - | + | \|/ ResourceConfigure - -3.1 Resource -Clients of an arbiter request access + +3.1 Resource +Clients of an arbiter request access to a shared resource using the Resource interface: interface Resource { @@ -490,41 +498,41 @@ interface Resource { async command bool isOwner(); } -A client lets an arbiter know it needs access to a resource by + A client lets an arbiter know it needs access to a resource by making a call to request(). If the resource is free, -SUCCESS is returned, and a granted event is signaled -back to the client. If the resource is busy, SUCCESS will -still be returned, but the request will be queued -according to the queuing policy of the arbiter. Whenever a client is -done with the resource, it calls the release() command, and the next -client in the request queue is given access to the resource and -is signaled its granted() event. If a client ever makes multiple -requests before receiving a granted event, an EBUSY value is returned, -and the request is not queued. Using this policy, clients are not able to +SUCCESS is returned, and a granted event is signaled +back to the client. If the resource is busy, SUCCESS will +still be returned, but the request will be queued +according to the queuing policy of the arbiter. Whenever a client is +done with the resource, it calls the release() command, and the next +client in the request queue is given access to the resource and +is signaled its granted() event. If a client ever makes multiple +requests before receiving a granted event, an EBUSY value is returned, +and the request is not queued. Using this policy, clients are not able to monolopize the resource queue by making multiple requests, but they may still be -able to monopolize the use of the resource if they do not release it in a +able to monopolize the use of the resource if they do not release it in a timely manner. -Clients can also request the use of a resource through the -immediateRequest() command. A call to immediateRequest() can either -return SUCCESS or FAIL, with requests made through this command never being -queued. If a call to immediateRequest() returns SUCCESS, the client is granted -access to the resource immediately after the call has returned, and no granted -event is ever signaled. If it returns FAIL, the client is not granted access to -the resource and the request does not get queued. The client will have to try + Clients can also request the use of a resource through the +immediateRequest() command. A call to immediateRequest() can either +return SUCCESS or FAIL, with requests made through this command never being +queued. If a call to immediateRequest() returns SUCCESS, the client is granted +access to the resource immediately after the call has returned, and no granted +event is ever signaled. If it returns FAIL, the client is not granted access to +the resource and the request does not get queued. The client will have to try and gain access to the resource again later. -A client can use the isOwner command of the Resource interface to -check if it is the current owner of the resource. This command is mostly + A client can use the isOwner command of the Resource interface to +check if it is the current owner of the resource. This command is mostly used to perform runtime checks to make sure that clients not owning a resource are not able to use it. If a call to isOwner fails, then no call should be made to commands provided by that resource. -The diagram below shows how a simple shared resource can be -built from a dedicated resource by using just the Resource interface + The diagram below shows how a simple shared resource can be +built from a dedicated resource by using just the Resource interface provided by an arbiter.: /|\ /|\ | | | Data Interface | Resource - | | + | | -------------------------------------------- | Shared Resource | -------------------------------------------- @@ -539,7 +547,7 @@ provided by an arbiter.: An arbiter MUST provide exactly one parameterized Resource interface, where the parameter is a client ID, following the Service Instance pattern[3]_. An arbitrated component SomeNameP MUST -#define SOME_NAME_RESOURCE to a string which can be passed to unique() +#define SOME_NAME_RESOURCE to a string which can be passed to unique() to obtain a client id. This #define must be placed in a separate file because of the way nesC files are preprocessed: including the SomeNameP component isn't enough to ensure that macros #define'd in @@ -549,14 +557,14 @@ inside a generic configuration. Wrapping the component in this way ensures that each Resource client is given a unique client ID, with the added benefit of properly coupling multiple components that all need to refer to the same client ID. -Appendix B also provides a complete example of how an I2C resource might be -abstracted according to this pattern. For further examples see the various + Appendix B also provides a complete example of how an I2C resource might be +abstracted according to this pattern. For further examples see the various chip implementations in the tinyos-2.x source tree under tinyos-2.x/chips/ - -3.2 ArbiterInfo + +3.2 ArbiterInfo Arbiters MUST provide an instance of the ArbiterInfo interface. -The ArbiterInfo interface allows a component to query the current +The ArbiterInfo interface allows a component to query the current status of an arbiter: interface ArbiterInfo { @@ -564,24 +572,24 @@ interface ArbiterInfo { async command uint8_t clientId(); } -In contrast to the parameterized Resource interface provided by an arbiter, -only a single ArbiterInfo interface is provided. Its purpose is + In contrast to the parameterized Resource interface provided by an arbiter, +only a single ArbiterInfo interface is provided. Its purpose is to allow one to find out: Whether the resource for which it is arbitrating use is currently in use or not Which client is using it. -One can view ArbiterInfo as an interface for obtaining global information about -the use of a resource, while Resource can be viewed as an interface for obtaining + One can view ArbiterInfo as an interface for obtaining global information about +the use of a resource, while Resource can be viewed as an interface for obtaining local access to that resource. -The primary use of the ArbiterInfo interface is to allow a shared resource to reject -any calls made through its data interface by clients that do not currently have access to + The primary use of the ArbiterInfo interface is to allow a shared resource to reject +any calls made through its data interface by clients that do not currently have access to it. For an example of how this interface is used in this fashion refer to Appendix B.: /|\ /|\ | | | Data Interface | Resource - | | + | | ----------------------------------------------------------- | Shared Resource | ----------------------------------------------------------- @@ -594,9 +602,9 @@ it. For an example of how this interface is used in this fashion refer to Appen ---------------------- ------------------------------- - -3.3 ResourceRequested -Sometimes it is useful for a client to be able to hold onto a resource until + +3.3 ResourceRequested +Sometimes it is useful for a client to be able to hold onto a resource until someone else needs it and only at that time decide to release it. Using the ResourceRequested interface, this information is made available to the current owner of a resource: @@ -610,10 +618,10 @@ interface ResourceRequested { client makes a request for the resource through the request() command of its Resource interface. If a request is made through the immediateRequest() command, then the immediateRequested() event is signaled. -An arbiter SHOULD provide a parameterized ResourceRequested interface to its -clients, but is not required to. The client id of the parameterized -ResourceRequested interface should be coupled with the client id of the Resource -interface to ensure that all events are signaled to the proper clients. Please + An arbiter SHOULD provide a parameterized ResourceRequested interface to its +clients, but is not required to. The client id of the parameterized +ResourceRequested interface should be coupled with the client id of the Resource +interface to ensure that all events are signaled to the proper clients. Please refer to Appendix B for an example of how this interface might be used.: /|\ /|\ /|\ @@ -632,16 +640,16 @@ refer to Appendix B for an example of how this interface might be used.: ---------------------- ---------------------------------------------------- - -3.4 ResourceConfigure -The existence of the ResourceConfigure interface allows a resource to be + +3.4 ResourceConfigure +The existence of the ResourceConfigure interface allows a resource to be automatically configured just before a client is granted access to it. Components providing the ResourceConfigure interface use the interfaces provided by an underlying dedicated resource to configure it into one -of its desired modes of operation. A cleint then wires its shared resource -abstraction to the component implementing the desired configuration. The -configure command is called immediataely before the client is granted access -to the resource, and the unconfigure command is called just before fully +of its desired modes of operation. A cleint then wires its shared resource +abstraction to the component implementing the desired configuration. The +configure command is called immediataely before the client is granted access +to the resource, and the unconfigure command is called just before fully releasing it.: interface ResourceConfigure { @@ -653,45 +661,45 @@ interface ResourceConfigure { ResourceConfigure ResourceConfigure ResourceConfigure | | /|\ | | | - \|/ \|/ | -------------------- ------------------- ------------------- + \|/ \|/ | +------------------- ------------------- ------------------- | Configuration 1 | | Configuration 2 | | Shared Resource | ------------------- ------------------- ------------------- | | /|\ | Control Interface | | ResourceConfigure \|/ \|/ | - ------------------------------ ----------- + ------------------------------ ----------- | Dedicated Resource | | Arbiter | ------------------------------ ----------- -The arbiter SHOULD use a parameterized ResourceConfigure interface, with + The arbiter SHOULD use a parameterized ResourceConfigure interface, with its client ID parameter coupled with the client id of its parameterized -Resource interface. If an arbiter uses the ResourceConfigure interface, -it MUST call ResourceConfigure.configure() on the granted client ID +Resource interface. If an arbiter uses the ResourceConfigure interface, +it MUST call ResourceConfigure.configure() on the granted client ID before it signals the Resource.granted() event. Similarly, after a valid -call to Resource.release(), it MUST call ResourceConfigure.unconfigure() +call to Resource.release(), it MUST call ResourceConfigure.unconfigure() on the releasing client ID. By calling ResourceConfigure.configure() just -before granting a client access to a resource and calling +before granting a client access to a resource and calling ResourceConfigure.unconfigure() just before fully releasing it, it is guaranteed -that a resource is always unconfigured before an attempt to configure it can be +that a resource is always unconfigured before an attempt to configure it can be made again. The commands included in this interface could have been made part of the standard -Resource interface (and changed into callback events), but at a higher cost than -keeping them separate. Introducing these new commands into the Resource interface -would have lead to a large number of clients all including redundant configuration -code, while using the call out approach to a separate component ensures that we +Resource interface (and changed into callback events), but at a higher cost than +keeping them separate. Introducing these new commands into the Resource interface +would have lead to a large number of clients all including redundant configuration +code, while using the call out approach to a separate component ensures that we only have a single instance of the code. -For an example of how configurations for the three different modes of the -Msp430 Usart component can take advantage of the ResourceConfigure -interface refer to Appendix B as well as section 4 on the use of + For an example of how configurations for the three different modes of the +Msp430 Usart component can take advantage of the ResourceConfigure +interface refer to Appendix B as well as section 4 on the use of cross-component reservation. - -3.5 ResourceDefaultOwner -The normal Resource interface is for use by clients that all share the resource -in an equal fashion. The ResourceDefaultOwner interface is for use by a single -client that needs to be given control of the resource whenever no one else is -using it. An arbiter MAY provide a single instance of the ResourceDefaultOwner + +3.5 ResourceDefaultOwner +The normal Resource interface is for use by clients that all share the resource +in an equal fashion. The ResourceDefaultOwner interface is for use by a single +client that needs to be given control of the resource whenever no one else is +using it. An arbiter MAY provide a single instance of the ResourceDefaultOwner interface. It MUST NOT provide more than one.: interface ResourceDefaultOwner { @@ -703,43 +711,43 @@ interface ResourceDefaultOwner { } The Arbiter MUST guarantee that the client of the ResourceDefaulrClient interface is -made the owner of the resource before the boot initialization sequence is -completed. When a normal resource client makes a request for the resource, the -ResourceDefaultOwner will receive either a requested() or an immediateRequested() -event depending on how the request was made. It must then decide if and when to -release it. Once released, all clients that have pending requests will be -granted access to the resource in the order determined by the queuing policy of -the arbiter in use. Once all pending requests have been granted (including -those that came in while other clients had access to the resource), the -ResourceDefaultOwner is automatically given control of the resource, receiving its -granted() event in the process. The ResourceDefaultOwner interface also contains -the same isOwner() command as the normal Resource interface, and the semantics +made the owner of the resource before the boot initialization sequence is +completed. When a normal resource client makes a request for the resource, the +ResourceDefaultOwner will receive either a requested() or an immediateRequested() +event depending on how the request was made. It must then decide if and when to +release it. Once released, all clients that have pending requests will be +granted access to the resource in the order determined by the queuing policy of +the arbiter in use. Once all pending requests have been granted (including +those that came in while other clients had access to the resource), the +ResourceDefaultOwner is automatically given control of the resource, receiving its +granted() event in the process. The ResourceDefaultOwner interface also contains +the same isOwner() command as the normal Resource interface, and the semantics of its use are exactly the same. -Although the ResourceDefaultOwner interface looks similar to a combination of the -normal Resource interface and the ResourceRequested interface, its intended use -is quite different. The ResourceDefaultOwner interface should only be used by -clients that wish to have access to a resource only when no other clients are -using it. They do not actively seek access to the resource, but rather use + Although the ResourceDefaultOwner interface looks similar to a combination of the +normal Resource interface and the ResourceRequested interface, its intended use +is quite different. The ResourceDefaultOwner interface should only be used by +clients that wish to have access to a resource only when no other clients are +using it. They do not actively seek access to the resource, but rather use it to perform operations when it would otherwise simply be idle. -The primary motivation behind the definition of the ResourceDefaultOwner + The primary motivation behind the definition of the ResourceDefaultOwner interface is to allow for an easy integration of power management -for a resource with its arbitration policy. Arbiters that want to allow -a resource to be controlled by a particular power management policy can -provide the ResourceDefaultOwner interface for use by a component that -implements that policy. The power management component will receive the +for a resource with its arbitration policy. Arbiters that want to allow +a resource to be controlled by a particular power management policy can +provide the ResourceDefaultOwner interface for use by a component that +implements that policy. The power management component will receive the granted() event whenever the resource has gone idle, and will proceed in -powering it down. When another client requests the resource, the power -manager will be notified through either the requested() or -immediateRequested() events as appropriate. It can then power up the resource -and release it once the power up has completed. Note that if power up is -a split-phase operation (takes a while), then calls by clients to -immediateRequest() when in the powered down state will return +powering it down. When another client requests the resource, the power +manager will be notified through either the requested() or +immediateRequested() events as appropriate. It can then power up the resource +and release it once the power up has completed. Note that if power up is +a split-phase operation (takes a while), then calls by clients to +immediateRequest() when in the powered down state will return FAIL. Please see the TEP on the Power Management of Non-Virtualized devices ([4]) for more details. - -4. Cross-Component Reservation + +4. Cross-Component Reservation In some cases, it is desirable to share the reservation of a single resource across multiple components. For example, on the TI MSP430, a single USART component can be used as an I2C bus, a UART, @@ -791,21 +799,21 @@ new Msp430Spi0C component is instantiated. This id is used as a parameter to the parameterized Resource interface provided by the Msp430Spi0P component. This is where the mapping of the two different ids begins. As well as providing a parameterized -Resource interface (Msp430Spi0P.Resource), the Msp430Spi0P component -also uses a parameterized Resource interface (Msp430Spi0P.UsartResource). -Whenever a client makes a call through the provided Resource interface -with id CLIENT_ID, an underlying call to the Msp430Spi0P.Resource interface -with the same id is implicitly made. By then wiring the Msp430Spi0P.UsartResource -interface with id CLIENT_ID to an instance of the Resource interface -provided by the instantiation of the Msp430Usart0C component, the mapping -is complete. Any calls to the Resource interface provided by a new -instantiation of the Msp430Spi0C component will now be made through a +Resource interface (Msp430Spi0P.Resource), the Msp430Spi0P component +also uses a parameterized Resource interface (Msp430Spi0P.UsartResource). +Whenever a client makes a call through the provided Resource interface +with id CLIENT_ID, an underlying call to the Msp430Spi0P.Resource interface +with the same id is implicitly made. By then wiring the Msp430Spi0P.UsartResource +interface with id CLIENT_ID to an instance of the Resource interface +provided by the instantiation of the Msp430Usart0C component, the mapping +is complete. Any calls to the Resource interface provided by a new +instantiation of the Msp430Spi0C component will now be made through a unique Resource interface on the underlying Msp430Usart0C component. This level of indirection is necessary because it may not always be desirable to directly wire the service level Resource interface to the underlying shared Resource interface. Sometimes we may want to perform some operations between a service level command being -called, and calling the underlying command on the shared resource. +called, and calling the underlying command on the shared resource. With such a mapping, inserting these operations is made possible. Having such a mapping is also important for services that need to explicitly keep track of the number of clients they have, @@ -821,8 +829,8 @@ reuse is encouraged. Implementations of components similar to this one can be found in the tinyos-2.x source tree in the tos/chips/msp430/uart directory - -5. Implementation + +5. Implementation Because most components use one of a small number of arbitration policies, tinyos-2.x includes a number of default resource arbiters. These arbiters can be found in tinyos-2.x/tos/system and are all @@ -841,19 +849,19 @@ generic module Arbiter { provides interface ResourceDefaultOwner; provides interface ArbiterInfo; uses interface ResourceConfigure[uint8_t id]; -} +} - The "Simple" arbiters are intended for use by resources that + The "Simple" arbiters are intended for use by resources that do not require the additional overhead incurred by providing the ResourceDefaultOwner interface. For many situations, changing an arbitration policy requires nothing more than changing the queuing policy it uses to decide the order in -which incoming requests should be granted. In this way, separating -queuing policy implementations from actual arbitration implementations -encourages code reuse. The introduction of the SimpleArbiterP and +which incoming requests should be granted. In this way, separating +queuing policy implementations from actual arbitration implementations +encourages code reuse. The introduction of the SimpleArbiterP and ArbiterP components found under tinyos-2.x/tos/system help in this separation. They can be wired to components providing -a particular queuing policy through the use of the ResourceQueue +a particular queuing policy through the use of the ResourceQueue interface.: interface ResourceQueue { @@ -861,9 +869,9 @@ interface ResourceQueue { async command bool isEnqueued(resource_client_id_t id); async command resource_client_id_t dequeue(); async command error_t enqueue(resource_client_id_t id); -} +} -An example of wiring a First-Come-First-Serve (FCFS) queuing policy to + An example of wiring a First-Come-First-Serve (FCFS) queuing policy to the SimpleArbiterP component using the ResourceQueue interface defined above can be seen below: @@ -892,8 +900,8 @@ implementation { This generic configuration can be instantiated by a resource in order to grant requests made by its clients in an FCFS fashion. -All of the default queuing policies provided in tinyos-2.x along with the -respective arbitration components that have been built using them are + All of the default queuing policies provided in tinyos-2.x along with the +respective arbitration components that have been built using them are given below: Queuing Policies: @@ -907,19 +915,19 @@ given below: SimpleRoundRobinArbiterC RoundRobinArbiterC -Keep in mind that neither the implementation of an arbiter nor its -queuing policy can be used to explicitly restrict access to an + Keep in mind that neither the implementation of an arbiter nor its +queuing policy can be used to explicitly restrict access to an underlying shared resource. The arbiter simply provides a standardized -way of managing client ids so that shared resources don't have to duplicate +way of managing client ids so that shared resources don't have to duplicate this functionality themselves every time they are implemented. In order to actually restrict clients from using a resource without first requesting it, a shared resource must use the functionality provided by the ArbiterInfo interface -to perform runtime checks on the current owner of a resource. Please refer +to perform runtime checks on the current owner of a resource. Please refer to the section on the ArbiterInfo interface in Appendix B for more information on how such runtime checks can be performed. - -6. Author's Address + +6. Author's Address Kevin Klues 503 Bryan Hall @@ -962,8 +970,8 @@ on how such runtime checks can be performed. email - handzisk@tkn.tu-berlin.de - -7. Citations + +7. Citations @@ -995,10 +1003,10 @@ on how such runtime checks can be performed. - -Appendix A: Resource Class Examples - -Dedicated Resource + +Appendix A: Resource Class Examples + +Dedicated Resource Timer 2 on the Atmega128 microprocessor is a dedicated resource represented by the HplAtm128Timer2C component: @@ -1012,19 +1020,19 @@ module HplAtm128Timer2C { Only a single client can wire to any of these interfaces as enforced through the nesC @exactlyonce attribute. Keep in mind that although the interfaces of -this component are only allowed to be wired to once, nothing prevents the -component wiring to them from virtualizing the services they provide at some -higher level. If you are unfamiliar with how @exactlyonce and other nesC -attributes are used to by the nesC compiler, please refer to section 9.1 of the +this component are only allowed to be wired to once, nothing prevents the +component wiring to them from virtualizing the services they provide at some +higher level. If you are unfamiliar with how @exactlyonce and other nesC +attributes are used to by the nesC compiler, please refer to section 9.1 of the TinyOS Programming Manual [5]. - -Virtualized Resource -The TimerMilliC component provides a virtual abstraction of millisecond -precision timers to application components [2]. It encapsulates the required -parameterized Timer interface through the use of a generic configuration. -Clients wishing to use a millisecond timer need only instantiate a single -instance of the TimerMilliC generic, leaving the fact that it is virtualized + +Virtualized Resource +The TimerMilliC component provides a virtual abstraction of millisecond +precision timers to application components [2]. It encapsulates the required +parameterized Timer interface through the use of a generic configuration. +Clients wishing to use a millisecond timer need only instantiate a single +instance of the TimerMilliC generic, leaving the fact that it is virtualized underneath transparent.: generic configuration TimerMilliC { @@ -1035,9 +1043,9 @@ implementation { Timer = TimerMilliP.TimerMilli[unique(UQ_TIMER_MILLI)]; } -The actual parameterized Timer interface is provided by the chip specific -HilTimerMilliC component. This interface is exposed through -the TimerMilliP component which wires HilTimerMilliC to the boot + The actual parameterized Timer interface is provided by the chip specific +HilTimerMilliC component. This interface is exposed through +the TimerMilliP component which wires HilTimerMilliC to the boot initialization sequence: configuration TimerMilliP { @@ -1051,19 +1059,19 @@ implementation { - -Appendix B: Arbiter Interface Examples + +Appendix B: Arbiter Interface Examples - -Resource +Most of the examples provided in this section use complex nesC syntax that may +be unfamiliar to the novice nesC programmer. Please refer to the TinyOS +programming Manual [5]_ for clarification as necessary. --> + +Resource Examples of how to use the Resource interface for arbitrating between multiple clients can be found in the tinyos-2.x source tree under tinyos-2.x/apps/tests/TestArbiter. -A specific example of where the Resource.isOwner() is used -can be seen in the HplTda5250DataP component of the Infineon + A specific example of where the Resource.isOwner() is used +can be seen in the HplTda5250DataP component of the Infineon Tda5250 radio implementation: async command error_t HplTda5250Data.tx(uint8_t data) { @@ -1094,8 +1102,8 @@ implementation { ... } -where I2CPacketImplP contains the actual implementation of the -I2C service, and I2CPacket.h contains the #define for the + where I2CPacketImplP contains the actual implementation of the +I2C service, and I2CPacket.h contains the #define for the name of the resource required by the arbiter: #ifndef I2CPACKETC_H @@ -1113,16 +1121,16 @@ generic configuration I2CPacketC { } implementation { enum { CLIENT_ID = unique(I2CPACKET_RESOURCE) }; - + components I2CPacketP as I2C; Resource = I2C.Resource[CLIENT_ID]; - I2CPacket = I2C.I2CPacket[CLIENT_ID]; + I2CPacket = I2C.I2CPacket[CLIENT_ID]; } In this example, an instance of the I2CPacket interface is coupled with an instance of the Resource interface on every new instantiation of the I2CPacketC component. In this way, a single Resource and a -single I2CPacket interface can be exported by this component together +single I2CPacket interface can be exported by this component together for use by a client. Clients of the I2C service would use it as follows: @@ -1140,19 +1148,19 @@ implementation { } - -ArbiterInfo + +ArbiterInfo In the implementation of the ADC component on the Msp430 microcontroller, a simple arbiter is used to provide a round robin sharing policy between clients of the ADC: -configuration Msp430Adc12C { - provides interface Resource[uint8_t id]; - provides interface Msp430Adc12SingleChannel[uint8_t id]; - provides interface Msp430Adc12FastSingleChannel[uint8_t id]; -} -implementation { - components Msp430Adc12P,MainC, +configuration Msp430Adc12C { + provides interface Resource[uint8_t id]; + provides interface Msp430Adc12SingleChannel[uint8_t id]; + provides interface Msp430Adc12FastSingleChannel[uint8_t id]; +} +implementation { + components Msp430Adc12P,MainC, new SimpleRoundRobinArbiterC(MSP430ADC12_RESOURCE) as Arbiter, ... @@ -1165,12 +1173,12 @@ implementation { ... } -In this configuration we see that the Resource interface provided by + In this configuration we see that the Resource interface provided by Msp430Adc12C is wired directly to the instance of the SimpleRoundRobinArbiterC component that is created. The ArbiterInfo interface provided by -SimpleRoundRobinArbiterC is then wired to Msp430Adc12P. The Msp430Adc12P +SimpleRoundRobinArbiterC is then wired to Msp430Adc12P. The Msp430Adc12P component then uses this interface to perform run time checks to ensure that -only the client that currently has access to the ADC resource is able to +only the client that currently has access to the ADC resource is able to use it: async command error_t Msp430Adc12SingleChannel.getSingleData[uint8_t id]() { @@ -1180,7 +1188,7 @@ async command error_t Msp430Adc12SingleChannel.getSingleData[uint8_t id]() { } else return ERESERVE; } - + async command error_t Msp430Adc12FastSingleChannel.configure[uint8_t id]() { if (call ADCArbiterInfo.clientId() == id){ clientID = id @@ -1188,67 +1196,67 @@ async command error_t Msp430Adc12FastSingleChannel.configure[uint8_t id]() { } else return ERESERVE; } - -async command error_t Msp430Adc12FastSingleChannel.getSingleData[uint8_t id]() + +async command error_t Msp430Adc12FastSingleChannel.getSingleData[uint8_t id]() { if (clientID = id) // Start getting data else return ERESERVE; } -In order for these runtime checks to succeed, users of the -Msp430Adc12SingleChannel and Msp430Adc12FastSingleChannel interfaces will have -to match their client id's with the client id of a corresponding Resource + In order for these runtime checks to succeed, users of the +Msp430Adc12SingleChannel and Msp430Adc12FastSingleChannel interfaces will have +to match their client id's with the client id of a corresponding Resource interface. This can be done in the following way: generic configuration Msp430Adc12ClientC() { provides interface Resource; provides interface Msp430Adc12SingleChannel; -} +} implementation { components Msp430Adc12C; enum { ID = unique(MSP430ADC12_RESOURCE) }; - + Resource = Msp430Adc12C.Resource[ID]; Msp430Adc12SingleChannel = Msp430Adc12C.SingleChannel[ID]; -} +} generic configuration Msp430Adc12FastClientC() { provides interface Resource; provides interface Msp430Adc12FastSingleChannel; -} +} implementation { components Msp430Adc12C; enum { ID = unique(MSP430ADC12_RESOURCE) }; - + Resource = Msp430Adc12C.Resource[ID]; Msp430Adc12FastSingleChannel = Msp430Adc12C.SingleChannel[ID]; -} +} Since these are generic components, clients simply need to instantiate them in order to get access to a single Resource interface that is already properly coupled with a Msp430Adc12SingleChannel or Msp430Adc12FastSingleChannel interface. -Take a look in the tinyos-2.x source tree under tinyos-2.x/tos/chips/adc12 + Take a look in the tinyos-2.x source tree under tinyos-2.x/tos/chips/adc12 to see the full implementation of these components in their original context. - -ResourceRequested + +ResourceRequested On the eyesIFXv2 platform, both the radio and the flash need access to the bus -provided by the Usart0 component on the Msp430 microcontroller. Using -a simple cooperative arbitration policy, these two components should able to -share the Usart resource by only holding on to it as long as they need it and -then releasing it for use by the other component. In the case of the MAC -implementation of the Tda5250 radio component, however, the Msp430 Usart -resource needs be held onto indefinitely. It only ever considers releasing the -resource if a request from the flash component comes in through its -ResourceRequested interface. If it cannot release it right away (i.e. it is in -the middle of receiving a packet), it defers the release until some later point -in time. Once it is ready to release the resource, it releases it, but then -immediately requests it again. The flash is then able to do what it wants with +provided by the Usart0 component on the Msp430 microcontroller. Using +a simple cooperative arbitration policy, these two components should able to +share the Usart resource by only holding on to it as long as they need it and +then releasing it for use by the other component. In the case of the MAC +implementation of the Tda5250 radio component, however, the Msp430 Usart +resource needs be held onto indefinitely. It only ever considers releasing the +resource if a request from the flash component comes in through its +ResourceRequested interface. If it cannot release it right away (i.e. it is in +the middle of receiving a packet), it defers the release until some later point +in time. Once it is ready to release the resource, it releases it, but then +immediately requests it again. The flash is then able to do what it wants with the Usart, with the radio regaining control soon thereafter. -In the CsmaMacP implementation of the Tda5250 radio we see the ResourceRequested + In the CsmaMacP implementation of the Tda5250 radio we see the ResourceRequested event being implemented: async event void ResourceRequested.requested() { @@ -1279,27 +1287,27 @@ implementation { ... } -Although the full implementation of these components is not provided, the -functionality they exhibit should be clear. The CsmaMacP component receives the -ResourceRequested.requested() event when the flash requests the use of the -Msp430 Usart0 resource. If it is already in the receive state, it tries to -reset the receive state through a call to a lower level component. This -component checks to see if the radio is in the middle of doing anything (i.e. -the radioBusy() == FALSE check), and if not, releases the resource and then + Although the full implementation of these components is not provided, the +functionality they exhibit should be clear. The CsmaMacP component receives the +ResourceRequested.requested() event when the flash requests the use of the +Msp430 Usart0 resource. If it is already in the receive state, it tries to +reset the receive state through a call to a lower level component. This +component checks to see if the radio is in the middle of doing anything (i.e. +the radioBusy() == FALSE check), and if not, releases the resource and then requests it again. -To see the full implementations of these components and their wirings to one -another, please refer to the tinyos-2.x source tree under -tinyos-2.x/tos/chips/tda5250, tinyos-2.x/tos/chips/tda5250/mac, -tinyos-2.x/tos/platforms/eyesIFX/chips/tda5250, and + To see the full implementations of these components and their wirings to one +another, please refer to the tinyos-2.x source tree under +tinyos-2.x/tos/chips/tda5250, tinyos-2.x/tos/chips/tda5250/mac, +tinyos-2.x/tos/platforms/eyesIFX/chips/tda5250, and tinyos-2.x/tos/platforms/eyesIFX/chips/msp430. - -Resource Configure -The Msp430 Usart0 bus can operate in three modes: SPI, I2C, -and UART. Using all three concurrently is problematic: only one should + +Resource Configure +The Msp430 Usart0 bus can operate in three modes: SPI, I2C, +and UART. Using all three concurrently is problematic: only one should be enabled at any given time. However, different clients of the bus might require the bus to be configured for different protocols. On Telos, for example -many of the available sensors use an I2C bus, while the radio and flash chip use +many of the available sensors use an I2C bus, while the radio and flash chip use SPI. A component providing the SPI service on top of the shared Usart component looks like this: @@ -1312,7 +1320,7 @@ generic configuration Msp430Spi0C() { } implementation { enum { CLIENT_ID = unique( MSP430_SPIO_BUS ) }; - + components Msp430SpiNoDma0P as SpiP; components new Msp430Usart0C() as UsartC; SpiP.ResourceConfigure[ CLIENT_ID ] <- UsartC.ResourceConfigure; @@ -1323,10 +1331,10 @@ implementation { And one providing the I2C service looks like this: -generic configuration Msp430I2CC() { +generic configuration Msp430I2CC() { provides interface Resource; provides interface I2CPacket<TI2CBasicAddr> as I2CBasicAddr; - ... + ... } implementation { enum { CLIENT_ID = unique( MSP430_I2CO_BUS ) }; @@ -1340,14 +1348,14 @@ implementation { } The implementation of the ResourceConfigure interface is -provided by both the Msp430SpiNoDma0P and the Msp430I2C0P. In the +provided by both the Msp430SpiNoDma0P and the Msp430I2C0P. In the two different components, the same Msp430Usart0C component is used, but wired to the proper implementation of the ResourceConfigure -interface. In this way, different instances of the Msp430Usart0C -can each have different configurations associated with them, but +interface. In this way, different instances of the Msp430Usart0C +can each have different configurations associated with them, but still provide the same functionality. -Take a look in the tinyos-2.x source tree under -tinyos-2.x/tos/chips/msp430/usart to see the full implementation of + Take a look in the tinyos-2.x source tree under +tinyos-2.x/tos/chips/msp430/usart to see the full implementation of these components along with the corresponding Uart implementation. diff --git a/doc/html/tep109.html b/doc/html/tep109.html index 27ed3ab4..d353a66f 100644 --- a/doc/html/tep109.html +++ b/doc/html/tep109.html @@ -3,7 +3,7 @@ - + Sensors and Sensor Boards - Sensors and Sensor Boards @@ -312,6 +306,7 @@ ul.auto-toc { + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -319,15 +314,15 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract + +Abstract This memo documents how sensor drivers are organized in TinyOS and how sets of sensor drivers are combined into sensor boards and sensor platforms, along with general principles followed by the components that provide access to sensors. - -1. Principles + +1. Principles This section describes the basic organization principles for sensor drivers in TinyOS. For background, a sensor can be attached to the microcontroller on a @@ -379,8 +374,8 @@ the driver MAY provide additional interfaces that would allow higher-level clients to obtain information needed to properly interpret the value. - -2. Sensor HIL Components + +2. Sensor HIL Components A sensor HIL component MUST provide: One or more SID interfaces [TEP114], for reading data. @@ -472,8 +467,8 @@ implementation { } - -3. Sensor HAL Components + +3. Sensor HAL Components Sensors with a richer interface than would be supported by the SID interfaces MAY provide a HAL component in addition to a HIL component. @@ -502,8 +497,8 @@ implementation { } - -4. Directory Organization Guidelines + +4. Directory Organization Guidelines Because the same physical sensor can be attached to TinyOS platforms in many different ways, the organization of sensor drivers SHOULD reflect the distinction between sensor and sensor interconnect. @@ -572,8 +567,8 @@ code that will enter the core source tree. In general, sensor components can be placed anywhere as long as the nesC compiler receives enough -I directives to locate all of the necessary pieces. - -5. Authors' Addresses + +5. Authors' Addresses David Gay 2150 Shattuck Ave, Suite 1300 @@ -616,8 +611,8 @@ receives enough -I directives to locate all of the necessary pieces email - gtolle@archrock.com - -6. Citations + +6. Citations @@ -637,10 +632,10 @@ receives enough -I directives to locate all of the necessary pieces - -Appendix A: Sensor Driver Examples - -1. Analog ADC-Connected Sensor + +Appendix A: Sensor Driver Examples + +1. Analog ADC-Connected Sensor The Analog sensor requires two components a component to present the sensor itself (HamamatsuS1087ParC) @@ -701,8 +696,8 @@ implementation { } - -2. Binary Pin-Connected Sensor + +2. Binary Pin-Connected Sensor The Binary sensor gets a bit more complex, because it has three components: @@ -814,8 +809,8 @@ implementation { } - -3. Digital Bus-Connected Sensor + +3. Digital Bus-Connected Sensor The Digital sensor is the most complex out of the set, and includes six components: diff --git a/doc/html/tep110.html b/doc/html/tep110.html index e1f4648c..ece6cd14 100644 --- a/doc/html/tep110.html +++ b/doc/html/tep110.html @@ -3,7 +3,7 @@ - + Virtualization - Virtualization @@ -303,14 +302,15 @@ ul.auto-toc { - + - + Philip Levis Draft-Created: 20-Jun-2005 Draft-Version: 1.1.2.2 Draft-Version: 1.5 Draft-Modified: 2006-02-08 Draft-Modified: 2006-12-12 Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu> + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -318,15 +318,15 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract + +Abstract This memo desribes how TinyOS 2.0 virtualizes common abstractions through a combination of static allocation and runtime arbitration. It describes the benefits and tradeoffs of this approach and how it is used in several major abstractions. - -1. Introduction + +1. Introduction The TinyOS component model allows flexible composition, but that flexibility is often limited by reasons which are not explicitly stated in components. These implicit assumptions can manifest as buggy @@ -350,8 +350,8 @@ System Key Interfaces). It describes the services OSKI provides and how their implementations are structured to simplify application writing. - -2. Distributions + +2. Distributions A distribution presents services to the programmer. A service is a set of generic (instantiable) components that represent API abstractions. To use an abstraction, a programmer instantiates the @@ -372,8 +372,8 @@ look something like this: Services often present abstractions at a fine grain. For example, the active message service has AMSender, AMReceiver, and AMSnooper, each of which is a separate abstraction. - -2.1 Controlling a Service + +2.1 Controlling a Service Every service has two abstractions: ServiceC, for powering it on and off, and ServiceNotifierC, for learning when the service's power state has changed. For example, active messages have the @@ -424,8 +424,8 @@ active messages being used by two components, RouterA and RouterB: application to use the service, at least one component has to call Service.start(). - -2.2 Service Initialization + +2.2 Service Initialization Because distributions are collections of services that are designed to work together, they can avoid many of the common issues that arise when composing TinyOS programs. For example, user code does not have @@ -436,13 +436,13 @@ initialized. Section 4 goes into an example implementation of how a distribution can achieve this. - -3. OSKI Services + +3. OSKI Services This section briefly describes the services that OSKI, an example distribution provides. It is intended to give a feel for how a distribution presents its abstractions. - -3.1 Timers + +3.1 Timers OSKI provides timers at one fidelity: milliseconds. Timers do not have a Service abstraction, as their use implicitly defines whether the service is active or not (the timer service is off if there are no @@ -466,8 +466,8 @@ configuration: } - -3.2 Active Messages + +3.2 Active Messages OSKI provides four functional active messaging abstractions: AMSender, AMReceiver, AMSnooper, and AMSnoopingReceiver. Each one takes an am_id_t as a parameter, @@ -525,8 +525,8 @@ its topology formation: The active messages layer has control abstractions, named AMServiceC and AMServiceNotifierC. Active messages follow an OR policy. - -3.3 Broadcasts + +3.3 Broadcasts In addition to active messages, OSKI provides a broadcasting service. Unlike active messages, which are addressed in terms of AM addresses, broadcasts are address-free. Broadcast communication has two @@ -537,9 +537,9 @@ the Packet interface. The broadcast service has control abstractions, named BroadcastServiceC and BroadcastServiceNotifierC, which follow an OR policy. - -3.4 Tree Collection/Convergecast -NOTE: These services are not supported as of the 2.x prerelease. + +3.4 Tree Collection/Convergecast +NOTE: These services are not supported as of the 2.x prerelease. They will be supported by the first full release. OSKI's third communication service is tree-based collection routing. This service has four abstractions: @@ -572,16 +572,16 @@ or not. CollectionServiceNotifierC abstractions, which follow an OR policy. - -3.5 UART -NOTE: These services are not supported as of the 2.x prerelease. -They will be supported by the first full release. -They will be fully defined pending discussion/codification of + +3.5 UART +NOTE: These services are not supported as of the 2.x prerelease. +They will be supported by the first full release. +They will be fully defined pending discussion/codification of UART interfaces. - -4. OSKI Service Structure and Design + +4. OSKI Service Structure and Design Presenting services through abstractions hides the underlying wiring details and gives a distribution a great deal of implementation freedom. One issue that arises, however, is initialization. If a user @@ -589,8 +589,8 @@ component instantiates a service, then a distribution MUST make sure the service is initialized properly. OSKI achieves this by encapsulating a complete service as a working component; abstractions export the service's interfaces. - -4.1 Example: Timers + +4.1 Example: Timers For example, the timer service provides a single abstraction, OskiTimerMilliC, which is a generic component. OskiTimerMilliC provides a single instance of the Timer<TMilli> interface. It is implemented as a @@ -642,8 +642,8 @@ itself to one of the sub-Inits. underlying Service Instance pattern: the abstractions take care of that. - -4.2 Example: Active Messages + +4.2 Example: Active Messages Active messaging reprsent a slightly more complex service, as it has several abstractions and a control interface. However, it follows the same basic pattern: abstractions are generics that export wirings to @@ -653,7 +653,7 @@ the underlying service, named Act provides { -interface SplitControl; +interface SplitControl; interface AMSend[am_id_t id]; interface Receive[am_id_t id]; interface Receive as Snoop[am_id_t id]; @@ -777,8 +777,8 @@ of AMServiceC. As with timers, encapsulating the service instance pattern in generic components relieves the programmer of having to deal with unique strings, a common source of bugs in TinyOS 1.x code. - -4.3 OSKI Requirements + +4.3 OSKI Requirements OSKI is a layer on top of system components: it presents a more usable, less error-prone, and simpler interface to common TinyOS functionality. For OSKI to work properly, a platform MUST be compliant @@ -793,11 +793,11 @@ o TEP 1XX: Collection Routing inoperable, exhibit strange behavior, or being uncompilable. - -5. Distribution Interfaces + +5. Distribution Interfaces The basic notion of a distribution is that it provides a self-contained, -tested, and complete (for an application domain) programming interface -to TinyOS. Layers can be added on top of a distribution, but as a +tested, and complete (for an application domain) programming interface +to TinyOS. Layers can be added on top of a distribution, but as a distribution is a self-contained set of abstractions, adding new services can lead to failures. A distribution represents a hard line above which all other code operates. One SHOULD NOT add new services, @@ -805,7 +805,7 @@ as they can disrupt the underlying organization. Of course, one MAY create a new distribution that extends an existing one, but this is in and of itself a new distribution. Generally, as distributions are intended to be higher-level abstractions, -they SHOULD NOT provide any asynchronous (async) events. They can, +they SHOULD NOT provide any asynchronous (async) events. They can, of course, provide async commands. The idea is that no code written on top of a distribution should be asynchronous, due to the complexity introduced by having to manage concurrency. Distributions are usually @@ -813,8 +813,8 @@ platform independent; if an application needs async events, then chances are it is operating close to the hardware, and so is not platform independent. - -6. Author's Address + +6. Author's Address Philip Levis 467 Soda Hall @@ -826,8 +826,8 @@ platform independent. email - pal@cs.berkeley.edu - -7. Citations + +7. Citations diff --git a/doc/html/tep111.html b/doc/html/tep111.html index 07cdbd02..1f59f098 100644 --- a/doc/html/tep111.html +++ b/doc/html/tep111.html @@ -3,7 +3,7 @@ - +message_t - message_t @@ -303,6 +302,7 @@ ul.auto-toc { Philip Levis + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -310,16 +310,16 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract + +Abstract This memo covers the TinyOS 2.x message buffer abstraction, message_t. -It describes the message buffer design considerations, how and where +It describes the message buffer design considerations, how and where message_t is specified, and how data link layers should access it. The major goal of message_t is to allow datagrams to be passed between different link layers as a contiguous region of memory with zero copies. - -1. Introduction + +1. Introduction In TinyOS 1.x, a message buffer is a TOS_Msg. A buffer contains an active message (AM) packet as well as packet metadata, such as timestamps, acknowledgement bits, and signal strength if the packet was received. @@ -327,18 +327,18 @@ acknowledgement bits, and signal strength if the packet was received. AM payload length (the default is 29 bytes). Fixed sized buffers allows TinyOS 1.x to have zero-copy semantics: when a component receives a buffer, rather than copy out the contents it can return a pointer -to a new buffer for the underlying layer to use for the next received +to a new buffer for the underlying layer to use for the next received packet. One issue that arises is what defines the TOS_Msg structure, as different -link layers may require different layouts. For example, 802.15.4 radio -hardware (such as the CC2420, used in the Telos and micaZ platforms) +link layers may require different layouts. For example, 802.15.4 radio +hardware (such as the CC2420, used in the Telos and micaZ platforms) may require 802.15.4 headers, while a software stack built on top of -byte radios (such as the CC1000, used in the mica2 platform) can specify +byte radios (such as the CC1000, used in the mica2 platform) can specify its own packet format. This means that TOS_Msg may be different on different platforms. The solution to this problem in TinyOS 1.x is for there to be a standard definition of TOS_Msg, which a platform (e.g., the micaZ) can -redefine to match its radio. For example, a mica2 mote uses the standard +redefine to match its radio. For example, a mica2 mote uses the standard definition, which is: typedef struct TOS_Msg { @@ -375,13 +375,13 @@ typedef struct TOS_Msg { uint8_t type; uint8_t group; int8_t data[TOSH_DATA_LENGTH]; - + // The following fields are not actually transmitted or received // on the radio! They are used for internal accounting only. // The reason they are in this structure is that the AM interface // requires them to be part of the TOS_Msg that is passed to // send/receive operations. - + uint8_t strength; uint8_t lqi; bool crc; @@ -394,11 +394,11 @@ the link layer fields leads components to directly access the packet structure. This introduces dependencies between higher level components and the structure layout. For example, many network services built on top of data link layers care whether sent packets are acknowledged. They -therefore check the ack field of TOS_Msg. If a link layer does not +therefore check the ack field of TOS_Msg. If a link layer does not provide acknowledgements, it must still include the ack field and always set it to 0, wasting a byte of RAM per buffer. Second, this model does not easily support multiple data link layers. -Radio chip implementations assume that the fields they require are +Radio chip implementations assume that the fields they require are defined in the structure and directly access them. If a platform has two different link layers (e.g., a CC1000 and a CC2420 radio), then a TOS_Msg needs to allocate the right amount of space for both @@ -407,17 +407,17 @@ header fields. This is very difficult to do in C. The data payload is especially problematic. Many components refer to this field, so it must be at a fixed offset from the beginning of the structure. -Depending on the underlying link layer, the header fields +Depending on the underlying link layer, the header fields preceding it might have different lengths, and packet-level radios -often require packets to be contiguous memory regions. Overall, these +often require packets to be contiguous memory regions. Overall, these complexities make specifying the format of TOS_Msg very difficult. TinyOS has traditionally used statically sized packet buffers, rather than more dynamic approaches, such as scatter-gather I/O -in UNIX sockets (see the man page for recv(2) for details). +in UNIX sockets (see the man page for recv(2) for details). TinyOS 2.x continues this approach. - -2. message_t + +2. message_t In TinyOS 2.x, the standard message buffer is message_t. The message_t structure is defined in tos/types/message.h: @@ -428,26 +428,26 @@ typedef nx_struct message_t { nx_uint8_t metadata[sizeof(message_metadata_t)]; } message_t; -This format keeps data at a fixed offset on a platform, which + This format keeps data at a fixed offset on a platform, which is important when passing a message buffer between two different link layers. If the data payload were at different offsets for different link layers, then passing a packet between two link layers would require a memmove(3) operation (essentially, a copy). Unlike in TinyOS 1.x, where TOS_Msg as explicitly an active messaging packet, message_t is a more general -data-link buffer. In practice, most data-link layers in TinyOS 2.x -provide active messaging, but it is possible for a non-AM stack to +data-link buffer. In practice, most data-link layers in TinyOS 2.x +provide active messaging, but it is possible for a non-AM stack to share message_t with AM stacks. The header, footer, and metadata formats are all opaque. Source code cannot access fields directly. Instead, data-link layers provide access -to fields through nesC interfaces. Section 3 discusses this in +to fields through nesC interfaces. Section 3 discusses this in greater depth. Every link layer defines its header, footer, and metadata -structures. These structures MUST be external structs (nx_struct), -and all of their fields MUST be external types (nx_*), for two +structures. These structures MUST be external structs (nx_struct), +and all of their fields MUST be external types (nx_*), for two reasons. First, external types ensure cross-platform compatibility [1]. -Second, it forces structures to be aligned on byte boundaries, -circumventing issues with the +Second, it forces structures to be aligned on byte boundaries, +circumventing issues with the alignment of packet buffers and field offsets within them. Metadata fields must be nx_structs for when complete packets are forwarded to the serial port in order to log traffic. @@ -485,7 +485,7 @@ or metadata section. The platform looks like this: typedef union message_header { - cc1000_header_t cc1k; + cc1000_header_t cc1k; serial_header_t serial; } message_header_t; @@ -521,37 +521,37 @@ typedef union mega_mica_metadata { message_t fields to be a union of the underlying link layer structures. This ensures that enough space is allocated for all underlying link layers. - -3. The message_t fields + +3. The message_t fields TinyOS 2.x components treat packets as abstract data types (ADTs), rather than C structures, obtaining all of the traditional benefits of this approach. First and foremost, clients of a packet layer do not depend on particular field names or locations, allowing the implementations to choose packet formats and make a variety of optimizations. -Components above the basic data-link layer MUST always access -packet fields through interfaces. A component that introduces -new packet fields SHOULD provide an interface to those that + Components above the basic data-link layer MUST always access +packet fields through interfaces. A component that introduces +new packet fields SHOULD provide an interface to those that are of interest to other components. These interfaces SHOULD take the form of get/set operations that take and return values, rather than offsts into the structure. -For example, active messages have an interface named AMPacket -which provides access commands to AM fields. In TinyOS 1.x, a -component would directly access TOS_Msg.addr; in TinyOS 2.x, + For example, active messages have an interface named AMPacket +which provides access commands to AM fields. In TinyOS 1.x, a +component would directly access TOS_Msg.addr; in TinyOS 2.x, a component calls AMPacket.getAddress(msg). The most basic of these interfaces is Packet, which provides -access to a packet payload. TEP 116 describes common TinyOS +access to a packet payload. TEP 116 describes common TinyOS packet ADT interfaces [3]. -Link layer components MAY access packet fields differently than other + Link layer components MAY access packet fields differently than other components, as they are aware of the actual packet format. They can therefore implement the interfaces that provide access to the fields for other components. - -3.1 Headers -The message_t header field is an array of bytes whose size is + +3.1 Headers +The message_t header field is an array of bytes whose size is the size of a platform's union of data-link headers. -Because radio stacks often prefer packets to be stored contiguously, -the layout of a packet in memory does not necessarily reflect the +Because radio stacks often prefer packets to be stored contiguously, +the layout of a packet in memory does not necessarily reflect the layout of its nesC structure. A packet header MAY start somewhere besides the beginning of the message_t. For example, consider the Telos platform: @@ -571,30 +571,30 @@ a 12-byte serial packet on the Telos platform: +-----------+-----------------------------+-------+ message_t | header | data | meta | +-----------+-----------------------------+-------+ - + +-----------+------------+ +-------+ CC2420 | header | data | | meta | +-----------+------------+ +-------+ - +-----+------------+ -Serial | hdr | data | - +-----+------------+ + +-----+------------+ +Serial | hdr | data | + +-----+------------+ Neither the CC2420 nor the serial stack has packet footers, and the serial stack does not have any metadata. The packet for a link layer does not necessarily start at the beginning of the message_t. Instead, it starts at a negative offset from the -data field. When a link layer component needs to read or write protocol -header fields, it MUST compute the location of the header as a negative +data field. When a link layer component needs to read or write protocol +header fields, it MUST compute the location of the header as a negative offset from the data field. For example, the serial stack header has active message fields, such as the AM type. The command that returns the AM type, AMPacket.type(), looks like this: serial_header_t* getHeader(message_t* msg) { return (serial_header_t*)(msg->data - sizeof(serial_header_t)); -} +} command am_id_t AMPacket.type(message_t* msg) { - serial_header_t* hdr = getheader(msg); + serial_header_t* hdr = getheader(msg); return hdr->type; } @@ -609,9 +609,9 @@ It is an example of what components MUST NOT do: serial_header_t* getHeader(message_t* msg) { return (serial_header_t*)(msg->header); -} +} -In the case of Telos, for example, this would result in a packet + In the case of Telos, for example, this would result in a packet layout that looks like this: 11 bytes TOSH_DATA_LENGTH 7 bytes @@ -619,27 +619,27 @@ layout that looks like this: message_t | header | data | meta | +-----------+-----------------------------+-------+ - +-----+ +------------+ -Serial | hdr | | data | - +-----+ +------------+ + +-----+ +------------+ +Serial | hdr | | data | + +-----+ +------------+ - -3.2 Data + +3.2 Data The data field of message_t stores the single-hop packet payload. It is TOSH_DATA_LENGTH bytes long. The default size is 28 bytes. A TinyOS application can redefine TOSH_DATA_LENGTH at compile time with a command-line option to ncc: -DTOSH_DATA_LENGTH=x. Because this value can be reconfigured, it is possible that two different versions of an application can have different MTU sizes. -If a packet layer receives a packet whose payload size is +If a packet layer receives a packet whose payload size is longer than TOSH_DATA_LENGTH, it MUST discard the packet. As headers are right justified to the beginning of the data payload, the data payloads of all link layers on a platform start at the same fixed offset from the beginning of the message buffer. - -3.3 Footer + +3.3 Footer The message_footer_t field ensures that message_t has enough space to store the footers for all underlying link layers when there are MTU-sized packets. Like headers, footers are not necessarily stored @@ -648,11 +648,11 @@ implementation dependent. A single-hop layer MAY store the footer contiguously with the data region. For short packets, this can mean that the footer will actually be stored in the data field. - -3.4 Metadata -The metadata field of message_t stores data that -a single-hop stack uses or collects does not transmit. -This mechanism allows packet layers to store per-packet + +3.4 Metadata +The metadata field of message_t stores data that +a single-hop stack uses or collects does not transmit. +This mechanism allows packet layers to store per-packet information such as RSSI or timestamps. For example, this is the CC2420 metadata structure: @@ -666,8 +666,8 @@ typedef nx_struct cc2420_metadata_t { } cc2420_metadata_t; - -3.5 Variable Sized Structures + +3.5 Variable Sized Structures The message_t structure is optimized for packets with fixed-size headers and footers. Variable-sized footers are generally easy to implement. Variable-sized headers are a bit more difficult. @@ -678,14 +678,14 @@ a known offset. There may be padding between the header and the data region, but assuming a byte-based send path this merely requires adjusting the index. If the underlying link hardware is packet-based, then the -protocol stack can either include metadata (e.g., in the +protocol stack can either include metadata (e.g., in the metadata structure) stating where the header begins or it can place the header at a fixed position and use memmove(3) on reception and transmit. In this latter case, on reception the packet is continguously read into the message_t beginning at the offset of the header structure. Once the packet is completely received, the header can be decoded, -its length calculated, and the data region of the packet +its length calculated, and the data region of the packet can be moved to the data field. On transmission, the opposite occurs: the data region (and footer if need be) are moved to be contiguous with the header. Note that @@ -694,24 +694,24 @@ Alternatively, the radio stack can institute a single copy at the botttom layer. - -4. Implementation -The definition of message_t can be found in + +4. Implementation +The definition of message_t can be found in tinyos-2.x/tos/types/message.h. The definition of the CC2420 message format can be found in tinyos-2.x/tos/chips/cc2420/CC2420.h. -The defintion of the CC1000 message format can be found in + The defintion of the CC1000 message format can be found in tinyos-2.x/tos/chips/cc1000/CC1000Msg.h. The definition of the standard serial stack packet format can be found in tinyos-2.x/tos/lib/serial/Serial.h The definition of -the telos family packet format can be found in +the telos family packet format can be found in tinyos-2.x/tos/platform/telosa/platform_message.h and the micaz format can be found in tinyos-2.x/tos/platforms/micaz/platform_message.h. - -5. Author's Address + +5. Author's Address Philip Levis 358 Gates Hall @@ -723,8 +723,8 @@ the telos family packet format can be found in email - pal@cs.stanford.edu - -6. Citations + +6. Citations diff --git a/doc/html/tep112.html b/doc/html/tep112.html index fdde709e..1d31e63a 100644 --- a/doc/html/tep112.html +++ b/doc/html/tep112.html @@ -3,7 +3,7 @@ - +Microcontroller Power Management - Microcontroller Power Management @@ -303,14 +302,15 @@ ul.auto-toc { - + - + Robert Szewczyk, Philip Levis, Martin Turon, Lama Nachman, Philip Buonadonna, Vlado Handziski Draft-Created: 19-Sep-2005 Draft-Version: 1.6 Draft-Version: 1.7 Draft-Modified: 2006-12-20 Draft-Modified: 2007-01-10 Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu> + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -318,13 +318,13 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract + +Abstract This memo documents how TinyOS manages the lower power state of a microcontroller. - -1. Introduction + +1. Introduction Microcontrollers often have several power states, with varying power draws, wakeup latencies, and peripheral support. The microcontroller should always be in the lowest possible power state that can satisfy @@ -340,8 +340,8 @@ bit, and a power state override. This memo documents these mechanisms and how they work, as well as the basics of subsystem power management. - -2. Background + +2. Background The TinyOS scheduler[2] puts a processor into a sleep state when the task queue is empty. However, processors can have a spectrum of power states. For example, the MSP430 has one active mode (issuing @@ -393,8 +393,8 @@ to give the TinyOS microcontroller power manager information on their requirements, which it considers when calculating the right low power state. - -3. Microcontroller Power Management + +3. Microcontroller Power Management TinyOS 2.x uses three basic mechanisms to manage and control microcontroller power states: a dirty bit, a chip-specific low power state calculation function, and a power state override function. The @@ -457,8 +457,8 @@ whose signature MUST include the following interfaces: McuSleepC MAY have additional interfaces. - -3.1 The Dirty Bit + +3.1 The Dirty Bit Whenever a Hardware Presentation Layer (HPL, see TEP 2: Hardware Abstraction Architecture[1]) component changes an aspect of hardware configuration that might change the possible low power state @@ -468,8 +468,8 @@ McuPowerState.update() is called, then McuSleepC MUST recompute the low power state before the next time it goes to sleep as a result of McuSleep.sleep() being called. - -3.2 Low Power State Calculation + +3.2 Low Power State Calculation McuSleepC is responsible for calculating the lowest power state that it can safely put the microcontroller into without disrupting the operation of TinyOS subsystems. McuSleepC SHOULD minimize how often it @@ -549,8 +549,8 @@ combine function would look like this: - -3.3 Power State Override + +3.3 Power State Override When McuSleepC computes the best low power state, it MUST call PowerOverride.lowestState(). McuSleepC SHOULD have a default implementation of this command, which returns the lowest power state @@ -573,8 +573,8 @@ mcu_power_t means that this command can have fan-out calls. Section 5 describes one example use of McuPowerOverride, in the timer stack for the Atmega128 microcontroller family. - -4. Peripherals and Subsystems + +4. Peripherals and Subsystems At the HIL level, TinyOS subsystems generally have a simple, imperative power management interface. Depending on the latencies involved, this interface is either StdControl, SplitControl, @@ -587,24 +587,24 @@ change in status and control registers (e.g., a clock is disabled). Following the requirements in 3.1, the MCU power management subsystem will be notified of a significant change and act appropriately when the system next goes to sleep. TEP 115[5] -describes the power management of non-virtualized devices in +describes the power management of non-virtualized devices in greater detail, and TEP 108[4] describes how TinyOS can automatically include power management into shared non-virtualized devices. - -5. Implementation -An implementation of McuSleepC can be found in tinyos-2.x/tos/chips/atm128, + +5. Implementation +An implementation of McuSleepC can be found in tinyos-2.x/tos/chips/atm128, tinyos-2.x/tos/chips/msp430, and tinyos-2.x/tos/chips/px27ax. An example of a use of McuPowerOverride can be found in the atmega128 timer system. Because some low-power states have much longer wakeup latencies than others, the timer system does not allow long latencies if it has a timer -that is going to fire soon. The implementation can be found in +that is going to fire soon. The implementation can be found in tinyos-2.x/tos/chips/atm128/timer/HplAtm128Timer0AsyncP.nc, and tinyos-2.x/tos/chips/atm128/timer/HplAtm128Timer0AsyncC.nc automatically wires it to McuSleepC if it is included. - -6. Author's Address + +6. Author's Address Robert Szewczyk Moteiv Corporation @@ -659,8 +659,8 @@ wires it to McuSleepC if it is included. - -6. Citations + +6. Citations diff --git a/doc/html/tep113.html b/doc/html/tep113.html index 1d0a36ee..db1be6fc 100644 --- a/doc/html/tep113.html +++ b/doc/html/tep113.html @@ -3,7 +3,7 @@ - +Serial Communication - Serial Communication @@ -311,6 +310,7 @@ ul.auto-toc { + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -318,8 +318,8 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract + +Abstract This memo describes the structure and standard implementation of the TinyOS 2.x serial communication system for mote-to-PC data exchange. The system is broken into three levels (encoding, framing, @@ -329,8 +329,8 @@ are not bound to the mote's radio packet format. Additionally, one of the supported packet formats is platform independent, so PC-side applications can communicate with arbitrary motes. - -1. Introduction + +1. Introduction Users need to read data out of a TinyOS network. The most common approach is to attach a mote to a PC or laptop with a wired connection. While the interface on the PC side can vary from a serial @@ -345,8 +345,8 @@ parallel with platform-independent communication, which simplifies the PC toolchain. This memo documents the protocols and structure of the TinyOS 2.x serial communication stack. - -2. Serial Stack Structure + +2. Serial Stack Structure The TinyOS 2.x serial communication stack is broken up into four functional components. From bottom to top, they are @@ -357,20 +357,20 @@ functional components. From bottom to top, they are Structurally, they look like this: - _____________________ -| | + _____________________ +| | | Dispatcher | Packet formatting. -|_____________________| - _____________________ -| | +|_____________________| + _____________________ +| | | Protocol | Acknowledgements, CRC computation, |_____________________| windowing. - _____________________ -| | + _____________________ +| | | Encoder/Framer | Translating raw bytes into frame |_____________________| delimiters, escape bytes. - _____________________ -| | + _____________________ +| | | Raw UART | Platform code for reading/writing |_____________________| bytes over the serial connection. @@ -401,15 +401,15 @@ particular packet format begins (based on its header size). Section 3.4 describes how the default TinyOS 2.x implementation, SerialDispatcherC does this. - -3. The 2.x Serial Stack Implementation + +3. The 2.x Serial Stack Implementation Section 2 describes the basic structure of the TinyOS 2.x serial stack. This section describes its actual implementation, including SerialActiveMessageC, which sits on top of the Dispatcher. All of the components except for UartC are part of the serial library that lives in tos/lib/serial. - -3.1 Raw UART: UartC + +3.1 Raw UART: UartC The UART HIL[TEP2] is UartC, which provides a byte-level interface to the underlying serial communication. It provides the SerialByteComm interface: @@ -439,8 +439,8 @@ interface SerialFlush { It may provide additional interfaces for configuring the serial port. This TEP does not consider this topic. - -3.2 Encoder/Framer: HdlcTranslateC + +3.2 Encoder/Framer: HdlcTranslateC HdlcTranslateC is the serial encoder/framer. It uses the SerialByteComm interface and provides the SerialFrameComm interface: @@ -475,8 +475,8 @@ the transmitEscape flag to true, stores the data byte XOR -3.3 Protocol: SerialP + +3.3 Protocol: SerialP The SerialP component implements the serial protocol using PPP/HDLC- like framing (See RFC 1662[RFC1662]). Type dispatch and buffer management are left to higher layers in the serial stack. The protocol @@ -535,8 +535,8 @@ stored in a queue separate from the data buffer, so a data packet to be transmitted may begin spooling into SerialP while SerialP is actively sending an acknowledgement. - -3.4 Dispatcher: SerialDispatcherC + +3.4 Dispatcher: SerialDispatcherC SerialDispatcherC handles the data packets that the Protocol component receives. It uses the SendBytePacket and ReceiveBytePacket interfaces, and provides parameterized Send and Receive interfaces. The parameter @@ -574,8 +574,8 @@ active messages (TOS_SERIAL_802_1 TOS_SERIAL_UNKNOWN_ID are reserved. New packet formats MUST NOT reuse any reserved identifiers. - -3.5 SerialActiveMessageC + +3.5 SerialActiveMessageC SerialActiveMessageC is a platform-independent active message layer that operates on top of the serial communication stack. SerialActiveMessageC is a configuration that wires @@ -597,18 +597,18 @@ configuration SerialActiveMessageC { implementation { components new SerialActiveMessageP() as AM, SerialDispatcherC; components SerialPacketInfoActiveMessageP as Info; - + Init = SerialDispatcherC; Leds = SerialDispatcherC; - + AMSend = AM; Receive = AM; Packet = AM; AMPacket = AM; - + AM.SubSend -> SerialDispatcherC.Send[TOS_SERIAL_ACTIVE_MESSAGE_ID]; AM.SubReceive -> SerialDispatcherC.Receive[TOS_SERIAL_ACTIVE_MESSAGE_ID]; - + SerialDispatcherC.SerialPacketInfo[TOS_SERIAL_ACTIVE_MESSAGE_ID] -> Info; } @@ -629,17 +629,17 @@ typedef nx_struct SerialAMHeader { } SerialAMHeader; - -3.6 Packet Format + +3.6 Packet Format A data packet in the TinyOS 2.x serial stack has the following format over the wire. Each protocol field is associated with a specific component: ____________________________________________ | | | | | | | | - | | | | | | | | + | | | | | | | | |_|_|_|_|_______________________________|__|_| F P S D Payload CR F - + F = Framing byte, denoting start of packet: HdlcTranslateC P = Protocol byte: SerialP S = Sequence number byte: SerialP @@ -658,8 +658,8 @@ destination 0xbeef with a payload of 1 2 3 4 5 would look like this: (P) is 0x40 (64), corresponding to SERIAL_PROTO_ACK (in Serial.h). - -4. Access Abstractions + +4. Access Abstractions Two generic components: SerialAMSenderC and SerialAMReceiverC connect to SerialActiveMessageC to provide virtualized access to the serial stack. Each instantiation of SerialAMSenderC has its own queue of @@ -673,8 +673,8 @@ Section 4 of TEP 116[TEP116] for more in services in the TEP 116, the serial component virtualizations provide no snooping capabilities. - -5. Author's Address + +5. Author's Address Philip Levis 358 Gates @@ -695,8 +695,8 @@ no snooping capabilities. email - benjamin.m.greenstein@intel.com - -6. Citations + +6. Citations diff --git a/doc/html/tep114.html b/doc/html/tep114.html index 0716697f..ad214be2 100644 --- a/doc/html/tep114.html +++ b/doc/html/tep114.html @@ -3,7 +3,7 @@ - +SIDs: Source and Sink Independent Drivers - SIDs: Source and Sink Independent Drivers @@ -303,14 +302,15 @@ ul.auto-toc { - + - + Gilman Tolle, Philip Levis, and David Gay Draft-Created: 30-Oct-2005 Draft-Version: 1.6 Draft-Version: 1.7 Draft-Modified: 2006-12-12 Draft-Modified: 2007-01-10 Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu> + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -318,13 +318,13 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract -This memo documents a set of hardware- and sensor-independent interfaces + +Abstract +This memo documents a set of hardware- and sensor-independent interfaces for data sources and sinks in TinyOS 2.x. - -1. Introduction + +1. Introduction Sensing is an integral part of any sensor network application. Having a wide variety of sensor interfaces usually does not impose a large burden on an application developer, as any given application uses a @@ -335,8 +335,8 @@ systems, they require a sensor-independent interface. TinyOS 2.0 therefore has telescoping sensor abstractions, providing both simple and sensor-independent as well as sensor-specific interfaces. - -2. Sensors in TinyOS 1.x + +2. Sensors in TinyOS 1.x Early TinyOS sensors were generally analog. To sample one of these sensors, an application makes an analog-to-digital conversion using the MCU ADC. Because all early sensors required ADC conversions, the @@ -380,8 +380,8 @@ interfaces for high performance or special case use, but also simple and common interfaces for basic and portable use. Providing a telescoping sensor abstraction allows both classes of use. - -3. Sensors in TinyOS 2.x + +3. Sensors in TinyOS 2.x TinyOS 2.x has several sensor-independent interfaces, which cover a range of common use cases. These interfaces can be used to write a Source- or Sink-Independent Driver (SID). A SID is source/sink @@ -389,8 +389,8 @@ independent because its interfaces do not themselves contain information on the sort of sensor or device they sit on top of. A SID SHOULD provide one or more of the interfaces described in this section, depending on its expected uses and underlying data model. - -3.1 Split-Phase Small Scalar I/O + +3.1 Split-Phase Small Scalar I/O The first set of interfaces can be used for low-rate scalar I/O: interface Read<val_t> { @@ -432,8 +432,8 @@ complexity of code that is a client of a SID interface. include many basic sensors, such as photo, temp, voltage, and ADC readings. - -3.2 Split-Phase Large Scalar I/O + +3.2 Split-Phase Large Scalar I/O If the SID's data object is too big to be passed efficienctly on the stack, it can provide read/write interfaces that pass parameters by pointer rather than value: @@ -474,11 +474,11 @@ ReadWriteRef. val parameter points to MUST be filled with zeroes. Examples of sensors that are suited to this set of interfaces include those that generate multiple simultaneous readings for which -passing by value is inefficient, such as a two-axis digital +passing by value is inefficient, such as a two-axis digital accelerometer. - -3.4 Single-Phase Scalar I/O + +3.4 Single-Phase Scalar I/O Some devices may have their state cached or readily available. In these cases, the device can provide a single-phase instead of split-phase operation. Examples include a node's MAC address (which @@ -516,8 +516,8 @@ interface GetSetRef<val_t> { } - -3.5 Notification-Based Scalar I/O + +3.5 Notification-Based Scalar I/O Some sensor devices represent triggers, rather than request-driven data acquisition. Examples of such sensors include switches, passive-IR (PIR) motion sensors, tone detectors, and smoke @@ -540,8 +540,8 @@ if an enabled sensor is powered down, then when powered up it MUST remain enabled. The val parameter is used as defined in the Read interface. - -3.7 Split-Phase Streaming I/O + +3.7 Split-Phase Streaming I/O Some sensors can provide a continuous stream of readings, and some actuators can accept a continuous stream of new data. Depending on the rate needed and jitter bounds that higher level components can @@ -559,11 +559,11 @@ interface ReadStream<val_t> { command error_t read( uint32_t usPeriod ); - event void bufferDone( error_t result, + event void bufferDone( error_t result, val_t* buf, uint16_t count ); event void readDone( error_t result ); -} +} The postBuffer command takes an array parameterized by the sample type, and the number of entries in that buffer. A driver can then @@ -594,7 +594,7 @@ interface WriteStream<val_t> { command error_t write( uint32_t period ); - event void bufferDone( error_t result, + event void bufferDone( error_t result, val_t* buf, uint16_t count ); event void writeDone( error_t result ); @@ -604,8 +604,8 @@ interface WriteStream<val_t> { for the ReadStream interface, as are write() and writeDone(). - -4. Summary + +4. Summary According to the design principles described in the HAA[_haa], authors should write device drivers that provide rich, device-specific interfaces that expose the full capabilities of each device. In @@ -615,8 +615,8 @@ providing such an abstraction, driver authors can support developers who only need simple interfaces, and can reduce the effort needed to connect a sensor into a more general system. - -5. Author's Address + +5. Author's Address Gilman Tolle 2168 Shattuck Ave. @@ -647,8 +647,8 @@ connect a sensor into a more general system. - -6. Citations + +6. Citations diff --git a/doc/html/tep115.html b/doc/html/tep115.html index eeff6bea..22440dec 100644 --- a/doc/html/tep115.html +++ b/doc/html/tep115.html @@ -3,7 +3,7 @@ - +Power Management of Non-Virtualised Devices - Power Management of Non-Virtualised Devices @@ -307,11 +306,12 @@ ul.auto-toc { - Draft-Modified: 2007-02-21 Draft-Discuss: TinyOS Developer List + Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu> + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -319,13 +319,13 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract + +Abstract This memo documents how TinyOS 2.x manages the power state of physical (not virtualised) abstractions. - -1. Introduction + +1. Introduction TinyOS platforms have limited energy. A unified power management strategy for all devices and peripherpals is not feasible, as they vary significantly in warm-up times, power profiles, and @@ -354,8 +354,8 @@ arbitrates access with the mechanisms described in - -2. Power Management Models + +2. Power Management Models There are two different models to managing the power state of a peripheral in TinyOS: explicit power management and implicit power management. @@ -383,13 +383,13 @@ should be on or off based on the interfaces they provide to their clients. For example, when a client requests the ADC, this implies the ADC should be on; if there are no requests of the ADC, this implies it should be off. Therefore shared devices do not need to provide a -power control interface. They can use an implicit power management policy. +power control interface. They can use an implicit power management policy. Section 4.2 discusses this in more detail.: /|\ /|\ | | Data Interface Resource - | | + | | ----------------------------------------------------------------------- | Shared Device (implicitly power managed) | ----------------------------------------------------------------------- @@ -410,8 +410,8 @@ Section 4.2 discusses this in more detail.: --------------------------------- -------------------------------- - -3. Explicit Power Management + +3. Explicit Power Management Just as in TinyOS 1.x, TinyOS 2.x has StdControl and SplitControl interfaces in order to control the on and off power states of explicitly managed peripherals. TinyOS 2.x also @@ -422,10 +422,10 @@ The selection of the right interface depends on the latencies involved in changing between these two states as well as the nature of the code (sync or async) executing any of the interfaces commands. - -3.1 Power Management with StdControl + +3.1 Power Management with StdControl Whenever the powerup and powerdown times of a non-virtualised device -are negligible, they SHOULD provide the StdControl interface as +are negligible, they SHOULD provide the StdControl interface as defined below: interface StdControl { @@ -452,7 +452,7 @@ either command MUST return either SUCCESS or FAIL. device MUST be completely powered on, allowing calls to commands of other interfaces implemented by the device to succeed. Upon the successful return of a call to StdControl.stop(), a -device MUST be completely powered down, and any calls to commands +device MUST be completely powered down, and any calls to commands of other interfaces implemented by that device MUST return FAIL or EOFF. If a device is not able to complete the StdControl.start() or StdControl.stop() request for any reason, it MUST return FAIL. @@ -466,9 +466,9 @@ to describe the valid return values for any call made through the -Call -Device On -Device Off +Call +Device On +Device Off @@ -497,8 +497,8 @@ configuration DeviceC { } - -3.2 Power Management with SplitControl + +3.2 Power Management with SplitControl When a device's powerup and powerdown times are non-negligible, the ``SplitControl`` interface MUST be used in place of the ``StdControl`` interface. The definition of this interface can be seen below: @@ -526,18 +526,18 @@ device's power state could not be changed. More explicitly: Successful calls to SplitControl.stop() MUST signal one of SplitControl.stopDone(SUCCESS) or SplitControl.stopDone(FAIL). Upon signaling a SplitControl.startDone(SUCCESS), a device MUST -be completely powered on, and operation requests through calls to commands +be completely powered on, and operation requests through calls to commands of other interfaces implemented by the device MAY succeed. -Upon signalling a SplitControl.stopDone(SUCCESS), a device MUST be -completely powered down, and any subsequent calls to commands of other + Upon signalling a SplitControl.stopDone(SUCCESS), a device MUST be +completely powered down, and any subsequent calls to commands of other interfaces implemented by the device MUST return EOFF or FAIL. If a device is powered on and a successful call to SplitControl.stop() -signals a SplitControl.stopDone(FAIL), the device MUST still be fully -powered on, and operation requests through calls to commands of other +signals a SplitControl.stopDone(FAIL), the device MUST still be fully +powered on, and operation requests through calls to commands of other interfaces implemented by the device MAY succeed. -If a device is powered down and a successful call to SplitControl.start() -signals a SplitControl.startDone(FAIL), the device MUST still be fully -powered down, and operation requests through calls to commands of other + If a device is powered down and a successful call to SplitControl.start() +signals a SplitControl.startDone(FAIL), the device MUST still be fully +powered down, and operation requests through calls to commands of other interfaces implemented by the device MUST return EOFF or FAIL. If a device is not able to complete the SplitControl.start() or SplitControl.stop() requests they MUST return FAIL. @@ -565,11 +565,11 @@ stopDone for stop) MUST NOT be signaled. -Call -Device On -Device Off -Starting -Stopping +Call +Device On +Device Off +Starting +Stopping @@ -611,8 +611,8 @@ configuration DeviceC { } - -3.3 Power Management with AsyncStdControl + +3.3 Power Management with AsyncStdControl The commands and the events of the ``StdControl`` and the ``SplitControl`` interfaces are synchronous and can not be called from within asynchronous code (such as interrupt service routines, etc.). For the @@ -641,54 +641,54 @@ configuration DeviceC { Note The AsyncStdControl interface should be provided whenever it might be -necessary to allow a device to be powered on or off while running in -async context. If it is anticipated that a device will not (or more +necessary to allow a device to be powered on or off while running in +async context. If it is anticipated that a device will not (or more likely should not) be powered on or off while in asynchronous context, -then the StdControl interface SHOULD be provided instead. Components +then the StdControl interface SHOULD be provided instead. Components that wish to power the device on or off from within async context would -then be required to post a task before doing so. In practice, -AsyncStdControl is provided by low-level hardware resources, while -StdControl is provided by higher level services built on top of these +then be required to post a task before doing so. In practice, +AsyncStdControl is provided by low-level hardware resources, while +StdControl is provided by higher level services built on top of these resources. - -4. Implicit Power Management + +4. Implicit Power Management While explicit power management provides the mechanism for changing power states, it does not specify a policy. This does not represent a large problem for the simple case -of dedicated devices, but can become crucial for non-trivial cases -involving complex interdependencies between devices controlled by multiple +of dedicated devices, but can become crucial for non-trivial cases +involving complex interdependencies between devices controlled by multiple clients. -For example, if component A is a client of both component B + For example, if component A is a client of both component B and component C, what happens with B and C if StdControl.stop() is called on component A ? Should components -B and C also be stopped? What about the reverse case where both -B and C are clients of the single shared component, A? If -devices B and C are shut off, should A be shut off as well? +B and C also be stopped? What about the reverse case where both +B and C are clients of the single shared component, A? If +devices B and C are shut off, should A be shut off as well? How can one decide when it is appropriate to cascade such powerup and powerdown requests? The complex nature of the problem is evident from the number of unexpected behaviors in TinyOS 1.x involving StdControl. On several platforms, one of the SPI buses is shared between the radio and the flash device. On some of them, issuing StdControl.stop() on the -radio results in a series of cascaded calls that result in SPI bus -becoming disabled, rendering the communication with the flash impossible. -Of course, the right policy would involve tracking the clients of the -SPI bus and powering it off only once both the radio and the flash +radio results in a series of cascaded calls that result in SPI bus +becoming disabled, rendering the communication with the flash impossible. +Of course, the right policy would involve tracking the clients of the +SPI bus and powering it off only once both the radio and the flash devices were no longer using it. Conversely, the SPI bus should be powered on whenever there is at least one active client. -The selection of the right power management policy to use is a complex -task that depends on the nature of the devices in use, their -interdependency, as well as on any specific application requirements. -For cases when some of these features are known a-priori or are -restricted in some sense, it is preferable that the system provide -architectural support for enforcing a meaningful default power-management -policy instead of passing that task on to the application programmer to be + The selection of the right power management policy to use is a complex +task that depends on the nature of the devices in use, their +interdependency, as well as on any specific application requirements. +For cases when some of these features are known a-priori or are +restricted in some sense, it is preferable that the system provide +architectural support for enforcing a meaningful default power-management +policy instead of passing that task on to the application programmer to be solved on a case-by-case basis. - -4.1. Power Management Policies + +4.1. Power Management Policies Just as generic arbiters are offered in TinyOS 2.x to provide the arbitration functionality required by shared resources, generic power management policies are also offered to allow the power management of @@ -718,27 +718,27 @@ interface ResourceDefaultOwner { ResourceDefaultOwner.granted() event to be signaled in order to gain ownership over the resource device. Once it owns the device, the Power Manager is free to execute its -power-management policy using the StdControl-like interface provided by the -underlying resource. Different power managers can implement different +power-management policy using the StdControl-like interface provided by the +underlying resource. Different power managers can implement different policies. In the simplest case, this would involve an immediate power-down -via one of the stop() commands. When the power-state transition -involves non-negligible costs in terms of wake-up latency or power -consumption, the PowerManager might revert to a more intelligent -strategy that tries to reduce these effects. As pointed out in the -introduction, one such strategy might involve the use of a timer to defer -the power-down of the resource to some later point in time, giving any -resource clients a window of opportunity to put in requests before the +via one of the stop() commands. When the power-state transition +involves non-negligible costs in terms of wake-up latency or power +consumption, the PowerManager might revert to a more intelligent +strategy that tries to reduce these effects. As pointed out in the +introduction, one such strategy might involve the use of a timer to defer +the power-down of the resource to some later point in time, giving any +resource clients a window of opportunity to put in requests before the device is fully shut down. -Regardless of the power management policy in use, the Power Manager -remains owner of the resource as long as the resource is not requested + Regardless of the power management policy in use, the Power Manager +remains owner of the resource as long as the resource is not requested by one of its clients. Whenever a client puts in a request, the -Power Manager will receive a ResourceDefaultOwner.requested() event -(or immediateRequested() event) from the arbiter it is associated with. -Upon receiving this event, the Power Manager MUST power up the +Power Manager will receive a ResourceDefaultOwner.requested() event +(or immediateRequested() event) from the arbiter it is associated with. +Upon receiving this event, the Power Manager MUST power up the resource through the StdControl-like interface provided by the lower level abstraction of the physical device. The Power Manager SHOULD release the ownership of the resource (using the ResourceDefaultOwner.release() -command) but MUST wait until after the resource has been fully powered on +command) but MUST wait until after the resource has been fully powered on before doing so. Modeling devices as shared resources and allowing them to be controlled in the way described here, solves the problems outlined in @@ -750,7 +750,7 @@ management policy being used and the reception of the events answers the question of when. As long as the resource at the bottom of a large set of nested resource clients has been fully released, the power mananger will be able to power down the resource appropriately. -Using the model described above, a resource that uses one of these policies + Using the model described above, a resource that uses one of these policies according to the implicitly power management model could be built as shown below: module MyFlashP { @@ -764,7 +764,7 @@ module MyFlashP { } implementation { ... -} +} generic module PowerManagerC(uint8_t POWERDOWN_DELAY) { provides { @@ -794,12 +794,12 @@ implementation { , MyFlashP; Init = MyFlashP; - Resource = FcfsArbiter; + Resource = FcfsArbiter; FlashCommands = MyFlashP; PowerManagerC.ResourceDefaultUser -> FcfsArbiter; PowerManagerC.SplitControl -> MyFlashP; - + } This example implementation is built out of three components. The @@ -814,25 +814,25 @@ management model. It includes the Power Manager is wired to both the ResourceDefaultUser interface provided by the arbiter, and the -SplitControl interface provided by the flash. All clients of this flash +SplitControl interface provided by the flash. All clients of this flash device are directly connected to the resource interface provided by the arbiter. As outlined above, the PowerManagerC component will use -the events signaled through the ResourceDefaultUser interface to determine +the events signaled through the ResourceDefaultUser interface to determine when to make calls to power the device up and power it down through the SplitControl interface. - -4.2. Example Power Managers: PowerManagerC and DeferredPowerManagerC + +4.2. Example Power Managers: PowerManagerC and DeferredPowerManagerC TinyOS 2.x currently has two default power management policies -that it provides. These policies are implemented by the various -components located under tinyos-2.x/lib/power. The first policy +that it provides. These policies are implemented by the various +components located under tinyos-2.x/lib/power. The first policy is implemented using an immediate power control scheme, whereby devices are powered on and off immediately after they have been requested and released. The second policy is implemented using -a deferred power control scheme, whereby devices are powered +a deferred power control scheme, whereby devices are powered on immediately after being requested, but powered off after some small delay from being released. -Each policy has three different implementations for use by each of + Each policy has three different implementations for use by each of the StdControl, SplitControl, and AsyncStdControl interfaces. For reference, each of the available components are listed below @@ -854,8 +854,8 @@ interfaces. - -5. Author's Address + +5. Author's Address Kevin Klues 503 Bryan Hall @@ -889,11 +889,11 @@ interfaces. Stanford, CA 94305-9030 phone - +1 650 725 9046 -email - pal@cs.stanford.edu +email - pal@cs.stanford.edu - -6. Citations + +6. Citations diff --git a/doc/html/tep116.html b/doc/html/tep116.html index df229cd2..67190d7a 100644 --- a/doc/html/tep116.html +++ b/doc/html/tep116.html @@ -3,7 +3,7 @@ - +Packet Protocols - Packet Protocols @@ -303,14 +302,15 @@ ul.auto-toc { - + - + Philip Levis Draft-Created: 10-Dec-2004 Draft-Version: 1.9 Draft-Version: 1.10 Draft-Modified: 2007-03-21 Draft-Modified: 2007-03-28 Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu> + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -318,21 +318,21 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract -The memo documents the interfaces used by packet protocol components in -TinyOS 2.x as well as the structure and implementation of ActiveMessageC, + +Abstract +The memo documents the interfaces used by packet protocol components in +TinyOS 2.x as well as the structure and implementation of ActiveMessageC, the basic data-link HIL component. It also documents the virtualized active message interfaces AMSenderC and AMReceiverC. - -1. Introduction + +1. Introduction Sensor nodes are network-centric devices. Much of their software complexity comes from network protocols and their interactions. In TinyOS, the basic network abstraction is an active message, a single-hop, unreliable packet. Active messages have a destination address, provide synchronous acknowledgements, and can be of -variable length up to a fixed maximum size. They also have a +variable length up to a fixed maximum size. They also have a type field, which is essentially a protocol identifier for components built on top of this abstraction. In TinyOS 1.x, the component GenericComm provides interfaces for @@ -352,11 +352,11 @@ configuration GenericComm { This component, while simple, has several issues. First, it has the activity() commmand, which does not have a single caller in the entire -TinyOS tree. This command requires GenericComm to allocate a +TinyOS tree. This command requires GenericComm to allocate a timer, wasting CPU cycles and RAM. Second, it does not allow a node to receive packets besides those destined to it. Several network -protocols (e.g., MintRoute [1], TAG [2]) take advantage +protocols (e.g., MintRoute [1], TAG [2]) take advantage of snooping on these packets for a variety of improvements in efficiency or performance. This has led to the creation of GenericCommPromiscuous, whose Receive interface does not distinguish @@ -364,7 +364,7 @@ between packets received that were addressed to the node and packets received that were addressed to other nodes. Choosing one of the two implementations is a global decision across an application. There is a way to enable both reception -semantics at the same time for a different protocols, +semantics at the same time for a different protocols, but they require a creative use of default event handlers. Third, it assumes that components will directly access the packet structure, the accepted approach in TinyOS 1.x. However, directly @@ -378,27 +378,27 @@ This TEP documents the interfaces used to access packet buffers, as well as ActiveMessageC, the basic data-link packet communication HIL. - -2. Communication interfaces + +2. Communication interfaces Packet-level communication has three basic classes of interfaces. -Packet interfaces are for accessing message fields and payloads. +Packet interfaces are for accessing message fields and payloads. Send interfaces are for transmitting packets, and are -distinguished by their addressing scheme. +distinguished by their addressing scheme. The Receive interface is for handling packet reception events. Finally, depending on whether the protocol has a dispatch identifier field, the Receive and Send interfaces may be parameterized in order to support multiple higher-level clients. - -2.1 Packet interfaces -The basic TinyOS 2.x message buffer type is message_t, which is + +2.1 Packet interfaces +The basic TinyOS 2.x message buffer type is message_t, which is described in TEP 111. message_t right-justifies data-link -headers to the data payload so that higher-level components can +headers to the data payload so that higher-level components can pass buffers between different data link layers without having -to move data payloads. This means that the data payload of a +to move data payloads. This means that the data payload of a data link frame is always at a fixed offset of a message_t. Once protocols layer on top of each other, the data payload for components on top of the data link layer are -no longer at a fixed offset. Where a component can put its +no longer at a fixed offset. Where a component can put its header or data depends on what headers underlying components introduce. Therefore, in order to be able to find out where it can put its data, it must query the components below it. @@ -421,7 +421,7 @@ component can also obtain the size of the data region with a call to A component can set the payload length with setPayLoadLength. As Send interfaces always include a length parameter in their send call, this command is not required for -sending, and so is never called in common use cases. Instead, +sending, and so is never called in common use cases. Instead, it is a way for queues and other packet buffering components to store the full state of a packet without requiring additional memory allocation. @@ -430,11 +430,11 @@ comes from whether the packet is being received or sent. In the receive case, determining the size of the existing data payload is needed; in the send case, a component needs to know how much data it can put in the packet. -The Packet interface assumes that headers have a fixed size. -It is difficult to return a pointer into the data region when its + The Packet interface assumes that headers have a fixed size. +It is difficult to return a pointer into the data region when its position will only be known once the header values are bound. Generally, an incoming call to the Packet interface of a protocol -has an accompanying outgoing call to the Packet interface of the +has an accompanying outgoing call to the Packet interface of the component below it. The one exception to this is the data link layer. For example, if there is a network that introduces 16-bit sequence numbers to packets, it might look like this: @@ -475,24 +475,24 @@ implementation { if (len != NULL) { *len -= SEQNO_OFFSET; } - return payload + SEQNO_OFFSET; - } + return payload + SEQNO_OFFSET; + } } The above example is incomplete: it does not include the code for the send path that increments sequence numbers. -In practice, calls to Packet are very efficient even if they + In practice, calls to Packet are very efficient even if they pass through many components before reaching the data link layer. nesC's inlining means that in almost all cases there will not actually be any function calls, and since payload position and length calculations all use constant offsets, -the compiler generally uses constant folding to generate a +the compiler generally uses constant folding to generate a fixed offset. The Packet interface provides access to the one field all packet layers have, the data payload. Communication layers can add additional header and footer fields, and may need to provide access to these fields. If a packet communication component provides access to header -and/or footer fields, it MUST do so through an interface. The interface +and/or footer fields, it MUST do so through an interface. The interface SHOULD have a name of the form XPacket, where X is a name that describes the communication layer. For example, active message components provide both the Packet interface and the AMPacket interface. The latter @@ -520,19 +520,19 @@ stores these values in the packet buffer itself (where the field is), but when necessary it may use the metadata region of message_t or other locations. - -2.2 Sending interfaces + +2.2 Sending interfaces There are multiple sending interfaces, corresponding to different addressing modes. For example, address-free protocols, such as collection routing, provide the basic Send interface. Active message communication has a destination of an AM address, so -it provides the AMSend interface. This, for example, is the +it provides the AMSend interface. This, for example, is the basic, address-free Send interface: interface Send { command error_t send(message_t* msg, uint8_t len); command error_t cancel(message_t* msg); - event void sendDone(message_t* msg, error_t error); + event void sendDone(message_t* msg, error_t error); command uint8_t maxPayloadLength(); command void* getPayload(message_t* msg); @@ -546,7 +546,7 @@ interface AMSend { event void sendDone(message_t* msg, error_t error); command uint8_t maxPayloadLength(); - command void* getPayload(message_t* msg); + command void* getPayload(message_t* msg); } Sending interfaces MUST include these four commands and one event. @@ -560,7 +560,7 @@ both Packet and the sending interface for basic use cases. When called with a length that is too long for the underlying maximum transfer unit (MTU), the send command MUST return ESIZE. The Send and AMSend interfaces have an explicit queue of -depth one. A call to send on either of these interfaces MUST +depth one. A call to send on either of these interfaces MUST return EBUSY if a prior call to send returned SUCCESS but no sendDone event has been signaled yet. More explicitly: @@ -581,8 +581,8 @@ with ECANCEL as its error code. If there is a pending sendDone event and cancel returns FAIL, then sendDone SHOULD occur as if the cancel was not called. - -2.3 Receive interface + +2.3 Receive interface Receive is the interface for receiving packets. It has this signature: interface Receive { @@ -603,12 +603,12 @@ to Packet. The comman and the same semantics as its twin in Packet. Receive has a buffer-swap policy. The handler of the event MUST return a pointer to a valid message buffer for the signaler to use. This -approach enforces an equilibrium between upper and lower packet +approach enforces an equilibrium between upper and lower packet layers. If an upper layer cannot handle packets as quickly as they are arriving, it still has to return a valid buffer to the lower layer. This buffer could be the msg parameter passed to it: it just returns the buffer it was given without looking at it. Following -this policy means that a data-rate mismatch in an upper-level component +this policy means that a data-rate mismatch in an upper-level component will be isolated to that component. It will drop packets, but it will not prevent other components from receiving packets. If an upper layer did not have to return a buffer immediately, then when an @@ -628,8 +628,8 @@ handles a receive event: // Case 1 message_t* Receive.receive(message_t* msg, void* payload, uint8_t len) { - return msg; -} + return msg; +} // Case 2 uint16_t value; @@ -656,33 +656,33 @@ and use the pointer returned from receive MUST NOT be touched, used, or stored after the signaling of receive. - -2.4 Dispatch + +2.4 Dispatch A packet protocol MAY have a dispatch identifier. This generally manifests as the protocol component providing parameterized interfaces (rather than -a single interface instance). A dispatch identifier allows multiple +a single interface instance). A dispatch identifier allows multiple services to use a protocol independently. If a protocol provides a dispatch mechanism, then each dispatch identifier SHOULD correspond to a single packet format: if an identifier corresponds to multiple packet -formats, then there is no way to disambiguate them. Packets whose internal +formats, then there is no way to disambiguate them. Packets whose internal structure depends on their fields (for example, a packet that has a control field which indicates which optional fields are present) do not pose such problems. - -3. HIL: ActiveMessageC -A platform MUST provide ActiveMessageC as a basic HIL to -packet-level communication. ActiveMessageC provides a best-effort, -single-hop communication abstraction. Every active message has a -16-bit destination address and an 8-bit type. There is one reserved -destination address, AM_BROADCAST_ADDR, which has the value + +3. HIL: ActiveMessageC +A platform MUST provide ActiveMessageC as a basic HIL to +packet-level communication. ActiveMessageC provides a best-effort, +single-hop communication abstraction. Every active message has a +16-bit destination address and an 8-bit type. There is one reserved +destination address, AM_BROADCAST_ADDR, which has the value of 0xffff. ActiveMessageC has the following signature: configuration ActiveMessageC { provides { interface Init; - interface SplitControl; + interface SplitControl; interface AMSend[uint8_t id]; interface Receive[uint8_t id]; @@ -694,13 +694,13 @@ configuration ActiveMessageC { } } -The Receive interface is for packets destined to the node, while -the Snoop interface is for packets destined to other nodes. A -packet is destined for a node if its destination AM address is -either the AM broadcast address or an address associated with -the AM stack. Different link layers have different snooping -capabilities. The Snoop interface does not assume always-on -listening, for example, in the case of a TDMA or RTS/CTS data + The Receive interface is for packets destined to the node, while +the Snoop interface is for packets destined to other nodes. A +packet is destined for a node if its destination AM address is +either the AM broadcast address or an address associated with +the AM stack. Different link layers have different snooping +capabilities. The Snoop interface does not assume always-on +listening, for example, in the case of a TDMA or RTS/CTS data link layer. By separating out these two interfaces, ActiveMessageC avoids the complications encountered in 1.x with regards to GenericComm vs. GenericCommPromiscuous. @@ -709,19 +709,19 @@ pass-through wiring to a chip-specific HAL active message implementation. The definition of ActiveMessageC is left to the platform for when a node has more than one radio. In this case, the platform decides how to map the -basic packet abstraction to the hardware underneath. Approaches +basic packet abstraction to the hardware underneath. Approaches include choosing one radio or having some form of address-based dispatch. - -4. AM Services: AMSenderC, AMReceiverC, AMSnooperC, AMSnoopingReceiverC + +4. AM Services: AMSenderC, AMReceiverC, AMSnooperC, AMSnoopingReceiverC TinyOS 2.x provides four component single-hop communication virtualizations to applications: AMReceiverC, AMSnooperC, AMSnoopingReceiverC, and AMSenderC. Each is a generic component that takes an active message ID as a parameter. These components assume the existence of ActiveMessageC. - -4.1 Dispatch: am_id_t + +4.1 Dispatch: am_id_t Active messages have an 8-bit type field, which allows multiple protocols to all use AM communication without conflicting. Following the guidelines for protocol dispatch identifiers, each @@ -729,8 +729,8 @@ am_id_t used in a network SHOULD have a single packet format, so that the am_id_t, combined with the packet contents, are sufficient to determine the exact packet format. - -4.2 AMReceiverC + +4.2 AMReceiverC AMReceiverC has the following signature: generic configuration AMReceiverC(am_id_t t) { @@ -749,8 +749,8 @@ NOT instantiate two AMReceivers with the same am_id_t and MUST NOT instantiate an AMReceiver and an AMSnoopingReceiver with the same am_id_t. - -4.3 AMSnooperC + +4.3 AMSnooperC AMSnooper has an identical signature to AMReceiver: generic configuration AMSnooperC(am_id_t t) { @@ -769,8 +769,8 @@ NOT instantiate two AMSnoopers with the same am_id_t and MUST NOT instantiate an AMSnooper and an AMSnoopingReceiver with the same am_id_t. - -4.4 AMSnoopingReceiverC + +4.4 AMSnoopingReceiverC AMSnoopingReceiverC has an identical signature to AMReceiverC: generic configuration AMSnoopingReceiverC(am_id_t t) { @@ -788,8 +788,8 @@ swaps buffers, a program that instantiates an AMSnoopingReceiverC with a certain am_id_t MUST NOT instantiate another AMSnoopingReceiverC, AMSnooperC, or AMReceiverC with the same am_id_t. - -4.5 AMSenderC + +4.5 AMSenderC AMSenderC has the following signature: generic configuration AMSenderC(am_id_t AMId) { @@ -806,27 +806,27 @@ EBUSY only if there is a send request outstanding on this particular AMSenderC. That is, each AMSenderC has a queue of depth one. The exact order in which pending AMSenderC requests are serviced is undefined, but it MUST be fair, where fair means that each client with outstanding -packets receives a reasonable approximation of an equal share of the +packets receives a reasonable approximation of an equal share of the available transmission bandwidth. - -5. Power Management and Local Address + +5. Power Management and Local Address In addition to standard datapath interfaces for sending and receiving packets, an active message layer also has control interfaces. - -5.1 Power Management + +5.1 Power Management The communication virtualizations do not support power management. ActiveMessageC provides SplitControl for explicit power control. -For packet communication to operate properly, a component in an +For packet communication to operate properly, a component in an application has to call ActiveMessageC.SplitControl.start(). -The HAL underneath ActiveMessageC MAY employ power management +The HAL underneath ActiveMessageC MAY employ power management techniques, such as TDMA scheduling or low power listening, when "on." - -5.2 Local Active Message Address -An application can change ActiveMessageC's local AM address + +5.2 Local Active Message Address +An application can change ActiveMessageC's local AM address at runtime. This will change which packets a node receives and the source address it embeds in packets. To change the local AM address at runtime, a component can wire to the component @@ -836,8 +836,8 @@ a radio has multiple stacks those may have other components for changing their addresses in a stack-specific fashion. - -5. HAL Requirements + +5. HAL Requirements A radio chip X MUST have a packet abstraction with the following signature: @@ -850,12 +850,12 @@ provides interface Packet; provides interface AMPacket; provides interface PacketAcknowledgments; -The component SHOULD be named XActiveMessageC, where X is -the name of the radio chip. The component MAY have additional interfaces. + The component SHOULD be named XActiveMessageC, where X is +the name of the radio chip. The component MAY have additional interfaces. These interfaces can either be chip-specific or chip-independent. - -6. message_t + +6. message_t Active messages are a basic single-hop packet abstraction. Therefore, following TEP 111 [3], all data link and active message headers MUST be in the message_header_t structure of message_t. This ensures @@ -863,7 +863,7 @@ that an active message received from one data link layer (e.g., the radio) can be passed to another data link layer (e.g., the UART) without shifting the data payload. This means that the message_header_t must include all data needed for AM fields, which might introduce headers -in addition to those of the data link. For example, this is an example +in addition to those of the data link. For example, this is an example structure for a CC2420 (802.15.4) header: typedef nx_struct cc2420_header_t { @@ -880,14 +880,14 @@ typedef nx_struct cc2420_header_t { type field, however, has been added to the header structure in order to support AM dispatch. - -7. Implementation -The following files in tinyos-2.x/tos/system provide reference + +7. Implementation +The following files in tinyos-2.x/tos/system provide reference implementations of the abstractions described in this TEP. AMSenderC.nc, AMReceiverC.nc, AMSnooperC.nc, -and AMSnoopingReceiverC.nc are implementations of +and AMSnoopingReceiverC.nc are implementations of virtualized AM services. AMQueueP provides a send queue of n entries for n AMSenderC clients, such that each client has a dedicated entry. @@ -907,7 +907,7 @@ example implementations of packet protocol interfaces: packet protocols provide. -Send.nc is the transmission interface for address-free +Send.nc is the transmission interface for address-free protocols. @@ -928,8 +928,8 @@ can be found in tos/chips/CC2420/ The micaz platform and telos family have an ActiveMessageC.nc which exports the interfaces of CC2420ActiveMessageC. - -8. Author's Address + +8. Author's Address Philip Levis 358 Gates Hall @@ -940,8 +940,8 @@ which exports the interfaces of C phone - +1 650 725 9046 - -9. Citations + +9. Citations diff --git a/doc/html/tep117.html b/doc/html/tep117.html index 077bb58a..2f84dc7a 100644 --- a/doc/html/tep117.html +++ b/doc/html/tep117.html @@ -3,7 +3,7 @@ - +Low-Level I/O - Low-Level I/O @@ -303,14 +302,15 @@ ul.auto-toc { - + - + Phil Buonadonna, Jonathan Hui Draft-Created: 23-Jan-2006 Draft-Version: 1.1.2.9 Draft-Version: 1.5 Draft-Modified: 2006-09-30 Draft-Modified: 2006-12-12 Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu> + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -318,13 +318,13 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract + +Abstract The memo documents the TinyOS 2.x interfaces used for controlling digital IO functionality and digital interfaces. - -1. Introduction + +1. Introduction The canonical TinyOS device is likely to have a variety of digital interfaces. These interfaces may be divided into two broad categories. The first are general purpose digital I/O lines (pins) for @@ -338,8 +338,8 @@ bus formats, we presume SPI, I2C, and UART to have the largest coverage. This memo documents the interfaces used for pins and the three buses. - -2. Pins + +2. Pins General Purpose I/O (GPIO) pins are single, versatile digital I/O signals individually controllable on a particular chip or platform. Each GPIO can be placed into either an input mode or an @@ -380,8 +380,8 @@ interfaces: GpioCapture - -2.1 GeneralIO + +2.1 GeneralIO The GeneralIO HIL interface is the fundamental mechanism for controlling a GPIO pin. The interface provides a mechanism for setting the pin mode and reading/setting the pin value. The toggle function switches the @@ -403,8 +403,8 @@ interface GeneralIO } - -2.2 GpioInterrupt + +2.2 GpioInterrupt The GPIO Interrupt HIL interface provides baseline event control for a GPIO pin. It provides a mechanism to detect a rising edge OR a falling edge. Note that calls to enableRisingEdge and enableFallingEdge are @@ -424,8 +424,8 @@ interface GpioInterrupt { } - -2.3 GpioCapture + +2.3 GpioCapture The GpioCapture interface provides a means of associating a timestamp with a GPIO event. Platforms MAY provide this interface. Some platforms may have hardware support for such a feature. Other @@ -447,14 +447,14 @@ interface GpioCapture { - -3. Buses + +3. Buses Bus operations may be divided into two categories: data and control. The control operations of a particular bus controller are platform specific and not covered here. Instead, we focus on the data interfaces at the HIL level that are expected to be provided. - -3.1 Serial Peripheral Interface + +3.1 Serial Peripheral Interface The Serial Peripheral Interface (SPI) is part of a larger class of Synchronous Serial Protocols. The term SPI typically refers to the Motorola SPI protocols. Other protocols include the National @@ -484,8 +484,8 @@ interface SpiPacket { } - -3.2 I2C + +3.2 I2C The Inter-Integrated Circuit (I2C) interface is another type of digital bus that is often used for chip-to-chip communication. It is also known as a two-wire interface. @@ -506,7 +506,7 @@ interface I2CPacket<addr_size> { The interface is typed according to the addressing space the underlying implementation supports. Valid type values are below. -TI2CExtdAddr - Interfaces uses the extended (10-bit) addressing mode. +TI2CExtdAddr - Interfaces uses the extended (10-bit) addressing mode. TI2CBasicAddr - Interfaces uses the basic (7-bit) addressing mode. The i2c_flags_t values are defined below. The flags define the @@ -516,12 +516,12 @@ ORed together. I2C_START - Transmit an I2C STOP at the beginning of the operation. I2C_STOP - Transmit an I2C STOP at the end of the operation. Cannot be used with the I2C_ACK_END flag. -I2C_ACK_END - ACK the last byte sent from the buffer. This flags is only valid +I2C_ACK_END - ACK the last byte sent from the buffer. This flags is only valid a write operation. Cannot be used with the I2C_STOP flag. - -3.3 UART + +3.3 UART The Universal Asynchronous Receiver/Transmitter (UART) interface is a type of serial interconnect. The interface is "asynchronous" since it recovers timing from the data stream itself, rather than a separate @@ -539,11 +539,11 @@ enabled, the enableReceiveInterrupt command MUST return FAIL. interface UartStream { async command error_t send( uint8_t* buf, uint16_t len ); async event void sendDone( uint8_t* buf, uint16_t len, error_t error ); - + async command error_t enableReceiveInterrupt(); async command error_t disableReceiveInterrupt(); async event void receivedByte( uint8_t byte ); - + async command error_t receive( uint8_t* buf, uint8_t len ); async event void receiveDone( uint8_t* buf, uint16_t len, error_t error ); } @@ -563,8 +563,8 @@ interface UartByte { - -4. Implementation + +4. Implementation Example implementations of the pin interfaces can be found in tos/chips/msp430/pins, tos/chips/atm128/pins, and tos/chips/pxa27x/gpio. Example implementations of the SPI interfaces can be found in tos/chips/msp430/usart, @@ -574,8 +574,8 @@ tos/chips/atm128/i2c, and tos/chips/pxa27x/i2c. Example implementations of the UART interfaces can be found in tos/chips/msp430/usart, tos/chips/atm128/uart/ and tos/chips/pxa27x/uart. - -5. Author's Address + +5. Author's Address Phil Buonadonna Arch Rock Corporation @@ -593,8 +593,8 @@ tos/chips/atm128/uart/ and tos/chips/pxa27x/uart. phone - +1 415 692-0828 x2835 - -6. Citations + +6. Citations diff --git a/doc/html/tep118.html b/doc/html/tep118.html index b5895d4a..f4beab0e 100644 --- a/doc/html/tep118.html +++ b/doc/html/tep118.html @@ -3,7 +3,7 @@ - +Dissemination - Dissemination @@ -303,14 +302,15 @@ ul.auto-toc { - + - + Philip Levis and Gilman Tolle Draft-Created: 10-Dec-2004 Draft-Version: 1.1.2.3 Draft-Version: 1.6 Draft-Modified: 2006-06-20 Draft-Modified: 2006-12-12 Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu> + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -318,15 +318,15 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract + +Abstract The memo documents the interfaces, components, and semantics for disseminating small (smaller than a single packet payload) pieces of data in TinyOS 2.x. Dissemination is reliably delivering a piece of data to every node in a network. - -1. Introduction + +1. Introduction Dissemination is a basic sensor network protocol. The ability to reliably deliver a piece of data to every node allows administrators to reconfigure, query, and reprogram a network. Reliability is @@ -355,15 +355,15 @@ rejoins the network it will only see the most recent. The rest of this document describes a set of components and interfaces for a dissemination service of this kind. - -2. Dissemination interfaces + +2. Dissemination interfaces Small-value dissemination has two interfaces: DisseminationValue and DisseminationUpdate. The former is for consumers of a disseminated value, the latter is for producers. They are as follows: interface DisseminationValue<t> { command const t* get(); - event void changed(); + event void changed(); } interface DisseminationUpdate<t> { @@ -391,8 +391,8 @@ network might reach consensus when nodes have different values. The dissemination protocol therefore MUST have a tie-breaking mechanism, so that eventually every node has the same data value. - -3 Dissemination Service + +3 Dissemination Service A dissemination service MUST provide one component, DisseminatorC, which has the following signature: @@ -421,8 +421,8 @@ implementation { Two different instances of DisseminatorC MUST NOT share the same value for the key argument. - -4 Dissemination Keys + +4 Dissemination Keys One issue that comes up when using this interfaces is the selection of a key for each value. On one hand, using unique() is easy, but this means that the keyspaces for two different compilations of the same @@ -438,7 +438,7 @@ namespace are separated by their most significant bit. A component author might write something like this: #include <disseminate_keys.h> -configuration SomeComponentC { +configuration SomeComponentC { ... } implementation { @@ -449,7 +449,7 @@ implementation { #endif components SomeComponentP; components new DisseminatorC(uint8_t, DIS_SOME_COMPONENT_KEY); - SomeComponentP.ConfigVal -> DisseminatorC; + SomeComponentP.ConfigVal -> DisseminatorC; } To override, you can then make a disseminate_keys.h in your app @@ -464,8 +464,8 @@ protocol. The GUID enables nodes to detect versions from other binaries and not store them. This GUID won't be part of the external interface, but will be used internally. - -5. More Complex Dissemination + +5. More Complex Dissemination An application can use this low-level networking primitive to build more complex dissemination systems. For example, if you want have a dissemination that only nodes which satisfy a predicate receive, you @@ -473,15 +473,15 @@ can do that by making the <t> a struct that stores a predicate and data value in it, and layering the predicate evaluation on top of the above interfaces. - -6. Implementation + +6. Implementation An implementation of this TEP can be found in tinyos-2.x/tos/lib/net. This dissemination implementation uses network trickles [2]. Each dissemination value has a separate trickle. - -6. Author's Address + +6. Author's Address Philip Levis 358 Gates Hall @@ -501,8 +501,8 @@ trickle. email - gtolle@archedrock.com - -7. Citations + +7. Citations @@ -517,7 +517,7 @@ trickle. -Docutils System Messages +Docutils System Messages System Message: ERROR/3 (txt/tep118.txt, line 116); backlink Unknown target name: "tep111". diff --git a/doc/html/tep119.html b/doc/html/tep119.html index 9b5d1274..4b51140a 100644 --- a/doc/html/tep119.html +++ b/doc/html/tep119.html @@ -3,7 +3,7 @@ - + Collection - Collection @@ -307,6 +306,7 @@ ul.auto-toc { + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -314,8 +314,8 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract + +Abstract The memo documents the interfaces, components, and semantics used by collection protocol in TinyOS 2.x. Collection provides a best-effort, multihop delivery of packets to the root of a tree. There may be @@ -323,25 +323,25 @@ multiple roots in a network, and in this case the semantics implemented are of anycast delivery to at least one of the roots. A node sending a packet does not specify which root the packet is destined to. - -1. Introduction + +1. Introduction Collecting data at a base station is a common requirement of sensor network applications. The general approach used is to build one or more collection trees, each of which is rooted at a base -station. When a node has data which needs to be collected, it +station. When a node has data which needs to be collected, it sends the data up the tree, and it forwards collection data that other nodes send to it. Sometimes, depending on the form of data collection, systems need to be able to inspect packets as they go by, either to gather statistics, compute aggregates, or suppress redundant transmissions. When a network has multiple base stations that act as root nodes, -rather than one tree, it has a forest of trees. By picking a +rather than one tree, it has a forest of trees. By picking a parent node, a collection protocol implicitly joins one of these trees. Collection provides a best-effort, multihop delivery of packets to one of a network's tree roots: it is an anycast protocol. The semantics is that the protocol will make a reasonable effort to deliver the message to at least -one of the roots in the network. There are however no guarantees of +one of the roots in the network. There are however no guarantees of delivery, and there can be duplicates delivered to one or more roots. There is also no ordering guarantees. Given the limited state that nodes can store and a general need @@ -354,8 +354,8 @@ family: Loop detection, detecting when a node selects one of its descendants as a new parent. -Duplicate suppression, detecting and dealing with when lost -acknowledgments are causing packets to replicate in the + Duplicate suppression, detecting and dealing with when lost +acknowledgments are causing packets to replicate in the network, wasting bandwidth. Link estimation, evaluating the link quality to single-hop neighbors. @@ -366,16 +366,16 @@ from introducing interference for subsequent packets. The rest of this document describes a set of components and interfaces for a collection service outlined above. - -2. Collection interfaces + +2. Collection interfaces A node can perform four different roles in collection: producer, consumer, snooper, and in-network processor. Depending on their role, the nodes use different interfaces to interact with the collection component. A consumer is a root of a tree. The set of all roots and the paths that lead to them form the collection routing infrastructure in the network. -For any connected set of nodes implementing the collection protocol -there is only one collection infrastructure, i.e., all roots in this +For any connected set of nodes implementing the collection protocol +there is only one collection infrastructure, i.e., all roots in this set active at the same time are part of the same infrastructure. A node is configured to become a root by using the RootControl interface. RootControl.setRoot() MUST make the current node a root of @@ -413,8 +413,8 @@ to Receive during instantiation. a packet. The collection identifier is specified as a parameter to Intercept during instantiation. - -3 Collection Services + +3 Collection Services A collection service MUST provide one component, CollectionC, which has the following signature: @@ -463,8 +463,8 @@ is supposed to forward, it MAY signal Snoop.receive. CollectionC SHOULD NOT configure a node as a root by default. Packet and CollectionPacket allow components to access collection data packet fields [1]. - -3.1 CollectionSenderC + +3.1 CollectionSenderC Collection has a virtualized sending abstraction, the generic component CollectionSenderC: @@ -482,8 +482,8 @@ have a single packet format, so that receivers can parse a packet based on its collection ID and contents. - -4 Implementation + +4 Implementation An implementation of this TEP can be found in tinyos-2.x/tos/lib/net/ctp and tinyos-2.x/tos/lib/net/le, in the CTP protocol. It is beyond the scope of this document to fully @@ -498,8 +498,8 @@ ease of use through modularization. Neighbor management and link estimation are decoupled from the routing protocol. Furthermore, the routing protocol and route selection are decoupled from the forwarding policies, such as queueing and timing. - -4.1 LinkEstimatorP + +4.1 LinkEstimatorP LinkEstimatorP estimates the quality of link to or from each neighbor. Link estimation can be done in a variety of ways, and we do not impose one here. It is decoupled from the establishment of @@ -552,23 +552,23 @@ interface LinkEstimator { } - -4.2 CtpRoutingEngineP + +4.2 CtpRoutingEngineP CtpRoutingEngineP is responsible for computing routes to the roots of a tree. In traditional networking terminology, this is part of the control plane of the network, and is does not directly forward any -data packets, which is the responsibility of CtpForwardingEngine. +data packets, which is the responsibility of CtpForwardingEngine. The main interface between the two is UnicastNameFreeRouting. CtpRoutingEngineP uses the LinkEstimator interface to learn about the nodes in the neighbor table maintained by LinkEstimatorP and the quality of links to and from the neighbors. The routing protocol on which collection is implemented MUST be a tree-based routing -protocol with a single or multiple roots. CtpRoutingEngineP +protocol with a single or multiple roots. CtpRoutingEngineP allows a node to be configured as a root or a non-root node dynamically. CtpRoutingEngineP maintains multiple candidate next hops: -generic module CtpRoutingEngineP(uint8_t routingTableSize, - uint16_t minInterval, +generic module CtpRoutingEngineP(uint8_t routingTableSize, + uint16_t minInterval, uint16_t maxInterval) { provides { interface UnicastNameFreeRouting as Routing; @@ -577,7 +577,7 @@ generic module CtpRoutingEngineP(uint8_t routingTableSize, interface StdControl; interface CtpRoutingPacket; interface Init; - } + } uses { interface AMSend as BeaconSend; interface Receive as BeaconReceive; @@ -603,10 +603,10 @@ interface UnicastNameFreeRouting { } - -4.3 CtpForwardingEngineP + +4.3 CtpForwardingEngineP The CtpForwardingEngineP component provides all the top level interfaces -(except RootControl) which CollectionC provides and an application +(except RootControl) which CollectionC provides and an application uses. It deals with retransmissions, duplicate suppression, packet timing, loop detection, and also informs the LinkEstimator of the outcome of attempted transmissions.: @@ -663,10 +663,10 @@ QEntryPool - -5. Author's Address + +5. Author Addresses -Rodrigo Fonseca +Rodrigo Fonseca 473 Soda Hall Berkeley, CA 94720-1776 @@ -675,9 +675,9 @@ QEntryPool Omprakash Gnawali -Ronald Tutor Hall (RTH) 418 +Ronald Tutor Hall (RTH) 418 3710 S. McClintock Avenue -Los Angeles, CA 90089 +Los Angeles, CA 90089 phone - +1 213 821-5627 email - gnawali@usc.edu @@ -686,7 +686,7 @@ QEntryPool Kyle Jamieson The Stata Center 32 Vassar St. -Cambridge, MA 02139 +Cambridge, MA 02139 email - jamieson@csail.mit.edu @@ -701,8 +701,8 @@ QEntryPool email - pal@cs.stanford.edu - -6. Citations + +6. Citations @@ -712,7 +712,7 @@ QEntryPool - + [2] TEP 124: The Collection Tree Protocol (CTP) - (upcoming) [2] TEP 123: The Collection Tree Protocol (CTP) diff --git a/doc/html/tep120.html b/doc/html/tep120.html index e50e9f14..71707b07 100644 --- a/doc/html/tep120.html +++ b/doc/html/tep120.html @@ -3,9 +3,20 @@ - + TinyOS Alliance Structure - + + + + + + + + + + + + - TinyOS Alliance Structure @@ -299,29 +309,41 @@ ul.auto-toc { - - + + + + + + + + + + + + + + + + + + + + + + + + - + - + Draft TinyOS-Version: All Authors: Philippe Bonnet - David Culler - Deborah Estrin - Ramesh Govindan - Mike Horton - Jeonghoon Kang - Philip Levis - Lama Nachman - Jack Stankovic - Rob Szewczyk - Matt Welsh - Adam Wolisz Author: Philippe Bonnet Author: David Culler Author: Deborah Estrin Author: Ramesh Govindan Author: Mike Horton Author: Jeonghoon Kang Author: Philip Levis Author: Lama Nachman Author: Jack Stankovic Author: Rob Szewczyk Author: Matt Welsh Author: Adam Wolisz Draft-Created: 17-April-2006 Draft-Version: 1.1.2.5 Draft-Version: 1.5 Draft-Modified: 2006-10-25 Draft-Modified: 2006-12-12 Draft-Discuss: TinyOS Alliance <tinyos-alliance at mail.millennium.berkeley.edu> + Note This memo documents a blueprint for an open alliance aroung @@ -330,24 +352,24 @@ suggestions for improvement. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract + +Abstract This memo describes the goals and organization structure of the TinyOS Alliance. It covers membership, the working group forums for contribution, intellectual property, source licensing, and the TinyOS Steering Committee (TSC). - -1. Charter + +1. Charter Formulate a legal and organizational framework for an alliance that can facilitate the continued advancement of the open embedded network ecosystem around TinyOS and support the activities, interactions, and development of the worldwide academic and industrial TinyOS community. - -2. Overview -This memo defines a blueprint and conceptual foundation for an open -alliance that fulfills the above charter. + +2. Overview +This memo defines a blueprint and conceptual foundation for an open +alliance that fulfills the above charter. It defines the following ten aspects of the alliance: @@ -363,9 +385,9 @@ It defines the following ten aspects of the alliance: Work products -We (the Alliance) recognize that each of these aspects contributes to the -whole, is inter-related and needs to be consistent overall. This document -attempts to address them sequentially, recognizing that each depends on the + We (the Alliance) recognize that each of these aspects contributes to the +whole, is inter-related and needs to be consistent overall. This document +attempts to address them sequentially, recognizing that each depends on the others. It draws on lessons from several related organizations, although each of these also has significantly different goals from those set out in the charter. @@ -377,7 +399,7 @@ different goals from those set out in the charter. OSGI - Service layer FSF - Foundational software -We (the Alliance) draw most strongly upon the IETF, even though that + We (the Alliance) draw most strongly upon the IETF, even though that organization was focused around creating and standardizing protocols, rather than developing a code base. Its emphasis on rough consensus AND @@ -439,8 +461,8 @@ from obtaining blocking IP. It does discourage contributions that might pull IP into the pool. We prefer a process of declaration and multiple implementation. - -3. Mission + +3. Mission The mission of the TinyOS Alliance is to provide a forum to facilitate: @@ -451,20 +473,20 @@ TinyOS technology and surrounding tools through the creation of standard interfaces and protocols, vetted extensions, open reference implementations, technical documents, testing and verification suites, and educational materials, -the contribution of innovative technology from a world-wide research + the contribution of innovative technology from a world-wide research community and the maturation and dissemination of these contributions, and -the promotion of the technology, the community, and the impact of networked + the promotion of the technology, the community, and the impact of networked embedded systems. - -4. Organizational Structure + +4. Organizational Structure The Alliance has a technical advisory function: guide the evolution of the TinyOS architecture, formulate and track progress of working groups, and provide an open and impartial process for technical -documentation. It also has an organizational advisory function: manage +documentation. It also has an organizational advisory function: manage industry interaction, legal and IP issues, evolution of the organization itself, membership issues and so on. @@ -482,8 +504,8 @@ and built on consensus. Directors, a small support staff (primarily volunteer or outsourced) and a Steering Committee. The Steering Committee oversees a collection of Working Groups, each with a Chair and Members. - -4.1 Steering Committee + +4.1 Steering Committee In the steady state the Steering Committee will consist of the chairs of working groups plus a handful of elected members at large. Tenure of a position on the Steering Committee will consist of two years with @@ -517,26 +539,26 @@ procedures, membership criteria, selection of venues, oversight of access to code repositories and Alliance web sites, and regular Alliance meetings. - -4.2 Working Groups + +4.2 Working Groups The working groups form the core of the alliance. Each working group will have a chair who will be responsible for WG processes, reporting, meetings, and membership. Working groups and their functions are discussed in more detail in a later section. - -4.3 Board of Directors + +4.3 Board of Directors The non-profit will require a Board of Directors responsible for corporate matters. - -5. Membership and Participation + +5. Membership and Participation We desire to continue the TinyOS tradition of promoting broad membership. This means that we want to keep barriers to entry low in all respects: legal, financial, and organizational. As with IETF and Apache, we want to shape the organization as a meritocracy that -encourages, promotes, and credits the contributions of its members. +encourages, promotes, and credits the contributions of its members. Companies have essential role, but merit, not finances should dictate direction. Membership and influence should recognize the importance of adopters, not just developers. @@ -559,7 +581,7 @@ have voting rights. There is no individual membership fee, but members will be responsible for nominal registration fees at Alliance meetings. -Corporations and organizational have institutional membership, which reflects + Corporations and organizational have institutional membership, which reflects their degree of effort. @@ -589,11 +611,11 @@ be members of corporations, academic institutions, govermental institutions, or unaffiliated. We will provide a fee structure that encourages the participation of small companies and start-ups. - -6. Working Groups + +6. Working Groups There will be two forms of working groups. LONG-STANDING groups are chartered to develop important areas or subsystems. For -example, we expect longstanding groups on +example, we expect longstanding groups on routing, management, platforms, testing, programming tools, and education. SHORT-TERM groups have a fixed mandate to tackle a particular topic. For example, there may be groups to develop a @@ -620,8 +642,8 @@ IP, but standards should not require the use of such IP and should allow for multiple, interoperable implementations. The Steering committee will be engaged in ratification of standards. - -7. Intellectual Property + +7. Intellectual Property In general we want to promote the development, adoption and use of open technology. We want to avoid having the advancement of embedded networks getting trapped into proprietary IP. Accordingly, our IP @@ -674,8 +696,8 @@ explicit, and not present in core software. It will typically involve development tools, such as the compilers and peripheral Linux-based devices. - -8. Source Licensing + +8. Source Licensing In general, we want to provide a mechanism where individuals and companies can easily contribute source, can utilize what is available, and can gain recognition for their efforts. Following the TinyOS @@ -750,14 +772,14 @@ those that do so, and provide a complaint mechanism to identify misuse. of standardized interfaces and protocols. Alliance is not the only vehicle for producing a hardened, tested, certified code base. To do so would require the Alliance host a large technical staff, as -OSDL does. +OSDL does. Comapanies may do so, or produce implementations with enhanced performance, reliability, or efficiency using their own proprietary technology. The Alliance encourages such innovation while promoting standardized interfaces that allows such technology to interoperate. - -9. Funding + +9. Funding Initially, we expect that there are no full time employees in the Alliance and that funding needs are limited to such items as lawyer's fees, web site costs, and insurance. If the Alliance eventually @@ -773,32 +795,32 @@ associated with adminstration of the meetings. to avoid the heavy-handed quid-pro-quo seen in many industrial consortiums where funding determines influence. The best use of funds and the best form of influence is direct contribution to the work -products of the Alliance. +products of the Alliance. To keep the structure of the Alliance and its operations minimalist and lean, membership focuses on desired impact and recognition, rather than control. We want the best way to influence the direction of the Alliance -to be to contribute technical work and demonstrate leadership, rather than +to be to contribute technical work and demonstrate leadership, rather than try to control what individuals can or cannot contribute. Companies and institutions are encouraged to contribute financial and in-kind support. It will be essential that companies provide initial funding to create the legal structure and to establish basic IT capabilities to host the web site and working groups. Institutional members -will pay an annual membership fee. In some cases, a +will pay an annual membership fee. In some cases, a contributing corporate member may provide in-kind services such as lawyers' time used to -draw up or comment on by-laws. +draw up or comment on by-laws. Targeted contributions will be -solicited and encouraged. In this case the donator need not +solicited and encouraged. In this case the donator need not become a contributing corporate member, e.g., in those cases where such a membership may be prohibited or unwanted. The costs of meetings, such as the TinyOS technology exchange, will be covered through registration fees and not by institutional membership fees. - -10. Work Products -The broad mission of the Alliance calls for a broad range of + +10. Work Products +The broad mission of the Alliance calls for a broad range of work products. Foremost among these are a set of TEPs documenting systems and protocols as well as TEPs that provide guidance @@ -807,10 +829,10 @@ robust and open reference implementations for the community to use, refine, improve, and discuss. These reference implementations will not preclude alternative, compatibile implementations which may have additional features or optimizations. The Alliance Working Groups -will periodically produce periodic releases of these reference +will periodically produce periodic releases of these reference implementations for the community to use and improve. The Alliance will support community contributions -of innovative extensions and systems by providing a CVS repository +of innovative extensions and systems by providing a CVS repository to store them. In order to keep these contributions organized for users, the Steering Committee may nominate one or more people to caretake @@ -826,21 +848,21 @@ simple and complex example applications, and user guides. is to teach new developers about the internals and workings of the technology, the Alliance will develop and make available several end-user applications and tools. The goal is to improve -the accessibility of the technology to end-users while +the accessibility of the technology to end-users while demonstrating its effectiveness. Historical examples of such applications include Surge and TinyDB. An important part of this effort is good documentation for users who are not expert programmers, as well as tools and graphical environments. - -11. Conclusions -By focusing on consensus building and technical excellence, the + +11. Conclusions +By focusing on consensus building and technical excellence, the Alliance seeks to avoid being a forum for political and economic positioning. It will achieve this by focusing on working groups -and the contributions of individuals, while not taking strong +and the contributions of individuals, while not taking strong positions on the benefits or drawbacks of different approaches. The variety of application domains sensornets are used in and -the huge differences in requirements mean that having a suite +the huge differences in requirements mean that having a suite of solutions, rather than a single one, is often not only desirable but essential. Over the past five years, low-power embedded sensor networks have @@ -850,7 +872,7 @@ that actively works to deploy these systems and collaborate with industry, making advances quickly accessible and usable. A great catalyst to this growth has been the presence of a large community around a shared, free code base. -The time has come to create an organizational structure to + The time has come to create an organizational structure to allow the effort to grow further. As sensornets become more widespread, contributions and advancements will be from an increasingly broad demographic of users, and bringing them all together will speed @@ -861,22 +883,22 @@ it depends on broad collaboration and participation, placing a minimalist set of expectations that will encourage the exchange of ideas and technology. - -12. Author's Address + +12. Author's Address -Philippe Bonnet <bonnet.p@gmail.com> -David Culler <culler@cs.berkeley.edu> +Philippe Bonnet <bonnet.p@gmail.com> +David Culler <culler@cs.berkeley.edu> David Culler <dculler at archrock.com>, -Deborah Estrin <destrin@cs.ucla.edu> -Ramesh Govindan <ramesh@usc.edu> -Mike Horton <mhorton@xbow.com> -Jeonghoon Kang <budge@keti.re.kr> +Deborah Estrin <destrin@cs.ucla.edu> +Ramesh Govindan <ramesh@usc.edu> +Mike Horton <mhorton@xbow.com> +Jeonghoon Kang <budge@keti.re.kr> Philip Levis <pal@cs.stanford.edu> Lama Nachman <lama.nachman@intel.com> Jack Stankovic <stankovic@cs.virginia.edu> -Rob Szewczyk <rob@moteiv.com> -Matt Welsh <mdw@cs.harvard.edu> -Adam Wolisz <awo@ieee.org> +Rob Szewczyk <rob@moteiv.com> +Matt Welsh <mdw@cs.harvard.edu> +Adam Wolisz <awo@ieee.org> diff --git a/doc/html/tep121.html b/doc/html/tep121.html index f0e0bc52..3653e4a3 100644 --- a/doc/html/tep121.html +++ b/doc/html/tep121.html @@ -3,7 +3,7 @@ - + Towards TinyOS for 8051 - Towards TinyOS for 8051 @@ -311,20 +310,21 @@ ul.auto-toc { + Note This memo is informational. It will hopefully be a basis for discussions and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract + +Abstract This TEP covers our effort of porting TinyOS to the nRF24E1 platform. We ported the basic modules of TinyOS: Timer, UART, ADC and LEDS. - -1. Project Outline + +1. Project Outline The original 8 bit 8051 chip is a member of the mcs51 family and was developed in 1980 by Intel. It is still to this date one of the most widely used microcontrollers. Porting TinyOS to the 8051 System on chip @@ -355,8 +355,8 @@ the 8051 features. This work was done under the supervision of Martin Leopold at University of Copenhagen. - -2. Project Approach + +2. Project Approach The approach to the porting project has been pragmatic. The focus has been on producing working code, so testing and debugging have been key elements of our work. The process has been to implement new @@ -381,12 +381,12 @@ input from the ADC pins. - -3. Development Environment and Tool Chain + +3. Development Environment and Tool Chain The following subsections describe the different development tools, their selection and interconnection. - -3.1 Selection of Development Tools/Compilers + +3.1 Selection of Development Tools/Compilers A large number of 8051 compilers exist primarily for the DOS and Windows platforms. We have focused on two popular and regularly updated compilers: KEIL and the Small Device C Compiler (SDCC). @@ -417,8 +417,8 @@ the tool chain. We decided to substitute SDCC with the KEIL development kit. This gave us a working debug environment - with minimal change to the already produced code. - -3.1.1 Our Recommendation + +3.1.1 Our Recommendation In our experience the SDCC compiler and associated tools are not yet mature enough to support our development. We recommend pursuing other alternatives such as KEIL or other compiler suites. @@ -426,8 +426,8 @@ alternatives such as KEIL or other compiler suites. the use of open source software and cross-platform development. We hope SDCC will prove an reliable alternative in the future. - -3.2 Tool Chain Overview + +3.2 Tool Chain Overview The following figure and sections are an overview of the current tool chain. The tool chain is based on TinyOS 1.x, NesC 1.1.3, avr-gcc 3.4.3, PERL v. 5.8.6 and SDCC 2.5.4 or KEIL C51 version 7.20. @@ -435,12 +435,12 @@ PERL v. 5.8.6 and SDCC 2.5.4 or KEIL C51 version 7.20. Mangle- TinyOS script ------> app.c -----> app_mangled.c --------> app.hex ------> nRF24E1 +-----> app.c -----> app_mangled.c --------> app.hex ------> nRF24E1 NesC PERL SDCC/KEIL nRFPROG - -3.3 Description of the Tool Chain + +3.3 Description of the Tool Chain The compilation of the TinyOS test program outputs two files, a 'main.exe' file and an 'app.c' file. The 'app.c' file contains all the needed code to run the TinyOS application. However the C code produced @@ -456,8 +456,8 @@ as the rope, tying the output from NesC to the input of SDCC or KEIL. produces a hex file that is transferred to the chip by the nRFPROG software. - -3.4 Description of the Mangling Script + +3.4 Description of the Mangling Script The mangling script is written in PERL, a commonly used general purpose scripting language with powerful pattern matching capabilities and extensive handling of regular expressions. The mangle script handles all @@ -470,7 +470,7 @@ additional alterations. or -"./sdccMangleAppC.pl -SDCC -file build/mcs51/app.c > +"./sdccMangleAppC.pl -SDCC -file build/mcs51/app.c > build/mcs51/app_mangled.c" The 'sdccMangleAppC.pl' script handles a number of needed alterations: @@ -488,8 +488,8 @@ respectively Each of these alterations will be explained in the sections below. - -3.4.1 SFR and SBIT Declarations + +3.4.1 SFR and SBIT Declarations In order to make TinyOS accept the 8051 special function registers (SFR) and special bit variables (SBIT), we have included them into the TinyOS 8051 platform folder as a 8051.h file. @@ -498,7 +498,7 @@ a specific bit within these SFR. In order to make TinyOS accept the SFRs we have type defined them in the NesC code as: -typedef int sfr; +typedef int sfr; sfr P0 __attribute((x80)); which is altered to @@ -513,8 +513,8 @@ updated June 2003) for translating SFR and SBIT declarations from KEIL to SDCC, but it produces code with illegal syntax, so either do not use it, or alter it to produce code with the right syntax. - -3.4.2 SDCC/KEIL Data Types + +3.4.2 SDCC/KEIL Data Types TinyOS and SDCC/KEIL do not support the same data types, so some alterations were needed to compile the code with SDCC and KEIL. @@ -533,8 +533,8 @@ we are working with software that does not support this data type, on a very small hardware memory model, we decided to change the NesC 64 bit data types to 32 bit. This is done in the mangling script. - -3.4.3 Reserved Keywords in SDCC + +3.4.3 Reserved Keywords in SDCC A number of keywords are reserved in SDCC. Half of them represent a directive to the compiler, defining which memory segment on the nRF24E1 the specific lines of code refer to. To ensure that the developer does @@ -599,22 +599,22 @@ Lower 128 bytes | direct and | KEIL it can be changed through selecting it in the options pane for the target. - -3.4.4 Removal of inlining + +3.4.4 Removal of inlining NesC assumes that GCC is being used for the final compilation. GCC supports inline functions and can be made to optimize code quite aggressively, so the code generated by NesC does not need to be very efficient. Unfortunately SDCC does not support code inlining, so the inline statements have to be removed, when compiling for SDCC. Lines with the following format are affected: -static inline void TOSH_sleep(void ); + static inline void TOSH_sleep(void ); static __inline void TOSH_SET_RED_LED_PIN(void); __inline void__nesc_enable_interrupt(void); -Lines with the noinline attribute is substituted with the + Lines with the noinline attribute is substituted with the #pragma NO_INLINE. - -3.4.5 Removal of Preprocessor Line Numbering + +3.4.5 Removal of Preprocessor Line Numbering Also NesC produce preprocessor line number meta data, to allow the compiler to report error messages referring to the original code. We do not really need them for anything, so we filter them out to minimize the @@ -622,26 +622,26 @@ code size. It also eases the code reading significantly. If needed for debug purposes the regular expression in the mangle script which remove them can be commented out. - -3.4.6 Change $ in Identifiers + +3.4.6 Change $ in Identifiers The SDCC compiler is very strict when it comes to valid symbols in identifiers. NesC produce GCC-code which inserts $ as a separator character in identifiers. We mangle the $ to two underscores in order to enable SDCC/KEIL to compile. - -3.4.7 Interrupt Vectors + +3.4.7 Interrupt Vectors The syntax for declaration of interrupt vectors are different in GCC and SDCC/KEIL. So we mangle the interrupt declaration: -From: void __attribute((interrupt)) __vector_5(void) + From: void __attribute((interrupt)) __vector_5(void) To: void __vector_5(void) interrupt 5 Additionally KEIL does not understand that the interrupt vector is defined previous to its use. So we remove the forward declaration of the vectors in the mangle script, when compiling for KEIL. - -4. TinyOS Modifications + +4. TinyOS Modifications TinyOS is based on modules with different levels of hardware abstraction. When porting TinyOS to a new platform, you change the underlying hardware dependencies in TinyOS, and you have to rebuild the @@ -653,26 +653,26 @@ affected the higher abstractions, such as changes in interfaces and interrupt handling. Modified TinyOS modules overview: -+------------------------------------------------------------+ ++------------------------------------------------------------+ | TinyOS Application | App -+------------------------------------------------------------+ ++------------------------------------------------------------+ \/ /\ \/ /\ \/ /\ \/ /\ ----- -+----------+ +----------+ +---------+ +--------+ ++----------+ +----------+ +---------+ +--------+ | Timer | | UART | | ADC | | LEDs | HAL +----------+ +----------+ +---------+ +--------+ \/ /\ \/ /\ \/ /\ ----- ++----------+ +---------------------+ +---------+ +| HPLClock | | HPLUART | | HPLADC | \/ HPL +----------+ +---------------------+ +---------+ -| HPLClock | | HPLUART | | HPLADC | \/ HPL -+----------+ +---------------------+ +---------+ - \/ /\ \/ \/ /\ \/ /\ ----- -+----------+ +--------+ +--------+ +---------+ +--------+ -| Timer2 | | Timer1 | > | Serial | | Sensors | | Port | HW -+----------+ +--------+ | Port | +---------+ +--------+ + \/ /\ \/ \/ /\ \/ /\ ----- ++----------+ +--------+ +--------+ +---------+ +--------+ +| Timer2 | | Timer1 | > | Serial | | Sensors | | Port | HW ++----------+ +--------+ | Port | +---------+ +--------+ +--------+ The following sections describe the changes to the four groups of modules. - -4.1 HPLClock and related modules + +4.1 HPLClock and related modules The 8051 chip has three independent timer/counter circuits: Timer0, Timer1 and Timer2, which can run in various modes. Each timer/counter consists of a 16-bit register that is accessible to software as three @@ -687,8 +687,8 @@ Using a different timer circuit would limit the interval to 0.192 ms, which would result in a great deal of interrupts and consume processing power for administrational overhead. - -4.1.1 Timer + +4.1.1 Timer The Timer module (HAL) uses the HPLClock module to handle the hardware timing. These two modules communicate through the clock interface. However, the standard TinyOS clock interface is designed for an MCU with @@ -700,26 +700,26 @@ options, and the possibility to use a 16 bit timer/counter to compensate for the reduced prescaler options, we decided to widen the clock interface from 8 to 16 bit. We are using the factor 1/4 for the prescaler. -The interface change has affected the following methods: -result_t setRate(uint16_t interval, char scale) -void setInterval(uint16_t value) -void setNextInterval(uint16_t value) + The interface change has affected the following methods: +result_t setRate(uint16_t interval, char scale) +void setInterval(uint16_t value) +void setNextInterval(uint16_t value) uint16_t getInterval() result_t setIntervalAndScale(uint16_t interval, uint8_t scale) -uint16_t readCounter() +uint16_t readCounter() void setCounter(uint16_t n) -See: -Clock.h -Clock.nc -HPLClock.nc -TimerM.nc -TimerC.nc + See: +Clock.h +Clock.nc +HPLClock.nc +TimerM.nc +TimerC.nc 8051.h - -4.2 HPLUART + +4.2 HPLUART The UART is depending on a timer to generate a baud rate for the serial port. The architecture only allows two of the three timers (Timer1 or Timer2), to act as such. Since Timer2 is already used by the clock @@ -735,15 +735,15 @@ as arguments. These pointers refer to the first and last bytes to be sent. The HPLUART interrupt handler was also modified to take the multiple byte data into account. -See: -8051.h -HPLUART.nc -HPLUARTC.nc + See: +8051.h +HPLUART.nc +HPLUARTC.nc HPLUARTM.nc - -4.3 HPLADC + +4.3 HPLADC The TinyOS standard ADC interface was developed for the AVR which includes hardware functionality for repetitive sampling at a given interval. Implementing this functionality on the 8051, which does not @@ -751,15 +751,15 @@ support this in hardware, would require use of the last timer. We chose not to implement repetitive sampling, therefore the setSampleRate method currently has no use. -See: -8051.h -ADCM.nc -HPLADCC.nc + See: +8051.h +ADCM.nc +HPLADCC.nc HPLADCM.nc - -4.4 LEDS + +4.4 LEDS TinyOS features three standard LEDs (Red, Green and Yellow), but the nRF24E1 evaluation board is not equipped with programmable LEDs so we used the general purpose ports (GPIO). @@ -774,19 +774,19 @@ Port0. To visualize the status of the GPIO, including the three standard LEDs, we built a LED expansion board. -The three LEDs are currently wired to: -Red -> P1.0 + The three LEDs are currently wired to: +Red -> P1.0 Green -> P1.1 Yellow -> P0.7. -See: -8051.h -hardware.h -mcs51hardware.h + See: +8051.h +hardware.h +mcs51hardware.h LedsC.nc - -4.5 Interrupts + +4.5 Interrupts In TinyOS interrupts are not implemented as a single module, they are mainly facilitated in atomic blocks and in the init, start and stop methods of the various HPL modules. The init, start and stop methods @@ -796,8 +796,8 @@ module. While the atomic block handle the enabling of global interrupts. This is used to avoid preempting code execution in critical blocks. - -5. Conclusion + +5. Conclusion The project have reached a plateau of development in porting TinyOS to the 8051 platform, on which future development can be based. The basic modules (Timer, UART, ADC and LEDS) have been implemented making 8051 @@ -806,8 +806,8 @@ field of sensor networks, the radio module, is still missing. The result of our work will be uploaded to the TinyOS 8051 Working Group website. - -6. Future Work + +6. Future Work The work presented in this TEP is short of being a complete porting of TinyOS to the 8051 platform. Two obvious future tasks are implementing a Radio module involving the SPI interface and Power Management for duty @@ -817,36 +817,36 @@ main hurdle is the three wire SPI interface. should target TinyOS 2.0. This might be a challenge with the timer interface being so different from TinyOS 1.x. - -7. Authors + +7. Authors -Anders Egeskov Petersen -University of Copenhagen, Dept. of Computer Science -Universitetsparken 1 -DK-2100 KÂ¯benhavn Ã¿ -Denmark +Anders Egeskov Petersen +University of Copenhagen, Dept. of Computer Science +Universitetsparken 1 +DK-2100 KÃ¸benhavn Ã +Denmark -Sidsel Jensen -University of Copenhagen, Dept. of Computer Science -Universitetsparken 1 -DK-2100 KÂ¯benhavn Ã¿ -Denmark +Sidsel Jensen +University of Copenhagen, Dept. of Computer Science +Universitetsparken 1 +DK-2100 KÃ¸benhavn Ã +Denmark email - purps@diku.dk Martin Leoold -University of Copenhagen, Dept. of Computer Science -Universitetsparken 1 -DK-2100 KÂ¯benhavn Ã¿ -Denmark +University of Copenhagen, Dept. of Computer Science +Universitetsparken 1 +DK-2100 KÃ¸benhavn Ã +Denmark Phone +45 3532 1464 email - leopold@diku.dk - -8. Citations + +8. Citations @@ -857,7 +857,7 @@ interface being so different from TinyOS 1.x. - [PEH] Martin Leopold. "Power Estimation using the Hogthrob Prototype Platform" M.Sc. + [PEH] Martin Leopold. "Power Estimation using the Hogthrob Prototype Platform" M.Sc. Thesis, DIKU, Copenhagen University, Denmark, December 2004 . diff --git a/doc/html/tep123.html b/doc/html/tep123.html index 74ef2151..7380643d 100644 --- a/doc/html/tep123.html +++ b/doc/html/tep123.html @@ -3,7 +3,7 @@ - + The Collection Tree Protocol (CTP) - The Collection Tree Protocol (CTP) @@ -311,6 +310,7 @@ ul.auto-toc { + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -318,17 +318,17 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract -This memo documents the Collection Tree Protocol (CTP), which -provides best-effort anycast datagram communication to one of the + +Abstract +This memo documents the Collection Tree Protocol (CTP), which +provides best-effort anycast datagram communication to one of the collection roots in a network. - -1. Introduction + +1. Introduction - -2. Assumptions and Limitations + +2. Assumptions and Limitations CTP is a tree-based collection protocol. Some number of nodes in a network advertise themselves as tree roots. Nodes form a set of routing trees to these roots. CTP is address-free in that a node does not @@ -345,8 +345,8 @@ protocols. Has single-hop source and destination fields. -CTP assumes that it has link quality estimates of some number of nearby -neighbors. These provide an estimate of the number of transmissions it + CTP assumes that it has link quality estimates of some number of nearby +neighbors. These provide an estimate of the number of transmissions it takes for the node to send a unicast packet whose acknowledgment is successfully received. CTP has several mechanisms in order to improve delivery reliability, @@ -356,8 +356,8 @@ a best effort that tries very hard. might benefit from a different protocol, which can, for example, pack multiple small frames into a single data-link packet. - -3. Collection and CTP + +3. Collection and CTP CTP uses expected transmissions (ETX) as its routing gradient. A root has an ETX of 0. The ETX of a node is the ETX of its parent plus the ETX of its link to its parent. This additive measure assumes that @@ -398,22 +398,22 @@ routing layer increments on each hop. A link-level retransmission has the same THL value, while a looped version of the packet is unlikely to do so. - -4. CTP Data Frame + +4. CTP Data Frame The CTP data frame format is as follows: - 1 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 + 1 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |P|C| reserved | THL | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | ETX | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| origin | +| origin | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| seqno | collect_id | +| seqno | collect_id | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| data ... +| data ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Field definitions are as follows: @@ -429,7 +429,7 @@ to do so. data: the data payload, of zero or more bytes. A node forwarding a data frame MUST NOT modify the data payload. -Together, the origin, seqno and collect_id fields denote a unique + Together, the origin, seqno and collect_id fields denote a unique *origin packet.* Together, the origin, seqno, collect_id, and THL denote a unique *packet instance* within the network. The distinction is important for duplicate suppression in the presence @@ -438,21 +438,21 @@ asked to forward the same packet twice due to a routing loop, it will drop the packet. However, if it suppresses packet instances, then it will route succesfully in the presence of transient loops unless the THL happens to wrap around to a forwarded packet instance. -A node MUST send CTP data frames as unicast messages with link-layer + A node MUST send CTP data frames as unicast messages with link-layer acknowledgments enabled. - -5. CTP Routing Frame + +5. CTP Routing Frame The CTP routing frame format is as follows: - 1 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 + 1 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |P|C| reserved | parent | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| parent | ETX | +| parent | ETX | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -| ETX | +| ETX | +-+-+-+-+-+-+-+-+ The fields are as follows: @@ -474,8 +474,8 @@ below its own. When a parent hears a child advertise an ETX below its own, it MUST schedule a routing frame for transmission in the near future. - -6. Implementation + +6. Implementation An implementation of CTP can be found in the tos/lib/net/ctp directory of TinyOS 2.0. This section describes the structure of that implementation and is not in any way part of the specification of CTP. @@ -489,8 +489,8 @@ routing hop. to send. It decides when and if to send them. The name is a little misleading: the forwarding engine is responsible for forwarded traffic as well as traffic generated on the node. - -6.1 Link Estimation + +6.1 Link Estimation The implementation uses two mechanisms to estimate the quality of a link: periodic LEEP [1] packets and data packets. The implementation sends routing beacons as LEEP packets. These packets seed the neighbor table @@ -515,7 +515,7 @@ of 6. The estimator combines the beacon and data estimates by incorporating them into an exponentially weighted moving average. Beacon-based estimates seed the neighbor table. The expectation is that the low -beacon rate in a stable network means that for a selected route, +beacon rate in a stable network means that for a selected route, data estimates will outweigh beacon estimates. Additionally, as the rate at which CTP collects data estimates is proportional to the transmission rate, then it can quickly detect a broken link and @@ -523,8 +523,8 @@ switch to another candidate neighbor. The component tos/lib/net/le/LinkEstimatorP implements the link estimator. It couples LEEP-based and data-based estimates. - -6.2 Routing Engine + +6.2 Routing Engine The implementation's routing engine is responsible for picking the next hop for a data transmission. It keeps track of the path ETX values of a subset of the nodes maintained by the link estimation table. The minimum @@ -533,8 +533,8 @@ ETX of that node. The path ETX is therefore the sum of link ETX values along the entire route. The component tos/lib/net/ctp/CtpRoutingEngineP implements the routing engine. - -6.3 Forwarding Engine + +6.3 Forwarding Engine The component tos/lib/net/ctp/CtpForwardingEngineP implements the forwarding engine. It has five repsonsibilities: @@ -575,10 +575,10 @@ stream packets as quickly as possible, in order to prevent self-collisions along the path. - -7. Citations + +7. Citations -Rodrigo Fonseca +Rodrigo Fonseca 473 Soda Hall Berkeley, CA 94720-1776 @@ -587,9 +587,9 @@ along the path. Omprakash Gnawali -Ronald Tutor Hall (RTH) 418 +Ronald Tutor Hall (RTH) 418 3710 S. McClintock Avenue -Los Angeles, CA 90089 +Los Angeles, CA 90089 phone - +1 213 821-5627 email - gnawali@usc.edu @@ -598,7 +598,7 @@ along the path. Kyle Jamieson The Stata Center 32 Vassar St. -Cambridge, MA 02139 +Cambridge, MA 02139 email - jamieson@csail.mit.edu @@ -613,8 +613,8 @@ along the path. email - pal@cs.stanford.edu - -8. Citations + +8. Citations diff --git a/doc/html/tep124.html b/doc/html/tep124.html index 39875ed0..070012f6 100644 --- a/doc/html/tep124.html +++ b/doc/html/tep124.html @@ -3,7 +3,7 @@ - +The Link Estimation Exchange Protocol (LEEP) - The Link Estimation Exchange Protocol (LEEP) @@ -311,6 +310,7 @@ ul.auto-toc { + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -318,36 +318,36 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract + +Abstract The memo documents the Link Estimation Exchange Protocol (LEEP). Nodes use LEEP to estimate and exchange information about the quality of links to the neighbors. - -1. Introduction + +1. Introduction Routing protocols often require bi-directional link qualities to compute the routes. Nodes can estimate the quality of the in-bound link from a neighbor by estimating the ratio of successfully received messages and the total transmitted messages. LEEP appends in-bound -packet reception rate (PRR) estimates to packets. Other nodes hearing +packet reception rate (PRR) estimates to packets. Other nodes hearing these packets can combine the in-bound PRR values with their own in-bound values to compute bi-directional link quality. - -2. Definitions - -2.1 Link Quality + +2. Definitions + +2.1 Link Quality The link quality between a directed node pair (A,B) is the probability that a packet transmitted by A will be successfully received by B. The -bidirectional link quality of an undirected node pair (A,B) is the +bidirectional link quality of an undirected node pair (A,B) is the product of the link quality of (A,B) and (B,A). This definition assumes independent link losses. It also includes the case when the link quality of (A,B) and (B,A) are different; this can occur due to local interference or noise. - -2.2 In-bound Link Quality + +2.2 In-bound Link Quality In a node pair (A,B), with B as the node of reference, in-bound link quality is a value in the range of 0 to 255 that describes the quality of the link from A to B estimated by B by counting the successfully @@ -355,31 +355,31 @@ received packets from A among all the transmitted packets or using link quality indicators such as LQI and RSSI provided by the radio on the node B, or some other methods. - -2.3 Out-bound Link Quality + +2.3 Out-bound Link Quality In a node pair (A,B), with B as the node of reference, out-bound link quality is defined as the quality of the link from B to A. B can determine the out-bound link quality if A advertises its in-bound link qualities. LEEP is the protocol that is used to exchange the in-bound link qualities. - -2.4 Link Information Entry + +2.4 Link Information Entry Link Information Entry created by node k is a tuple (n,q) where q is the in-bound link quality from node n to k. - -3. The Link Estimation Exchange Protocol (LEEP) - -3.1 Assumptions + +3. The Link Estimation Exchange Protocol (LEEP) + +3.1 Assumptions Following are the assumptions made by LEEP: 3.1.1. The data link frame has a single-hop source field. 3.1.2. The data link layer provides a broadcast address. 3.1.3. The data link layer provides the length of the LEEP frame. - -3.2 The Protocol + +3.2 The Protocol To compute the bi-directional link quality, in-bound link quality must be exchanged among the neighbors. LEEP maintains a sequence number that is incremented by one for each outgoing LEEP frame. The sequence @@ -392,8 +392,8 @@ neighbors. The Link Information entry on the LEEP frame allows the receiver node to find the out-bound link quality to the transmitter node identified by the data link source address. - -3.3 LEEP Frame + +3.3 LEEP Frame A LEEP frame has a header, the payload, and a footer with the Link Information (LI) entries as shown in this diagram: @@ -408,8 +408,8 @@ increase the size of the LEEP frame beyond the maximum payload length allowed by the data link layer. A LEEP frame can have 0 Link Information entry. - -3.3.1 LEEP header + +3.3.1 LEEP header The following diagram shows the LEEP header format: 1 @@ -427,8 +427,8 @@ Information entry. - -3.3.2 Link Information Entry + +3.3.2 Link Information Entry The following diagram shows the Link Information Entry format: 1 @@ -449,8 +449,8 @@ to the node that transmits this Link Information entry - -4. Implementation + +4. Implementation The following files in tinyos-2.x/tos/lib/net/le provide a reference implementation of LEEP described in this TEP. @@ -468,21 +468,21 @@ the entries to be exchanged that could not fit in the previous LEEP frame. The LEEP frames are transmitted whenever the CTP [1] beacons, sent as a LEEP payload, are sent. - -5. Author's Address + +5. Author's Address Omprakash Gnawali -Ronald Tutor Hall (RTH) 418 +Ronald Tutor Hall (RTH) 418 3710 S. McClintock Avenue -Los Angeles, CA 90089 +Los Angeles, CA 90089 phone - +1 213 821-5627 email - gnawali@usc.edu - -6. Citations + +6. Citations diff --git a/doc/html/tep125.html b/doc/html/tep125.html index d606bb6b..0302d5f4 100644 --- a/doc/html/tep125.html +++ b/doc/html/tep125.html @@ -3,7 +3,7 @@ - +TinyOS 802.15.4 Frames - TinyOS 802.15.4 Frames @@ -303,14 +302,15 @@ ul.auto-toc { - + - + Jonathan Hui, Philip Levis, and David Moss Draft-Created: 2-Feb-2007 Draft-Version: 1.1 Draft-Version: 1.2 Draft-Modified: 2007-04-03 Draft-Modified: 2007-04-09 Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu> + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -318,13 +318,13 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract + +Abstract This memo documents the frame format for 802.15.4 packets in TinyOS 2.0. - -1. Introduction + +1. Introduction 802.15.4 is a data-link and physical packet format for low-power wireless networks that is used in many TinyOS platforms. The TinyOS 2.0 active message layer adds a packet field for higher-level @@ -333,15 +333,15 @@ for 802.15.4 networks. The first format is for isolated TinyOS networks; the second format is for networks that share the spectrum with 6lowpan networks[1]_. - -2. 802.15.4 + +2. 802.15.4 802.15.4 supports several different source and destination addressing modes, and so has a variable sized packet header.[2]_ A TinyOS device MUST support packet frames with 16-bit short source and destination addresses. A TinyOS device MAY support additional 802.15.4 frame formats. - -3. Frame Format + +3. Frame Format TinyOS has two 802.15.4 frame formats. The first format, the T-Frame, is for TinyOS networks which do not share their channel with other wireless networking archtiectures. This frame format assumes that TinyOS can use @@ -372,14 +372,14 @@ this code has not been determined. To inform 6lowpan that this is not a 6lowpan packet, the code used MUST be in the range of 192-55. The AM type 6lowpan is reserved. A TinyOS program MUST NOT use it. - -4. Implementation + +4. Implementation An implementation of the T-Frame can be found in tinyos-2.x/tos/chips/cc2420. -An implementation of the I-Frame will soon be found in + An implementation of the I-Frame will soon be found in tinyos-2.x/tos/chips/cc2420. - -5. Author Addresses + +5. Author Addresses Jonathan Hui diff --git a/doc/html/tep126.html b/doc/html/tep126.html index 8ef62518..9f9d6c3d 100644 --- a/doc/html/tep126.html +++ b/doc/html/tep126.html @@ -3,7 +3,7 @@ - + CC2420 Radio Stack - CC2420 Radio Stack @@ -303,14 +302,15 @@ ul.auto-toc { - + - + David Moss, Jonathan Hui, Philip Levis, and Jung Il Choi Draft-Created: 5-Mar-2007 Draft-Version: 1.1 Draft-Version: 1.3 Draft-Modified: 2007-03-23 Draft-Modified: 2007-04-20 Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu> + Note This memo documents a part of TinyOS for the TinyOS Community, and @@ -318,44 +318,46 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with TEP 1. - -Abstract + +Abstract This TEP documents the architecture of the CC2420 low power listening -radio stack found in TinyOS 2.x. Radio stack layers and implementation +radio stack found in TinyOS 2.x. Radio stack layers and implementation details of the CC2420 stack will be discussed. Readers will be better informed about existing features, possible improvements, and limitations of the CC2420 radio stack. Furthermore, lessons learned from -the construction of the CC2420 radio stack can help guide development +the construction of the stack can help guide development of future TinyOS radio stacks. - -1. Introduction -The TI/Chipcon CC2420 radio is a complex device, requiring a rather -complex software radio stack implementation. Although much of the -functionality is available within the radio chip itself, there are -still many factors to consider when implementing a flexible, + +1. Introduction +The TI/Chipcon CC2420 radio is a complex device, taking care of +many of the low-level details of transmitting and receiving packets +through hardware. Specifying the proper behavior of that hardware +requires a well defined radio stack implementation. Although much +of the functionality is available within the radio chip itself, there +are still many factors to consider when implementing a flexible, general radio stack. The software radio stack that drives the CC2420 radio consists of many layers that sit between the application and hardware. The highest levels of the radio stack modify data and headers in each packet, while -the lowest levels determine the actual send and receive behavior. -By understanding the functionality at each layer of the stack, as well -as the architecture of a layer itself, it is possible to easily extend +the lowest levels determine the actual send and receive behavior. +By understanding the functionality at each layer of the stack, as well +as the architecture of a layer itself, it is possible to easily extend or condense the CC2420 radio stack to meet project requirements. Some details about the CC2420 are out of the scope of this document. -These details can be found in the CC2420 datasheet [1]. +These details can be found in the CC2420 datasheet [1]. - -2. CC2420 Radio Stack Layers - -2.1 Layer Architecture -The CC2420 radio stack consists of layers of functionality stacked + +2. CC2420 Radio Stack Layers + +2.1 Layer Architecture +The CC2420 radio stack consists of layers of functionality stacked on top of each other to provide a complete mechanism that -modifies, filters, transmits, and controls inbound and outbound messages. -Each layer is a distinct module that can provide and use three sets of -interfaces in relation to the actual radio stack: Send, Receive, and -SplitControl. If a general layer provides one of those interfaces, it -also uses that interface from the layer below it in the stack. This +modifies, filters, transmits, and controls inbound and outbound messages. +Each layer is a distinct module that can provide and use three sets of +interfaces in relation to the actual radio stack: Send, Receive, and +SplitControl. If a general layer provides one of those interfaces, it +also uses that interface from the layer below it in the stack. This allows any given layer to be inserted anywhere in the stack through independant wiring. For example:: @@ -369,7 +371,7 @@ provides interface SplitControl; uses interface SplitControl as subControl; The actual wiring of the CC2420 radio stack is done at the highest level -of the stack, inside CC2420ActiveMessageC. This configuration defines +of the stack, inside CC2420ActiveMessageC. This configuration defines three branches: Send, Receive, and SplitControl. Note that not all layers need to provide and use all three Send, Receive, and SplitControl interfaces:: @@ -380,71 +382,351 @@ LplC.SubControl -> CsmaC; // Send Layers AM.SubSend -> UniqueSendC; -UniqueSendC.SubSend -> TransportC; -TransportC.SubSend -> LplC.Send; -LplC.SubSend -> CC2420DispatchC.Send; -CC2420DispatchC.SubSend -> CsmaC; +UniqueSendC.SubSend -> LinkC; +LinkC.SubSend -> LplC.Send; +LplC.SubSend -> TinyosNetworkC.Send; +TinyosNetworkC.SubSend -> CsmaC; // Receive Layers AM.SubReceive -> LplC; -LplC.SubReceive -> UniqueReceiveC; -UniqueReceiveC.SubReceive -> CC2420DispatchC.Receive; -CC2420DispatchC.SubReceive -> CsmaC; +LplC.SubReceive -> UniqueReceiveC.Receive; +UniqueReceiveC.SubReceive -> TinyosNetworkC.Receive; +TinyosNetworkC.SubReceive -> CsmaC; If another layer were to be added, CC2420ActiveMessageC would need to be modified to wire it into the correct location. - -2.1 Layer Descriptions -The main layers we see in this version of the stack are: - -ActiveMessageP: This is the highest layer in the stack, responsible + +2.1 Layer Descriptions +The layers found within this radio stack are in the following order: + +ActiveMessageP: This is the highest layer in the stack, responsible for filling in details in the packet header and providing information -about the packet to the application level [2]. Because the CC2420 radio -chip itself uses 802.15.4 headers in hardware [1], it is not possible -for the layer to rearrange header bytes. -UniqueSend: This layer generates a unique data sequence -number (DSN) byte for the packet header. This byte is generated once -per outgoing packet. A receiver can detect duplicate packets by comparing -the source and DSN byte of a received packet with previous packets. -DSN is defined in the 802.15.4 specification [3]. -MessageTransportP: This layer provides the MessageTransport -interface, and is responsible for retrying a packet transmission if no -acknowledgement was heard from the receiver. MessageTransport is +about the packet to the application level [2]. Because the CC2420 radio +chip itself uses 802.15.4 headers in hardware [1], it is not possible +for the layer to rearrange header bytes. + +UniqueSend: This layer generates a unique Data Sequence +Number (DSN) byte for the packet header. This byte is incremented once +per outgoing packet, starting with a pseudo-randomly generated number. +A receiver can detect duplicate packets by comparing +the source and DSN byte of a received packet with previous packets. +DSN is defined in the 802.15.4 specification [3]. + +PacketLink: This layer provides automatic retransmission functionality +and is responsible for retrying a packet transmission if no +acknowledgement was heard from the receiver. PacketLink is activated on a per-message basis, meaning the outgoing packet will -not use MessageTransport unless it is configured ahead of time to do so. -MessageTransport is most reliable when software acknowledgements are enabled, -as opposed to hardware auto acknowledgements. -LowPowerListeningP [4]: This layer provides the asynchronous low -power listening functionality of the radio. It is broken up into -two parts: CC2420LowPowerListeningP and CC2420DutyCycleP. The -DutyCycleP component is responsible for turning the radio on -and off and performing detections. After a detection occurs, -DutyCycleP is hands off responsibility to LowPowerListeningP to turn -the radio off and continue duty cycling when convenient. Low power listening -transmissions are activated on a per-message basis, and the layer -will retransmit the full outbound packet over and over until either a -response from the receiver is heard or the transmit time expires. -UniqueReceive: This layer maintains a history of the source address +not use PacketLink unless it is configured ahead of time to do so. +PacketLink is most reliable when software acknowledgements are enabled +as opposed to hardware auto acknowledgements. + +CC2420AckLplP / CC2420NoAckLplP [4]: These layers provide +asynchronous low power listening implementations. Supporting both of them +is CC2420DutyCycleP. The DutyCycleP component is responsible for +turning the radio on and off and performing receive checks. +After a detection occurs, DutyCycleP is hands off responsibility to +LowPowerListeningP to perform some transaction and turn the radio off +when convenient. Low power listening transmissions are activated on +a per-message basis, and the layer will continuously retransmit the full outbound +packet until either a response from the receiver is heard or the +transmit time expires. +The AckLplP implementation supports acknowledgement gaps during the +low power listening packetized preamble, which allows +transmitters to stop early but penalizes receive check lengths. +AckLplP low power listening is optimal for high transmission, long +receive check interval networks. +The NoAckLplP implementation does not support acknowledgements during +the packetized preamble. It continuously modulates the channel, +allowing the receiver to perform the smallest possible receive check. +NoAckLpl low power listening is effective for low transmission, short +receive check interval networks. + +UniqueReceive: This layer maintains a history of the source address and DSN byte of the past few packets it has received, and helps -filter out duplicate received packets. -DispatchC: This layer allows the TinyOS 2.x radio stack to interoperate -with other non-TinyOS networks. The 6LowPAN specifications include -a network identifier byte after the standard 802.15.4 header [5]. -If interoperability frames are used, the dispatch layer provides -functionality for setting the network byte on outgoing packets -and filtering non-TinyOS incoming packets. -CsmaC: This layer is responsible for defining 802.15.4 FCF +filter out duplicate received packets. + +TinyosNetworkC: This layer allows the TinyOS 2.x radio stack to +interoperate with other non-TinyOS networks. Proposed 6LowPAN +specifications include a network identifier byte after the +standard 802.15.4 header [5]. If interoperability frames are +used, the dispatch layer provides functionality for setting +the network byte on outgoing packets and filtering non-TinyOS +incoming packets. + +CsmaC: This layer is responsible for defining 802.15.4 FCF byte information in the outbound packet, providing default backoff times when the radio detects a channel in use, and -defining the power-up/power-down procedure for the radio. -TransmitP/ReceiveP: These layers are responsible for interacting -directly with the radio through the SPI bus, interrupts, and GPIO lines. +defining the power-up/power-down procedure for the radio. + +TransmitP/ReceiveP: These layers are responsible for interacting +directly with the radio through the SPI bus, interrupts, and GPIO lines. + + + ++++ + + + + + Application Layer + +System Message: ERROR/3 (txt/tep126.txt, line 184) +Unexpected indentation. + +System Message: WARNING/2 (txt/tep126.txt, line 184) +Blank line required after table. + + + + + + + + +System Message: WARNING/2 (txt/tep126.txt, line 186) +Block quote ends without a blank line; unexpected unindent. + ++++ + + + + + Active Message Layer + +System Message: ERROR/3 (txt/tep126.txt, line 189) +Unexpected indentation. + +System Message: WARNING/2 (txt/tep126.txt, line 189) +Blank line required after table. + + + + + + +System Message: WARNING/2 (txt/tep126.txt, line 190) +Block quote ends without a blank line; unexpected unindent. + ++++ + + + + + Unique Send Layer + +System Message: ERROR/3 (txt/tep126.txt, line 193) +Unexpected indentation. + +System Message: WARNING/2 (txt/tep126.txt, line 193) +Blank line required after table. + + + + + +System Message: WARNING/2 (txt/tep126.txt, line 194) +Block quote ends without a blank line; unexpected unindent. + ++++ + + + + + Optional Packet Link Layer + +System Message: ERROR/3 (txt/tep126.txt, line 197) +Unexpected indentation. + +System Message: WARNING/2 (txt/tep126.txt, line 197) +Blank line required after table. + + + + + + +System Message: WARNING/2 (txt/tep126.txt, line 198) +Block quote ends without a blank line; unexpected unindent. + ++++ + + + + + Optional Low Power Listening Implementations + +System Message: ERROR/3 (txt/tep126.txt, line 201) +Unexpected indentation. + +System Message: WARNING/2 (txt/tep126.txt, line 201) +Blank line required after table. + + + + + + +System Message: WARNING/2 (txt/tep126.txt, line 202) +Block quote ends without a blank line; unexpected unindent. + ++++ + + + + + Unique Receive Filtering Layer + +System Message: ERROR/3 (txt/tep126.txt, line 205) +Unexpected indentation. + +System Message: WARNING/2 (txt/tep126.txt, line 205) +Blank line required after table. + + + - -3. CC2420 Packet Format and Specifications + + +System Message: WARNING/2 (txt/tep126.txt, line 206) +Block quote ends without a blank line; unexpected unindent. + ++++ + + + + + Optional 6LowPAN TinyOS Network Layer + +System Message: ERROR/3 (txt/tep126.txt, line 209) +Unexpected indentation. + +System Message: WARNING/2 (txt/tep126.txt, line 209) +Blank line required after table. + + + + + + +System Message: WARNING/2 (txt/tep126.txt, line 210) +Block quote ends without a blank line; unexpected unindent. + ++++ + + + + + Carrier Sense Multiple Access (CSMA) + +System Message: ERROR/3 (txt/tep126.txt, line 213) +Unexpected indentation. + +System Message: WARNING/2 (txt/tep126.txt, line 213) +Blank line required after table. + + + + + + + +System Message: WARNING/2 (txt/tep126.txt, line 214) +Block quote ends without a blank line; unexpected unindent. + +System Message: ERROR/3 (txt/tep126.txt, line 214) +Malformed table. +++------------+------------+ +| | + + + +System Message: WARNING/2 (txt/tep126.txt, line 216) +Blank line required after table. + + + +System Message: WARNING/2 (txt/tep126.txt, line 216) +Block quote ends without a blank line; unexpected unindent. ++----------+----------+ +----------+----------+ +| ReceiveP | | TransmitP | ++----------+----------+ +----------+----------+ + +System Message: ERROR/3 (txt/tep126.txt, line 219) +Unexpected indentation. + + +| + + +System Message: WARNING/2 (txt/tep126.txt, line 219); backlink +Inline substitution_reference start-string without end-string. + +System Message: WARNING/2 (txt/tep126.txt, line 220) +Line block ends without a blank line. + ++ + + + + +System Message: ERROR/3 (txt/tep126.txt, line 221) +Unexpected indentation. + +System Message: WARNING/2 (txt/tep126.txt, line 221) +Blank line required after table. + + + + + + + +System Message: WARNING/2 (txt/tep126.txt, line 222) +Block quote ends without a blank line; unexpected unindent. + ++++ + + + + + SPI bus, GPIO, Interrupts, Timer Capture + + + + +3. CC2420 Packet Format and Specifications The CC2420 Packet structure is defined in CC2420.h. The default I-Frame CC2420 header takes on the following format:: @@ -455,13 +737,14 @@ typedef nx_struct cc2420_header_t { nxle_uint16_t destpan; nxle_uint16_t dest; nxle_uint16_t src; - nxle_uint8_t network; + nxle_uint8_t network; // optionally included with 6LowPAN layer nxle_uint8_t type; } cc2420_header_t; -All fields up to 'network' are 802.15.4 specified fields, and are -used in the CC2420 hardware itself. The 'network' field is a 6LowPAN -interoperability specification [5]. The 'type' field is a + All fields up to 'network' are 802.15.4 specified fields, and are +used in the CC2420 hardware itself. The 'network' field is a 6LowPAN +interoperability specification [5] only to be included when the +6LowPAN TinyosNetwork layer is included. The 'type' field is a TinyOS specific field. The TinyOS T-Frame packet does not include the 'network' field, nor the functionality found in the Dispatch layer to set and check @@ -469,119 +752,120 @@ the 'network' field. No software footer is defined for the CC2420 radio. A 2-byte CRC byte is auto-appended to each outbound packet by the CC2420 radio hardware itself. -The CC2420 hardware has three RAM buffers: TXFIFO, RXFIFO, and a -security RAM buffer. The TXFIFO and RXFIFO are both 128 bytes, -while the security RAM buffer is 112 bytes. Therefore, the maximum size -of a packet is 128 bytes including its headers and CRC. Increasing -the packet size will increase data throughput and RAM consumption -in the TinyOS application, but will also increase the probability -that interference will cause the packet to be destroyed and need -to be retransmitted, which wastes energy. The TOSH_DATA_LENGTH -preprocessor variable can be altered to increase the size -of the message_t payload at compile time [2]. - - -4. CSMA/CA - -4.1 Clear Channel Assessment -By default, the CC2420 radio stack performs a clear channel assessment + The maximum size of a packet is 128 bytes including its headers and +CRC, which matches the 802.15.4 specifications. Increasing the +packet size will increase data throughput and RAM consumption +in the TinyOS application, but will also increase the probability +that interference will cause the packet to be destroyed and need +to be retransmitted. The TOSH_DATA_LENGTH preprocessor variable can +be altered to increase the size of the message_t payload at +compile time [2]. + + +4. CSMA/CA + +4.1 Clear Channel Assessment +By default, the CC2420 radio stack performs a clear channel assessment (CCA) before transmitting. If the channel is not clear, the radio backs -off for some short, random period of time before attempting to transmit +off for some short, random period of time before attempting to transmit again. The CC2420 chip itself provides a strobe command to transmit the packet if the channel is currently clear. To specify whether or not to transmit with clear channel assessment, -the CC2420TransmitP component provides two commands: --async command error_t Send.sendCCA( message_t* p_msg ) -async command error_t Send.send( message_t* p_msg ) - -It is up to the CC2420CsmaP component to select the correct method of -transmission. Sending a packet without CCA will transmit it as quickly -as possible, but interference from other transmitters will prevent -it from being delivered in many cases. Transmitting without CCA will -also effectively jam other DSSS transmitters on the same channel. -Future implementations should allow the application layer to specify -the use of CCA on a per-packet basis, similar to how the application -layer has the option to specify the backoff period for an outgoing -message. - - -4.2 Radio Backoff +the CC2420TransmitP requests CCA backoff input through the RadioBackoff +interface on a per-message basis. By default, each packet will be +transmitted with CCA enabled. +If layers above the CSMA layer wish to disable the clear channel +assessments before transmission, they must intercept the +RadioBackoff.requestCca(...) event for that message and call back +using RadioBackoff.setCca(FALSE). + + +4.2 Radio Backoff A backoff is a period of time where the radio pauses before attempting -to transmit. When the radio needs to backoff, it can choose one of three +to transmit. When the radio needs to backoff, it can choose one of three backoff periods: initialBackoff, congestionBackoff, and lplBackoff. These are implemented through the RadioBackoff interface, which signals out a request to specify the backoff period. Unlike the CsmaBackoff interface, components that are interested in adjusting the backoff can -call back using commands in the RadioBackoff interface. This allows -multiple components to adjust the backoff period for packets they are +call back using commands in the RadioBackoff interface. This allows +multiple components to adjust the backoff period for packets they are specifically listening to adjust. The lower the backoff period, the faster the transmission, but the more likely the transmitter is to hog the channel. Also, backoff periods should be as random as possible -to prevent two transmitters from sampling the channel at the same +to prevent two transmitters from sampling the channel at the same moment. InitialBackoff is the shortest backoff period, requested on the first attempt to transmit a packet. CongestionBackoff is a longer backoff period used when the channel is -found to be in use. By using a longer backoff period in this case, +found to be in use. By using a longer backoff period in this case, the transmitter is less likely to unfairly tie up the channel. LplBackoff is the backoff period used for a packet being delivered -with low power listening. Because low power listening requires +with low power listening. Because low power listening requires the channel to be modulated as continuously as possible while avoiding -interference with other transmitters, the low power listening +interference with other transmitters, the low power listening backoff period is intentionally short. - -5. Acknowledgements - -5.1 Hardware vs. Software Acknowledgements + +5. Acknowledgements + +5.1 Hardware vs. Software Acknowledgements Originally, the CC2420 radio stack only used hardware generated auto-acknowledgements provided by the CC2420 chip itself. This led to some issues, such as false acknowledgements where the radio chip -would receive a packet and acknowledge its reception and the +would receive a packet and acknowledge its reception and the microcontroller would never actually receive the packet. -The current CC2420 stack uses software acknowledgements, which + The current CC2420 stack uses software acknowledgements, which have a higher drop percentage. When used with the UniqueSend -and UniqueReceive interfaces, dropped acknowledgements are more desirable -than false acknowledgements. Received packets are always acknowledged +and UniqueReceive interfaces, dropped acknowledgements are more desirable +than false acknowledgements. Received packets are always acknowledged before being filtered as a duplicate. -Use the PacketAcknowledgements or MessageTransport interfaces + Use the PacketAcknowledgements or PacketLink interfaces to determine if a packet was successfully acknowledged. - -5.2 Data Sequence Numbers - UniqueSend and UniqueReceive + +5.2 Data Sequence Numbers - UniqueSend and UniqueReceive The 802.15.4 specification identifies a Data Sequence Number (DSN) -byte in the message header to filter out duplicate packets [3]. -The UniqueSend interface at the top of the CC2420 radio stack is -responsible for setting the DSN byte. It is set exactly one time -per outgoing message. Even if lower levels such as MessageTransport -or LowPowerListening retransmit the packet, the DSN byte stays the -same. +byte in the message header to filter out duplicate packets [3]. +The UniqueSend interface at the top of the CC2420 radio stack is +responsible for setting the DSN byte. Upon boot, an initial DSN +byte is generated using a pseudo-random number generator with a +maximum of 8-bits (256) values. This number is incremented on +each outgoing packet transmission. Even if lower levels such as +PacketLink or LowPowerListening retransmit the packet, the DSN byte +stays the same for that packet. The UniqueReceive interface at the bottom of the CC2420 radio stack -is responsible for filtering out duplicate messages based on +is responsible for filtering out duplicate messages based on source address and DSN. The UniqueReceive interface is not meant -to stop sophisticated replay attacks. +to stop sophisticated replay attacks. ' +As packets are received, DSN and source address information is placed +into elements of an array. Each subsequent message from previously +logged addresses overwrite information in the element allocated to +that source address. This prevents UniqueReceive's history from +losing DSN byte information from sources that are not able to access +the channel as often. If the number of elements in the history array +runs out, UniqueReceive uses a best effort method to avoid replacing +recently updated DSN/Source information entries. - -6. Message Transport Implementation -Message transport is a layer added to the CC2420 radio stack to help unicast -packets get delivered successfully. In previous version of TinyOS radio -stacks, it was left up to the application layer to retry a message + +6. PacketLink Implementation +PacketLink is a layer added to the CC2420 radio stack to help unicast +packets get delivered successfully. In previous version of TinyOS radio +stacks, it was left up to the application layer to retry a message transmission if the application determined the message was not properly -received. The Message Transport layer helps to remove the reliable delivery +received. The PacketLink layer helps to remove the reliable delivery responsibility and functional baggage from application layers. - -6.1 Compiling in the Message Transport layer -Because the Message Transport layer uses up extra memory footprint, + +6.1 Compiling in the PacketLink layer +Because the PacketLink layer uses up extra memory footprint, it is not compiled in by default. Developers can simply define -the preprocessor variable MESSAGE_TRANSPORT to compile the functionality -of the Message Transport layer in with the CC2420 stack. +the preprocessor variable PACKET_LINK to compile the functionality +of the PacketLink layer in with the CC2420 stack. - -6.2 Implementation and Usage -To send a message using Message Transport, the MessageTransport + +6.2 Implementation and Usage +To send a message using PacketLink, the PacketLink interface must be called ahead of time to specify two fields in the outbound message's metadata:: @@ -594,48 +878,53 @@ transmission. The second command, setRetryDelay(..), specifies the amount of delay in milliseconds between each retry. The combination of these two commands can set a packet to retry as many times as needed for as long as necessary. -Because Message Transport relies on acknowledgements, false -acknowledgements from the receiver will cause Message Transport to fail. +Because PacketLink relies on acknowledgements, false acknowledgements +from the receiver will cause PacketLink to fail. If using software +acknowledgements, false acknowledgements can still occur as a result +of the limited DSN space, other 802.15.4 radios in the area with +the same destination address, etc. - -7. Asynchronous Low Power Listening Implementation + +7. Asynchronous Low Power Listening Implementation Because the Low Power Listening layer uses up extra memory footprint, it is not compiled in by default. Developers can simply define the preprocessor variable LOW_POWER_LISTENING to compile the functionality of the Low Power Listening layer in with the CC2420 stack. - -7.1 Design Considerations + +7.1 Design Considerations The CC2420 radio stack low power listening implementation relies on clear channel assessments to determine if there is a transmitter nearby. This allows the receiver to turn on and determine there are no transmitters in a shorter amount of time than leaving the radio on long enough to pick up a full packet. The transmitters perform a message delivery by transmitting -the full packet over and over again for twice the duration of the receiver's -duty cycle period. Transmitting for twice as long increases the -probability that the message will be detected by the receiver, and -allows the receiver to shave off a small amount of time it needs to +the full packet over and over again for twice the duration of the receiver's +duty cycle period. Transmitting for twice as long increases the +probability that the message will be detected by the receiver, and +allows the receiver to shave off a small amount of time it needs to keep its radio on. -Typically, the transmission of a single packet takes on the following + Typically, the transmission of a single packet takes on the following form over time: + ---+++ - + LPL Backoff Packet Transmission Packet Tx Ack Wait -To decrease the amount of time required for a receive check, the channel -must be modulated by the transmitter as continuously as possible. -The only period where the channel is modulated is during the -Packet Transmission phase. The receiver must continuosly sample the CCA pin + +To decrease the amount of time required for a receive check, the channel +must be modulated by the transmitter as continuously as possible. +The only period where the channel is modulated is during the +Packet Transmission phase. The receiver must continuosly sample the CCA pin a moment longer than the LPL Backoff period and Ack Wait period combined to overlap the Packet Transmission period. By making the LPL backoff period as short as possible, we can decrease the amount of time a receiver's @@ -643,73 +932,95 @@ radio must be turned on when performing a receive check. If two transmitters attempt to transmit using low power listening, one transmitter may hog the channel if its LPL backoff period is set too short. Both nodes transmitting at the same time -will cause interference and prevent each other from +will cause interference and prevent each other from successfully delivering their messages to the intended recipient. -To allow multiple transmitters to transmit low power listening packets -at the same time, the LPL backoff period needed to be increased + To allow multiple transmitters to transmit low power listening packets +at the same time, the LPL backoff period needed to be increased greater than the desired minimum. This increases the amount of time receiver radios need to be on to perform a receive check because the channel is no longer being modulated as continuously as possible. -In other words, the channel is allowed to be shared amongst multiple +In other words, the channel is allowed to be shared amongst multiple transmitters at the expense of power consumption. - -7.2 Minimizing Power Consumption + +7.2 Minimizing Power Consumption There are several methods the CC2420 radio stack uses to minimize power consumption: + +Invalid Packet Shutdown + + +System Message: WARNING/2 (txt/tep126.txt, line 471) +Enumerated list ends without a blank line; unexpected unindent. -1. Invalid Packet Shutdown: Typically, packets are filtered out by address at the radio hardware level. When a receiver wakes up and does not receive any -packets into the low power listening layer of the radio stack, it -will automatically go back to sleep after some period of time. As a -secondary backup, if address decoding on the radio chip is disabled, -the low power listening implementation will shut down the radio if -three packets are receive that do not belong to the node. This helps -prevent against denial of sleep attacks or the typical transmission -behavior found in an ad-hoc network with many nodes. -2. Early Transmission Completion: +packets into the low power listening layer of the radio stack, it +will automatically go back to sleep after some period of time. As a +secondary backup, if address decoding on the radio chip is disabled, +the low power listening implementation will shut down the radio if +three packets are receive that do not belong to the node. This helps +prevent against denial of sleep attacks or the typical transmission +behavior found in an ad-hoc network with many nodes. + +Early Transmission Completion + + +System Message: WARNING/2 (txt/tep126.txt, line 482) +Enumerated list ends without a blank line; unexpected unindent. + A transmitter typically sends a packet for twice the amount of time as the receiver's receive check period. This increases the probability that the receiver will detect the packet. However, if the transmitter receives an acknowledgement before the end of its transmission period, it will stop transmitting to save energy. This is an improvement over previous low power listening implementations, which transmitted -for the full period of time regardless of whether the receiver has -already woken up and received the packet. -3. Auto Shutdown: +for the full period of time regardless of whether the receiver has +already woken up and received the packet. + +Auto Shutdown + + +System Message: WARNING/2 (txt/tep126.txt, line 492) +Enumerated list ends without a blank line; unexpected unindent. + If the radio does not send or receive messages for some period of -time while low power listening is enabled, the radio will automatically -turn off and begin duty cycling at its specified duty cycle period. -4. CCA Sampling Strategy: -The actual receive check is performed in a loop inside a function, +time while low power listening is enabled, the radio will automatically +turn off and begin duty cycling at its specified duty cycle period. + +CCA Sampling Strategy + + +System Message: WARNING/2 (txt/tep126.txt, line 497) +Enumerated list ends without a blank line; unexpected unindent. + +The actual receive check is performed in a loop inside a function, not a spinning task. This allows the sampling to be performed -continuously, with the goal of turning the radio off as quickly as -possible without interruption. - +continuously, with the goal of turning the radio off as quickly as +possible without interruption. - -8. CC2420 Settings and Registers + +8. CC2420 Settings and Registers To interact with registers on the CC2420 chip, the SPI bus must be -acquired, the chip selecct (CSn) pin must be cleared, and then the +acquired, the chip selecct (CSn) pin must be cleared, and then the interaction may occur. After the interaction completes, the CSn pin must be set high. -All registers and strobes are defined in the CC2420.h file, and most + All registers and strobes are defined in the CC2420.h file, and most are accessible through the CC2420SpiC component. If your application requires access to a specific register or strobe, the CC2420SpiC component is the place to add access to it. Configuring the CC2420 requires the developer to access the CC2420Config -interface provided by CC2420ControlC. First call the CC2420Config commands to -change the desired settings of the radio. Next, call CC2420Config.sync() -to commit these changes to the radio chip. If the radio is currently -off, the changes will be committed at the time it is turned on. +interface provided by CC2420ControlC. First call the CC2420Config commands to +change the desired settings of the radio. If the radio happens to +be off, the changes will be committed at the time it is turned on. +Alternatively, calling sync() will commit the changes to the CC2420. RSSI can be sampled directly by calling the ReadRssi interface provided by CC2420ControlC. See page 50 of the CC2420 datasheet for information -on how to convert RSSI to LQI and why it may not be such a good idea [1]. +on how to convert RSSI to LQI and why it may not be such a good idea [1]. - -9. Cross-platform Portability + +9. Cross-platform Portability To port the CC2420 radio to another platform, the following interfaces need to be implemented:: @@ -721,7 +1032,7 @@ interface GeneralIO as FIFOP; interface GeneralIO as RSTN; interface GeneralIO as SFD; interface GeneralIO as VREN; - + // SPI Bus interface Resource; interface SpiByte; @@ -735,97 +1046,97 @@ interface GpioInterrupt as InterruptFIFOP; The GpioCapture interface is tied through the Timer to provide a relative time at which the interrupt occurred. This is useful for timestamping received packets for node synchronization. -If the CC2420 is not connected to the proper interrupt lines, + If the CC2420 is not connected to the proper interrupt lines, interrupts can be emulated through the use of a spinning task that polls the GPIO pin. The MICAz implementation, for example, does this for the CCA interrupt. - -10. Future Improvement Recommendations + +10. Future Improvement Recommendations Many improvements can be made to the CC2420 stack. Below are some recommendations: - -10.1 AES Encryption + +10.1 AES Encryption The CC2420 chip itself provides AES-128 encryption. The implementation involves loading the security RAM buffers on the CC2420 with the information to be encrypted - this would be the payload of a packet, without the header. After the payload is encrypted, the microcontroller reads -out of the security RAM buffer and concatenates the data with the +out of the security RAM buffer and concatenates the data with the unencrypted packet header. This full packet would be uploaded again to the CC2420 TXFIFO buffer and transmitted. Because the CC2420 cannot begin encryption at a particular offset -and needs to be written, read, and re-written, use of the AES-128 may be +and needs to be written, read, and re-written, use of the AES-128 may be inefficient and will certainly decrease throughput. - -10.2 Authentication -In many cases, authentication is more desirable than encryption. + +10.2 Authentication +In many cases, authentication is more desirable than encryption. Encryption significantly increases energy and decreases packet throughput, -which does not meet some application requirements. A layer could be +which does not meet some application requirements. A layer could be developed and added toward the bottom of the radio stack that validates neighbors, preventing packets from invalid neighbors from reaching the application layer. Several proprietary authentication layers have -been developed for the CC2420 stack, but so far none are available to +been developed for the CC2420 stack, but so far none are available to the general public. -A solid authentication layer would most likely involve the use of a + A solid authentication layer would most likely involve the use of a neighbor table and 32-bit frame counts to prevent against replay attacks. Once a neighbor is verified and established, the node needs to ensure that future packets are still coming from the same trusted source. Again, -some high speed low energy proprietary methods to accomplish this exist, but +some high speed low energy proprietary methods to accomplish this exist, but encryption is typically the standard method used. - -10.3 Synchronous Low Power Listening -A synchronous low power listening layer can be transparently built on + +10.3 Synchronous Low Power Listening +A synchronous low power listening layer can be transparently built on top of the asynchronous low power listening layer. One implementation of this has already been done on a version of the CC1000 radio stack. -Moteiv's Boomerang radio stack also has a synchronous low power listening +Moteiv's Boomerang radio stack also has a synchronous low power listening layer built as a standalone solution. In the case of building a synchronous layer on top of the asynchronous -low power listening layer, a transmitter's radio stack can detect when -a particular receiver is performing its receive checks by verifying the -packet was acknowledged after a sendDone event. The transmitter can then +low power listening layer, a transmitter's radio stack can detect when +a particular receiver is performing its receive checks by verifying the +packet was acknowledged after a sendDone event. The transmitter can then build a table to know when to begin transmission for that particular receiver. -Each successful transmission would need to adjust the table with updated +Each successful transmission would need to adjust the table with updated information to avoid clock skew problems. The asynchronous low power listening stack needs to be altered a bit to make this strategy successful. Currently, duty cycling is started and stopped as packets are detected, received, and transmitted. The stack would need to be altered to keep a constant clock running in the background that determines when to perform receive checks. The -clock should not be affected by normal radio stack Rx/Tx behavior. This +clock should not be affected by normal radio stack Rx/Tx behavior. This would allow the receiver to maintain a predictable receive check cycle for the transmitter to follow. If the synchronous low power listening layer loses synchronization, the radio stack can always fall back on the asynchronous low power listening layer for successful message delivery. - -10.4 Neighbor Tables -Moteiv's Boomerange Sensornet Protocol (SP) implementation is a very + +10.4 Neighbor Tables +Moteiv's Boomerange Sensornet Protocol (SP) implementation is a good model to follow for radio stack architecture. One of the nice features of SP is the design and implementation of the neighbor table. By providing and sharing neighbor table information across the entire CC2420 radio stack, RAM can be conserved throughout the radio stack and TinyOS applications. - -10.5 Radio Independant Layers + +10.5 Radio Independant Layers The best radio stack architecture is one that is completely radio independant. Many of the layers in the CC2420 stack can be implemented independant of the hardware underneath if the radio stack architecture was redesigned -and reimplemented. The low power listening receive check strategy may need a -hardware-dependant implementation, but other layers like MessageTransport, +and reimplemented. The low power listening receive check strategy may need a +hardware-dependant implementation, but other layers like PacketLink, UniqueSend, UniqueReceive, ActiveMessage, Dispatch, etc. do not require a CC2420 underneath to operate properly. The ultimate TinyOS radio stack would be one that forms an abstraction between radio-dependant layers and radio-independant layers, and operates with the same behavior across any radio chip. - -10.6 Extendable Metadata + +10.6 Extendable Metadata Layers added into the radio stack may require extra bytes of metadata. -The MessageTransport layer, for example, requires two extra fields +The PacketLink layer, for example, requires two extra fields in each message's metadata to hold the message's max retries and delay between retries. The low power listening layer requires an extra field to specify the destination's duty cycle period for @@ -837,11 +1148,11 @@ of the metadata struct that would adjust its size based on which layers were compiled in and what size fields they required. A combination of compiler support in the form of unique(..) and uniqueCount(..) functions made it possible for the array to adjust its size. -Explicit compiler support would be the most desirable solution to add + Explicit compiler support would be the most desirable solution to add fields to a struct as they are needed. - -10.7 Error Correcting Codes (ECC) + +10.7 Error Correcting Codes (ECC) When two nodes are communicating near the edge of their RF range, it has been observed that interference may cause the packet to be corrupted enough that the CRC byte and payload actually passes @@ -850,13 +1161,13 @@ in 65535 chance of a CRC byte passing the check for a corrupted packet. Although this is slim, in many cases it is unacceptable. Some work arounds have implemented an extra byte of software generated CRC to add to the reliability, and tests have proven its effectiveness. -Taking this a step further, an ECC layer in the radio stack would help -correct corrupted payloads and increase the distance at which nodes +Taking this a step further, an ECC layer in the radio stack would help +correct corrupted payloads and increase the distance at which nodes can reliably communicate. - -11. Author's Address + +11. Author's Address David Moss Rincon Research Corporation @@ -891,36 +1202,36 @@ can reliably communicate. email - - -12. Citations - + +12. Citations + - + [1] (1, 2, 3) TI/Chipcon CC2420 Datasheet. http://www.chipcon.com/files/CC2420_Data_Sheet_1_3.pdf [1] (1, 2, 3) TI/Chipcon CC2420 Datasheet. http://www.chipcon.com/files/CC2420_Data_Sheet_1_3.pdf - + - + [2] (1, 2) TEP111: message_t [2] (1, 2) TEP111: message_t - + - + [3] (1, 2) IEEE 802.15.4 Specification: http://standards.ieee.org/getieee802/802.15.html [3] (1, 2) IEEE 802.15.4 Specification: http://standards.ieee.org/getieee802/802.15.html - + - + [4] TEP105: Low Power Listening [4] TEP105: Low Power Listening - + - + [5] (1, 2) TEP125: TinyOS 802.15.4 Frames [5] (1, 2) TEP125: TinyOS 802.15.4 Frames diff --git a/doc/html/tep2.html b/doc/html/tep2.html index 0457e0e6..8ff51197 100644 --- a/doc/html/tep2.html +++ b/doc/html/tep2.html @@ -3,9 +3,9 @@ - + Hardware Abstraction Architecture - + - Hardware Abstraction Architecture @@ -300,7 +299,7 @@ ul.auto-toc { - @@ -312,6 +311,7 @@ Cory Sharp, Adam Wolisz, David Culler, David Gay TinyOS-Version: 2.0 Author: Vlado Handziski, Joseph Polastre, Jan-Hinrich Hauer, + Vlado Handziski, Joseph Polastre, Jan-Hinrich Hauer, Cory Sharp, Adam Wolisz, David Culler, David Gay Draft-Created: 14-Sep-2004 + Note This document specifies a Best Current Practices for the TinyOS @@ -322,8 +322,8 @@ this document are taken verbatim from the [T2_TR] technical report. This memo is in full compliance with [TEP1]. - -Abstract + +Abstract This TEP documents a Hardware Abstraction Architecture (HAA) for TinyOS 2.0 that balances the conflicting requirements of code reusability and portability on the one hand and efficiency and @@ -335,8 +335,8 @@ allows the applications to utilize a platform's full capabilities -- exported at the second layer, when the performance requirements outweigh the need for cross-platform compatibility. - -1. Introduction + +1. Introduction The introduction of hardware abstraction in operating systems has proved valuable for increasing portability and simplifying application development by hiding the hardware intricacies from the rest of the @@ -358,16 +358,16 @@ promotes efficiency through rich hardware-specific interfaces and the lowest layer structures access to hardware registers and interrupts. The rest of this TEP specifies: -the details of the HAA and its three distinct layers + the details of the HAA and its three distinct layers (2. Architecture) -guidelines on selecting the "right" level of abstraction + guidelines on selecting the "right" level of abstraction (3. Combining different levels of abstraction) how hardware abstractions can be shared among different TinyOS platforms (4. Horizontal decomposition) -the level of hardware abstraction for the processing units + the level of hardware abstraction for the processing units (5. CPU abstraction) how some hardware abstractions may realize different degrees of -alignment with the HAA top layer +alignment with the HAA top layer (6. HIL alignment) The HAA is the architectural basis for many TinyOS 2.0 documentary @@ -375,8 +375,8 @@ TEPs, e.g. [TEP focus on the hardware abstraction for a particular hardware module, and [TEP112] and [TEP115] explain how power management is realized. - -2. Architecture + +2. Architecture In the proposed architecture (Fig.1), the hardware abstraction functionality is organized in three distinct layers of components. Each layer has clearly defined responsibilities and is dependent on @@ -387,7 +387,7 @@ applications. As we move from the hardware towards this top interface, the components become less and less hardware dependent, giving the developer more freedom in the design and the implementation of reusable applications. -+ +-----------------------------+ | | | Cross-platform applications | @@ -425,7 +425,7 @@ reusable applications. |HW Platform 1| |HW Platform 2| |HW Platform 3| |HW Platform 4| +-------------+ +-------------+ +-------------+ +-------------+ - + Fig.1: The proposed Hardware Abstraction Architecture In contrast to the more traditional two step approach used in other @@ -439,8 +439,8 @@ tap to the HAL interfaces that provide access to the full capabilities of the hardware module. The rest of the section discusses the specific roles of each component layer in more detail. - -Hardware Presentation Layer (HPL) + +Hardware Presentation Layer (HPL) The components belonging to the HPL are positioned directly over the HW/SW interface. As the name suggests, their major task is to "present" the capabilities of the hardware using the native concepts @@ -496,8 +496,8 @@ then switch between the different USART modules by simple rewiring (not rewriting) the HPL components, without any changes to the implementation code. - -Hardware Adaptation Layer (HAL) + +Hardware Adaptation Layer (HAL) The adaptation layer components represent the core of the architecture. They use the raw interfaces provided by the HPL components to build useful abstractions hiding the complexity @@ -518,8 +518,8 @@ and not via standard narrow ones that hide all the functionality behind few overloaded commands. This also enables more efficient compile-time detection of abstraction interface usage errors. - -Hardware Interface Layer (HIL) + +Hardware Interface Layer (HIL) The final tier in the architecture is formed by the HIL components that take the platform-specific abstractions provided by the HAL and convert them to hardware-independent interfaces used by cross-platform @@ -558,8 +558,8 @@ also branch, providing multiple different HIL interfaces with increasing levels of functionality. - -3. Combining different levels of abstraction + +3. Combining different levels of abstraction Providing two levels of abstraction to the application --the HIL and HAL-- means that a hardware asset may be accessed at two levels in parallel, e.g. from different parts of the application and the OS @@ -581,7 +581,7 @@ programmer of the MAC might directly use the hardware specific interface of the HAL component as it provides much finer control over the conversion process. (Fig.2) depicts how the ADC hardware stack on the MSP430 MCU on the level of HIL and HAL in parallel. -+ +--------------------------------+ | APP | +-+----------------------------+-+ @@ -623,8 +623,8 @@ more complex arbitration and resource control functionality -4. Horizontal decomposition + +4. Horizontal decomposition In addition to the vertical decomposition of the HAA, a horizontal decomposition can promote reuse of the hardware resource abstractions that are common on different platforms. To this aim, @@ -634,7 +634,7 @@ flash-chip, etc. Each chip decomposition follows the HAA model, providing HIL implementation(s) as the topmost component(s). Platforms are then built as compositions of different chip components with the help of "glue" components that perform the mapping (Fig.3) -+ +----------------------------------------------------+ | AppC | | /Application Component/ | @@ -706,8 +706,8 @@ access to the bus resource. In this way, the chip can be safely used both in dedicated scenarios, as well as in situations where multiple chips are connected to the same physical bus interconnect. - -5. CPU abstraction + +5. CPU abstraction In TinyOS most of the variability between the processing units is hidden from the OS simply by using a nesC/C based programming language with a common compiler suite (GCC). For example, the standard library @@ -724,8 +724,8 @@ architectures need to be supported by TinyOS in the future, this part of the hardware abstraction functionality will have to be explicitly addressed. - -6. HIL alignment + +6. HIL alignment While the HAA requires that the HIL provides full hardware independence (Strong/Real HILs), some abstractions might only partially meet this goal (Weak HILs). This section introduces @@ -736,8 +736,8 @@ concept of a HIL. It also uses the following differentiation: definition may be different platform-specific X: X is defined on just one platform - -Strong/Real HILs + +Strong/Real HILs Strong/Real HILs mean that "code using these abstractions can reasonably be expected to behave the same on all implementations". This matches the original definition of the HIL level according to @@ -750,8 +750,8 @@ them (i.e., they are platform-defined abstract data types), for example, the TinyOS 2.x message buffer abstraction, message_t ([TEP111]). - -Weak HILs + +Weak HILs Weak HILs mean that one "can write portable code over these abstractions, but any use of them involves platform-specific behavior". Although such platform-specific behavior can --at least at @@ -773,23 +773,23 @@ still be easier to port than code built on top of HALs, because weak which should help programmers and provide guidance to platform developers. - -Hardware Independent Interfaces (HII) + +Hardware Independent Interfaces (HII) Hardware Independent Interfaces (HII), is just an interface definition intended for use across multiple platforms. Examples include the SID interfaces, the pin interfaces from [TEP117], the Alarm/Counter/etc interfaces from [TEP102]. - -Utility components + +Utility components Utility components are pieces of clearly portable code (typically generic components), which aren't exposing a self-contained service. Examples include the components in tos/lib/timer and the ArbitratedRead* components. These provide and use HIIs. - -6. Conclusion + +6. Conclusion The proposed hardware abstraction architecture provides a set of core services that eliminate duplicated code and provide a coherent view of the system across different platforms. It supports the concurrent use @@ -799,11 +799,11 @@ platform dependence to only the places where performance matters, while using standard cross-platform hardware interfaces for the remainder of the application. - -Author's Address + +Author's Address -Vlado Handziski (handzisk at tkn.tu-berlin.de) [1] -Joseph Polastre (polastre at cs.berkeley.edu) [2] +Vlado Handziski (handzisk at tkn.tu-berlin.de) [1] +Joseph Polastre (polastre at cs.berkeley.edu) [2] Jan-Hinrich Hauer (hauer at tkn.tu-berlin.de) [1] Cory Sharp (cssharp at eecs.berkeley.edu) [2] Adam Wolisz (awo at ieee.org) [1] @@ -813,9 +813,9 @@ remainder of the application. - [1] (1, 2, 3) Technische Universitaet Berlin -Telecommunication Networks Group -Sekr. FT 5, Einsteinufer 25 + [1] (1, 2, 3) Technische Universitaet Berlin +Telecommunication Networks Group +Sekr. FT 5, Einsteinufer 25 10587 Berlin, Germany @@ -823,7 +823,7 @@ Sekr. FT 5, Einsteinufer 25 [2](1, 2, 3) University of California, Berkeley -Computer Science Department +Computer Science Department Berkeley, CA 94720 USA @@ -836,8 +836,8 @@ CA 94704 - -Citations + +Citations @@ -850,11 +850,11 @@ Wireless Sensor Networks (EWSN 2005), Istanbul, Turkey, 2005. - [T2_TR] P. Levis, D. Gay, V. Handziski, J.-H.Hauer, B.Greenstein, -M.Turon, J.Hui, K.Klues, C.Sharp, R.Szewczyk, J.Polastre, -P.Buonadonna, L.Nachman, G.Tolle, D.Culler, and A.Wolisz, -"T2: A Second Generation OS For Embedded Sensor Networks", -Technical Report TKN-05-007, Telecommunication Networks Group, + [T2_TR] P. Levis, D. Gay, V. Handziski, J.-H.Hauer, B.Greenstein, +M.Turon, J.Hui, K.Klues, C.Sharp, R.Szewczyk, J.Polastre, +P.Buonadonna, L.Nachman, G.Tolle, D.Culler, and A.Wolisz, +"T2: A Second Generation OS For Embedded Sensor Networks", +Technical Report TKN-05-007, Telecommunication Networks Group, Technische UniversitÃ¤t Berlin, November 2005. @@ -868,7 +868,7 @@ Technische UniversitÃ¤t Berlin, November 2005. - [NetBSD] "The NetBSD project home page", Online, + [NetBSD] "The NetBSD project home page", Online, http://www.netbsd.org diff --git a/doc/html/tep3.html b/doc/html/tep3.html index a5f6123a..2f947dc3 100644 --- a/doc/html/tep3.html +++ b/doc/html/tep3.html @@ -3,7 +3,7 @@ - + Coding Standard - Coding Standard @@ -303,14 +302,15 @@ ul.auto-toc { - + - + Ion Yannopoulos, David Gay Draft-Created: 31-Dec-2004 Draft-Version: 1.1.2.3 Draft-Version: 1.5 Draft-Modified: 2006-01-16 Draft-Modified: 2006-12-12 Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu> + Note This document specifies a Best Current Practices for the @@ -318,8 +318,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]. - -Contents + +Contents 1 Introduction 2 General Conventions @@ -351,8 +351,8 @@ is in full compliance with 6 Citations - -1 Introduction + +1 Introduction The purpose of a naming convention is twofold: @@ -369,16 +369,16 @@ than it is written. If you deviate from the suggestions or requirements below, be consistent in how you do so. If you add any new conventions to your code, note it in a README. - -2 General Conventions - -2.1 General + +2 General Conventions + +2.1 General 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 +392,24 @@ documentation block. - -3 Packages + +3 Packages 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. - -3.1 Directory structure + +3.1 Directory structure Each package should have it's own directory. It may have as many @@ -472,12 +472,12 @@ components fairly easily however. - -4 Language Conventions - -4.1 nesC convention - -4.1.1 Names + +4 Language Conventions + +4.1 nesC convention + +4.1.1 Names All nesC files must have a .nc extension. The nesC compiler requires @@ -504,8 +504,8 @@ in '_t'. - -4.1.2 Packages + +4.1.2 Packages Each package may use a prefix for its component, interface and @@ -518,7 +518,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. @@ -530,14 +530,14 @@ components and Atm128 for hardware abstraction layer components. - -4.1.3 Preprocessor + +4.1.3 Preprocessor 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 +552,12 @@ can't catch. - -4.2 C Convention + +4.2 C Convention 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 +565,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 +591,8 @@ by underscores. - -4.3 Java convention + +4.3 Java convention The standard Java coding convention [Java_Coding_Convention] @@ -601,8 +601,8 @@ should be followed. - -4.4 Other languages + +4.4 Other languages No established conventions. @@ -610,18 +610,18 @@ should be followed. - -5 TinyOS Conventions + +5 TinyOS Conventions 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. - -5.1 Error returns + +5.1 Error returns 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 +643,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. - -5.2 Passing pointers between components + +5.2 Passing pointers between components 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 +700,8 @@ above. In the future, some tool may check that programs respect these ownership transfer rules. - -5.3 Usage of wiring annotations + +5.3 Usage of wiring annotations 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 +721,8 @@ annotation SHOULD be used on initialisation interfaces (typically, the wire initialisation code. - -6 Citations + +6 Citations

[1]	Erik Cota-Robles and James P. Held. "A Comparison of Windows +
[1]	Erik Cota-Robles and James P. Held. "A Comparison of Windows Driver Model Latency Performance on Windows NT and Windows 98." In Proceedings of the Third Symposium on Operating System Design and Implementation (OSDI).

[2]	TEP 124: The Collection Tree Protocol (CTP) - (upcoming)
[2]	TEP 123: The Collection Tree Protocol (CTP)

[PEH]	Martin Leopold. "Power Estimation using the Hogthrob Prototype Platform" M.Sc. +
[PEH]	Martin Leopold. "Power Estimation using the Hogthrob Prototype Platform" M.Sc. Thesis, DIKU, Copenhagen University, Denmark, December 2004 .

[1]	(1, 2, 3) TI/Chipcon CC2420 Datasheet. http://www.chipcon.com/files/CC2420_Data_Sheet_1_3.pdf
[1]	(1, 2, 3) TI/Chipcon CC2420 Datasheet. http://www.chipcon.com/files/CC2420_Data_Sheet_1_3.pdf

[3]	(1, 2) IEEE 802.15.4 Specification: http://standards.ieee.org/getieee802/802.15.html
[3]	(1, 2) IEEE 802.15.4 Specification: http://standards.ieee.org/getieee802/802.15.html

[4]	TEP105: Low Power Listening
[4]	TEP105: Low Power Listening

[5]	(1, 2) TEP125: TinyOS 802.15.4 Frames
[5]	(1, 2) TEP125: TinyOS 802.15.4 Frames

TinyOS-Version:	2.0
Author:	Vlado Handziski, Joseph Polastre, Jan-Hinrich Hauer, +	Vlado Handziski, Joseph Polastre, Jan-Hinrich Hauer, Cory Sharp, Adam Wolisz, David Culler, David Gay
Draft-Created:	14-Sep-2004

[1]	(1, 2, 3) Technische Universitaet Berlin -Telecommunication Networks Group -Sekr. FT 5, Einsteinufer 25 +
[1]	(1, 2, 3) Technische Universitaet Berlin +Telecommunication Networks Group +Sekr. FT 5, Einsteinufer 25 10587 Berlin, Germany

[T2_TR]	P. Levis, D. Gay, V. Handziski, J.-H.Hauer, B.Greenstein, -M.Turon, J.Hui, K.Klues, C.Sharp, R.Szewczyk, J.Polastre, -P.Buonadonna, L.Nachman, G.Tolle, D.Culler, and A.Wolisz, -"T2: A Second Generation OS For Embedded Sensor Networks", -Technical Report TKN-05-007, Telecommunication Networks Group, +
[T2_TR]	P. Levis, D. Gay, V. Handziski, J.-H.Hauer, B.Greenstein, +M.Turon, J.Hui, K.Klues, C.Sharp, R.Szewczyk, J.Polastre, +P.Buonadonna, L.Nachman, G.Tolle, D.Culler, and A.Wolisz, +"T2: A Second Generation OS For Embedded Sensor Networks", +Technical Report TKN-05-007, Telecommunication Networks Group, Technische UniversitÃ¤t Berlin, November 2005.

[NetBSD]	"The NetBSD project home page", Online, +
[NetBSD]	"The NetBSD project home page", Online, http://www.netbsd.org

Ion Yannopoulos, David Gay
Draft-Created:	31-Dec-2004
Draft-Version:	1.1.2.3
Draft-Version:	1.5
Draft-Modified:	2006-01-16
Draft-Modified:	2006-12-12
Draft-Discuss:	TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>