mbed official / mbed-dev

mbed library sources. Supersedes mbed-src.

Dependents:   Nucleo_Hello_Encoder BLE_iBeaconScan AM1805_DEMO DISCO-F429ZI_ExportTemplate1 ... more

platform/mbed_power_mgmt.h@189:f392fc9709a3, 2019-02-20 (annotated)

Committer:
AnnaBridge
Date:
Wed Feb 20 22:31:08 2019 +0000
Revision:
189:f392fc9709a3
Parent:
188:bcfe06ba3d64 
mbed library release version 165

Who changed what in which revision?

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