mbed_power_mgmt.h

00001 /** \addtogroup platform */
00002 /** @{*/
00003 /**
00004  * \defgroup platform_power_mgmt Power management functions
00005  * @{
00006  */
00007 
00008 /* mbed Microcontroller Library
00009  * Copyright (c) 2006-2018 ARM Limited
00010  *
00011  * Licensed under the Apache License, Version 2.0 (the "License");
00012  * you may not use this file except in compliance with the License.
00013  * You may obtain a copy of the License at
00014  *
00015  *     http://www.apache.org/licenses/LICENSE-2.0
00016  *
00017  * Unless required by applicable law or agreed to in writing, software
00018  * distributed under the License is distributed on an "AS IS" BASIS,
00019  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00020  * See the License for the specific language governing permissions and
00021  * limitations under the License.
00022  */
00023 #ifndef MBED_POWER_MGMT_H
00024 #define MBED_POWER_MGMT_H
00025 
00026 #include "sleep_api.h"
00027 #include "mbed_toolchain.h"
00028 #include <stdbool.h>
00029 
00030 #ifdef __cplusplus
00031 extern "C" {
00032 #endif
00033 
00034 /** Sleep manager API
00035  * The sleep manager provides API to automatically select sleep mode.
00036  *
00037  * There are two sleep modes:
00038  * - sleep
00039  * - deepsleep
00040  *
00041  * Use locking/unlocking deepsleep for drivers that depend on features that
00042  * are not allowed (=disabled) during the deepsleep. For instance, high frequency
00043  * clocks.
00044  *
00045  * Example:
00046  * @code
00047  *
00048  * void driver::handler()
00049  * {
00050  *     if (_sensor.get_event()) {
00051  *         // any event - we are finished, unlock the deepsleep
00052  *         sleep_manager_unlock_deep_sleep();
00053  *         _callback();
00054  *     }
00055  * }
00056  *
00057  * int driver::measure(event_t event, callback_t& callback)
00058  * {
00059  *      _callback = callback;
00060  *      sleep_manager_lock_deep_sleep();
00061  *      // start async transaction, we are waiting for an event
00062  *      return _sensor.start(event, callback);
00063  * }
00064  * @endcode
00065  */
00066 #ifdef MBED_SLEEP_TRACING_ENABLED
00067 
00068 void sleep_tracker_lock(const char *const filename, int line);
00069 void sleep_tracker_unlock(const char *const filename, int line);
00070 
00071 #define sleep_manager_lock_deep_sleep()              \
00072     do                                               \
00073     {                                                \
00074         sleep_manager_lock_deep_sleep_internal();    \
00075         sleep_tracker_lock(MBED_FILENAME, __LINE__); \
00076     } while (0);
00077 
00078 #define sleep_manager_unlock_deep_sleep()              \
00079     do                                                 \
00080     {                                                  \
00081         sleep_manager_unlock_deep_sleep_internal();    \
00082         sleep_tracker_unlock(MBED_FILENAME, __LINE__); \
00083     } while (0);
00084 
00085 #else
00086 
00087 #define sleep_manager_lock_deep_sleep() \
00088     sleep_manager_lock_deep_sleep_internal()
00089 
00090 #define sleep_manager_unlock_deep_sleep() \
00091     sleep_manager_unlock_deep_sleep_internal()
00092 
00093 #endif // MBED_SLEEP_TRACING_ENABLED
00094 
00095 /** Lock the deep sleep mode
00096  *
00097  * This locks the automatic deep mode selection.
00098  * sleep_manager_sleep_auto() will ignore deepsleep mode if
00099  * this function is invoked at least once (the internal counter is non-zero)
00100  *
00101  * Use this locking mechanism for interrupt driven API that are
00102  * running in the background and deepsleep could affect their functionality
00103  *
00104  * The lock is a counter, can be locked up to USHRT_MAX
00105  * This function is IRQ and thread safe
00106  */
00107 void sleep_manager_lock_deep_sleep_internal(void);
00108 
00109 /** Unlock the deep sleep mode
00110  *
00111  * Use unlocking in pair with sleep_manager_lock_deep_sleep().
00112  *
00113  * The lock is a counter, should be equally unlocked as locked
00114  * This function is IRQ and thread safe
00115  */
00116 void sleep_manager_unlock_deep_sleep_internal(void);
00117 
00118 /** Get the status of deep sleep allowance for a target
00119  *
00120  * @return true if a target can go to deepsleep, false otherwise
00121  */
00122 bool sleep_manager_can_deep_sleep(void);
00123 
00124 /** Enter auto selected sleep mode. It chooses the sleep or deeepsleep modes based
00125  *  on the deepsleep locking counter
00126  *
00127  * This function is IRQ and thread safe
00128  *
00129  * @note
00130  * If MBED_DEBUG is defined, only hal_sleep is allowed. This ensures the debugger
00131  * to be active for debug modes.
00132  *
00133  */
00134 void sleep_manager_sleep_auto(void);
00135 
00136 /** Send the microcontroller to sleep
00137  *
00138  * @note This function can be a noop if not implemented by the platform.
00139  * @note This function will be a noop in debug mode (debug build profile when MBED_DEBUG is defined).
00140  * @note This function will be a noop while uVisor is in use.
00141  * @note This function will be a noop if the following conditions are met:
00142  *   - The RTOS is present
00143  *   - The processor turn off the Systick clock during sleep
00144  *   - The target does not implement tickless mode
00145  *
00146  * The processor is setup ready for sleep, and sent to sleep using __WFI(). In this mode, the
00147  * system clock to the core is stopped until a reset or an interrupt occurs. This eliminates
00148  * dynamic power used by the processor, memory systems and buses. The processor, peripheral and
00149  * memory state are maintained, and the peripherals continue to work and can generate interrupts.
00150  *
00151  * The processor can be woken up by any internal peripheral interrupt or external pin interrupt.
00152  *
00153  * @note
00154  *  The mbed interface semihosting is disconnected as part of going to sleep, and can not be restored.
00155  * Flash re-programming and the USB serial port will remain active, but the mbed program will no longer be
00156  * able to access the LocalFileSystem
00157  */
00158 static inline void sleep(void)
00159 {
00160 #if !(defined(FEATURE_UVISOR) && defined(TARGET_UVISOR_SUPPORTED))
00161 #if DEVICE_SLEEP
00162 #if (MBED_CONF_RTOS_PRESENT == 0) || (DEVICE_STCLK_OFF_DURING_SLEEP == 0) || defined(MBED_TICKLESS)
00163     sleep_manager_sleep_auto();
00164 #endif /* (MBED_CONF_RTOS_PRESENT == 0) || (DEVICE_STCLK_OFF_DURING_SLEEP == 0) || defined(MBED_TICKLESS) */
00165 #endif /* DEVICE_SLEEP */
00166 #endif /* !(defined(FEATURE_UVISOR) && defined(TARGET_UVISOR_SUPPORTED)) */
00167 }
00168 
00169 /** Send the microcontroller to deep sleep
00170  *
00171  * @note This function can be a noop if not implemented by the platform.
00172  * @note This function will be a noop in debug mode (debug build profile when MBED_DEBUG is defined)
00173  * @note This function will be a noop while uVisor is in use.
00174  *
00175  * This processor is setup ready for deep sleep, and sent to sleep. This mode
00176  * has the same sleep features as sleep plus it powers down peripherals and clocks. All state
00177  * is still maintained.
00178  *
00179  * The processor can only be woken up by an external interrupt on a pin or a watchdog timer.
00180  *
00181  * @note
00182  *  The mbed interface semihosting is disconnected as part of going to sleep, and can not be restored.
00183  * Flash re-programming and the USB serial port will remain active, but the mbed program will no longer be
00184  * able to access the LocalFileSystem
00185  */
00186 
00187 MBED_DEPRECATED_SINCE("mbed-os-5.6", "One entry point for an application, use sleep()")
00188 static inline void deepsleep(void)
00189 {
00190 #if !(defined(FEATURE_UVISOR) && defined(TARGET_UVISOR_SUPPORTED))
00191 #if DEVICE_SLEEP
00192     sleep_manager_sleep_auto();
00193 #endif /* DEVICE_SLEEP */
00194 #endif /* !(defined(FEATURE_UVISOR) && defined(TARGET_UVISOR_SUPPORTED)) */
00195 }
00196 
00197 /** Resets the processor and most of the sub-system
00198  *
00199  * @note Does not affect the debug sub-system
00200  */
00201 static inline void system_reset(void)
00202 {
00203     NVIC_SystemReset();
00204 }
00205 
00206 #ifdef __cplusplus
00207 }
00208 #endif
00209 
00210 #endif
00211 
00212 /** @}*/
00213 /** @}*/