Kev Mann / mbed-dev-OS5_10_4

RTC auf true

platform/mbed_power_mgmt.h@2:7aab896b1a3b, 2019-03-13 (annotated)

Committer:
kevman
Date:
Wed Mar 13 11:03:24 2019 +0000
Revision:
2:7aab896b1a3b
Parent:
0:38ceb79fef03 
2019-03-13

Who changed what in which revision?

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