Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
mbed_power_mgmt.h
1 /** \addtogroup platform */
2 /** @{*/
3 /**
4  * \defgroup platform_power_mgmt Power management functions
5  * @{
6  */
7 
8 /* mbed Microcontroller Library
9  * Copyright (c) 2006-2018 ARM Limited
10  * SPDX-License-Identifier: Apache-2.0
11  *
12  * Licensed under the Apache License, Version 2.0 (the "License");
13  * you may not use this file except in compliance with the License.
14  * You may obtain a copy of the License at
15  *
16  * http://www.apache.org/licenses/LICENSE-2.0
17  *
18  * Unless required by applicable law or agreed to in writing, software
19  * distributed under the License is distributed on an "AS IS" BASIS,
20  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21  * See the License for the specific language governing permissions and
22  * limitations under the License.
23  */
24 #ifndef MBED_POWER_MGMT_H
25 #define MBED_POWER_MGMT_H
26 
27 #include "hal/sleep_api.h"
28 #include "mbed_toolchain.h"
29 #include "hal/ticker_api.h"
30 #include <stdbool.h>
31 
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35 
36 /**
37  * @defgroup hal_sleep_manager Sleep manager API
38  * The sleep manager provides API to automatically select sleep mode.
39  *
40  * There are two sleep modes:
41  * - sleep
42  * - deepsleep
43  *
44  * Use locking/unlocking deepsleep for drivers that depend on features that
45  * are not allowed (=disabled) during the deepsleep. For instance, high frequency
46  * clocks.
47  *
48  * # Defined behavior
49  * * The lock is a counter
50  * * The lock can be locked up to USHRT_MAX - Verified by ::test_lock_eq_ushrt_max
51  * * The lock has to be equally unlocked as locked - Verified by ::test_lock_eq_ushrt_max
52  * * The function sleep_manager_lock_deep_sleep_internal() locks the automatic deep mode selection - Verified by ::test_lock_unlock
53  * * The function sleep_manager_unlock_deep_sleep_internal() unlocks the automatic deep mode selection - Verified by ::test_lock_unlock
54  * * The function sleep_manager_sleep_auto() chooses the sleep or deep sleep modes based on the lock - Verified by ::test_sleep_auto
55  * * The function sleep_manager_lock_deep_sleep_internal() is IRQ and thread safe - Verified by ::sleep_manager_multithread_test and ::sleep_manager_irq_test
56  * * The function sleep_manager_unlock_deep_sleep_internal() is IRQ and thread safe - Verified by ::sleep_manager_multithread_test and ::sleep_manager_irq_test
57  * * The function sleep_manager_sleep_auto() is IRQ and thread safe
58  *
59  * Example:
60  * @code
61  *
62  * void driver::handler()
63  * {
64  * if (_sensor.get_event()) {
65  * // any event - we are finished, unlock the deepsleep
66  * sleep_manager_unlock_deep_sleep();
67  * _callback();
68  * }
69  * }
70  *
71  * int driver::measure(event_t event, callback_t& callback)
72  * {
73  * _callback = callback;
74  * sleep_manager_lock_deep_sleep();
75  * // start async transaction, we are waiting for an event
76  * return _sensor.start(event, callback);
77  * }
78  * @endcode
79  * @{
80  */
81 
82 /**
83  * @defgroup hal_sleep_manager_tests Sleep manager API tests
84  * Tests to validate the proper implementation of the sleep manager
85  *
86  * To run the sleep manager hal tests use the command:
87  *
88  * mbed test -t <toolchain> -m <target> -n tests-mbed_hal-sleep_manager*
89  *
90  */
91 
92 #ifdef MBED_SLEEP_TRACING_ENABLED
93 
94 void sleep_tracker_lock(const char *const filename, int line);
95 void sleep_tracker_unlock(const char *const filename, int line);
96 
97 #define sleep_manager_lock_deep_sleep() \
98  do \
99  { \
100  sleep_manager_lock_deep_sleep_internal(); \
101  sleep_tracker_lock(MBED_FILENAME, __LINE__); \
102  } while (0);
103 
104 #define sleep_manager_unlock_deep_sleep() \
105  do \
106  { \
107  sleep_manager_unlock_deep_sleep_internal(); \
108  sleep_tracker_unlock(MBED_FILENAME, __LINE__); \
109  } while (0);
110 
111 #else
112 
113 #define sleep_manager_lock_deep_sleep() \
114  sleep_manager_lock_deep_sleep_internal()
115 
116 #define sleep_manager_unlock_deep_sleep() \
117  sleep_manager_unlock_deep_sleep_internal()
118 
119 #endif // MBED_SLEEP_TRACING_ENABLED
120 
121 /** Lock the deep sleep mode
122  *
123  * This locks the automatic deep mode selection.
124  * sleep_manager_sleep_auto() will ignore deepsleep mode if
125  * this function is invoked at least once (the internal counter is non-zero)
126  *
127  * Use this locking mechanism for interrupt driven API that are
128  * running in the background and deepsleep could affect their functionality
129  *
130  * The lock is a counter, can be locked up to USHRT_MAX
131  * This function is IRQ and thread safe
132  */
133 void sleep_manager_lock_deep_sleep_internal(void);
134 
135 /** Unlock the deep sleep mode
136  *
137  * Use unlocking in pair with sleep_manager_lock_deep_sleep().
138  *
139  * The lock is a counter, should be equally unlocked as locked
140  * This function is IRQ and thread safe
141  */
142 void sleep_manager_unlock_deep_sleep_internal(void);
143 
144 /** Get the status of deep sleep allowance for a target
145  *
146  * @return true if a target can go to deepsleep, false otherwise
147  */
148 bool sleep_manager_can_deep_sleep(void);
149 
150 /** Check if the target can deep sleep within a period of time
151  *
152  * This function in intended for use in testing. The amount
153  * of time this functions waits for deeps sleep to be available
154  * is currently 2ms. This may change in the future depending
155  * on testing requirements.
156  *
157  * @return true if a target can go to deepsleep, false otherwise
158  */
159 bool sleep_manager_can_deep_sleep_test_check(void);
160 
161 /** Enter auto selected sleep mode. It chooses the sleep or deepsleep modes based
162  * on the deepsleep locking counter
163  *
164  * This function is IRQ and thread safe
165  *
166  * @note
167  * If MBED_DEBUG is defined, only hal_sleep is allowed. This ensures the debugger
168  * to be active for debug modes.
169  *
170  */
171 void sleep_manager_sleep_auto(void);
172 
173 /** Send the microcontroller to sleep
174  *
175  * @note This function can be a noop if not implemented by the platform.
176  * @note This function will be a noop in debug mode (debug build profile when MBED_DEBUG is defined).
177  * @note This function will be a noop if the following conditions are met:
178  * - The RTOS is present
179  * - The processor turn off the Systick clock during sleep
180  * - The target does not implement tickless mode
181  *
182  * The processor is setup ready for sleep, and sent to sleep using __WFI(). In this mode, the
183  * system clock to the core is stopped until a reset or an interrupt occurs. This eliminates
184  * dynamic power used by the processor, memory systems and buses. The processor, peripheral and
185  * memory state are maintained, and the peripherals continue to work and can generate interrupts.
186  *
187  * The processor can be woken up by any internal peripheral interrupt or external pin interrupt.
188  *
189  * @note
190  * The mbed interface semihosting is disconnected as part of going to sleep, and can not be restored.
191  * Flash re-programming and the USB serial port will remain active, but the mbed program will no longer be
192  * able to access the LocalFileSystem
193  */
194 static inline void sleep(void)
195 {
196 #if DEVICE_SLEEP
197 #if (MBED_CONF_RTOS_PRESENT == 0) || (DEVICE_SYSTICK_CLK_OFF_DURING_SLEEP == 0) || defined(MBED_TICKLESS)
198  sleep_manager_sleep_auto();
199 #endif /* (MBED_CONF_RTOS_PRESENT == 0) || (DEVICE_SYSTICK_CLK_OFF_DURING_SLEEP == 0) || defined(MBED_TICKLESS) */
200 #endif /* DEVICE_SLEEP */
201 }
202 
203 /** Send the microcontroller to deep sleep
204  *
205  * @deprecated
206  * Do not use this function. Applications should use sleep() API which puts the system in deepsleep mode if supported.
207  *
208  * @note This function can be a noop if not implemented by the platform.
209  * @note This function will be a noop in debug mode (debug build profile when MBED_DEBUG is defined)
210  *
211  * This processor is setup ready for deep sleep, and sent to sleep. This mode
212  * has the same sleep features as sleep plus it powers down peripherals and clocks. All state
213  * is still maintained.
214  *
215  * The processor can only be woken up by an external interrupt on a pin or a watchdog timer.
216  *
217  * @note
218  * The mbed interface semihosting is disconnected as part of going to sleep, and can not be restored.
219  * Flash re-programming and the USB serial port will remain active, but the mbed program will no longer be
220  * able to access the LocalFileSystem
221  */
222 
223 MBED_DEPRECATED_SINCE("mbed-os-5.6", "One entry point for an application, use sleep()")
224 static inline void deepsleep(void)
225 {
226 #if DEVICE_SLEEP
227  sleep_manager_sleep_auto();
228 #endif /* DEVICE_SLEEP */
229 }
230 
231 /** Provides the time spent in sleep mode since boot.
232  *
233  * @return Time spent in sleep
234  * @note Works only if platform supports LP ticker.
235  */
236 us_timestamp_t mbed_time_sleep(void);
237 
238 /** Provides the time spent in deep sleep mode since boot.
239  *
240  * @return Time spent in deep sleep
241  * @note Works only if platform supports LP ticker.
242  */
243 us_timestamp_t mbed_time_deepsleep(void);
244 
245 /** Provides the time spent in idle mode since boot.
246  *
247  * @return Idle thread time.
248  * @note Works only if platform supports LP ticker.
249  */
250 us_timestamp_t mbed_time_idle(void);
251 
252 /** Provides the time since the system is up i.e. boot.
253  *
254  * @return System uptime.
255  * @note Works only if platform supports LP ticker.
256  */
257 us_timestamp_t mbed_uptime(void);
258 
259 /** @}*/
260 
261 /** Resets the processor and most of the sub-system
262  *
263  * @note Does not affect the debug sub-system
264  */
265 MBED_NORETURN static inline void system_reset(void)
266 {
267  NVIC_SystemReset();
268 }
269 
270 #ifdef __cplusplus
271 }
272 #endif
273 
274 #endif
275 
276 /** @}*/
277 /** @}*/
sleep_manager_can_deep_sleep
bool sleep_manager_can_deep_sleep(void)
Get the status of deep sleep allowance for a target.
us_timestamp_t
uint64_t us_timestamp_t
A us timestamp stored in a 64 bit integer.
Definition: ticker_api.h:39
mbed_time_idle
us_timestamp_t mbed_time_idle(void)
Provides the time spent in idle mode since boot.
sleep_manager_unlock_deep_sleep_internal
void sleep_manager_unlock_deep_sleep_internal(void)
Unlock the deep sleep mode.
deepsleep
static void deepsleep(void)
Send the microcontroller to deep sleep.
Definition: mbed_power_mgmt.h:224
mbed_uptime
us_timestamp_t mbed_uptime(void)
Provides the time since the system is up i.e.
mbed_time_deepsleep
us_timestamp_t mbed_time_deepsleep(void)
Provides the time spent in deep sleep mode since boot.
MBED_NORETURN
#define MBED_NORETURN
MBED_NORETURN Declare a function that will never return.
Definition: mbed_toolchain.h:314
sleep_manager_can_deep_sleep_test_check
bool sleep_manager_can_deep_sleep_test_check(void)
Check if the target can deep sleep within a period of time.
system_reset
static void system_reset(void)
Resets the processor and most of the sub-system.
Definition: mbed_power_mgmt.h:265
sleep_manager_lock_deep_sleep_internal
void sleep_manager_lock_deep_sleep_internal(void)
Lock the deep sleep mode.
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:379
sleep
static void sleep(void)
Send the microcontroller to sleep.
Definition: mbed_power_mgmt.h:194
sleep_manager_sleep_auto
void sleep_manager_sleep_auto(void)
Enter auto selected sleep mode.
mbed_time_sleep
us_timestamp_t mbed_time_sleep(void)
Provides the time spent in sleep mode since boot.
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.