Add Kernel::get_ms_count

Give C++ access to the RTOS's absolute timebase, reducing the need to
run private Timers and similar. Allows wait_until functionality, and
makes it easier to avoid time drift.

Place it in a new header and namespace in case we want more kernel
functions in future.

Try to cover over the breaking API change potentially upcoming in
CMSIS-RTOS 2.1.1, when it reduces the tick count from 64-bit to 32-bit.
(See ARM-software/CMSIS_5#277)

Explicitly state that ticks are milliseconds in mbed OS, despite CMSIS
RTOS 2 permitting different tick rates.

See also ARMmbed#3648 (wait_until
for condition variables) and
ARMmbed#5378 (EventQueue should
use RTOS tick count).

Author: kjbracey

rtos/Kernel.cpp

@@ -0,0 +1,63 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2017 ARM Limited
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+#include "rtos/Kernel.h"
+
+#include "mbed.h"
+
+namespace rtos {
+
+uint64_t Kernel::get_ms_count() {
+    // CMSIS-RTOS 2.1.0 and 2.1.1 differ in the time type. 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)
+
+    // 2.1.0 uint64_t osKernelGetTickCount(void), not documented as callable from ISR (but RTX does allow)
+    // 2.1.1 uint32_t osKernelGetTickCount(void), callable from ISR
+    // 2.1.x who knows? We assume could go back to uint64_t
+    if (sizeof osKernelGetTickCount() == sizeof(uint64_t)) {
+        return osKernelGetTickCount();
+    } else /* assume 32-bit */ {
+        // Based on suggestion in CMSIS-RTOS 2.1.1 docs, but with reentrancy
+        // protection for the tick memory. We use critical section rather than a
+        // mutex, as hopefully this method can be callable from interrupt later -
+        // only thing currently preventing it is that pre CMSIS RTOS 2.1.1, it's
+        // not defined as safe.
+        // We assume this is called multiple times per 32-bit wrap period (49 days).
+        static uint32_t tick_h, tick_l;
+
+        core_util_critical_section_enter();
+        // The 2.1.1 API says this is legal from an ISR - we assume this means
+        // it's also legal with interrupts disabled. RTX implementation kind
+        // of conflates the two.
+        uint32_t tick32 = osKernelGetTickCount();
+        if (tick32 < tick_l) {
+            tick_h++;
+        }
+        tick_l = tick32;
+        uint64_t ret = ((uint64_t) tick_h << 32) | tick_l;
+        core_util_critical_section_exit();
+        return ret;
+    }
+}
+
+}

rtos/Kernel.h

@@ -0,0 +1,51 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2017 ARM Limited
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+#ifndef KERNEL_H
+#define KERNEL_H
+
+#include <stdint.h>
+
+namespace rtos {
+/** \addtogroup rtos */
+/** @{*/
+
+/** Functions in the Kernel namespace control RTOS kernel information. */
+namespace Kernel {
+
+/** Read the current RTOS kernel millisecond tick count.
+     The tick count corresponds to the tick count used by the RTOS for timing
+     purposes. It increments monotonically from 0 at boot, hence effectively
+     never wraps. If the underlying RTOS only provides a 32-bit tick count,
+     this method expands it to 64 bits.
+     @return  RTOS kernel current tick count
+     @note mbed OS always uses millisecond RTOS ticks, and this could only wrap
+           after half a billion years
+     @note You cannot call this function from ISR context.
+ */
+uint64_t get_ms_count();
+
+} // namespace Kernel
+
+} // namespace rtos
+#endif
+
+/** @}*/

rtos/rtos.h

@@ -26,6 +26,7 @@
 #define RTOS_H
 
 #include "mbed_rtos_storage.h"
+#include "rtos/Kernel.h"
 #include "rtos/Thread.h"
 #include "rtos/Mutex.h"
 #include "rtos/RtosTimer.h"