[Tinyos Core WG] Tep 115

[Kevin Klues]

When talking about this, we should really have two more columns added to the
table which indicate the "return" values of the startDone() and stopDone()
events that are signaled.

To summarize the two different proposals we have....

Phil's:
+-------------+-----------+------------+----------+----------+
| Call        | Device On | Device Off | Starting | Stopping |
+=============+===========+============+==========+==========+
| start()     |  SUCCESS  |   SUCCESS  |   EBUSY  |  EBUSY   |
|             |           |   FAIL     |          |          |
+-------------+-----------+------------+----------+----------+
| startDone() |  SUCCESS  |   SUCCESS  |    N/A   |   N/A    |
|             |           |   FAIL     |          |          |
+-------------+-----------+------------+----------+----------+
| stop()      |  SUCCESS  |   SUCCESS  |   EBUSY  |  EBUSY   |
|             |  FAIL     |            |          |          |
+-------------+-----------+------------+----------+----------+
| stopDone()  |  SUCCESS  |   SUCCESS  |    N/A   |   N/A    |
|             |  FAIL     |            |          |          |
+-------------+-----------+------------+----------+----------+
|  operation  |  depends  |    EOFF    |   FAIL   |   FAIL   |
+-------------+-----------+------------+----------+----------+

Mine:
+-------------+-----------+------------+----------+----------+
| Call        | Device On | Device Off | Starting | Stopping |
+=============+===========+============+==========+==========+
| start()     |   FAIL    |   SUCCESS  |   FAIL   |  EBUSY   |
|             |           |   FAIL     |          |          |
+-------------+-----------+------------+----------+----------+
| startDone() |    N/A    |   SUCCESS  |    N/A   |   N/A    |
|             |           |   FAIL     |          |          |
|             |           |   N/A      |          |          |
+-------------+-----------+------------+----------+----------+
| stop()      |  SUCCESS  |    FAIL    |   FAIL   |  EBUSY   |
|             |  FAIL     |            |          |          |
+-------------+-----------+------------+----------+----------+
| stopDone()  |  SUCCESS  |     N/A    |    N/A   |   N/A    |
|             |  FAIL     |            |          |          |
|             |  N/A      |            |          |          |
+-------------+-----------+------------+----------+----------+
|  operation  |  depends  |    EOFF    |   FAIL   |   FAIL   |
+-------------+-----------+------------+----------+----------+

On 2/12/07, Kevin Klues < klueska at gmail.com> wrote:
>
> I really don't like the idea of start() returning SUCCESS when the device
> is already on because it seems strange to me to have to signal a startDone()
> event in these cases.  We could just not signal the event, but I like to
> think that whenever you get a SUCCESS on start() it will be followed by a
> startDone().  By simply returning FAIL in these cases, this problem could be
> avoided.
>
> If we return FAIL on these calls, then returning EBUSY when starting would
> be ambiguous since you wouldn't know whether you should try and call start()
> again later or not.  You wouldn't want to if it was returned while waiting
> on a startDone(), but you might if it was because you were waiting on a
> stopDone().
>
> With my proposal you would know the following information based on all
> return values...
> SUCCESS - your call to try and start the device succeeded and you will
> receive a startDone() event letting you know if it actually started up or
> not.
> FAIL - You really shouldn't have been calling start() in the first place
> because a) the device is already on or b) you are still waiting on a
> startDone() event at which point you will proceed as if your redundant call
> to start had succeeded.
> EBUSY - explicity tells you that the device is in the process of being
> shut off so if you really plan on starting it up again you might want to
> consider doing so in the body of your stopDone() event.
>
> Kevin
>
>
> On 2/12/07, Philip Levis <pal at cs.stanford.edu > wrote:
> >
> > 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
> >
>
>
>
> --
> ~Kevin




-- 
~Kevin
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.millennium.berkeley.edu/pipermail/tinyos-2.0wg/attachments/20070212/5e6ef53a/attachment-0001.html