Deprecate wait/wait_ms APIs

Author: kjbracey

UNITTESTS/features/cellular/framework/AT/at_cellularsms/unittest.cmake

@@ -26,5 +26,5 @@ set(unittest-test-sources
   stubs/CellularUtil_stub.cpp
   stubs/us_ticker_stub.cpp
   stubs/mbed_assert_stub.c
-  stubs/mbed_wait_api_stub.cpp
+  stubs/ThisThread_stub.cpp
 )

UNITTESTS/features/cellular/framework/AT/athandler/unittest.cmake

@@ -23,7 +23,6 @@ set(unittest-test-sources
   stubs/EventQueue_stub.cpp
   stubs/FileHandle_stub.cpp
   stubs/us_ticker_stub.cpp
-  stubs/mbed_wait_api_stub.cpp
   stubs/mbed_assert_stub.c
   stubs/mbed_poll_stub.cpp
   stubs/Timer_stub.cpp

UNITTESTS/stubs/UARTSerial_stub.cpp

@@ -130,11 +130,6 @@ int UARTSerial::enable_output(bool enabled)
     return 0;
 }
 
-void UARTSerial::wait_ms(uint32_t millisec)
-{
-
-}
-
 void UARTSerial::set_flow_control(mbed::SerialBase::Flow, PinName, PinName)
 {
 

components/storage/blockdevice/COMPONENT_SPIF/SPIFBlockDevice.cpp

@@ -15,10 +15,10 @@
  */
 
 #include "SPIFBlockDevice.h"
+#include "rtos/ThisThread.h"
 #include "mbed_critical.h"
 
 #include <string.h>
-#include "mbed_wait_api.h"
 
 #include "mbed_trace.h"
 #define TRACE_GROUP "SPIF"
@@ -910,7 +910,7 @@ bool SPIFBlockDevice::_is_mem_ready()
     bool mem_ready = true;
 
     do {
-        wait_ms(1);
+        rtos::ThisThread::sleep_for(1);
         retries++;
         //Read the Status Register from device
         if (SPIF_BD_ERROR_OK != _spi_send_general_command(SPIF_RDSR, SPI_NO_ADDRESS_COMMAND, NULL, 0, status_value,

drivers/UARTSerial.cpp

@@ -19,12 +19,7 @@
 #if (DEVICE_SERIAL && DEVICE_INTERRUPTIN)
 
 #include "platform/mbed_poll.h"
-
-#if MBED_CONF_RTOS_PRESENT
-#include "rtos/ThisThread.h"
-#else
-#include "platform/mbed_wait_api.h"
-#endif
+#include "platform/mbed_thread.h"
 
 namespace mbed {
 
@@ -114,7 +109,7 @@ int UARTSerial::sync()
     while (!_txbuf.empty()) {
         api_unlock();
         // Doing better than wait would require TxIRQ to also do wake() when becoming empty. Worth it?
-        wait_ms(1);
+        thread_sleep_for(1);
         api_lock();
     }
 
@@ -178,7 +173,7 @@ ssize_t UARTSerial::write(const void *buffer, size_t length)
             }
             do {
                 api_unlock();
-                wait_ms(1); // XXX todo - proper wait, WFE for non-rtos ?
+                thread_sleep_for(1); // XXX todo - proper wait?
                 api_lock();
             } while (_txbuf.full());
         }
@@ -221,7 +216,7 @@ ssize_t UARTSerial::read(void *buffer, size_t length)
             return -EAGAIN;
         }
         api_unlock();
-        wait_ms(1);  // XXX todo - proper wait, WFE for non-rtos ?
+        thread_sleep_for(1);  // XXX todo - proper wait?
         api_lock();
     }
 
@@ -407,17 +402,6 @@ int UARTSerial::enable_output(bool enabled)
     return 0;
 }
 
-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
-    rtos::ThisThread::sleep_for(millisec);
-#else
-    ::wait_ms(millisec);
-#endif
-}
 } //namespace mbed
 
 #endif //(DEVICE_SERIAL && DEVICE_INTERRUPTIN)

drivers/UARTSerial.h

@@ -255,8 +255,6 @@ class UARTSerial : private SerialBase, public FileHandle, private NonCopyable<UA
 
 private:
 
-    void wait_ms(uint32_t millisec);
-
     /** SerialBase lock override */
     virtual void lock(void);
 

features/cellular/framework/AT/ATHandler.cpp

@@ -21,7 +21,6 @@
 #include "ATHandler.h"
 #include "mbed_poll.h"
 #include "FileHandle.h"
-#include "mbed_wait_api.h"
 #include "mbed_debug.h"
 #include "rtos/ThisThread.h"
 #include "Kernel.h"

platform/PlatformMutex.h

@@ -37,8 +37,9 @@
  * - When the RTOS is absent, all methods are defined as noop.
  */
 
-#ifdef MBED_CONF_RTOS_PRESENT
+#ifdef MBED_CONF_RTOS_API_PRESENT
 
+// rtos::Mutex is itself a dummy class if the RTOS API is present, but not the RTOS
 #include "rtos/Mutex.h"
 typedef rtos::Mutex PlatformMutex;
 

platform/mbed_poll.cpp

@@ -16,14 +16,7 @@
  */
 #include "mbed_poll.h"
 #include "FileHandle.h"
-#if MBED_CONF_RTOS_PRESENT
-#include "rtos/Kernel.h"
-#include "rtos/ThisThread.h"
-using namespace rtos;
-#else
-#include "drivers/Timer.h"
-#include "drivers/LowPowerTimer.h"
-#endif
+#include "mbed_thread.h"
 
 namespace mbed {
 
@@ -39,23 +32,10 @@ int poll(pollfh fhs[], unsigned nfhs, int timeout)
      * interested in. In future, his spinning behaviour will be replaced with
      * condition variables.
      */
-#if MBED_CONF_RTOS_PRESENT
     uint64_t start_time = 0;
     if (timeout > 0) {
-        start_time = Kernel::get_ms_count();
+        start_time = get_ms_count();
     }
-#define TIME_ELAPSED() int64_t(Kernel::get_ms_count() - start_time)
-#else
-#if MBED_CONF_PLATFORM_POLL_USE_LOWPOWER_TIMER
-    LowPowerTimer timer;
-#else
-    Timer timer;
-#endif
-    if (timeout > 0) {
-        timer.start();
-    }
-#define TIME_ELAPSED() timer.read_ms()
-#endif // MBED_CONF_RTOS_PRESENT
 
     int count = 0;
     for (;;) {
@@ -78,14 +58,12 @@ int poll(pollfh fhs[], unsigned nfhs, int timeout)
         }
 
         /* Nothing selected - this is where timeout handling would be needed */
-        if (timeout == 0 || (timeout > 0 && TIME_ELAPSED() > timeout)) {
+        if (timeout == 0 || (timeout > 0 && int64_t(get_ms_count() - start_time) > timeout)) {
             break;
         }
-#ifdef MBED_CONF_RTOS_PRESENT
         // TODO - proper blocking
         // wait for condition variable, wait queue whatever here
-        rtos::ThisThread::sleep_for(1);
-#endif
+        thread_sleep_for(1);
     }
     return count;
 }

platform/mbed_wait_api.h

@@ -25,6 +25,7 @@
 #ifndef MBED_WAIT_API_H
 #define MBED_WAIT_API_H
 
+#include "platform/mbed_toolchain.h"
 #include "platform/mbed_atomic.h"
 #include "device.h"
 
@@ -62,7 +63,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.14",
+                      "'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.
@@ -72,7 +82,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.14",
+                      "'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.
@@ -82,7 +101,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

@@ -16,7 +16,10 @@
  */
 
 // This implementation of the wait functions will be compiled only
-// if the RTOS is present.
+// if the RTOS is present. Note that we still use these old
+// bare metal versions of wait and wait_ms rather than using
+// thread_sleep_for for backwards compatibility. People should
+// be prompted to shift via their deprecation.
 #ifdef MBED_CONF_RTOS_PRESENT
 
 #include "platform/mbed_wait_api.h"
@@ -30,7 +33,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;
     }
 

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);