[Tinyos-2-commits] CVS: tinyos-2.x/doc/html tep114.html,1.10,1.11
Phil Levis
scipio at users.sourceforge.net
Tue Jun 10 10:45:30 PDT 2008
Update of /cvsroot/tinyos/tinyos-2.x/doc/html
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv1111/html
Modified Files:
tep114.html
Log Message:
Clean up to make it Documentary.
Index: tep114.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep114.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -C2 -d -r1.10 -r1.11
*** tep114.html 18 Sep 2007 19:50:33 -0000 1.10
--- tep114.html 10 Jun 2008 17:45:28 -0000 1.11
***************
*** 4,8 ****
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" />
<title>SIDs: Source and Sink Independent Drivers</title>
<meta name="author" content="Gilman Tolle, Philip Levis, and David Gay" />
--- 4,8 ----
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
! <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
<title>SIDs: Source and Sink Independent Drivers</title>
<meta name="author" content="Gilman Tolle, Philip Levis, and David Gay" />
***************
*** 390,393 ****
--- 390,429 ----
sit on top of. A SID SHOULD provide one or more of the interfaces
described in this section.</p>
+ <p>This table summarizes the SID interfaces:</p>
+ <table border="1" class="docutils">
+ <colgroup>
+ <col width="42%" />
+ <col width="19%" />
+ <col width="19%" />
+ <col width="19%" />
+ </colgroup>
+ <tbody valign="top">
+ <tr><td>Name</td>
+ <td>Phase</td>
+ <td>Data type</td>
+ <td>Section</td>
+ </tr>
+ <tr><td>Read</td>
+ <td>Split</td>
+ <td>Scalar</td>
+ <td>3.1</td>
+ </tr>
+ <tr><td>Get</td>
+ <td>Single</td>
+ <td>Scalar</td>
+ <td>3.2</td>
+ </tr>
+ <tr><td>Notify</td>
+ <td>Trigger</td>
+ <td>Scalar</td>
+ <td>3.3</td>
+ </tr>
+ <tr><td>ReadStream</td>
+ <td>Split</td>
+ <td>Stream</td>
+ <td>3.4</td>
+ </tr>
+ </tbody>
+ </table>
<div class="section">
<h2><a id="split-phase-small-scalar-i-o" name="split-phase-small-scalar-i-o">3.1 Split-Phase Small Scalar I/O</a></h2>
***************
*** 398,432 ****
event void readDone( error_t result, val_t val );
}
-
- interface Write<val_t> {
- command error_t write( val_t val );
- event void writeDone( error_t result );
- }
- </pre>
- <p>A component that provides both read and write functionality might want
- to use a combined version of the interface, to reduce the amount of
- wiring required by the client application:</p>
- <pre class="literal-block">
- interface ReadWrite<val_t> {
- command error_t read();
- event void readDone( error_t result, val_t val );
-
- command error_t write( val_t val );
- event void writeDone( error_t result );
- }
</pre>
- <p>A component that can support concurrent reads and writes SHOULD
- provide separate Read/Write interfaces. A component whose internal
- logic will cause a read to fail while a write is pending or a write to
- fail while a read is pending MUST provide a ReadWrite interface.</p>
<p>If the <tt class="docutils literal"><span class="pre">result</span></tt> parameter of the <tt class="docutils literal"><span class="pre">Read.readDone</span></tt> and
<tt class="docutils literal"><span class="pre">ReadWrite.readDone</span></tt> events is not SUCCESS, then the memory of the
<tt class="docutils literal"><span class="pre">val</span></tt> parameter MUST be filled with zeroes.</p>
! <p>If the call to <tt class="docutils literal"><span class="pre">Read.read</span></tt> has returned SUCCESS, but the
! <tt class="docutils literal"><span class="pre">Read.readDone</span></tt> event has not yet been signalled, then a subsequent
! call to <tt class="docutils literal"><span class="pre">Read.read</span></tt> MUST not return SUCCESS. This simple locking
! technique, as opposed to a more complex system in which multiple
! read/readDone pairs may be outstanding, is intended to reduce the
! complexity of code that is a client of a SID interface.</p>
<p>Examples of sensors that would be suited to this class of interface
include many basic sensors, such as photo, temp, voltage, and ADC
--- 434,446 ----
event void readDone( error_t result, val_t val );
}
</pre>
<p>If the <tt class="docutils literal"><span class="pre">result</span></tt> parameter of the <tt class="docutils literal"><span class="pre">Read.readDone</span></tt> and
<tt class="docutils literal"><span class="pre">ReadWrite.readDone</span></tt> events is not SUCCESS, then the memory of the
<tt class="docutils literal"><span class="pre">val</span></tt> parameter MUST be filled with zeroes.</p>
! <p>If the call to <tt class="docutils literal"><span class="pre">read</span></tt> has returned SUCCESS, but the <tt class="docutils literal"><span class="pre">readDone</span></tt>
! event has not yet been signalled, then a subsequent call to <tt class="docutils literal"><span class="pre">read</span></tt>
! MUST return EBUSY or FAIL. This simple locking technique, as opposed
! to a more complex system in which multiple read/readDone pairs may be
! outstanding, is intended to reduce the complexity of SID client code.</p>
<p>Examples of sensors that would be suited to this class of interface
include many basic sensors, such as photo, temp, voltage, and ADC
***************
*** 434,521 ****
</div>
<div class="section">
! <h2><a id="split-phase-large-scalar-i-o" name="split-phase-large-scalar-i-o">3.2 Split-Phase Large Scalar I/O</a></h2>
! <p>If the SID's data object is large, it can provide read/write
! interfaces that pass parameters by pointer rather than value:</p>
! <pre class="literal-block">
! interface ReadRef<val_t> {
! command error_t read( val_t* val );
! event void readDone( error_t result, val_t* val );
! }
!
! interface WriteRef<val_t> {
! command error_t write( val_t* val );
! event void writeDone( error_t result, val_t* val );
! }
!
! interface ReadWriteRef<val_t> {
! command error_t read( val_t* val );
! event void readDone( error_t result, val_t* val );
!
! command error_t write( val_t* val );
! event void writeDone( error_t result, val_t* val );
! }
! </pre>
! <p>The caller is responsible for managing storage pointed to by the val
! pointer which is passed to read() or write(). The SID takes ownership
! of the storage, stores a new value into it or copy a value out of it,
! and then relinquishes it when signaling readDone() or writeDone(). If
! read or write() returns SUCCESS then the caller MUST NOT access or
! modify the storage pointed to by the val pointer until it handles the
! readDone() or writeDone() event.</p>
! <p>As is the case with the parameters by value, whether a component
! provides separate ReadRef and WriteRef or ReadWriteRef affects the
! concurrency it allows. If a component can allow the two to execute
! concurrently, then it SHOULD provide separate ReadRef and WriteRef
! interfaces. If the two cannot occur concurrently, then it MUST provide
! ReadWriteRef.</p>
! <p>If the <tt class="docutils literal"><span class="pre">result</span></tt> parameter of the <tt class="docutils literal"><span class="pre">ReadRef.readDone</span></tt> and
! <tt class="docutils literal"><span class="pre">ReadWriteRef.readDone</span></tt> events is not SUCCESS, then the memory the
! <tt class="docutils literal"><span class="pre">val</span></tt> parameter points to MUST be filled with zeroes.</p>
! <p>Examples of sensors that are suited to this set of interfaces include
! those that generate multiple simultaneous readings for which
! passing by value is inefficient, such as a two-axis digital
! accelerometer.</p>
! </div>
! <div class="section">
! <h2><a id="single-phase-scalar-i-o" name="single-phase-scalar-i-o">3.4 Single-Phase Scalar I/O</a></h2>
<p>Some devices may have their state cached or readily available. In
these cases, the device can provide a single-phase instead of
split-phase operation. Examples include a node's MAC address (which
the radio stack caches in memory), profiling information (e.g.,
! packets received), or a GPIO pin. These devices MAY use these
! single-phase interfaces:</p>
<pre class="literal-block">
interface Get<val_t> {
command val_t get();
}
-
- interface Set<val_t> {
- command void set( val_t val );
- }
-
- interface GetSet<val_t> {
- command val_t get();
- command void set( val_t val );
- }
- </pre>
- <p>If a device's data object is readily available but still too large to
- be passed on the stack, then the device MAY use these interfaces:</p>
- <pre class="literal-block">
- interface GetRef<val_t> {
- command error_t get( val_t* val );
- }
-
- interface SetRef<val_t> {
- command error_t set( val_t* val );
- }
-
- interface GetSetRef<val_t> {
- command error_t get( val_t* val );
- command error_t set( val_t* val );
- }
</pre>
</div>
<div class="section">
! <h2><a id="notification-based-scalar-i-o" name="notification-based-scalar-i-o">3.5 Notification-Based Scalar I/O</a></h2>
<p>Some sensor devices represent triggers, rather than request-driven
data acquisition. Examples of such sensors include switches,
--- 448,466 ----
</div>
<div class="section">
! <h2><a id="single-phase-scalar-i-o" name="single-phase-scalar-i-o">3.2 Single-Phase Scalar I/O</a></h2>
<p>Some devices may have their state cached or readily available. In
these cases, the device can provide a single-phase instead of
split-phase operation. Examples include a node's MAC address (which
the radio stack caches in memory), profiling information (e.g.,
! packets received), or a GPIO pin. These devices MAY use the
! Get interface:</p>
<pre class="literal-block">
interface Get<val_t> {
command val_t get();
}
</pre>
</div>
<div class="section">
! <h2><a id="notification-based-scalar-i-o" name="notification-based-scalar-i-o">3.3 Notification-Based Scalar I/O</a></h2>
<p>Some sensor devices represent triggers, rather than request-driven
data acquisition. Examples of such sensors include switches,
***************
*** 536,545 ****
events for the interface instance used by a single particular
client. They are distinct from the sensor's power state. For example,
! if an enabled sensor is powered down, then when powered up it MUST
remain enabled.</p>
<p>The val parameter is used as defined in the Read interface.</p>
</div>
<div class="section">
! <h2><a id="split-phase-streaming-i-o" name="split-phase-streaming-i-o">3.7 Split-Phase Streaming I/O</a></h2>
<p>Some sensors can provide a continuous stream of readings, and some
actuators can accept a continuous stream of new data. Depending on the
--- 481,493 ----
events for the interface instance used by a single particular
client. They are distinct from the sensor's power state. For example,
! if an enabled sensor is powered down, then when powered up it will
remain enabled.</p>
+ <p>If <tt class="docutils literal"><span class="pre">enable</span></tt> returns SUCCESS, the interface MUST subsequently
+ signal notifications when appropriate. If <tt class="docutils literal"><span class="pre">disable</span></tt> returns SUCCESS,
+ the interface MUST NOT signal any notifications.</p>
<p>The val parameter is used as defined in the Read interface.</p>
</div>
<div class="section">
! <h2><a id="split-phase-streaming-i-o" name="split-phase-streaming-i-o">3.4 Split-Phase Streaming I/O</a></h2>
<p>Some sensors can provide a continuous stream of readings, and some
actuators can accept a continuous stream of new data. Depending on the
***************
*** 550,554 ****
enough when each new reading must be transferred from asynchronous to
synchronous context through the task queue.</p>
! <p>The ReadStreaming interface MAY be provided by a device that can
provide a continuous stream of readings:</p>
<pre class="literal-block">
--- 498,502 ----
enough when each new reading must be transferred from asynchronous to
synchronous context through the task queue.</p>
! <p>The ReadStream interface MAY be provided by a device that can
provide a continuous stream of readings:</p>
<pre class="literal-block">
***************
*** 587,610 ****
buffers. If a readDone() is pending, calls to postBuffer MUST return
FAIL.</p>
! <p>The following interface can be used for bulk writes:</p>
! <pre class="literal-block">
! interface WriteStream<val_t> {
!
! command error_t postBuffer( val_t* buf, uint16_t count );
!
! command error_t write( uint32_t period );
!
! event void bufferDone( error_t result,
! val_t* buf, uint16_t count );
!
! event void writeDone( error_t result );
! }
! </pre>
! <p>postBuffer() and bufferDone() are matched in the same way described
! for the ReadStream interface, as are write() and writeDone().</p>
</div>
</div>
<div class="section">
! <h1><a id="summary" name="summary">4. Summary</a></h1>
<p>According to the design principles described in the HAA[_haa], authors
should write device drivers that provide rich, device-specific
--- 535,561 ----
buffers. If a readDone() is pending, calls to postBuffer MUST return
FAIL.</p>
! <p>In the ReadStream interface, <tt class="docutils literal"><span class="pre">postBuffer</span></tt> returns SUCCESS if the buffer
! was successfully added to the queue, FAIL otherwise. A return value
! of SUCCESS from <tt class="docutils literal"><span class="pre">read</span></tt> indicates reading has begun and the interface
! will signal <tt class="docutils literal"><span class="pre">bufferDone</span></tt> and/or <tt class="docutils literal"><span class="pre">readDone</span></tt> in the future. A
! return value of FAIL means the read did not begin and the interface
! MUST NOT signal <tt class="docutils literal"><span class="pre">readDone</span></tt> or <tt class="docutils literal"><span class="pre">bufferDone</span></tt>. Calls to <tt class="docutils literal"><span class="pre">read</span></tt>
! MAY return EBUSY if the component cannot service the request.</p>
</div>
</div>
<div class="section">
! <h1><a id="implementation" name="implementation">4. Implementation</a></h1>
! <p>An implementation of the Read interface can be found in
! <tt class="docutils literal"><span class="pre">tos/system/SineSensorC.nc</span></tt> and <tt class="docutils literal"><span class="pre">tos/system/ArbitratedReadC.nc</span></tt>.</p>
! <p>An implementation of the Get interface can be found in
! <tt class="docutils literal"><span class="pre">tos/platforms/telosb/UserButtonC.nc</span></tt>.</p>
! <p>An implementation of the ReadStream interface can be found in
! <tt class="docutils literal"><span class="pre">tos/sensorboards/mts300/MageXStreamC.nc</span></tt>.</p>
! <p>Implementations of the Notify interface can be found in
! <tt class="docutils literal"><span class="pre">tos/platforms/telosb/SwitchToggleC.nc</span></tt> and
! <tt class="docutils literal"><span class="pre">tos/platforms/telosb/UserButtonP.nc</span></tt>.</p>
! </div>
! <div class="section">
! <h1><a id="summary" name="summary">5. Summary</a></h1>
<p>According to the design principles described in the HAA[_haa], authors
should write device drivers that provide rich, device-specific
***************
*** 617,621 ****
</div>
<div class="section">
! <h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Gilman Tolle</div>
--- 568,572 ----
</div>
<div class="section">
! <h1><a id="author-s-address" name="author-s-address">6. Author's Address</a></h1>
<div class="line-block">
<div class="line">Gilman Tolle</div>
More information about the Tinyos-2-commits
mailing list