Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
mbed_wait_api.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2019 ARM Limited
3  * SPDX-License-Identifier: Apache-2.0
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 #ifndef MBED_WAIT_API_H
18 #define MBED_WAIT_API_H
19 
20 #include "platform/mbed_toolchain.h"
21 #include "platform/mbed_atomic.h"
22 #include "device.h"
23 
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27 
28 /** \addtogroup platform-public-api */
29 /** @{*/
30 
31 /**
32  * \defgroup platform_wait_api wait_api functions
33  * @{
34  */
35 
36 /** Generic wait functions.
37  *
38  * These provide simple NOP type wait capabilities.
39  *
40  * Example:
41  * @code
42  * #include "mbed.h"
43  *
44  * DigitalOut heartbeat(LED1);
45  *
46  * int main() {
47  * while (1) {
48  * heartbeat = 1;
49  * wait(0.5);
50  * heartbeat = 0;
51  * wait(0.5);
52  * }
53  * }
54  * @endcode
55  */
56 
57 /** Waits for a number of seconds, with microsecond resolution (within
58  * the accuracy of single precision floating point).
59  *
60  * @param s number of seconds to wait
61  *
62  * @note
63  * If the RTOS is present, this function spins to get the exact number of microseconds for
64  * microsecond precision up to 10 milliseconds. If delay is larger than 10 milliseconds and not in ISR, it is the same as
65  * `wait_ms`. We recommend `wait_us` and `wait_ms` over `wait`.
66  *
67  * @deprecated
68  * 'wait' is deprecated in favor of explicit sleep functions. To sleep, 'wait' should be replaced by
69  * 'ThisThread::sleep_for' (C++) or 'thread_sleep_for' (C). If you wish to wait (without sleeping), call
70  * 'wait_us'. 'wait_us' is safe to call from ISR context.
71  */
72 MBED_DEPRECATED_SINCE("mbed-os-5.14",
73  "'wait' is deprecated in favor of explicit sleep functions. To sleep, 'wait' should be replaced by "
74  "'ThisThread::sleep_for' (C++) or 'thread_sleep_for' (C). If you wish to wait (without sleeping), call "
75  "'wait_us'. 'wait_us' is safe to call from ISR context.")
76 void wait(float s);
77 
78 /** Waits a number of milliseconds.
79  *
80  * @param ms the whole number of milliseconds to wait
81  *
82  * @note
83  * If the RTOS is present, it calls ThisThread::sleep_for(), which is same as CMSIS osDelay().
84  * You can't call this from interrupts, and it doesn't lock hardware sleep.
85  *
86  * @deprecated
87  * 'wait_ms' is deprecated in favor of explicit sleep functions. To sleep, 'wait_ms' should be replaced by
88  * 'ThisThread::sleep_for' (C++) or 'thread_sleep_for' (C). If you wish to wait (without sleeping), call
89  * 'wait_us'. 'wait_us' is safe to call from ISR context.
90  */
91 MBED_DEPRECATED_SINCE("mbed-os-5.14",
92  "'wait_ms' is deprecated in favor of explicit sleep functions. To sleep, 'wait_ms' should be replaced by "
93  "'ThisThread::sleep_for' (C++) or 'thread_sleep_for' (C). If you wish to wait (without sleeping), call "
94  "'wait_us'. 'wait_us' is safe to call from ISR context.")
95 void wait_ms(int ms);
96 
97 /** Waits a number of microseconds.
98  *
99  * @param us the whole number of microseconds to wait
100  *
101  * @note
102  * This function always spins to get the exact number of microseconds.
103  * This will affect power and multithread performance. Therefore, spinning for
104  * millisecond wait is not recommended, and ThisThread::sleep_for should
105  * be used instead.
106  *
107  * @note You may call this function from ISR context, but large delays may
108  * impact system stability - interrupt handlers should take less than
109  * 50us.
110  */
111 void wait_us(int us);
112 
113 /** Waits a number of nanoseconds.
114  *
115  * This function spins the CPU to produce a small delay. It should normally
116  * only be used for delays of 10us (10000ns) or less. As it is calculated
117  * based on the expected execution time of a software loop, it may well run
118  * slower than requested based on activity from other threads and interrupts.
119  * If greater precision is required, this can be called from inside a critical
120  * section.
121  *
122  * @param ns the number of nanoseconds to wait
123  *
124  * @note
125  * wait_us() will likely give more precise time than wait_ns for large-enough
126  * delays, as it is based on a timer, but its set-up time may be excessive
127  * for the smallest microsecond counts, at which point wait_ns() is better.
128  *
129  * @note
130  * Any delay larger than a millisecond (1000000ns) is liable to cause
131  * overflow in the internal loop calculation. You shouldn't normally be
132  * using this for such large delays anyway in real code, but be aware if
133  * calibrating. Make repeated calls for longer test runs.
134  *
135  * @note You may call this function from ISR context.
136  *
137  */
138 void wait_ns(unsigned int ns);
139 
140 /* Optimize if we know the rate */
141 #if DEVICE_USTICKER && defined US_TICKER_PERIOD_NUM
142 void _wait_us_ticks(uint32_t ticks);
143 void _wait_us_generic(unsigned int us);
144 
145 /* Further optimization if we know us_ticker is always running */
146 #if MBED_CONF_TARGET_INIT_US_TICKER_AT_BOOT
147 #define _us_ticker_is_initialized true
148 #else
149 extern bool _us_ticker_initialized;
150 #define _us_ticker_is_initialized core_util_atomic_load_bool(&_us_ticker_initialized)
151 #endif
152 
153 #if US_TICKER_PERIOD_DEN == 1 && (US_TICKER_MASK * US_TICKER_PERIOD_NUM) >= 0xFFFFFFFF
154 /* Ticker is wide and slow enough to have full 32-bit range - can always use it directly */
155 #define _us_is_small_enough(us) true
156 #else
157 /* Threshold is determined by specification of us_ticker_api.h - smallest possible
158  * time range for the us_ticker is 16-bit 8MHz, which gives 8192us. This also leaves
159  * headroom for the multiplication in 32 bits.
160  */
161 #define _us_is_small_enough(us) ((us) < 8192)
162 #endif
163 
164 /* Speed optimisation for small wait_us. Care taken to preserve binary compatibility */
165 inline void _wait_us_inline(unsigned int us)
166 {
167  /* Threshold is determined by specification of us_ticker_api.h - smallest possible
168  * time range for the us_ticker is 16-bit 8MHz, which gives 8192us. This also leaves
169  * headroom for the multiplication in 32 bits.
170  */
171  if (_us_is_small_enough(us) && _us_ticker_is_initialized) {
172  const uint32_t ticks = ((us * US_TICKER_PERIOD_DEN) + US_TICKER_PERIOD_NUM - 1) / US_TICKER_PERIOD_NUM;
173  _wait_us_ticks(ticks);
174  } else {
175  _wait_us_generic(us);
176  }
177 }
178 
179 #define wait_us(us) _wait_us_inline(us)
180 #endif // Known-rate, initialised timer
181 
182 #ifdef __cplusplus
183 }
184 #endif
185 
186 #endif
187 
188 /** @}*/
189 /** @}*/
wait_us
void wait_us(int us)
Waits a number of microseconds.
wait_ms
void wait_ms(int ms)
Waits a number of milliseconds.
wait_ns
void wait_ns(unsigned int ns)
Waits a number of nanoseconds.
wait
void wait(float s)
Generic wait functions.
thread_sleep_for
void thread_sleep_for(uint32_t millisec)
Sleep for a specified time period in millisec:
MBED_DEPRECATED_SINCE
#define MBED_DEPRECATED_SINCE(D, M)
MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warnin...
Definition: mbed_toolchain.h:378
sleep
static void sleep(void)
Send the microcontroller to sleep.
Definition: mbed_power_mgmt.h:195
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.