Add Thread::wait_until

API is somewhat loose to cope with potential shift in the underlying
RTOS APIs.

Author: kjbracey

rtos/Thread.cpp

@@ -353,6 +353,35 @@ osStatus Thread::wait(uint32_t millisec) {
     return osDelay(millisec);
 }
 
+osStatus Thread::wait_until(uint64_t millisec) {
+    // CMSIS-RTOS 2.1.0 and 2.1.1 differ in the time type, which we determine
+    // by looking at the return type of osKernelGetTickCount. We assume
+    // our header at least matches the implementation, so we don't try looking
+    // at the run-time version report. (There's no compile-time version report)
+    if (sizeof osKernelGetTickCount() == sizeof(uint64_t)) {
+        // CMSIS-RTOS 2.1.0 has a 64-bit API. The corresponding RTX 5.2.0 can't
+        // delay more than 0xfffffffe ticks, but there's no limit stated for
+        // the generic API.
+        return osDelayUntil(millisec);
+    } else {
+        // 64-bit time doesn't wrap (for half a billion years, at last)
+        uint64_t now = Kernel::get_ms_count();
+        // Report being late on entry
+        if (now >= millisec) {
+            return osErrorParameter;
+        }
+        // We're about to make a 32-bit delay call, so have at least this limit
+        if (millisec - now > 0xFFFFFFFF) {
+            return osErrorParameter;
+        }
+        // And this may have its own internal limit - we'll find out.
+        // We hope/assume there's no problem with passing
+        // osWaitForever = 0xFFFFFFFF - that value is only specified to have
+        // special meaning for osSomethingWait calls.
+        return osDelay(millisec - now);
+    }
+}
+
 osStatus Thread::yield() {
     return osThreadYield();
 }

rtos/Thread.h

@@ -360,14 +360,33 @@ class Thread : private mbed::NonCopyable<Thread> {
     */
     static osEvent signal_wait(int32_t signals, uint32_t millisec=osWaitForever);
 
-    /** Wait for a specified time period in millisec:
+    /** Wait for a specified time period in milliseconds
+      Being tick-based, the delay will be up to the specified time - eg for
+      a value of 1 the system waits until the next millisecond tick occurs,
+      leading to a delay of 0-1 milliseconds.
       @param   millisec  time delay value
       @return  status code that indicates the execution status of the function.
 
       @note You cannot call this function from ISR context.
     */
     static osStatus wait(uint32_t millisec);
 
+    /** Wait until a specified time in millisec
+      The specified time is according to Kernel::get_ms_count().
+      @param   millisec absolute time in millisec
+      @return  status code that indicates the execution status of the function.
+      @note not callable from interrupt
+      @note if millisec is equal to or lower than the current tick count, this
+            returns immediately, either with an error or "osOK".
+      @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
+            delay is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
+            it may return with an immediate error, or wait for the maximum delay.
+
+      @note You cannot call this function from ISR context.
+    */
+    static osStatus wait_until(uint64_t millisec);
+
     /** Pass control to next thread that is in state READY.
       @return  status code that indicates the execution status of the function.