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