schneider françois / mbed-dev

helpfor studient

Dependents:   STM32_F103-C8T6basecanblink_led

Fork of mbed-dev by mbed official

platform/mbed_power_mgmt.h@186:9c2029bfadbe, 2018-04-20 (annotated)

Committer:
Anna Bridge
Date:
Fri Apr 20 11:31:35 2018 +0100
Revision:
186:9c2029bfadbe
Parent:
185:08ed48f1de7f 
Update to latest version of mbed lib

Who changed what in which revision?

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