[Tinyos Core WG] Tep 115

[Philip Levis]

On Feb 11, 2007, at 10:44 PM, Kevin Klues wrote:

> My personal inclination is to follow an approach similar to the one  
> taken by the XE1205.  It keeps the device driver implementation  
> simple, while providing enough useful information to its clients in  
> the rare case that they mistakenly call start or stop at  
> inappropriate times.
>
> Specifically, I'm leaning towards the following solution:
>
> If the device is currently off......
> - Calling start() returns SUCCESS if it was capable of starting the  
> process of initializing the device, it returns FAIL if it could  
> not, and it returns EBUSY if there is a pending stop() in  
> progress.  Any redundant calls to start either while it is in the  
> process of starting ( i.e. before its startDone gets signaled) or  
> calls made after the device has been started also return FAIL.  In  
> this way, SUCCESS always signifies that the processing of starting  
> a device was successful, EBUSY signifies that the request could not  
> be processed because the device is in the process of powering down  
> (but will be available for powerup shortly), and FAIL means that  
> start simply should never have been called in the first place.
>
> - Calling stop() always returns FAIL
>
> If the device is currently on, then the reverse is true, and all  
> calls to start() will always FAIL.
>
> In terms of the table.....
>
> +-----------+-----------+------------+----------+----------+
> | Call      | Device On | Device Off | Starting | Stopping |
> +===========+===========+============+==========+==========+
> | start()   |   FAIL    |  SUCCESS   |   FAIL   |  EBUSY   |
> |           |           |  FAIL      |          |          |
> +-----------+-----------+------------+----------+----------+
> | stop()    |  SUCCESS  |    FAIL    |  EBUSY   |   FAIL   |
> |           |  FAIL     |            |          |          |
> +-----------+-----------+------------+----------+----------+
> | operation |  depends  |    EOFF    |   FAIL   |   FAIL   |  
> +-----------+-----------+------------+----------+----------+
>
> Operations called on the device while it is off will return EOFF in  
> order to inform its user that the device needs to be turned on.   
> Calls made while switching state will simply return FAIL.
>

I'd be tempted to go with two changes:

+----------------------+-----------+------------+----------+----------+
| Call                 | Device On | Device Off | Starting | Stopping |
+======================+===========+============+==========+==========+
| SplitControl.start() |  SUCCESS  |  SUCCESS   | EBUSY    |  EBUSY   |
|                      |           |  FAIL      |          |          |
+----------------------+-----------+------------+----------+----------+
| SplitControl.stop()  |  SUCCESS  |  SUCCESS   | EBUSY    |  EBUSY   |
|                      |  FAIL     |            |          |          |
+----------------------+-----------+------------+----------+----------+
| operation            |  depends  |  FAIL      | FAIL     | FAIL     |
|                      |           |  EOFF      | EOFF     | EOFF     |
|                      |           |  EOFF      | SUCCESS  |          |
+----------------------+-----------+------------+----------+----------+

Not having to distinguish the starting and stopping states could make  
things a lot easier. EBUSY means " try again later"

The SUCCESS on calling start() when on and stop() when off comes from  
this issue: if you call start() and it returns FAIL, you do not know  
if the device is on or not. With this other approach, if you call  
start() and it returns FAIL, you know it is off. If you call start()  
and it returns SUCCESS, when you known when startDone() occurs you  
will be on.

Phil