Update of Std/Split Control interface definitions to be in line with TEP115. Also...

diff --git a/tos/interfaces/AsyncStdControl.nc b/tos/interfaces/AsyncStdControl.nc
index ddefc1902ed0ff9b69c217b78ff31455e572375b..7d07e7d918c644684ae0b90b9eb3d151a7556889 100644 (file)
--- a/tos/interfaces/AsyncStdControl.nc
+++ b/tos/interfaces/AsyncStdControl.nc
@@ -67,7 +67,8 @@ interface AsyncStdControl
   /**
    * Start this component and all of its subcomponents.
    *
-   * @return SUCCESS if the component was successfully turned on<br>
+   * @return SUCCESS if the component was either already on or was 
+   *         successfully turned on<br>
    *         FAIL otherwise
    */
   async command error_t start();
@@ -76,7 +77,8 @@ interface AsyncStdControl
    * Stop the component and any pertinent subcomponents (not all
    * subcomponents may be turned off due to wakeup timers, etc.).
    *
-   * @return SUCCESS if the component was successfully turned off<br>
+   * @return SUCCESS if the component was either already off or was 
+   *         successfully turned off<br>
    *         FAIL otherwise
    */
   async command error_t stop();

diff --git a/tos/interfaces/SplitControl.nc b/tos/interfaces/SplitControl.nc
index b60f2066a4f8ef6f4c61731340708bbfc51a1c17..a5c83a83dcb401e4d042f822ea0f3972bbc0b314 100644 (file)
--- a/tos/interfaces/SplitControl.nc
+++ b/tos/interfaces/SplitControl.nc
@@ -70,10 +70,14 @@ interface SplitControl
    * values of SUCCESS will always result in a <code>startDone()</code>
    * event being signalled.
    *
-   * @return SUCCESS if issuing the start command was successful<br>
+   * @return SUCCESS if the device is already in the process of 
+   *         starting or the device was off and the device is now ready to turn 
+   *         on.  After receiving this return value, you should expect a 
+   *         <code>startDone</code> event in the near future.<br>
    *         EBUSY if the component is in the middle of powering down
    *               i.e. a <code>stop()</code> command has been called,
    *               and a <code>stopDone()</code> event is pending<br>
+   *         EALREADY if the device is already on <br>
    *         FAIL Otherwise
    */
   command error_t start();
@@ -88,15 +92,18 @@ interface SplitControl
   event void startDone(error_t error);
 
   /**
-   * Stop the component and pertinent subcomponents (not all
-   * subcomponents may be turned off due to wakeup timers, etc.).
-   * Return values of SUCCESS will always result in a
-   * <code>stopDone()</code> event being signalled.
+   * Start this component and all of its subcomponents.  Return
+   * values of SUCCESS will always result in a <code>startDone()</code>
+   * event being signalled.
    *
-   * @return SUCCESS if issuing the stop command was successful<br>
+   * @return SUCCESS if the device is already in the process of 
+   *         stopping or the device was on and the device is now ready to turn 
+   *         off.  After receiving this return value, you should expect a 
+   *         <code>stopDone</code> event in the near future.<br>
    *         EBUSY if the component is in the middle of powering up
    *               i.e. a <code>start()</code> command has been called,
    *               and a <code>startDone()</code> event is pending<br>
+   *         EALREADY if the device is already off <br>
    *         FAIL Otherwise
    */
   command error_t stop();

diff --git a/tos/interfaces/StdControl.nc b/tos/interfaces/StdControl.nc
index 1a6a3fb341a76301ca09ada29ea3485cec19a230..abb02c9f7906e1c6dc5cc4140a9eaafdaedf2338 100644 (file)
--- a/tos/interfaces/StdControl.nc
+++ b/tos/interfaces/StdControl.nc
@@ -65,19 +65,21 @@
 interface StdControl
 {
   /**
-  * Start this component and all of its subcomponents.
-  *
-  * @return SUCCESS if the component was successfully turned on<br>
-  *         FAIL otherwise
-  */
+   * Start this component and all of its subcomponents.
+   *
+   * @return SUCCESS if the component was either already on or was 
+   *         successfully turned on<br>
+   *         FAIL otherwise
+   */
   command error_t start();
 
   /**
-  * Stop the component and any pertinent subcomponents (not all
-  * subcomponents may be turned off due to wakeup timers, etc.).
-  *
-  * @return SUCCESS if the component was successfully turned off<br>
-  *         FAIL otherwise
-  */
+   * Stop the component and any pertinent subcomponents (not all
+   * subcomponents may be turned off due to wakeup timers, etc.).
+   *
+   * @return SUCCESS if the component was either already off or was 
+   *         successfully turned off<br>
+   *         FAIL otherwise
+   */
   command error_t stop();
 }

diff --git a/tos/types/TinyError.h b/tos/types/TinyError.h
index 3974a93ed83c64076c926c8f47e6465130d87dcd..d733a4260477c1ba50048188b08356921b31cfc7 100644 (file)
--- a/tos/types/TinyError.h
+++ b/tos/types/TinyError.h
@@ -41,6 +41,7 @@ enum {
   EINVAL         = 6,           // An invalid parameter was passed
   ERETRY         = 7,           // A rare and transient failure: can retry
   ERESERVE       = 8,           // Reservation required before usage
+  EALREADY       = 9,           // The device state you are requesting is already set
 };
 
 typedef uint8_t error_t __attribute__((combine(ecombine)));