From fc8e8f67c600a46ccf17d473bd2cbf3ec4796e54 Mon Sep 17 00:00:00 2001 From: Kevin Bracey Date: Mon, 28 Jan 2019 12:49:01 +0200 Subject: [PATCH] Deprecate wait/wait_ms APIs --- .../AT/at_cellularsms/unittest.cmake | 2 +- .../framework/AT/athandler/unittest.cmake | 1 - UNITTESTS/stubs/UARTSerial_stub.cpp | 5 ---- .../COMPONENT_SPIF/SPIFBlockDevice.cpp | 4 +-- drivers/UARTSerial.cpp | 24 +++------------ drivers/UARTSerial.h | 2 -- features/cellular/framework/AT/ATHandler.cpp | 1 - platform/PlatformMutex.h | 3 +- platform/mbed_poll.cpp | 30 +++---------------- platform/mbed_wait_api.h | 21 ++++++++++++- platform/mbed_wait_api_rtos.cpp | 7 +++-- rtos/ThisThread.h | 2 ++ 12 files changed, 40 insertions(+), 62 deletions(-) diff --git a/UNITTESTS/features/cellular/framework/AT/at_cellularsms/unittest.cmake b/UNITTESTS/features/cellular/framework/AT/at_cellularsms/unittest.cmake index 616b49e49a..484235c818 100644 --- a/UNITTESTS/features/cellular/framework/AT/at_cellularsms/unittest.cmake +++ b/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 ) diff --git a/UNITTESTS/features/cellular/framework/AT/athandler/unittest.cmake b/UNITTESTS/features/cellular/framework/AT/athandler/unittest.cmake index db74d7adc7..b3e55b5260 100644 --- a/UNITTESTS/features/cellular/framework/AT/athandler/unittest.cmake +++ b/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 diff --git a/UNITTESTS/stubs/UARTSerial_stub.cpp b/UNITTESTS/stubs/UARTSerial_stub.cpp index ebfd83d203..7b03671fe6 100644 --- a/UNITTESTS/stubs/UARTSerial_stub.cpp +++ b/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) { diff --git a/components/storage/blockdevice/COMPONENT_SPIF/SPIFBlockDevice.cpp b/components/storage/blockdevice/COMPONENT_SPIF/SPIFBlockDevice.cpp index 0882276649..cce0957afd 100644 --- a/components/storage/blockdevice/COMPONENT_SPIF/SPIFBlockDevice.cpp +++ b/components/storage/blockdevice/COMPONENT_SPIF/SPIFBlockDevice.cpp @@ -15,10 +15,10 @@ */ #include "SPIFBlockDevice.h" +#include "rtos/ThisThread.h" #include "mbed_critical.h" #include -#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, diff --git a/drivers/UARTSerial.cpp b/drivers/UARTSerial.cpp index e9213555d7..37e992c7ff 100644 --- a/drivers/UARTSerial.cpp +++ b/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) diff --git a/drivers/UARTSerial.h b/drivers/UARTSerial.h index 2959ce77e2..5f6d6faee6 100644 --- a/drivers/UARTSerial.h +++ b/drivers/UARTSerial.h @@ -255,8 +255,6 @@ public: private: - void wait_ms(uint32_t millisec); - /** SerialBase lock override */ virtual void lock(void); diff --git a/features/cellular/framework/AT/ATHandler.cpp b/features/cellular/framework/AT/ATHandler.cpp index d016415a96..0f599d7532 100644 --- a/features/cellular/framework/AT/ATHandler.cpp +++ b/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" diff --git a/platform/PlatformMutex.h b/platform/PlatformMutex.h index a63672dc0c..3f751c4149 100644 --- a/platform/PlatformMutex.h +++ b/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; diff --git a/platform/mbed_poll.cpp b/platform/mbed_poll.cpp index a1e7627616..b25c8f043a 100644 --- a/platform/mbed_poll.cpp +++ b/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; } diff --git a/platform/mbed_wait_api.h b/platform/mbed_wait_api.h index a614212092..f6e72266a8 100644 --- a/platform/mbed_wait_api.h +++ b/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 diff --git a/platform/mbed_wait_api_rtos.cpp b/platform/mbed_wait_api_rtos.cpp index b4333ba45f..da2c0f464e 100644 --- a/platform/mbed_wait_api_rtos.cpp +++ b/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; } diff --git a/rtos/ThisThread.h b/rtos/ThisThread.h index 492ad88113..c7278c7f6c 100644 --- a/rtos/ThisThread.h +++ b/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);