Deprecate wait/wait_ms APIs

Author: kjbracey

drivers/UARTSerial.cpp

@@ -20,7 +20,7 @@
 
 #include "platform/mbed_poll.h"
 
-#if MBED_CONF_RTOS_PRESENT
+#if MBED_CONF_RTOS_API_PRESENT
 #include "rtos/ThisThread.h"
 #else
 #include "platform/mbed_wait_api.h"
@@ -413,7 +413,7 @@ void UARTSerial::wait_ms(uint32_t millisec)
     /* wait_ms implementation for RTOS spins until exact microseconds - we
      * want to just sleep until next tick.
      */
-#if MBED_CONF_RTOS_PRESENT
+#if MBED_CONF_RTOS_API_PRESENT
     rtos::ThisThread::sleep_for(millisec);
 #else
     ::wait_ms(millisec);

platform/mbed_wait_api.h

@@ -25,6 +25,8 @@
 #ifndef MBED_WAIT_API_H
 #define MBED_WAIT_API_H
 
+#include "mbed_toolchain.h"
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -60,6 +62,10 @@ extern "C" {
  *    microsecond precision up to 10 milliseconds. If delay is larger than 10 milliseconds and not in ISR, it is the same as
  *    `wait_ms`. We recommend `wait_us` and `wait_ms` over `wait`.
  */
+MBED_DEPRECATED_SINCE("mbed-os-5.13",
+                      "'wait'-named functions are now reserved for CPU-using delays that are safe to call from IRQ context. "
+                      "This call should be replaced by either a sleep call such as ThisThread::sleep_for (C++) or "
+                      "thread_sleep_for (C), or by a wait call such as wait_us(), depending on required behaviour.")
 void wait(float s);
 
 /** Waits a number of milliseconds.
@@ -70,6 +76,9 @@ void wait(float s);
  *    If the RTOS is present, it calls ThisThread::sleep_for(), which is same as CMSIS osDelay().
  *    You can't call this from interrupts, and it doesn't lock hardware sleep.
  */
+MBED_DEPRECATED_SINCE("mbed-os-5.13",
+                      "'wait'-named functions are now reserved for CPU-using delays that are safe to call from IRQ context. "
+                      "This sleeping call is replaced by ThisThread::sleep_for (C++) or thread_sleep_for (C).")
 void wait_ms(int ms);
 
 /** Waits a number of microseconds.
@@ -79,7 +88,7 @@ void wait_ms(int ms);
  *  @note
  *    This function always spins to get the exact number of microseconds.
  *    This will affect power and multithread performance. Therefore, spinning for
- *    millisecond wait is not recommended, and wait_ms() should
+ *    millisecond wait is not recommended, and ThisThread::sleep_for should
  *    be used instead.
  *
  *  @note You may call this function from ISR context, but large delays may

platform/mbed_wait_api_rtos.cpp

@@ -30,7 +30,7 @@
 void wait(float s)
 {
     if ((s >= 0.01f)  && core_util_are_interrupts_enabled()) {
-        wait_ms(s * 1000.0f);
+        rtos::ThisThread::sleep_for(s * 1000.0f);
         return;
     }
 
@@ -68,7 +68,7 @@ void wait_us(int us)
 {
     if (us > 10000) {
         MBED_WARNING(MBED_MAKE_ERROR(MBED_MODULE_PLATFORM, MBED_ERROR_UNKNOWN),
-                     "wait_us blocks deep sleep, wait_ms recommended for long delays\n");
+                     "wait_us blocks sleep, ThisThread::sleep_for required for long delays\n");
     }
     const ticker_data_t *const ticker = get_us_ticker_data();
     uint32_t start = ticker_read(ticker);

rtos/ThisThread.h

@@ -147,6 +147,7 @@ uint32_t flags_wait_any_until(uint32_t flags, uint64_t millisec, bool clear = tr
 /** Sleep for a specified time period in millisec:
   @param   millisec  time delay value
   @note You cannot call this function from ISR context.
+  @note The equivalent functionality is accessible in C via thread_sleep_for.
 */
 void sleep_for(uint32_t millisec);
 
@@ -156,6 +157,7 @@ void sleep_for(uint32_t millisec);
   @note You cannot call this function from ISR context.
   @note if millisec is equal to or lower than the current tick count, this
         returns immediately.
+  @note The equivalent functionality is accessible in C via thread_sleep_until.
 */
 void sleep_until(uint64_t millisec);