From: klueska <klueska>
Date: Sun, 15 Apr 2007 21:11:38 +0000 (+0000)
Subject: Update of Std/Split Control interface definitions to be in line with TEP115.  Also... 
X-Git-Tag: tinyos/2.0.1~42
X-Git-Url: https://oss.titaniummirror.com/gitweb/?p=tinyos-2.x.git;a=commitdiff_plain;h=477ad8ed7bc45a8117069d5fb8fa938b0a699f6c

Update of Std/Split Control interface definitions to be in line with TEP115.  Also added the EALREADY type to TinyError.h so that providers of the SplitControl interface can return this value
---

diff --git a/tos/interfaces/AsyncStdControl.nc b/tos/interfaces/AsyncStdControl.nc
index ddefc190..7d07e7d9 100644
--- 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 b60f2066..a5c83a83 100644
--- 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 1a6a3fb3..abb02c9f 100644
--- 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 3974a93e..d733a426 100644
--- 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)));