Keil Studio Cloud
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  */
134 void sleep_manager_lock_deep_sleep_internal(void);
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  */
143 void sleep_manager_unlock_deep_sleep_internal(void);
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  */
149 bool sleep_manager_can_deep_sleep(void);
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  */
160 bool sleep_manager_can_deep_sleep_test_check(void);
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)
199  sleep_manager_sleep_auto();
200 #endif /* (MBED_CONF_RTOS_PRESENT == 0) || (DEVICE_SYSTICK_CLK_OFF_DURING_SLEEP == 0) || defined(MBED_TICKLESS) */
201 #endif /* DEVICE_SLEEP */
202 }
203 
204 /** Provides the time spent in sleep mode since boot.
205  *
206  * @return Time spent in sleep
207  * @note Works only if platform supports LP ticker.
208  */
209 us_timestamp_t mbed_time_sleep(void);
210 
211 /** Provides the time spent in deep sleep mode since boot.
212  *
213  * @return Time spent in deep sleep
214  * @note Works only if platform supports LP ticker.
215  */
216 us_timestamp_t mbed_time_deepsleep(void);
217 
218 /** Provides the time spent in idle mode since boot.
219  *
220  * @return Idle thread time.
221  * @note Works only if platform supports LP ticker.
222  */
223 us_timestamp_t mbed_time_idle(void);
224 
225 /** Provides the time since the system is up i.e. boot.
226  *
227  * @return System uptime.
228  * @note Works only if platform supports LP ticker.
229  */
230 us_timestamp_t mbed_uptime(void);
231 
232 /** @}*/
233 
234 /** Resets the processor and most of the sub-system
235  *
236  * @note Does not affect the debug sub-system
237  */
238 MBED_NORETURN static inline void system_reset(void)
239 {
240  NVIC_SystemReset();
241 }
242 
243 #ifdef __cplusplus
244 }
245 #endif
246 
247 #endif
248 
249 /** @}*/
250 /** @}*/
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.
system_reset
static MBED_NORETURN void system_reset(void)
Resets the processor and most of the sub-system.
Definition: mbed_power_mgmt.h:238
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:323
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.
sleep_manager_lock_deep_sleep_internal
void sleep_manager_lock_deep_sleep_internal(void)
Lock the deep sleep mode.
sleep
static void sleep(void)
Send the microcontroller to sleep.
Definition: mbed_power_mgmt.h:195
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.