[PATCH] Deprecate sys_arch_sem_wait and sys_arch_mbox_fetch returning the time waited

These are now defined to return != SYS_ARCH_TIMEOUT on success rather than the time
waiting. The returned times were unused by lwip and this simplifies at
least some implementations.

Signed-off-by: goldsimon <goldsimon@gmx.de>

CHANGELOG

@@ -6,6 +6,11 @@ HISTORY
 
   ++ New features:
 
+  2017-07-20: Douglas
+  * sys: deprecate sys_arch_sem_wait and sys_arch_mbox_fetch returning the
+    time waited rather they are now defined to return != SYS_ARCH_TIMEOUT
+    on success.
+
   2017-07-03: Jakub Schmidtke
   * tcp: added support for sending TCP SACKs
 

doc/sys_arch.txt

@@ -64,17 +64,14 @@ The following functions must be implemented by the sys_arch:
 
 - u32_t sys_arch_sem_wait(sys_sem_t *sem, u32_t timeout)
 
-  Blocks the thread while waiting for the semaphore to be
+  Blocks the thread while waiting for the semaphore to be signaled. If the
-  signaled. If the "timeout" argument is non-zero, the thread should
+  "timeout" argument is non-zero, the thread should only be blocked for the
-  only be blocked for the specified time (measured in
+  specified time (measured in milliseconds). If the "timeout" argument is zero,
-  milliseconds). If the "timeout" argument is zero, the thread should be
+  the thread should be blocked until the semaphore is signalled.
-  blocked until the semaphore is signalled.
 
-  If the timeout argument is non-zero, the return value is the number of
+  The return value is SYS_ARCH_TIMEOUT if the semaphore wasn't signaled within
-  milliseconds spent waiting for the semaphore to be signaled. If the
+  the specified time or any other value if it was signaled (with or without
-  semaphore wasn't signaled within the specified time, the return value is
+  waiting).
-  SYS_ARCH_TIMEOUT. If the thread didn't have to wait for the semaphore
-  (i.e., it was already signaled), the function may return zero.
 
   Notice that lwIP implements a function with a similar name,
   sys_sem_wait(), that uses the sys_arch_sem_wait() function.
@@ -164,8 +161,8 @@ The following functions must be implemented by the sys_arch:
   should be dropped.
 
   The return values are the same as for the sys_arch_sem_wait() function:
-  Number of milliseconds spent waiting or SYS_ARCH_TIMEOUT if there was a
+  SYS_ARCH_TIMEOUT if there was a timeout, any other value if a messages
-  timeout.
+  is received.
 
   Note that a function with a similar name, sys_mbox_fetch(), is
   implemented by lwIP. 

src/include/lwip/sys.h

@@ -184,8 +184,7 @@ void sys_sem_signal(sys_sem_t *sem);
  * Wait for a semaphore for the specified timeout
  * @param sem the semaphore to wait for
  * @param timeout timeout in milliseconds to wait (0 = wait forever)
- * @return time (in milliseconds) waited for the semaphore
+ * @return SYS_ARCH_TIMEOUT on timeout, any other value on success
- *         or SYS_ARCH_TIMEOUT on timeout
  */
 u32_t sys_arch_sem_wait(sys_sem_t *sem, u32_t timeout);
 /**
@@ -262,9 +261,7 @@ err_t sys_mbox_trypost(sys_mbox_t *mbox, void *msg);
  * @param mbox mbox to get a message from
  * @param msg pointer where the message is stored
  * @param timeout maximum time (in milliseconds) to wait for a message (0 = wait forever)
- * @return time (in milliseconds) waited for a message, may be 0 if not waited
+ * @return SYS_ARCH_TIMEOUT on timeout, any other value if a message has been received
-           or SYS_ARCH_TIMEOUT on timeout
- *         The returned time has to be accurate to prevent timer jitter!
  */
 u32_t sys_arch_mbox_fetch(sys_mbox_t *mbox, void **msg, u32_t timeout);
 /* Allow port to override with a macro, e.g. special timeout for sys_arch_mbox_fetch() */