diff --git a/CHANGELOG b/CHANGELOG
index afefb10d..4be73f78 100644
--- a/CHANGELOG
+++ b/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
 
diff --git a/doc/sys_arch.txt b/doc/sys_arch.txt
index e47428c7..bb9da35e 100644
--- a/doc/sys_arch.txt
+++ b/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
-  signaled. If the "timeout" argument is non-zero, the thread should
-  only be blocked for the specified time (measured in
-  milliseconds). If the "timeout" argument is zero, the thread should be
-  blocked until the semaphore is signalled.
+  Blocks the thread while waiting for the semaphore to be signaled. If the
+  "timeout" argument is non-zero, the thread should only be blocked for the
+  specified time (measured in milliseconds). If the "timeout" argument is zero,
+  the thread should be blocked until the semaphore is signalled.
 
-  If the timeout argument is non-zero, the return value is the number of
-  milliseconds spent waiting for the semaphore to be signaled. If the
-  semaphore wasn't signaled within the specified time, the return value is
-  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.
+  The return value is SYS_ARCH_TIMEOUT if the semaphore wasn't signaled within
+  the specified time or any other value if it was signaled (with or without
+  waiting).
 
   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
-  timeout.
+  SYS_ARCH_TIMEOUT if there was a timeout, any other value if a messages
+  is received.
 
   Note that a function with a similar name, sys_mbox_fetch(), is
   implemented by lwIP. 
diff --git a/src/include/lwip/sys.h b/src/include/lwip/sys.h
index 4a6635e6..4e2386c4 100644
--- a/src/include/lwip/sys.h
+++ b/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
- *         or SYS_ARCH_TIMEOUT on timeout
+ * @return SYS_ARCH_TIMEOUT on timeout, any other value on success
  */
 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
-           or SYS_ARCH_TIMEOUT on timeout
- *         The returned time has to be accurate to prevent timer jitter!
+ * @return SYS_ARCH_TIMEOUT on timeout, any other value if a message has been received
  */
 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() */