mbed_wait_api.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2019 ARM Limited
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 #ifndef MBED_WAIT_API_H
00018 #define MBED_WAIT_API_H
00019 
00020 #include "platform/mbed_toolchain.h"
00021 #include "platform/mbed_atomic.h"
00022 #include "device.h"
00023 
00024 #ifdef __cplusplus
00025 extern "C" {
00026 #endif
00027 
00028 /** \addtogroup platform-public-api */
00029 /** @{*/
00030 
00031 /**
00032  * \defgroup platform_wait_api wait_api functions
00033  * @{
00034  */
00035 
00036 /** Generic wait functions.
00037  *
00038  * These provide simple NOP type wait capabilities.
00039  *
00040  * Example:
00041  * @code
00042  * #include "mbed.h"
00043  *
00044  * DigitalOut heartbeat(LED1);
00045  *
00046  * int main() {
00047  *     while (1) {
00048  *         heartbeat = 1;
00049  *         wait(0.5);
00050  *         heartbeat = 0;
00051  *         wait(0.5);
00052  *     }
00053  * }
00054  * @endcode
00055  */
00056 
00057 /** Waits for a number of seconds, with microsecond resolution (within
00058  *  the accuracy of single precision floating point).
00059  *
00060  *  @param s number of seconds to wait
00061  *
00062  *  @note
00063  *    If the RTOS is present, this function spins to get the exact number of microseconds for
00064  *    microsecond precision up to 10 milliseconds. If delay is larger than 10 milliseconds and not in ISR, it is the same as
00065  *    `wait_ms`. We recommend `wait_us` and `wait_ms` over `wait`.
00066  *
00067  *  @deprecated
00068  *    'wait' is deprecated in favor of explicit sleep functions. To sleep, 'wait' should be replaced by
00069  *    'ThisThread::sleep_for' (C++) or 'thread_sleep_for' (C). If you wish to wait (without sleeping), call
00070  *    'wait_us'. 'wait_us' is safe to call from ISR context.
00071  */
00072 MBED_DEPRECATED_SINCE ("mbed-os-5.14",
00073                       "'wait' is deprecated in favor of explicit sleep functions. To sleep, 'wait' should be replaced by "
00074                       "'ThisThread::sleep_for' (C++) or 'thread_sleep_for' (C). If you wish to wait (without sleeping), call "
00075                       "'wait_us'. 'wait_us' is safe to call from ISR context.")
00076 void wait(float s);
00077 
00078 /** Waits a number of milliseconds.
00079  *
00080  *  @param ms the whole number of milliseconds to wait
00081  *
00082  *  @note
00083  *    If the RTOS is present, it calls ThisThread::sleep_for(), which is same as CMSIS osDelay().
00084  *    You can't call this from interrupts, and it doesn't lock hardware sleep.
00085  *
00086  *  @deprecated
00087  *    'wait_ms' is deprecated in favor of explicit sleep functions. To sleep, 'wait_ms' should be replaced by
00088  *    'ThisThread::sleep_for' (C++) or 'thread_sleep_for' (C). If you wish to wait (without sleeping), call
00089  *    'wait_us'. 'wait_us' is safe to call from ISR context.
00090  */
00091 MBED_DEPRECATED_SINCE ("mbed-os-5.14",
00092                       "'wait_ms' is deprecated in favor of explicit sleep functions. To sleep, 'wait_ms' should be replaced by "
00093                       "'ThisThread::sleep_for' (C++) or 'thread_sleep_for' (C). If you wish to wait (without sleeping), call "
00094                       "'wait_us'. 'wait_us' is safe to call from ISR context.")
00095 void wait_ms(int ms);
00096 
00097 /** Waits a number of microseconds.
00098  *
00099  *  @param us the whole number of microseconds to wait
00100  *
00101  *  @note
00102  *    This function always spins to get the exact number of microseconds.
00103  *    This will affect power and multithread performance. Therefore, spinning for
00104  *    millisecond wait is not recommended, and ThisThread::sleep_for should
00105  *    be used instead.
00106  *
00107  *  @note You may call this function from ISR context, but large delays may
00108  *    impact system stability - interrupt handlers should take less than
00109  *    50us.
00110  */
00111 void wait_us(int us);
00112 
00113 /** Waits a number of nanoseconds.
00114  *
00115  * This function spins the CPU to produce a small delay. It should normally
00116  * only be used for delays of 10us (10000ns) or less. As it is calculated
00117  * based on the expected execution time of a software loop, it may well run
00118  * slower than requested based on activity from other threads and interrupts.
00119  * If greater precision is required, this can be called from inside a critical
00120  * section.
00121  *
00122  *  @param ns the number of nanoseconds to wait
00123  *
00124  *  @note
00125  *    wait_us() will likely give more precise time than wait_ns for large-enough
00126  *    delays, as it is based on a timer, but its set-up time may be excessive
00127  *    for the smallest microsecond counts, at which point wait_ns() is better.
00128  *
00129  *  @note
00130  *    Any delay larger than a millisecond (1000000ns) is liable to cause
00131  *    overflow in the internal loop calculation. You shouldn't normally be
00132  *    using this for such large delays anyway in real code, but be aware if
00133  *    calibrating. Make repeated calls for longer test runs.
00134  *
00135  *  @note You may call this function from ISR context.
00136  *
00137  */
00138 void wait_ns(unsigned int ns);
00139 
00140 /* Optimize if we know the rate */
00141 #if DEVICE_USTICKER && defined US_TICKER_PERIOD_NUM
00142 void _wait_us_ticks(uint32_t ticks);
00143 void _wait_us_generic(unsigned int us);
00144 
00145 /* Further optimization if we know us_ticker is always running */
00146 #if MBED_CONF_TARGET_INIT_US_TICKER_AT_BOOT
00147 #define _us_ticker_is_initialized true
00148 #else
00149 extern bool _us_ticker_initialized;
00150 #define _us_ticker_is_initialized core_util_atomic_load_bool(&_us_ticker_initialized)
00151 #endif
00152 
00153 #if US_TICKER_PERIOD_DEN == 1 && (US_TICKER_MASK * US_TICKER_PERIOD_NUM) >= 0xFFFFFFFF
00154 /* Ticker is wide and slow enough to have full 32-bit range - can always use it directly */
00155 #define _us_is_small_enough(us) true
00156 #else
00157 /* Threshold is determined by specification of us_ticker_api.h - smallest possible
00158  * time range for the us_ticker is 16-bit 8MHz, which gives 8192us. This also leaves
00159  * headroom for the multiplication in 32 bits.
00160  */
00161 #define _us_is_small_enough(us) ((us) < 8192)
00162 #endif
00163 
00164 /* Speed optimisation for small wait_us. Care taken to preserve binary compatibility */
00165 inline void _wait_us_inline(unsigned int us)
00166 {
00167     /* Threshold is determined by specification of us_ticker_api.h - smallest possible
00168      * time range for the us_ticker is 16-bit 8MHz, which gives 8192us. This also leaves
00169      * headroom for the multiplication in 32 bits.
00170      */
00171     if (_us_is_small_enough(us) && _us_ticker_is_initialized) {
00172         const uint32_t ticks = ((us * US_TICKER_PERIOD_DEN) + US_TICKER_PERIOD_NUM - 1) / US_TICKER_PERIOD_NUM;
00173         _wait_us_ticks(ticks);
00174     } else {
00175         _wait_us_generic(us);
00176     }
00177 }
00178 
00179 #define wait_us(us) _wait_us_inline(us)
00180 #endif // Known-rate, initialised timer
00181 
00182 #ifdef __cplusplus
00183 }
00184 #endif
00185 
00186 #endif
00187 
00188 /** @}*/
00189 /** @}*/