[Tinyos-2-commits] CVS: tinyos-2.x/doc/txt tep114.txt,1.8,1.9

Tue Jun 10 10:45:31 PDT 2008

Update of /cvsroot/tinyos/tinyos-2.x/doc/txt
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv1111/txt

Modified Files:
	tep114.txt 
Log Message:
Clean up to make it Documentary.

Index: tep114.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep114.txt,v
retrieving revision 1.8
retrieving revision 1.9
diff -C2 -d -r1.8 -r1.9
*** tep114.txt	18 Sep 2007 19:27:42 -0000	1.8
--- tep114.txt	10 Jun 2008 17:45:28 -0000	1.9
***************
*** 107,110 ****
--- 107,124 ----
  described in this section.

+ This table summarizes the SID interfaces:
+ 
+ +------------------------+-----------+-----------+-----------+
+ | Name                   | Phase     | Data type | Section   |
+ +------------------------+-----------+-----------+-----------+
+ | Read                   | Split     | Scalar    | 3.1       |
+ +------------------------+-----------+-----------+-----------+
+ | Get                    | Single    | Scalar    | 3.2       |
+ +------------------------+-----------+-----------+-----------+
+ | Notify                 | Trigger   | Scalar    | 3.3       |
+ +------------------------+-----------+-----------+-----------+
+ | ReadStream             | Split     | Stream    | 3.4       |
+ +------------------------+-----------+-----------+-----------+
+ 
  3.1 Split-Phase Small Scalar I/O
  --------------------------------------------------------------------
***************
*** 117,152 ****
    }

-   interface Write<val_t> {
-     command error_t write( val_t val );
-     event void writeDone( error_t result );
-   }
- 
- 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::
- 
-   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 );
-   }
- 
- 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.
- 
  If the ``result`` parameter of the ``Read.readDone`` and
  ``ReadWrite.readDone`` events is not SUCCESS, then the memory of the
  ``val`` parameter MUST be filled with zeroes.

! If the call to ``Read.read`` has returned SUCCESS, but the
! ``Read.readDone`` event has not yet been signalled, then a subsequent
! call to ``Read.read`` 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.

  Examples of sensors that would be suited to this class of interface
--- 131,143 ----
    }

  If the ``result`` parameter of the ``Read.readDone`` and
  ``ReadWrite.readDone`` events is not SUCCESS, then the memory of the
  ``val`` parameter MUST be filled with zeroes.

! If the call to ``read`` has returned SUCCESS, but the ``readDone``
! event has not yet been signalled, then a subsequent call to ``read``
! 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.

  Examples of sensors that would be suited to this class of interface
***************
*** 154,206 ****
  readings.

! 3.2 Split-Phase Large Scalar I/O 
! --------------------------------------------------------------------
! 
! If the SID's data object is large, it can provide read/write
! interfaces that pass parameters by pointer rather than value::
! 
!   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 );
!   }
! 
! 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.
! 
! 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.
! 
! If the ``result`` parameter of the ``ReadRef.readDone`` and
! ``ReadWriteRef.readDone`` events is not SUCCESS, then the memory the
! ``val`` parameter points to MUST be filled with zeroes. 
! 
! Examples of sensors that are suited to this set of interfaces include
! those that generate multiple simultaneous readings for which
! passing by value is inefficient, such as a two-axis digital 
! accelerometer.
! 
! 3.4 Single-Phase Scalar I/O
  --------------------------------------------------------------------

--- 145,149 ----
  readings.

! 3.2 Single-Phase Scalar I/O
  --------------------------------------------------------------------

***************
*** 209,214 ****
  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::

    interface Get<val_t> {
--- 152,157 ----
  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::

    interface Get<val_t> {
***************
*** 216,245 ****
    }

-   interface Set<val_t> {
-     command void set( val_t val );
-   }
- 
-   interface GetSet<val_t> {
-     command val_t get();
-     command void set( val_t val );
-   }
- 
- 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::

-   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 );
!   }
! 
! 3.5 Notification-Based Scalar I/O
  --------------------------------------------------------------------

--- 159,165 ----
    }

! 3.3 Notification-Based Scalar I/O
  --------------------------------------------------------------------

***************
*** 263,272 ****
  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.

  The val parameter is used as defined in the Read interface.

! 3.7 Split-Phase Streaming I/O
  --------------------------------------------------------------------

--- 183,196 ----
  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.

+ If ``enable`` returns SUCCESS, the interface MUST subsequently
+ signal notifications when appropriate. If ``disable`` returns SUCCESS,
+ the interface MUST NOT signal any notifications.
+ 
  The val parameter is used as defined in the Read interface.

! 3.4 Split-Phase Streaming I/O
  --------------------------------------------------------------------

***************
*** 280,284 ****
  synchronous context through the task queue.

! The ReadStreaming interface MAY be provided by a device that can
  provide a continuous stream of readings::

--- 204,208 ----
  synchronous context through the task queue.

! The ReadStream interface MAY be provided by a device that can
  provide a continuous stream of readings::

***************
*** 320,341 ****
  FAIL.

! The following interface can be used for bulk writes::

!   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 );
!   }

- postBuffer() and bufferDone() are matched in the same way described
- for the ReadStream interface, as are write() and writeDone().

! 4. Summary
  ====================================================================

--- 244,273 ----
  FAIL.

! In the ReadStream interface, ``postBuffer`` returns SUCCESS if the buffer
! was successfully added to the queue, FAIL otherwise. A return value
! of SUCCESS from ``read`` indicates reading has begun and the interface
! will signal ``bufferDone`` and/or ``readDone`` in the future. A
! return value of FAIL means the read did not begin and the interface
! MUST NOT signal ``readDone`` or ``bufferDone``. Calls to ``read``
! MAY return EBUSY if the component cannot service the request.

! 4. Implementation
! ====================================================================

! An implementation of the Read interface can be found in
! ``tos/system/SineSensorC.nc`` and ``tos/system/ArbitratedReadC.nc``.

! An implementation of the Get interface can be found in
! ``tos/platforms/telosb/UserButtonC.nc``.

! An implementation of the ReadStream interface can be found in
! ``tos/sensorboards/mts300/MageXStreamC.nc``.

! Implementations of the Notify interface can be found in
! ``tos/platforms/telosb/SwitchToggleC.nc`` and
! ``tos/platforms/telosb/UserButtonP.nc``.

! 5. Summary
  ====================================================================

***************
*** 349,353 ****
  connect a sensor into a more general system.

! 5. Author's Address
  ====================================================================

--- 281,285 ----
  connect a sensor into a more general system.

! 6. Author's Address
  ====================================================================