Add Semaphore::wait_until

Given the 64-bit timebase, add wait_until to Semaphore.

Naming is based on Thread::wait_until.

pthreads uses "timedwait", but that's not a good fit against our
existing wait() - pthreads only has an absolute-time wait, not relative.

Author: kjbracey

rtos/Semaphore.cpp

@@ -20,6 +20,7 @@
  * SOFTWARE.
  */
 #include "rtos/Semaphore.h"
+#include "rtos/Kernel.h"
 #include "platform/mbed_assert.h"
 
 #include <string.h>
@@ -57,6 +58,20 @@ int32_t Semaphore::wait(uint32_t millisec) {
     }
 }
 
+int32_t Semaphore::wait_until(uint64_t millisec) {
+    uint64_t now = Kernel::get_ms_count();
+    uint32_t timeout;
+
+    if (now >= millisec) {
+        return wait(0);
+    } else if (millisec - now >= osWaitForever) {
+        // API permits early return
+        return wait(osWaitForever - 1);
+    } else {
+        return wait(millisec - now);
+    }
+}
+
 osStatus Semaphore::release(void) {
     return osSemaphoreRelease(_id);
 }

rtos/Semaphore.h

@@ -67,6 +67,18 @@ class Semaphore : private mbed::NonCopyable<Semaphore> {
     */
     int32_t wait(uint32_t millisec=osWaitForever);
 
+    /** Wait until a Semaphore resource becomes available.
+      @param   millisec  absolute timeout time, referenced to Kernel::get_ms_count()
+      @return  number of available tokens, before taking one; or -1 in case of incorrect parameters
+      @note the underlying RTOS may have a limit to the maximum wait time
+            due to internal 32-bit computations, but this is guaranteed to work if the
+            wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
+            the acquire attempt will time out earlier than specified.
+
+      @note You cannot call this function from ISR context.
+    */
+    int32_t wait_until(uint64_t millisec);
+
     /** Release a Semaphore resource that was obtain with Semaphore::wait.
       @return status code that indicates the execution status of the function:
               @a osOK the token has been correctly released.