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"
@@ -412,7 +412,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
@@ -59,7 +61,16 @@ extern "C" {
  *    If the RTOS is present, this function spins to get the exact number of microseconds for
  *    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`.
+ *
+ *  @deprecated
+ *    'wait' is deprecated in favor of explicit sleep functions. To sleep, 'wait' should be replaced by
+ *    'ThisThread::sleep_for' (C++) or 'thread_sleep_for' (C). If you wish to wait (without sleeping), call
+ *    'wait_us'. 'wait_us' is safe to call from ISR context.
  */
+MBED_DEPRECATED_SINCE("mbed-os-5.13",
+                      "'wait' is deprecated in favor of explicit sleep functions. To sleep, 'wait' should be replaced by "
+                      "'ThisThread::sleep_for' (C++) or 'thread_sleep_for' (C). If you wish to wait (without sleeping), call "
+                      "'wait_us'. 'wait_us' is safe to call from ISR context.")
 void wait(float s);
 
 /** Waits a number of milliseconds.
@@ -69,7 +80,16 @@ void wait(float s);
  *  @note
  *    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.
+ *
+ *  @deprecated
+ *    'wait_ms' is deprecated in favor of explicit sleep functions. To sleep, 'wait_ms' should be replaced by
+ *    'ThisThread::sleep_for' (C++) or 'thread_sleep_for' (C). If you wish to wait (without sleeping), call
+ *    'wait_us'. 'wait_us' is safe to call from ISR context.
  */
+MBED_DEPRECATED_SINCE("mbed-os-5.13",
+                      "'wait_ms' is deprecated in favor of explicit sleep functions. To sleep, 'wait_ms' should be replaced by "
+                      "'ThisThread::sleep_for' (C++) or 'thread_sleep_for' (C). If you wish to wait (without sleeping), call "
+                      "'wait_us'. 'wait_us' is safe to call from ISR context.")
 void wait_ms(int ms);
 
 /** Waits a number of microseconds.
@@ -79,7 +99,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);