<br />Vlado Handziski</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">28-Mar-2005</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1.2.9</td>
+<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.3</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-06-21</td>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-09-08</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
</tr>
<p>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
-interface is TimerC. A client of a Timer instance can use it
+interface in TimerC. A client of a Timer instance can use it
independently of the others: TimerC virtualizes the underlying
hardware clock into N separate timers.</p>
<p>Some abstractions, however, are not well suited to virtualization:
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. Therefore, shared use of
-GenericComm follows a first-come, first-served arbitration policy. If
-a component sends a packet but GenericComm is busy, the component
-needs a way to tell when GenericComm is free so it can retry. TinyOS
+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
-signalled whenever a packet send completes. Interested components can
+signaled whenever a packet send completes. Interested components can
handle this event and retry.</p>
-<p>The approach to physical (rather than virtualized) abstractions
+<p>This approach to physical (rather than virtualized) abstractions
has several drawbacks:</p>
<ul class="simple">
<li>If you need to make several requests, you have to handle the
concept of "repeated start" when doing multiple bus transactions,
but it is not clear how to use this in TinyOS 1.x's I2C abstraction.</li>
<li>Most TinyOS 1.x services do not provide a very convenient way of
-monitoring an abstractions's availability for the purpose of retries,
+monitoring an abstraction's availability for the purpose of retries,
nor very clear documentation of which requests could happen simultaneously.</li>
</ul>
-<p>A single approach to resource sharing is not appropriate for all
-circumstances. For instance, requiring resource reservation allows
-programs to have better timing guarantees for access to an A/D converter.
-But if a program does not need precise timing guarantees (e.g., when measuring
-temperature in a biological monitoring application), this extra resource
-reservation step unnecessarily complicates code.</p>
+<p>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.,
+when measuring temperature in a biological monitoring application), this extra
+resource reservation step unnecessarily complicates code and can be handled
+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.</p>
</div>
<div class="section">
<h1><a id="resource-classes" name="resource-classes">2. Resource Classes</a></h1>
<p>TinyOS 2.x distinguishes between three kinds of abstractions:
-<em>dedicated</em>, <em>shared</em>, and <em>virtualized</em>.
-Components offer resource sharing mechanisms appropriate to their
-goals and level of abstraction. As discussed in Section 2.1, access
-control to dedicated abstractions is generally handled
-through nesC interfaces. As discussed in Section 2.2, access control
-to virtualized abstractions is handled through software design
-patterns such as the Service Instance <a class="footnote-reference" href="#id9" id="id1" name="id1">[3]</a> and/or
-queueing. Section 2.3 addresses with the most complex class of
-abstraction, shared, while Section 3 describes the
-components and interfaces used to arbitrate access to this class.</p>
-<p>Hardware Presentation Layer (HPL) components of the HAA <a class="footnote-reference" href="#id7" id="id2" name="id2">[1]</a> are not
-virtual, as virtualization inevitably requires state. Depending on their
-expected use, HPL abstractions are either dedicated or
+<em>dedicated</em>, <em>virtualized</em>, and <em>shared</em>. Components offer resource
+sharing mechanisms appropriate to their goals and level of abstraction.</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">It is important to point out that Hardware Presentation Layer (HPL)
+components of the HAA <a class="footnote-reference" href="#id4" id="id1" name="id1">[1]</a> can never be virtualized, as virtualization
+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.
-For example, on the MSP430 microcontroller, compare and counter registers are
-dedicated, while the USARTs are shared.</p>
+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.</p>
+</div>
<div class="section">
<h2><a id="dedicated" name="dedicated">2.1 Dedicated</a></h2>
<p>An abstraction is <em>dedicated</em> if it is a resource
-which a subsystem needs exclusive access to at all times. Examples of
-dedicated abstractions include interrupts and counters.
-Generally, a physical and dedicated abstraction is just an interface
-which its user wires to. For example, on the Atmega128, Timer 2 is
-presented by the component HplAtm128Timer2C:</p>
-<pre class="literal-block">
-module HplAtm128Timer2C {
- provides {
- interface HplTimer<uint8_t> as Timer2;
- interface HplTimerCtrl8 as Timer2Ctrl;
- interface HplCompare<uint8_t> as Compare2;
- }
-}
-</pre>
+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.</p>
<p>Dedicated abstractions MAY be annotated with the nesC attribute
-@atmostonce or @exactlyonce is to provide compile-time checks that
+@atmostonce or @exactlyonce to provide compile-time checks that
their usage assumptions are not violated.</p>
+<p>Please refer to Appendix A for an example of how a dedicated
+resource might be represented, including the use of
+the nesC @exactlyonce attribute.</p>
</div>
<div class="section">
-<h2><a id="virtual" name="virtual">2.2 Virtual</a></h2>
+<h2><a id="virtualized" name="virtualized">2.2 Virtualized</a></h2>
<p><em>Virtual</em> abstractions hide multiple clients from each other
-through software virtualization. Every client of the resource thinks it
-has its own independent instance of the resource, but these virtualized
-instances are multiplexed on top of a single underlying resource. Because
-the virtualization is in software, there is no upper bound on the number
-of clients of the abstraction, barring memory or efficiency constraints.
-For example, the TimerMilliC component provides a virtual and shared
-abstraction of millisecond precision timers to application
-components <a class="footnote-reference" href="#id8" id="id3" name="id3">[2]</a>. As virtualization usually requires keeping state
-that scales with the number of virtualized instances,
-virtualized resources often use the Service Instance pattern <a class="footnote-reference" href="#id9" id="id4" name="id4">[3]</a>,
-which is based on a parameterized interface. For example, HilTimerMilliC
-provides multiple virtualized timer clients and auto-wires the
-chip timer implementation (HilTimerMilliC <a class="footnote-reference" href="#id8" id="id5" name="id5">[2]</a>) to the boot initialization
-sequence:</p>
-<pre class="literal-block">
-configuration TimerMilliP {
- provides interface Timer<TMilli> as TimerMilli[uint8_t num];
-}
-implementation {
- components HilTimerMilliC, MainC;
- MainC.SoftwareInit -> HilTimerMilliC;
- TimerMilli = HilTimerMilliC;
-}
-</pre>
-<p>while TimerMilliC encapsulates this in a generic configuration:</p>
-<pre class="literal-block">
-generic configuration TimerMilliC {
- provides interface Timer<TMilli>;
-}
-implementation {
- components HilTimerMilliC;
- Timer = HilTimerMilliC.Timer[unique(UQ_TIMER_MILLI)];
-}
-</pre>
-<p>Virtualization generally allows a client to use a very simple interface.
-This simplicity comes at a cost of reduced efficiency and an inability to
-precisely control the underlying resource. For example, TimerMilli32C
-introduces CPU overhead from dispatching and maintaining all of the
-virtual timers as well as jitter from when two timers want to fire at
-the same time.</p>
+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
+pattern <a class="footnote-reference" href="#id6" id="id2" name="id2">[3]</a>, which is based on a parameterized interface.</p>
+<p>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
+example of how such a virtualized timer resource might be implemented.</p>
</div>
<div class="section">
<h2><a id="shared" name="shared">2.3 Shared</a></h2>
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.</p>
-<p>In TinyOS 2.x, a resource <em>arbiter</em> is responsible for this
-multiplexing. The arbiter determines which client has access to the
-resource. 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.</p>
<p>A motivating example of a shared resource is a bus.
The bus may have multiple peripherals on it, corresponding to
different subsystems. For example, on the Telos platform the flash
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
-physical but shared resource allows the radio stack to
-send a series of operations atomically across to the radio without
-having to buffer them all up in memory beforehand (which would
-introduce memory pressure).</p>
+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).</p>
+<p>In TinyOS 2.x, a resource <em>arbiter</em> 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
+release resources: there is no way for an arbiter to forcibly reclaim it.
+The following section is dedicated to describing the arbiter and its
+interfaces.</p>
</div>
</div>
<div class="section">
<h1><a id="resource-arbiters" name="resource-arbiters">3. Resource Arbiters</a></h1>
<p>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 also
-provides information useful for a variety of other services, such as
+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. An
-arbiter SHOULD also provide an instance of ResourceController and
-ResourceConfigure interfaces. An arbiter MAY provide additional
-interfaces or instance of interfaces in order to provide a particular
-arbitration policy.</p>
+arbiter SHOULD also provide a parameterized ResourceRequested interface
+and use a parameterized ResourceConfigure interface. It MAY also provide
+an instance of the ResourceController interface or any additional
+interfaces specific to the particular arbitration policy being
+implemented.</p>
<div class="section">
<h2><a id="resource" name="resource">3.1 Resource</a></h2>
<p>Clients of a shared resource arbiter request access
-with the Resource interface:</p>
+using the Resource interface:</p>
<pre class="literal-block">
interface Resource {
async command error_t request();
async command error_t immediateRequest();
event void granted();
- async command void release();
+ async command error_t release();
+ async command bool isOwner();
}
</pre>
-<p>A client lets an arbiter know it needs access to the resource with
-a call to request(). The arbiter signals the granted() event to a
-client when it gains exclusive access to the resource. A client
-can also acquire the resource with immediateRequest(). The
-return value of this call determines whether the client was able
-to acquire the resource. If immmediateRequest() does not successfully
-acquire the resource (does not return SUCCESS), then it can try to do
-so in the standard,
-split-phase way with request(). If the call to immediateRequest()
-returns SUCCESS, then the arbiter MUST NOT issue a granted() event.</p>
-<p>An arbiter MUST provide a parameterized Resource interface,
+<p>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
+hog the resource queue by making multiple requests, but they may still be
+able to hog the resource if they do not release it in a timely manner.</p>
+<p>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.</p>
+<p>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.</p>
+<p>An arbiter MUST provide exactly one parameterized Resource interface,
where the parameter is a client ID, following the Service
-Instance pattern <a class="footnote-reference" href="#id9" id="id6" name="id6">[3]</a>. An arbitrated component SomeNameC MUST
+Instance pattern[3]_. An arbitrated component SomeNameP MUST
#define SOME_NAME_RESOURCE to a string which can be passed to unique()
-to obtain a client id. For instance, an I2C bus might look like this:</p>
-<pre class="literal-block">
-includes I2CPacketC;
-configuration I2CPacketC {
- provides {
- interface Resource[uint8_t id];
- interface I2CPacket[uint8_t busId];
- }
-} ...
-</pre>
-<p>where I2CPacketC.h contains the #define for the resource:</p>
-<pre class="literal-block">
-#ifndef I2CPACKETC_H
-#define I2CPACKETC_H
-#define I2CPACKET_RESOURCE "I2CPacket.Resource"
-#endif
-</pre>
-<p>The #define for the unique string must be placed in a separate file
-because of the way nesC files are preprocessed: referring to I2CPacketC
-isn't enough to ensure that macros #define'd in I2CPacketC are visible
-in the referring component.</p>
-<p>For example, clients of the I2C service might use it as follows:</p>
-<pre class="literal-block">
-module I2CUserM {
- uses interface Resource as I2CResource;
- uses interface I2CPacket;
-} ...
-
-#include <I2CPacketC.h>
-configuration I2CUserC { }
-implementation {
- components I2CUserM, I2CPacketC;
-
- I2CUserM.I2CResource -> I2CPacketC.Resource[unique(I2C_RESOURCE)];
- I2CUserM.I2CPacket -> I2CPacket.I2CPacket[0x73]; // using I2C device 0x73
-}
-</pre>
+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
+SomeNameP are visible in the referring component.</p>
+<p>Please refer to Appendix B for an example of how to wrap this component
+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.</p>
+<p>For a complete example of how the I2C resource might be abstracted
+according to this pattern, please refer to Appendix B. For further
+examples please refer to the various chip implementations in the
+tinyos-2.x source tree under tinyos-2.x/chips/</p>
</div>
<div class="section">
-<h2><a id="resourcecontroller" name="resourcecontroller">3.2 ResourceController</a></h2>
-<p>An arbiter SHOULD provide one instance of the ResourceController
-interface and MAY provide more than one. The Resource interface is for
-simple and basic use cases, where clients are peers that share the
-resource in some equal fashion. ResourceController is for clients that
-require additional information due to the policies of the arbiter and
-how they use the resource. The ResourceController interface is based
-on Resource, but introduces two additional events, idle() and
-requested():</p>
-<pre class="literal-block">
-interface ResourceController {
- async command error_t request();
- async command error_t immediateRequest();
- event void granted();
- async command void release();
- async event void requested();
- async event void idle();
-}
-</pre>
-<p>An arbiter signals the requested event if the client currently has the resource
-and some other client has requested it. It signals the idle() event when
-no client holds the resource.</p>
-<p>ResourceController allows an arbiter to provide a much richer set of
-policies than simple sharing. For example, arbiters that want to
-incorporate a power management policy can provide ResourceController
-for a power management component. The power management component can
-detect when nobody is using the resource with idle(), acquire it
-atomically with immediateRequest(), and power it down. When another
-client requests the resource, the power manager will handle the
-requested() event. It can then power up the resource and release it
-when the power up completes. Note that if power up is a split-phase
-operation (takes a while), then calls by clients to immediateRequest()
-when in powered down state will not return SUCCESS. See TEP 115 for
-details. The default arbiters in TinyOS 2.x (see Section 4) all provide a
-single instance of ResourceController, in order to enable power
-management as described above.</p>
-<p>ResourceController can also be used for special case clients: the
-algorithm used to determine when its requests are handled in
-comparison to instances of Resource is arbiter specific. Therefore,
-arbiters MAY provide one or more instances of ResourceController. For
-example, the FcfsPriorityArbiter has a single high-priority client who
-is always granted access to the resource before any other client.
-Other clients only obtain the resource if the high-priority client has
-not requested it or when the high-priority client releases it.</p>
-</div>
-<div class="section">
-<h2><a id="arbiterinfo" name="arbiterinfo">3.3 ArbiterInfo</a></h2>
+<h2><a id="arbiterinfo" name="arbiterinfo">3.2 ArbiterInfo</a></h2>
<p>Arbiters MUST provide an instance of the ArbiterInfo interface.
The ArbiterInfo interface allows a component to query the current
status of an arbiter:</p>
</pre>
<p>The ArbiterInfo interface has a variety of uses. For example, the resource
implementation can use it to refuse requests from clients that do not
-currently have access. In this case, the abstraction would need to provide
-a parameterized interface for its operations so it could distinguish separate
-clients, and the client ID for its operations would need to be the same
-as the client ID for the arbiter.</p>
+currently have access. For an example of how this interface is used
+in this fashion please refer to Appendix B.</p>
+</div>
+<div class="section">
+<h2><a id="resourcerequested" name="resourcerequested">3.3 ResourceRequested</a></h2>
+<p>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:</p>
+<pre class="literal-block">
+interface ResourceRequested {
+ async event void requested();
+ async event void immediateRequested();
+}
+</pre>
+<p>A requested event is signaled to the current owner of the resource if another
+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.</p>
+<p>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.</p>
</div>
<div class="section">
<h2><a id="resourceconfigure" name="resourceconfigure">3.4 ResourceConfigure</a></h2>
-<p>The ResourceConfigure interface provides a mechanism for clients that need
-to use a resource with different configurations. Rather than forcing a
-client to reconfigure the resource itself, the component representing a
-client can wire to an arbiter's ResourceConfigure interface, which is called
-before the client is granted the resource.</p>
-<p>For example, 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 a time. However, different clients of the bus might need different bus
-protocols. For example, Telos sensors use an I2C, while the radio and flash
-chip use SPI.</p>
-<p>Arbiters MAY use a parameterized ResourceConfigure interface:</p>
+<p>The ResourceConfigure interface provides a mechanism for clients
+that need to use a resource with different configurations to do so.
+Rather than forcing a client to reconfigure the resource itself, the
+component representing a client can wire to an arbiter's
+ResourceConfigure interface, which is called just before granting the
+client the resource:</p>
<pre class="literal-block">
interface ResourceConfigure {
async command void configure();
async command void unconfigure();
}
</pre>
-<p>The parameter is the client ID, and corresponds directly to an instance of
-the Resource interface. For example:</p>
-<pre class="literal-block">
-generic component RoundRobinArbiterC {
- provides {
- interface Resource[uint8_t id];
- interface ResourceController;
- interface ArbiterInfo;
- }
- uses {
- interface ResourceConfigure[uint8_t id];
- }
-}
-</pre>
-<p>If an arbiter uses the ResourceConfigure interface, before it signals the
-Resource.granted() event and before it returns SUCCESS from a call to
-Resource.immediateRequest(), it MUST call ResourceConfigure.configure() on
-the granted client ID. Similarly, after a valid call to Resource.release(),
-it MUST call ResourceConfigure.unconfigure() on the releasing client ID.</p>
-<p>Using a parameterized interface that calls out rather than a decorator
-on the Resource interface simplifies code reuse. Using a decorator
-could lead to a large number of clients all including redundant
-configuration code, while the call out will only have one instance
-of the code. For example, an SPI client might look like this:</p>
+<p>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
+before it signals the Resource.granted() event. Similarly, after a valid
+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
+ResourceConfigure.unconfigure() just before fully releasing it, it is guaranteed
+that a resource is always unconfigured before an attempt to configure it can be
+made again.</p>
+<p>Using the parameterized ResourceConfigure interface that calls out rather than
+additional commands being put into the Resource interface
+simplifies code reuse. Introducing these new commands into the
+Resource interface could lead to a large number of clients all
+including redundant configuration code, while using the call out
+approach provided by the parameterized interface will only have one
+instance of the code.</p>
+<p>For an example of how the three different modes of the Msp430 Usart
+component can take advantage of this ResourceConfigure interface
+please refer to Appendix B as well as section 4 on the use of
+cross-component reservation.</p>
+</div>
+<div class="section">
+<h2><a id="resourcecontroller" name="resourcecontroller">3.5 ResourceController</a></h2>
+<p>The normal Resource interface is for use by clients that all share the resource
+in an equal fashion. The ResourceController 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 ResourceController
+interface.:</p>
<pre class="literal-block">
-generic component Msp430Spi0ClientC {
- provides {
- interface Resource;
- interface SPIByte;
- interface SPIPacket;
- }
-}
-implementation {
- enum {MSP430_SPI0_CLIENT = unique(MSP430_USART_RESOURCE);
- components Msp430Usart0C, Msp430Spi0Configure as Configure;
-
- Resource = Msp430Usart0C.Resource[MSP430_SPI0_CLIENT];
- Msp430Usart0C.ResourceConfigure[MSP430_SPI0_CLIENT] -> Configure;
+interface ResourceController {
+ async event void granted();
+ async command error_t release();
+ async command bool isOwner();
+ async event void requested();
+ async event void immediateRequested();
}
</pre>
-<p>Arbiters SHOULD provide a parameterized ResourceConfigure interface.</p>
+<p>The Arbiter MUST guarantee that the user of the ResourceController 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
+ResourceController 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
+ResourceController is automatically given control of the resource, receiving its
+granted() event in the process. The ResourceController interface also contains
+the same isOwner() command as the normal Resource interface, and the semantics
+of its use are exactly the same.</p>
+<p>Although the ResourceController interface looks similar to a combination of the
+normal Resource interface and the ResourceRequested interface, its intended use
+is quite different. The ResourceController 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 out access to the resource, but rather use
+it to perform operations when it would otherwise simply be idle.</p>
+<p>Combining the use of the Resource and ResourceRequested interfaces could be made
+to operate in a similar manner as the ResourceController interface, except that
+there is no way to tell a client with these interfaces that a resource has gone
+completely idle. Each client must actively request the use of the resource and
+be granted that resource in the order determined by the queuing policy of its
+arbiter. With the ResourceController interface, there is no active request of
+the resource. The arbiter simply signals the granted event to the
+ResourceController whenever there are no more pending requests and the last
+client that owned the resource releases it.</p>
+<p>The primary motivation behind the definition of the ResourceController
+interface was to allow for an easy integration of the power management
+policy used by the resource with the arbitration of the resource
+itself. Arbiters that want to allow a resource to be controlled by a particular power management policy can provide the ResourceController 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 then 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 not return
+SUCCESS. Please see the TEP on the Power Management of Non-Virtualized devices
+(<a class="footnote-reference" href="#id7" id="id3" name="id3">[4]</a>) for more details.</p>
+</div>
</div>
<div class="section">
-<h2><a id="cross-component-reservation" name="cross-component-reservation">3.5 Cross-component reservation</a></h2>
-<p>In some cases, it is desirable to share reservation of resources
-across components. For example, on the TI MSP430, the same pins can
-be used as an I2C bus, a UART, or an SPI connection. Clearly, on this
-chip, a reservation of the I2C bus implicitly reserves the
-corresponding UART and SPI. This can be accomplished in the framework
-described above by:</p>
+<h1><a id="cross-component-reservation" name="cross-component-reservation">4. Cross-Component Reservation</a></h1>
+<p>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,
+or an SPI connection. Clearly, on this chip, a reservation of the I2C
+bus implicitly restricts the corresponding UART and SPI
+services from gaining access to the resource. Enforcing such a policy
+can be accomplished in the framework described above by:</p>
+<blockquote>
<ol class="arabic simple">
-<li>using the same unique string for all three resources</li>
+<li>Creating a set of unique ids for each service using the shared
+resource.</li>
+<li>Mapping these ids onto the ids of the underlying resource</li>
</ol>
-<p>2) wiring the three parameterised Resource interfaces to the same
-arbiter</p>
-<p>The common way to do this is as follows (the UART and SPI components
-are omitted, they are similar to I2CC, low-level I2C component):</p>
+</blockquote>
+<p>Clients connecting to these services do not know that that this
+mapping is taking place. As far as they are concerned, the only
+arbitration taking place is between other clients using the same
+service. In the MSP430 example, a single client of the I2C bus could
+be contending with a single client of the SPI connection, but they
+would probably have the same service level client ID. These two
+service level client ids would be mapped onto 2 unique resource ids
+for use by the shared USART component. The proper way to achieve this
+mapping is through the use of generic components. The example given
+below shows how to perform this mapping for the SPI component on the
+MSP430. It is done similarly for the UART and I2C bus:</p>
<pre class="literal-block">
-#define I2C_RESOURCE MSP_BUS_RESOURCE
-configuration I2CC {
- provides interface Resource[uint8_t clientId];
- provides interface I2C;
+#include "Msp430Usart.h"
+generic configuration Msp430Spi0C() {
+ provides interface Resource;
+ provides interface SpiByte;
+ provides interface SpiPacket;
}
implementation {
- components MspBusC, I2CM;
+ enum { CLIENT_ID = unique(MSP430_SPIO_BUS) };
+
+ components Msp430Spi0P as SpiP;
+ Resource = SpiP.Resource[ CLIENT_ID ];
+ SpiByte = SpiP.SpiByte;
+ SpiPacket = SpiP.SpiPacket[ CLIENT_ID ];
- Resource = MspBusC.Resource;
- I2C = I2CM.I2C;
+ components new Msp430Usart0C() as UsartC;
+ SpiP.UsartResource[ CLIENT_ID ] -> UsartC.Resource;
+ SpiP.UsartInterrupts -> UsartC.HplMsp430UsartInterrupts;
}
</pre>
-<p>MspBusC (the arbiter for the MSP bus):</p>
-<pre class="literal-block">
-#define MSP_BUS_RESOURCE "MspBus.Resource"
-configuration {
- provides interface Resource[uint8_t clientId];
-} ...
-</pre>
-</div>
+<p>The definition of the MSP430_SPIO_BUS string is defined in
+Msp430Usart.h. A unique id is created from this string every time a
+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 <em>providing</em> a parameterized
+Resource interface, the Msp430Spi0P component also <em>uses</em> a
+parameterized Resource interface. Whenever a client makes a call
+through the provided Resource interface with id CLIENT_ID, an
+underlying call to the used Resource interface with the same id is
+implicitly made. By wiring the used Resource interface with id
+CLIENT_ID to the 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.</p>
+<p>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.
+With such a mapping, inserting these operations is made possible.</p>
+<p>Having such a mapping is also important for services that need to
+explicitly keep track of the number of clients they have,
+independent from how many total clients the underlying shared
+resource has. For example, a sensor implementation that uses an
+underlying ADC resource may wish to power down its sensor whenever it
+has no clients. It doesn't want to have to wait until the entire ADC
+is free to do so. Providing this mapping allows the implicit power
+manager components described in TEP 115 to be wired in at both levels
+of the abstraction without interfering with one another. In this
+way, implementations of these components become much simpler, and code
+reuse is encouraged.</p>
+<p>Implementations of components similar to this one can be found in the
+tinyos-2.x source tree in the tos/chips/msp430/uart directory</p>
</div>
<div class="section">
-<h1><a id="implementation" name="implementation">4. Implementation</a></h1>
+<h1><a id="implementation" name="implementation">5. Implementation</a></h1>
<p>Because most components use one of a small number of arbitration
-policies, TinyOS includes a number of default resource arbiters. These
+policies, tinyos-2.x includes a number of default resource arbiters. These
arbiters can be found in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/system</span></tt> and are all
-generic components that include this signature:</p>
+generic components that include one of the two signatures seen below:</p>
<pre class="literal-block">
-generic module ArbiterC {
+generic module SimpleArbiter {
+ provides interface Resource[uint8_t id];
+ provides interface ResourceRequested[uint8_t id];
+ provides interface ArbiterInfo;
+ uses interface ResourceConfigure[uint8_t id];
+}
+
+generic module Arbiter {
provides interface Resource[uint8_t id];
+ provides interface ResourceRequested[uint8_t id];
provides interface ResourceController;
provides interface ArbiterInfo;
uses interface ResourceConfigure[uint8_t id];
}
</pre>
-<p>For example, <tt class="docutils literal"><span class="pre">RoundRobinArbiterC</span></tt> provides round-robin arbitration. This
-arbiter assigns a fixed order to all clients and grants outstanding
-requests in that order, which is based on client ID. <tt class="docutils literal"><span class="pre">FcfsArbiterC</span></tt>
-provides a FIFO order, where requests are serviced in the order they
-are received. <tt class="docutils literal"><span class="pre">FcfsPriorityArbiterC</span></tt> is similar to FcfsArbiterC, but
-provides an additional ResourceController interface for the
-high-priority client.</p>
+<p>The "Simple" arbiters are intended for use by resources that
+do not require the additional overhead incurred by providing the
+ResourceController interface.</p>
+<p>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
+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
+interface.:</p>
+<pre class="literal-block">
+interface ResourceQueue {
+ async command bool isEmpty();
+ 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);
+}
+</pre>
+<p>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:</p>
+<pre class="literal-block">
+generic configuration SimpleFcfsArbiterC(char resourceName[]) {
+ provides {
+ interface Resource[uint8_t id];
+ interface ResourceRequested[uint8_t id];
+ interface ArbiterInfo;
+ }
+ uses interface ResourceConfigure[uint8_t id];
+}
+implementation {
+ components MainC;
+ components new FcfsResourceQueueC(uniqueCount(resourceName)) as Queue;
+ components new SimpleArbiterP() as Arbiter;
+
+ MainC.SoftwareInit -> Queue;
+
+ Resource = Arbiter;
+ ResourceRequested = Arbiter;
+ ArbiterInfo = Arbiter;
+ ResourceConfigure = Arbiter;
+
+ Arbiter.Queue -> Queue;
+}
+</pre>
+<p>This generic configuration can instantiated by a resource in order
+to grant requests made by its clients in an FCFS fashion.</p>
+<p>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:</p>
+<blockquote>
+<p>Queuing Policies:
+- FcfsResourceQueueC
+- RoundRobinResourceQueueC</p>
+<p>Arbiters:
+- SimpleFcfsArbiterC
+- FcfsArbiterC
+- SimpleRoundRobinArbiterC
+- RoundRobinArbiterC</p>
+</blockquote>
</div>
<div class="section">
-<h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
+<h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
<div class="line-block">
<div class="line">Kevin Klues</div>
<div class="line">503 Bryan Hall</div>
<div class="line">phone - +1 510 643 7572</div>
<div class="line">email - <a class="reference" href="mailto:culler@cs.berkeley.edu">culler@cs.berkeley.edu</a></div>
<div class="line"><br /></div>
-<div class="line"><br /></div>
<div class="line">Vlado Handziski</div>
<div class="line">Sekr FT5</div>
<div class="line">Einsteinufer 25</div>
</div>
</div>
<div class="section">
-<h1><a id="citations" name="citations">6. Citations</a></h1>
-<table class="docutils footnote" frame="void" id="id7" rules="none">
+<h1><a id="citations" name="citations">7. Citations</a></h1>
+<table class="docutils footnote" frame="void" id="id4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<tr><td class="label"><a class="fn-backref" href="#id2" name="id7">[1]</a></td><td>TEP 2: Hardware Abstraction Architecture.</td></tr>
+<tr><td class="label"><a class="fn-backref" href="#id1" name="id4">[1]</a></td><td>TEP 2: Hardware Abstraction Architecture.</td></tr>
</tbody>
</table>
-<table class="docutils footnote" frame="void" id="id8" rules="none">
+<table class="docutils footnote" frame="void" id="id5" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id10" name="id5">[2]</a></td><td>TEP 102: Timers.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id6" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<tr><td class="label"><a name="id8">[2]</a></td><td><em>(<a class="fn-backref" href="#id3">1</a>, <a class="fn-backref" href="#id5">2</a>)</em> TEP 102: Timers.</td></tr>
+<tr><td class="label"><a class="fn-backref" href="#id2" name="id6">[3]</a></td><td>Service Instance Pattern. In <em>Software Design Patterns for TinyOS.</em> David Gay, Philip Levis, and David Culler. Published in Proceedings of the ACM SIGPLAN/SIGBED 2005 Conference on Languages, Compilers, and Tools for Embedded Systems (LCTES'05).</td></tr>
</tbody>
</table>
-<table class="docutils footnote" frame="void" id="id9" rules="none">
+<table class="docutils footnote" frame="void" id="id7" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id3" name="id7">[4]</a></td><td>TEP 115: Power Management of Non-Virtualized Devices.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id8" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<tr><td class="label"><a name="id9">[3]</a></td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id4">2</a>, <a class="fn-backref" href="#id6">3</a>)</em> Service Instance Pattern. In <em>Software Design Patterns for TinyOS.</em> David Gay, Philip Levis, and David Culler. Published in Proceedings of the ACM SIGPLAN/SIGBED 2005 Conference on Languages, Compilers, and Tools for Embedded Systems (LCTES'05).</td></tr>
+<tr><td class="label"><a class="fn-backref" href="#id9" name="id8">[5]</a></td><td>TinyOS Programming. <a class="reference" href="http://csl.stanford.edu/~pal/pubs/tinyos-programming-1-0.pdf">http://csl.stanford.edu/~pal/pubs/tinyos-programming-1-0.pdf</a></td></tr>
</tbody>
</table>
</div>
+<div class="section">
+<h1><a id="appendix-a-resource-class-examples" name="appendix-a-resource-class-examples">Appendix A: Resource Class Examples</a></h1>
+<div class="section">
+<h2><a id="dedicated-resource" name="dedicated-resource">Dedicated Resource</a></h2>
+<p>Timer 2 on the Atmega128 microprocessor is a dedicated resource
+represented by the HplAtm128Timer2C component:</p>
+<pre class="literal-block">
+module HplAtm128Timer2C {
+ provides {
+ interface HplTimer<uint8_t> as Timer2 @exactlyonce();
+ interface HplTimerCtrl8 as Timer2Ctrl @exactlyonce();
+ interface HplCompare<uint8_t> as Compare2 @exactlyonce();
+ }
+}
+</pre>
+<p>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
+TinyOS Programming Manual <a class="footnote-reference" href="#id8" id="id9" name="id9">[5]</a>.</p>
+</div>
+<div class="section">
+<h2><a id="virtualized-resource" name="virtualized-resource">Virtualized Resource</a></h2>
+<p>The TimerMilliC component provides a virtual abstraction of millisecond
+precision timers to application components <a class="footnote-reference" href="#id5" id="id10" name="id10">[2]</a>. 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.:</p>
+<pre class="literal-block">
+generic configuration TimerMilliC {
+ provides interface Timer<TMilli>;
+}
+implementation {
+ components TimerMilliP;
+ Timer = TimerMilliP.TimerMilli[unique(UQ_TIMER_MILLI)];
+}
+</pre>
+<p>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:</p>
+<pre class="literal-block">
+configuration TimerMilliP {
+ provides interface Timer<TMilli> as TimerMilli[uint8_t num];
+}
+implementation {
+ components HilTimerMilliC, MainC;
+ MainC.SoftwareInit -> HilTimerMilliC;
+ TimerMilli = HilTimerMilliC;
+}
+</pre>
+</div>
+</div>
+<div class="section">
+<h1><a id="appendix-b-arbiter-interface-examples" name="appendix-b-arbiter-interface-examples">Appendix B: Arbiter Interface Examples</a></h1>
+<!-- Note:
+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. -->
+<div class="section">
+<h2><a id="id11" name="id11">Resource</a></h2>
+<p>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.</p>
+<p>A specific example of where the Resource.isOwner() is used
+can be seen in the HplTda5250DataP component of the Infineon
+Tda5250 radio implementation:</p>
+<pre class="literal-block">
+async command error_t HplTda5250Data.tx(uint8_t data) {
+ if(call UartResource.isOwner() == FALSE)
+ return FAIL;
+ call Usart.tx(data);
+ return SUCCESS;
+}
+</pre>
+<p>A call to the HplTda5250Data.tx command will fail if the radio does
+not currently have control of the underlying Usart resource. If it
+does, then the Usart.tx(data) command is called as requested.</p>
+<p>A component using the Resource interface to implement an I2C
+service might look like this:</p>
+<pre class="literal-block">
+#include I2CPacket.h
+configuration I2CPacketP {
+ provides interface Resource[uint8_t client];
+ provides interface I2CPacket<I2CAddrSize>[uint8_t client];
+}
+implementation {
+ components new FcfsArbiterC(I2CPACKET_RESOURCE) as Arbiter;
+ components I2CPacketImplP() as I2C;
+ ...
+
+ Resource = Arbiter;
+ I2CPacket = I2C;
+ ...
+}
+</pre>
+<p>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:</p>
+<pre class="literal-block">
+#ifndef I2CPACKETC_H
+#define I2CPACKETC_H
+#define I2CPACKET_RESOURCE "I2CPacket.Resource"
+#endif
+</pre>
+<p>This service would then be made available to a user through
+the generic configuration seen below:</p>
+<pre class="literal-block">
+#include I2CPacket.h
+generic configuration I2CPacketC {
+ provides interface Resource;
+ provides interface I2CPacket<I2CAddrSize>;
+}
+implementation {
+ enum { CLIENT_ID = unique(I2CPACKET_RESOURCE) };
+
+ components I2CPacketP as I2C;
+ Resource = I2C.Resource[CLIENT_ID];
+ I2CPacket = I2C.I2CPacket[CLIENT_ID];
+}
+</pre>
+<p>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
+for use by a client.</p>
+<p>Clients of the I2C service would use it as follows:</p>
+<pre class="literal-block">
+module I2CClientP {
+ uses interface Resource as I2CResource;
+ uses interface I2CPacket<I2CAddrSize>;
+} ...
+
+configuration I2CClientC { }
+implementation {
+ components I2CClientP, new I2CPacketC();
+
+ I2CClientP.I2CResource -> I2CPacketC.Resource;
+ I2CUserM.I2CPacket -> I2CPacket.I2CPacket;
+}
+</pre>
+</div>
+<div class="section">
+<h2><a id="id12" name="id12">ArbiterInfo</a></h2>
+<p>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:</p>
+<pre class="literal-block">
+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,
+ ...
+
+ Resource = Arbiter;
+ SingleChannel = Msp430Adc12P.SingleChannel;
+ FastSingleChannel = Msp430Adc12P.FastSingleChannel;
+
+ Msp430Adc12P.Init <- MainC;
+ Msp430Adc12P.ADCArbiterInfo -> Arbiter;
+ ...
+}
+</pre>
+<p>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
+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
+use it:</p>
+<pre class="literal-block">
+async command error_t Msp430Adc12SingleChannel.getSingleData[uint8_t id]() {
+ if (call ADCArbiterInfo.userId() == id){
+ configureChannel()
+ // Start getting data
+ }
+ else return ERESERVE;
+}
+
+async command error_t Msp430Adc12FastSingleChannel.configure[uint8_t id]() {
+ if (call ADCArbiterInfo.userId() == id){
+ clientID = id
+ configureChannel()
+ }
+ else return ERESERVE;
+}
+
+async command error_t Msp430Adc12FastSingleChannel.getSingleData[uint8_t id]()
+{
+ if (clientID = id)
+ // Start getting data
+ else return ERESERVE;
+}
+</pre>
+<p>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:</p>
+<pre class="literal-block">
+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];
+}
+</pre>
+<pre class="literal-block">
+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];
+}
+</pre>
+<p>Since these are generic components, users 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.</p>
+<p>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.</p>
+</div>
+<div class="section">
+<h2><a id="id13" name="id13">ResourceRequested</a></h2>
+<p>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
+the Usart, with the radio regaining control soon thereafter.</p>
+<p>In the CsmaMacP implementation of the Tda5250 radio we see the ResourceRequested
+event being implemented:</p>
+<pre class="literal-block">
+async event void ResourceRequested.requested() {
+ atomic {
+ /* This gives other devices the chance to get the Resource
+ because RxMode implies a new arbitration round. */
+ if (macState == RX) call Tda5250Control.RxMode()();
+ }
+}
+</pre>
+<p>Through several levels of wiring, the Tda5250 interface is provided to this
+component by the Tda5250RadioP component:</p>
+<pre class="literal-block">
+module Tda5250RadioP {
+ provides interface Tda5250Control;
+ uses interface Resource as UsartResource;
+ ...
+}
+implementation {
+ async command error_t Tda5250Control.RxMode() {
+ if(radioBusy() == FALSE)
+ call UsartResource.release();
+ call UsartResource.request();
+ }
+ event void UsartResource.granted() {
+ // Finish setting to RX Mode
+ }
+ ...
+}
+</pre>
+<p>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.</p>
+<p>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.</p>
+</div>
+<div class="section">
+<h2><a id="resource-configure" name="resource-configure">Resource Configure</a></h2>
+<p>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
+SPI.</p>
+<p>A component providing the SPI service on top of the shared Usart component looks
+like this:</p>
+<pre class="literal-block">
+generic configuration Msp430Spi0C() {
+ provides interface Resource;
+ provides interface SpiByte;
+ provides interface SpiPacket;
+ ...
+}
+implementation {
+ enum { CLIENT_ID = unique( MSP430_SPIO_BUS ) };
+
+ components Msp430SpiNoDma0P as SpiP;
+ components new Msp430Usart0C() as UsartC;
+ SpiP.ResourceConfigure[ CLIENT_ID ] <- UsartC.ResourceConfigure;
+ SpiP.UsartResource[ CLIENT_ID ] -> UsartC.Resource;
+ SpiP.UsartInterrupts -> UsartC.HplMsp430UsartInterrupts;
+ ...
+}
+</pre>
+<p>And one providing the I2C service looks like this:</p>
+<pre class="literal-block">
+generic configuration Msp430I2CC() {
+ provides interface Resource;
+ provides interface I2CPacket<TI2CBasicAddr> as I2CBasicAddr;
+ ...
+}
+implementation {
+ enum { CLIENT_ID = unique( MSP430_I2CO_BUS ) };
+
+ components Msp430I2C0P as I2CP;
+ components new Msp430Usart0C() as UsartC;
+ I2CP.ResourceConfigure[ CLIENT_ID ] <- UsartC.ResourceConfigure;
+ I2CP.UsartResource[ CLIENT_ID ] -> UsartC.Resource;
+ I2CP.I2CInterrupts -> UsartC.HplMsp430UsartInterrupts;
+ ...
+}
+</pre>
+<p>The implementation of the ResourceConfigure interface is
+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
+still provide the same functionality.</p>
+<p>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.</p>
+</div>
+</div>
</div>
</body>
</html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
-<title>Sensor Boards</title>
-<meta name="author" content="David Gay, Phil Levis, Wei Hong, and Joe Polastre" />
+<title>Sensors and Sensor Boards</title>
+<meta name="author" content="David Gay, Phil Levis, Wei Hong, Joe Polastre, and Gilman Tolle" />
<style type="text/css">
/*
</style>
</head>
<body>
-<div class="document" id="sensor-boards">
-<h1 class="title">Sensor Boards</h1>
+<div class="document" id="sensors-and-sensor-boards">
+<h1 class="title">Sensors and Sensor Boards</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">2.x</td>
</tr>
<tr><th class="docinfo-name">Author:</th>
-<td>David Gay, Phil Levis, Wei Hong, and Joe Polastre</td></tr>
-<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">19-Apr-2005</td>
-</tr>
-<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1.2.1</td>
-</tr>
-<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2005-10-31</td>
+<td>David Gay, Phil Levis, Wei Hong, Joe Polastre, and Gilman Tolle</td></tr>
+<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">10-Jun-2006</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
</tr>
</div>
<div class="section">
<h1><a id="abstract" name="abstract">Abstract</a></h1>
-<p>This memo documents how sensor boards are organized in TinyOS, and the
-general principles followed by the components that provide access to
-its sensors.</p>
+<p>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.</p>
</div>
<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
-<p>This document defines the default organization of a sensor board in
-TinyOS. There likely will be sensor boards that cannot conform
-to this specification, but following as closely to its spirit as possible
-will simplify generic applications that use a range of sensor boards.</p>
-<p>This document assumes that sensors return uninterpreted 16-bit values, and,
-optionally uninterpreted, arbitrary-size calibration data. Conversion of
-sensor values to something with actual physical meaning is beyond the
-scope of this document.</p>
-</div>
-<div class="section">
-<h1><a id="directory-organization" name="directory-organization">2. Directory Organization</a></h1>
+<h1><a id="principles" name="principles">1. Principles</a></h1>
+<p>This section describes the basic organization principles for sensor
+drivers in TinyOS.</p>
+<p>For background, a sensor may be attached to the microcontroller on a
+TinyOS platform through a few different types of connections:</p>
+<blockquote>
<ul class="simple">
-<li>A sensor board MUST have a unique name, composed of letters, numbers
-and underscores. Case is significant, but two sensor boards MUST
-differ in more than case. This is necessary to support platforms where
-filename case differences are not significant. We will use SBOARD to
-denote the sensor board name in the rest of this document.</li>
-<li>Each sensor board MUST have its own directory named SBOARD; default TinyOS
-sensor boards are placed in tinyos-2.x/tos/sensorboards, but
-sensor board directories can be placed anywhere as long as the nesC compiler
-receives a <cite>-I</cite> directive pointing to the sensor board's directory.</li>
-<li>Each sensor board directory MUST contain a <cite>.sensor</cite> file. This file
-is a perl script which contains any additional compiler settings needed for
-this sensor board (this file will be empty in many cases).</li>
-<li>If the sensor board wishes to define any C types or constants, it SHOULD
-place these in a file named SBOARD.h in the sensor board's directory.</li>
-<li>The sensor board directory SHOULD contain sensor board components
-for accessing each sensor on the sensor board. The conventions for these
-components are detailed in Section 3.</li>
-<li>A sensor board MAY include additional components providing alternative or
-higher-level interfaces to the sensors (e.g., for TinyDB). These components
-are beyond the scope of this document.</li>
-<li>Finally, the sensor board MAY contain any number of components,
-interfaces, C files, etc for internal use. To avoid name collisions, all
-externally visible names (interface types, components, C constants and
-types) used for internal purposes SHOULD be prefixed with SBOARD. All such
-components should end in P.</li>
+<li>Included within the microcontroller itself</li>
+<li>Connected to general-purpose IO pins for level/edge detection</li>
+<li>Connected to an ADC in the microcontroller for voltage sampling</li>
+<li>Connected to general-purpose IO pins for digital communication</li>
+<li>Connected through a standard digital bus protocol (1-Wire, I2C, SPI)</li>
</ul>
-<p>A simple example: the basic sensor board is named <cite>basicsb</cite>, it's directory
-is <cite>tinyos-2.x/tos/sensorboards/basicsb</cite>. It has no <cite>basicsb.h</cite> file and
-its <cite>.sensor</cite> file is empty. It has two components, <cite>PhotoC</cite> and <cite>TempC</cite>
-representing its light and temperature sensors.</p>
+</blockquote>
+<p>Physically, these connections may also be decoupled by attaching the
+sensors to a <cite>sensor board</cite>, which can be removed from the TinyOS
+platform, and may fit multiple different TinyOS platforms.</p>
+<p>The capabilities of a physical sensor are made available to a TinyOS
+application through a <cite>sensor driver</cite>.</p>
+<p>According to the HAA <a class="citation-reference" href="#tep2" id="id1" name="id1">[TEP2]</a>, TinyOS devices should provide both
+simple hardware-independent interfaces for common-case use (HIL) and
+rich hardware-dependent interfaces for special-case use (HAL). Sensor
+drivers should follow this spirit as well.</p>
+<p>TinyOS 2.x represents each sensor as an individual component. This
+allows the compilation process to minimize the amount of code
+included. A sensor board containing multiple sensors should be
+represented as a collection of components, one for each sensor,
+contained within a sensor board directory.</p>
+<p>Sensors, being physical devices that may be shared, can benefit from
+virtualization and arbitration. This document describes a design
+pattern for sensor virtualization that may be followed by sensor
+drivers.</p>
+<p>The same physical sensor may be attached to multiple different TinyOS
+platforms, through platform-dependent interconnections. The common
+logic of sensor driver should be factored into chip-dependent,
+platform-independent components, and those components should be bound
+to the hardware resources on a platform by platform-dependent
+components, and to the hardware resources on a sensor board by
+sensorboard-dependent components.</p>
+<p>A physical sensor has a general class and a specific set of
+performance characteristics, captured by the make and model of the
+sensor itself. The naming of the sensor driver components should
+reflect the specifc name of the sensor, and optionally provide a
+component with a generic name for application authors who only care
+about the general class of the sensor.</p>
+<p>This document assumes that sensors return uninterpreted values of
+arbitrary size or datatype. Conversion of sensor values to something
+with actual physical meaning is beyond the scope of this document.</p>
</div>
<div class="section">
-<h1><a id="sensor-board-components" name="sensor-board-components">3. Sensor Board Components</a></h1>
-<p>We have not yet selected any naming conventions for sensor board
-components. Please select reasonable namesldots</p>
-<p>A sensor board component MUST provide:</p>
+<h1><a id="sensor-hil-components" name="sensor-hil-components">2. Sensor HIL Components</a></h1>
+<p>A sensor HIL component MUST provide:</p>
<ul class="simple">
-<li>An <cite>Init</cite> interface.</li>
-<li>A <cite>StdControl</cite> or <cite>SplitControl</cite> interface for power management.</li>
-<li>A non-empty set of <cite>AcquireData</cite> interfaces for sampling.</li>
+<li>One or more SID interfaces <a class="citation-reference" href="#tep114" id="id2" name="id2">[TEP114]</a>, for reading data.</li>
</ul>
-<p>A sensor board component MAY provide:</p>
+<p>A sensor HIL component MAY provide:</p>
<ul class="simple">
-<li>Some <cite>CalibrationData</cite> interfaces for obtaining calibration data.
-A calibration interface for a sensor accessed via interface X should
-be called XCalibration.</li>
-<li>Some <cite>AcquireDataNow</cite> and <cite>AcquireDataBuffered</cite> interfaces, for high-speed
-or low-latency data acquisition.</li>
-<li>Any other appropriate interface.</li>
+<li>One or more SID interfaces <a class="citation-reference" href="#tep114" id="id3" name="id3">[TEP114]</a>, for reading or
+writing calibration coefficients or control registers.</li>
</ul>
-<p>The <cite>CalibrationData</cite> interface is shown below, while <cite>AcquireData</cite>,
-<cite>AcquireDataNow</cite> and <cite>AcquireDataBuffered</cite> are in TEP 101. The
-<cite>AcquireData</cite> interface returns uinterpreted 16-bit data. This might
-represent an A/D conversion result, a counter, etc. The optional
-calibration interface returns uninterpreted, arbitrary-size data.</p>
-<p>A sensor board component SHOULD be as lightweight as possible - it should
-just provide basic access to the physical sensors and SHOULD NOT attempt to do
-calibration, signal processing, etc. If such functionality is desired, it
-SHOULD be provided in separate components.</p>
-<div class="line-block">
-<div class="line-block">
-<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">CalibrationData</span> <span class="pre">{</span></tt></div>
-<div class="line-block">
-<div class="line-block">
-<div class="line"><tt class="docutils literal"><span class="pre">/*</span> <span class="pre">Collect</span> <span class="pre">uninterpreted</span> <span class="pre">calibration</span> <span class="pre">data</span> <span class="pre">from</span> <span class="pre">a</span> <span class="pre">sensor</span> <span class="pre">*/</span></tt></div>
-<div class="line"><br /></div>
-<div class="line"><tt class="docutils literal"><span class="pre">/**</span> <span class="pre">Request</span> <span class="pre">calibration</span> <span class="pre">data</span></tt></div>
-<div class="line-block">
-<div class="line"><tt class="docutils literal"><span class="pre">*</span> <span class="pre">@return</span> <span class="pre">SUCCESS</span> <span class="pre">if</span> <span class="pre">request</span> <span class="pre">accepted,</span> <span class="pre">FAIL</span> <span class="pre">if</span> <span class="pre">it</span> <span class="pre">is</span> <span class="pre">refused</span></tt></div>
-<div class="line"><tt class="docutils literal"><span class="pre">*</span> <span class="pre">data</span> <span class="pre">error</span> <span class="pre">will</span> <span class="pre">be</span> <span class="pre">signaled</span> <span class="pre">if</span> <span class="pre">SUCCESS</span> <span class="pre">is</span> <span class="pre">returned</span></tt></div>
-<div class="line"><tt class="docutils literal"><span class="pre">*/</span></tt></div>
-</div>
-<div class="line"><tt class="docutils literal"><span class="pre">command</span> <span class="pre">result_t</span> <span class="pre">get();</span></tt></div>
-<div class="line"><br /></div>
-</div>
-<div class="line"><tt class="docutils literal"><span class="pre">/**</span> <span class="pre">Returns</span> <span class="pre">calibration</span> <span class="pre">data</span></tt></div>
-<div class="line-block">
-<div class="line"><tt class="docutils literal"><span class="pre">*</span> <span class="pre">@param</span> <span class="pre">x</span> <span class="pre">Pointer</span> <span class="pre">to</span> <span class="pre">(uinterpreted)</span> <span class="pre">calibration</span> <span class="pre">data.</span> <span class="pre">This</span> <span class="pre">data</span></tt></div>
-<div class="line"><tt class="docutils literal"><span class="pre">*</span> <span class="pre">must</span> <span class="pre">not</span> <span class="pre">be</span> <span class="pre">modified.</span></tt></div>
-<div class="line"><tt class="docutils literal"><span class="pre">*</span> <span class="pre">@param</span> <span class="pre">len</span> <span class="pre">Length</span> <span class="pre">of</span> <span class="pre">calibration</span> <span class="pre">data</span></tt></div>
-<div class="line"><tt class="docutils literal"><span class="pre">*</span> <span class="pre">@return</span> <span class="pre">Ignored.</span></tt></div>
-<div class="line"><tt class="docutils literal"><span class="pre">*/</span></tt></div>
-</div>
-<div class="line"><tt class="docutils literal"><span class="pre">event</span> <span class="pre">result_t</span> <span class="pre">data(const</span> <span class="pre">void</span> <span class="pre">*x,</span> <span class="pre">uint8_t</span> <span class="pre">len);</span></tt></div>
-</div>
-</div>
-<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
+<p>A sensor device driver SHOULD be a generic component that virtualizes
+access to the sensor. A sensor device driver can provide such
+virtualization for itself by defining a nesC generic client
+component. When a client component is being used, a call to a
+top-level SID interface should be delayed when the device is busy,
+rather than failing. This virtualization may be easier to accomplish
+by using one of the arbiters provided by the system.</p>
+<p>For example:</p>
+<pre class="literal-block">
+generic configuration SensirionSht11C() {
+ provides interface Read<uint16_t> as Temperature;
+ provides interface ReadStream<uint16_t> as TemperatureStream;
+ provides interface Read<uint16_t> as Humidity;
+ provides interface ReadStream<uint16_t> as HumidityStream;
+}
+implementation {
+ // connect to the ADC HIL, GPIO HAL, or sensor's HAL
+}
+</pre>
+<p>When a HIL component is being used, the sensor MUST initialize itself,
+either by including the <cite>MainC</cite> component and wiring to the
+<cite>SoftwareInit</cite> interface, or by allowing a lower-level component (like
+an ADC) to initialize itself.</p>
+<p>In addition, the HIL sensor driver MUST start the physical sensor
+automatically. For sensors without a constant power draw, the sensor
+MAY be started once at boot time by wiring to the <cite>MainC.Boot</cite>
+interface. Sensors that draw appreciable power MUST be started in
+response to a call to one of the top-level SID interfaces, and stopped
+some time after that call completes. One of the power-management
+components described in <a class="citation-reference" href="#tep115" id="id4" name="id4">[TEP115]</a> may be useful for this purpose.</p>
+<p>Generally, simple types are made up of octets. However, sensor values
+often have levels of precision besides a multiple of 8. A device MAY
+specify the precision of one of its interfaces with the DeviceMetadata
+interface:</p>
+<pre class="literal-block">
+interface DeviceMetadata {
+ command uint8_t getSignificantBits();
+}
+</pre>
+<p>The name of the instance of DeviceMetadata SHOULD clearly indicate
+which interface it corresponds to.</p>
+<p>A value contained returned from the device through a SID interface
+MAY be left shifted so that it covers as much of the type's range as
+possible. For example, if a 12-bit ADC reading is presented as a
+16-bit Read interface:</p>
+<pre class="literal-block">
+component DemoSensorC {
+ provides interface Read<uint16_t>;
+}
+</pre>
+<p>then the driver MAY shift the 12-bit value left so that its range is
+0x0000 - 0xfff0, rather than 0x0000 - 0x0fff.</p>
+<p>Sensor driver components SHOULD be named according to the make and
+model of the sensing device being presented. Using specific names
+gives the developer the option to bind to a particular sensor, which
+provides compile-time detection of missing sensors. However, wrapper
+components using "common" names MAY also be provided by the driver
+author, to support application developers who are only concerned with
+the particular type of the sensor and not its make, model, or detailed
+performance characteristics.</p>
+<p>A "common" naming layer atop a HIL may look like this:</p>
+<pre class="literal-block">
+generic configuration TemperatureC() {
+ provides interface Read<uint16_t>;
+ provides interface ReadStream<uint16_t>;
+}
+implementation {
+ components new SensirionSht11C();
+ Read = SensirionSht11C.Temperature;
+ ReadStream = SensirionSht11C.TemperatureStream;
+}
+
+generic configuration HumidityC() {
+ provides interface Read<uint16_t>;
+ provides interface ReadStream<uint16_t>;
+}
+implementation {
+ components new SensirionSht11C();
+ Read = SensirionSht11C.Humidity;
+ ReadStream = SensirionSht11C.HumidityStream;
+}
+</pre>
</div>
-<p>Some common setups for sensor board components are:</p>
+<div class="section">
+<h1><a id="sensor-hal-components" name="sensor-hal-components">3. Sensor HAL Components</a></h1>
+<p>Sensors with a richer interface than would be supported by the SID
+interfaces MAY provide a HAL component in addition to a HIL
+component.</p>
+<p>A sensor HAL component MUST provide:</p>
<ul class="simple">
-<li>A single <cite>AcquireData</cite> interface. This is probably the most common case,
-where a single component corresponds to a single physical sensor, e.g., for
-light, temperature, pressure and there is no expectation of high sample
-rates.</li>
-<li>Multiple <cite>AcquireData</cite> interfaces. Some sensors might be strongly
-related, e.g., the axes of an accelerometer. A single component could then
-provide a sensor interface for each axis. For instance, a 2-axis
-accelerometer which can be sampled at high speed, and which has some
-calibration data might be declared with:</li>
+<li>A SID-based interface or a specific hardware-dependent interface
+with commands for sampling and controlling the sensor device.</li>
</ul>
-<div class="line-block">
-<div class="line"><tt class="docutils literal"><span class="pre">configuration</span> <span class="pre">Accelerometer2D</span> <span class="pre">{</span></tt></div>
-<div class="line-block">
-<div class="line"><tt class="docutils literal"><span class="pre">provides</span> <span class="pre">{</span></tt></div>
-<div class="line-block">
-<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">StdControl</span></tt></div>
-<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">AcquireData</span> <span class="pre">as</span> <span class="pre">AccelX;</span></tt></div>
-<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">AcquireDataNow</span> <span class="pre">as</span> <span class="pre">AccelXSingle;</span></tt></div>
-<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">AcquireDataBuffered</span> <span class="pre">as</span> <span class="pre">AccelXMultiple;</span></tt></div>
-<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">CalibrationData</span> <span class="pre">as</span> <span class="pre">AccelXCalibration;</span></tt></div>
-<div class="line"><br /></div>
-<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">AcquireData</span> <span class="pre">as</span> <span class="pre">AccelY;</span></tt></div>
-<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">AcquireDataNow</span> <span class="pre">as</span> <span class="pre">AccelYSingle;</span></tt></div>
-<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">AcquireDataBuffered</span> <span class="pre">as</span> <span class="pre">AccelYMultiple;</span></tt></div>
-<div class="line"><tt class="docutils literal"><span class="pre">interface</span> <span class="pre">CalibrationData</span> <span class="pre">as</span> <span class="pre">AccelYCalibration;</span></tt></div>
-</div>
-<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
-</div>
-<div class="line"><tt class="docutils literal"><span class="pre">}</span></tt></div>
-</div>
+<p>A sensor HAL component MAY need to provide:</p>
<ul class="simple">
-<li>A parameterised <cite>AcquireData</cite> interface. If a sensor board has multiple
-similar sensors, it may make sense to provide a single component to access
-all of these, using a parameterised <cite>AcquireData</cite> interface. For instance,
-a general purpose sensor board with multiple A/D channels might provide an
-<cite>AcquireData</cite> interface parameterised by the A/D channel id.</li>
-<li>In all of these examples, if high-speed sampling makes sensor for the
-sensor (e.g., a microphone), and the sensor is connected in a way that
-supports high-frequency and/or low-latency access (e.g., via an
-on-microcontroller A/D converter), the component should offer
-<cite>AcquireDataNow</cite> and <cite>AcquireDataBuffered</cite> interfaces.</li>
+<li>A <cite>StdControl</cite> or <cite>SplitControl</cite> interface for manual power
+management by the user, following the conventions described in
+<a class="citation-reference" href="#tep115" id="id5" name="id5">[TEP115]</a>.</li>
+<li>A Resource[] interface for requesting access to the device and
+possibly performing automated power management.</li>
+<li>Any other interfaces needed to control the device.</li>
</ul>
-<p>Sensor board components MUST respect the following conventions
-on the use of the <cite>Init</cite>, <cite>StdControl</cite>, and <cite>SplitControl</cite>
-interfaces. These are given assuming <cite>StdControl</cite> is used, but the
-behaviour with <cite>SplitControl</cite> is identical except that <cite>start</cite> and <cite>stop</cite>
-are not considered complete until the <cite>startDone</cite> and <cite>stopDone</cite> events are
-signaled. The conventions are:</p>
-<ol class="arabic">
-<li><p class="first"><cite>Init.init</cite>: must be called at mote boot time.</p>
-</li>
-<li><dl class="first docutils">
-<dt><cite>StdControl.start</cite>: ensure the sensor corresponding to this component is</dt>
-<dd><p class="first">ready for use. For instance, this should power-up the sensor if
-necessary. The application can call <cite>getData</cite> once <cite>StdControl.start</cite>
-completes.</p>
-<p class="last">If a sensor takes a while to power-up, the sensor board implementer can
-either use a <cite>SplitControl</cite> interface and signal <cite>startDone</cite>
-when the sensor is ready for use, or delay <cite>dataReady</cite> events
-until the sensor is ready. The former choice is preferable.</p>
-</dd>
-</dl>
-</li>
-<li><p class="first"><cite>StdControl.stop</cite>: put the sensor in a low-power mode.
-<cite>StdControl.start</cite> must be called before any further readings
-are taken. The behaviour of calls to <cite>StdControl.stop</cite> during
-sampling (i.e., when an <cite>dataReady</cite> event is going to be
-signaled) is undefined.</p>
-</li>
-</ol>
+<p>For example:</p>
+<pre class="literal-block">
+configuration SensirionSht11DeviceC {
+ provides interface Resource[ uint8_t client ];
+ provides interface SensirionSht11[ uint8_t client ];
+}
+implementation {
+ // connect to the sensor's platform-dependent HPL here
+}
+</pre>
+</div>
+<div class="section">
+<h1><a id="sensor-hpl-components" name="sensor-hpl-components">4. Sensor HPL Components</a></h1>
+<p>A sensor HPL is necessarily platform-dependent or
+sensorboard-dependent. These components should provide access to the
+physical resources needed by the sensor, in a platform-independent
+manner that can be used by the shared logic of the sensor HAL
+components. In the case of bus-based sensors, this HPL may be nothing
+more than wiring to the appropriate bus interface for use by the HAL
+component.</p>
+<p>For example:</p>
+<pre class="literal-block">
+configuration HplSensirionSht11C {
+ provides interface Init;
+ provides interface Resource[ uint8_t id ];
+ provides interface GeneralIO as DATA;
+ provides interface GeneralIO as SCK;
+ provides interface GpioInterrupt as InterruptDATA;
+}
+implementation {
+ // connect to platform or sensorboard-dependent resources
+ // power-manage the sensor through platform-specific means
+}
+</pre>
</div>
<div class="section">
-<h1><a id="sensor-file" name="sensor-file"><cite>.sensor</cite> File</a></h1>
-<p>This file is a perl script which gets executed as part of the <cite>ncc</cite>
-nesC compiler frontend. It can add or modify any compile-time options
-necessary for a particular sensor board. It MAY modify the following perl
-variables, and MUST NOT modify any others:</p>
+<h1><a id="directory-organization-guidelines" name="directory-organization-guidelines">5. Directory Organization Guidelines</a></h1>
+<p>Because the same physical sensor may be attached to TinyOS platforms
+in many different ways, the organization of sensor drivers should
+reflect the distinction between sensor and sensor interconnect.</p>
+<p>Sensor components commonly exist at three levels:
+platform-independent, sensorboard-dependent, and
+platform-dependent. Factoring a sensor driver into these three pieces
+allows for greater code reuse when the same sensor is attached to
+different sensorboards or platforms.</p>
+<p>Platform-independent sensor driver components for a particular sensor,
+like protocol logic, when in the core TinyOS 2.x source tree, SHOULD
+be placed into "tos/chips/<sensor>", where <sensor> reflects the make
+and model of the sensor device being supported. When not a part of the
+core source tree, this directory can be placed anywhere as long as the
+nesC compiler recieves a <cite>-I</cite> directive pointing to the sensor's
+directory. However, not all sensors have a sufficiently large amount
+of platform-independent logic to justify a separate "chips"
+directory. Sensor chips are more likely to be digital sensors than
+analog sensors, for example.</p>
+<p>A sensor board is a collection of sensor components with a fixed name,
+intended for attachment to multiple platforms. Each sensor board MUST
+have its own directory named <sensorboard>. Default TinyOS 2.x sensor
+boards are placed in "tos/sensorboards/<sensorboard>", but sensor
+board directories can be placed anywhere as long as the nesC compiler
+receives a <cite>-I</cite> directive pointing to the sensor board's directory.</p>
+<p>Both sensors and sensor boards MUST have unique names. Case is
+significant, but two sensor boards MUST differ in more than case. This
+is necessary to support platforms where filename case differences are
+not significant.</p>
+<p>Each sensor board directory MUST contain a <cite>.sensor</cite> file. This file
+is a perl script which gets executed as part of the <cite>ncc</cite> nesC
+compiler frontend. It can add or modify any compile-time options
+necessary for a particular sensor board. It MAY modify the following
+perl variables, and MUST NOT modify any others:</p>
<ul class="simple">
-<li>@new_args: This is the array of arguments which will be
-passed to nescc. For instance, you might add an include directive
-to @new_args with push @new_args, <cite>-Isomedir</cite></li>
+<li>@new_args: This is the array of arguments which will be passed to
+nescc. For instance, you might add an include directive to @new_args
+with push @new_args, <cite>-Isomedir</cite>. This could be used to include
+subdirectories.</li>
<li>@commonboards: This can be set to a list of sensor board names which
should be added to the include path list. These sensor boards must be
in tinyos-2.x/tos/sensorboards.</li>
</ul>
+<p>If the sensor board wishes to define any C types or constants, it
+SHOULD place these in a file named <sensorboard>.h in the sensor
+board's directory.</p>
+<p>A sensor board directory MAY contain a "chips" directory, with
+subdirectories for each of the sensors connected to the sensor board.
+If a "chips" subdirectory is used, sensorboard-dependent driver
+components needed to connect platform-independent logic to a
+particular attachment for that sensor should be placed in
+"<sensorboard>/chips/<sensor>".</p>
+<p>Components needed to connect the platform-independent sensor driver
+components or sensorboard-dependent components to the hardware
+resources available on a particular platform SHOULD be placed in
+"tos/<platform>/chips/<sensor>". In addition, components for a sensor
+that only exists on a particular platform should be placed in a such a
+directory.</p>
+<p>Sensors that exist as part of a larger chip, like a MCU internal
+voltage sensor, SHOULD be placed in a subdirectory of the chip's
+directory. "tos/<chip>/sensors/<sensor>".</p>
+<p>The <cite>.platform</cite> and <cite>.sensor</cite> files need to include enough <cite>-I</cite>
+directives to locate all of the necessary components needed to support
+the sensors on a platform and/or sensorboard.</p>
+<p>All of these directory organization guidelines are only intended for
+code that will enter the core source tree. In general, sensor
+components may be placed anywhere as long as the nesC compiler
+receives enough <cite>-I</cite> directives to locate all of the necessary pieces.</p>
</div>
<div class="section">
-<h1><a id="example-mts3x0" name="example-mts3x0">Example: mts3x0</a></h1>
-<p>The mica sensor board (mts300/mts310) has five sensors (and one actuator,
-the sounder) -- the accelerometer and magnetometer are only present on
-the mts310:</p>
-<table border="1" class="docutils">
-<colgroup>
-</colgroup>
-<tbody valign="top">
-</tbody>
-</table>
-<div class="line-block">
-<div class="line">Name | Component | Sensor Interfaces | Other Interfaces |</div>
-</div>
-<p>+===============+===========+===================+==================+</p>
-<div class="line-block">
-<div class="line">Accelerometer | AccelC | AccelX | |</div>
-</div>
-<div class="line-block">
-<div class="line">| | AccelY | |</div>
-</div>
-<div class="line-block">
-<div class="line">Magnetometer | MagC | MagX | MagSetting |</div>
-</div>
-<div class="line-block">
-<div class="line">| | MagY | |</div>
-</div>
-<div class="line-block">
-<div class="line">Microphone | MicC | MicADC | Mic |</div>
-</div>
-<div class="line-block">
-<div class="line">| | | MicInterrupt |</div>
-</div>
-<div class="line-block">
-<div class="line">Light | PhotoC | PhotoADC | |</div>
-</div>
-<div class="line-block">
-<div class="line">Temperature | TempC | TempADC | |</div>
-</div>
-<table border="1" class="docutils">
-<colgroup>
-</colgroup>
-<tbody valign="top">
-</tbody>
-</table>
-<p>Each physical sensor is represented by a separate component. Specific
-sensors that have more than one axis of measurement (AccelC and MagC)
-provide more than one <cite>AcquireData</cite> interface on a single component. Some
-sensors, such as the magnetometer and microphone, have additional
-functionality provided through sensor-specific interfaces.</p>
-<p>Although light and temperature are represented by separate components, in
-reality they share a single microcontroller pin. The two components PhotoC
-and TempC sit on top of the PhotoTempP component, which controls access to
-the shared pin, and orchestrates which sensor is currently connected to
-it. From a programmer's perspective, they appear as individual sensors,
-even though their underlying implementation is a bit more complex.</p>
-<p>The board's mts3x0.h file contains private configuration data
-(pin usage, ADC ports, etc).</p>
-<p>The mica sensor board has an empty .sensor file.</p>
-</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
+<h1><a id="authors-addresses" name="authors-addresses">6. Authors' Addresses</a></h1>
<div class="line-block">
<div class="line">David Gay</div>
<div class="line">2150 Shattuck Ave, Suite 1300</div>
<div class="line">email - <a class="reference" href="mailto:david.e.gay@intel.com">david.e.gay@intel.com</a></div>
<div class="line"><br /></div>
<div class="line">Wei Hong</div>
-<div class="line">Arched Rock</div>
-<div class="line">Berkeley, CA 94704</div>
+<div class="line">Arch Rock</div>
+<div class="line">657 Mission St. Suite 600</div>
+<div class="line">San Francisco, CA 94105</div>
<div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:wei.hong@gmail.com">wei.hong@gmail.com</a></div>
<div class="line"><br /></div>
<div class="line">Berkeley, CA 94720</div>
<div class="line"><br /></div>
<div class="line">email - <a class="reference" href="mailto:polastre@cs.berkeley.edu">polastre@cs.berkeley.edu</a></div>
+<div class="line"><br /></div>
+<div class="line">Gilman Tolle</div>
+<div class="line">Arch Rock</div>
+<div class="line">657 Mission St. Suite 600</div>
+<div class="line">San Francisco, CA 94105</div>
+<div class="line"><br /></div>
+<div class="line">email - <a class="reference" href="mailto:gtolle@archrock.com">gtolle@archrock.com</a></div>
+</div>
</div>
+<div class="section">
+<h1><a id="citations" name="citations">7. Citations</a></h1>
+<table class="docutils citation" frame="void" id="tep2" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id1" name="tep2">[TEP2]</a></td><td>TEP 2: Hardware Abstraction Architecture</td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="tep114" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="tep114">[TEP114]</a></td><td><em>(<a class="fn-backref" href="#id2">1</a>, <a class="fn-backref" href="#id3">2</a>)</em> TEP 114: SIDs: Source and Sink Indepedent Drivers</td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="tep115" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a name="tep115">[TEP115]</a></td><td><em>(<a class="fn-backref" href="#id4">1</a>, <a class="fn-backref" href="#id5">2</a>)</em> TEP 115: Power Management of Non-Virtualized Devices</td></tr>
+</tbody>
+</table>
</div>
</div>
</body>
projects / tinyos-2.x.git / commitdiff