-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