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 "hal/ticker_api.h"
00029 #include <stdbool.h>
00030 
00031 #ifdef __cplusplus
00032 extern "C" {
00033 #endif
00034 
00035 /** Sleep manager API
00036  * The sleep manager provides API to automatically select sleep mode.
00037  *
00038  * There are two sleep modes:
00039  * - sleep
00040  * - deepsleep
00041  *
00042  * Use locking/unlocking deepsleep for drivers that depend on features that
00043  * are not allowed (=disabled) during the deepsleep. For instance, high frequency
00044  * clocks.
00045  *
00046  * Example:
00047  * @code
00048  *
00049  * void driver::handler()
00050  * {
00051  *     if (_sensor.get_event()) {
00052  *         // any event - we are finished, unlock the deepsleep
00053  *         sleep_manager_unlock_deep_sleep();
00054  *         _callback();
00055  *     }
00056  * }
00057  *
00058  * int driver::measure(event_t event, callback_t& callback)
00059  * {
00060  *      _callback = callback;
00061  *      sleep_manager_lock_deep_sleep();
00062  *      // start async transaction, we are waiting for an event
00063  *      return _sensor.start(event, callback);
00064  * }
00065  * @endcode
00066  */
00067 #ifdef MBED_SLEEP_TRACING_ENABLED
00068 
00069 void sleep_tracker_lock(const char *const filename, int line);
00070 void sleep_tracker_unlock(const char *const filename, int line);
00071 
00072 #define sleep_manager_lock_deep_sleep()              \
00073     do                                               \
00074     {                                                \
00075         sleep_manager_lock_deep_sleep_internal();    \
00076         sleep_tracker_lock(MBED_FILENAME, __LINE__); \
00077     } while (0);
00078 
00079 #define sleep_manager_unlock_deep_sleep()              \
00080     do                                                 \
00081     {                                                  \
00082         sleep_manager_unlock_deep_sleep_internal();    \
00083         sleep_tracker_unlock(MBED_FILENAME, __LINE__); \
00084     } while (0);
00085 
00086 #else
00087 
00088 #define sleep_manager_lock_deep_sleep() \
00089     sleep_manager_lock_deep_sleep_internal()
00090 
00091 #define sleep_manager_unlock_deep_sleep() \
00092     sleep_manager_unlock_deep_sleep_internal()
00093 
00094 #endif // MBED_SLEEP_TRACING_ENABLED
00095 
00096 /** Lock the deep sleep mode
00097  *
00098  * This locks the automatic deep mode selection.
00099  * sleep_manager_sleep_auto() will ignore deepsleep mode if
00100  * this function is invoked at least once (the internal counter is non-zero)
00101  *
00102  * Use this locking mechanism for interrupt driven API that are
00103  * running in the background and deepsleep could affect their functionality
00104  *
00105  * The lock is a counter, can be locked up to USHRT_MAX
00106  * This function is IRQ and thread safe
00107  */
00108 void sleep_manager_lock_deep_sleep_internal(void);
00109 
00110 /** Unlock the deep sleep mode
00111  *
00112  * Use unlocking in pair with sleep_manager_lock_deep_sleep().
00113  *
00114  * The lock is a counter, should be equally unlocked as locked
00115  * This function is IRQ and thread safe
00116  */
00117 void sleep_manager_unlock_deep_sleep_internal(void);
00118 
00119 /** Get the status of deep sleep allowance for a target
00120  *
00121  * @return true if a target can go to deepsleep, false otherwise
00122  */
00123 bool sleep_manager_can_deep_sleep(void);
00124 
00125 /** Enter auto selected sleep mode. It chooses the sleep or deeepsleep modes based
00126  *  on the deepsleep locking counter
00127  *
00128  * This function is IRQ and thread safe
00129  *
00130  * @note
00131  * If MBED_DEBUG is defined, only hal_sleep is allowed. This ensures the debugger
00132  * to be active for debug modes.
00133  *
00134  */
00135 void sleep_manager_sleep_auto(void);
00136 
00137 /** Send the microcontroller to sleep
00138  *
00139  * @note This function can be a noop if not implemented by the platform.
00140  * @note This function will be a noop in debug mode (debug build profile when MBED_DEBUG is defined).
00141  * @note This function will be a noop while uVisor is in use.
00142  * @note This function will be a noop if the following conditions are met:
00143  *   - The RTOS is present
00144  *   - The processor turn off the Systick clock during sleep
00145  *   - The target does not implement tickless mode
00146  *
00147  * The processor is setup ready for sleep, and sent to sleep using __WFI(). In this mode, the
00148  * system clock to the core is stopped until a reset or an interrupt occurs. This eliminates
00149  * dynamic power used by the processor, memory systems and buses. The processor, peripheral and
00150  * memory state are maintained, and the peripherals continue to work and can generate interrupts.
00151  *
00152  * The processor can be woken up by any internal peripheral interrupt or external pin interrupt.
00153  *
00154  * @note
00155  *  The mbed interface semihosting is disconnected as part of going to sleep, and can not be restored.
00156  * Flash re-programming and the USB serial port will remain active, but the mbed program will no longer be
00157  * able to access the LocalFileSystem
00158  */
00159 static inline void sleep(void)
00160 {
00161 #if !(defined(FEATURE_UVISOR) && defined(TARGET_UVISOR_SUPPORTED))
00162 #if DEVICE_SLEEP
00163 #if (MBED_CONF_RTOS_PRESENT == 0) || (DEVICE_STCLK_OFF_DURING_SLEEP == 0) || defined(MBED_TICKLESS)
00164     sleep_manager_sleep_auto();
00165 #endif /* (MBED_CONF_RTOS_PRESENT == 0) || (DEVICE_STCLK_OFF_DURING_SLEEP == 0) || defined(MBED_TICKLESS) */
00166 #endif /* DEVICE_SLEEP */
00167 #endif /* !(defined(FEATURE_UVISOR) && defined(TARGET_UVISOR_SUPPORTED)) */
00168 }
00169 
00170 /** Send the microcontroller to deep sleep
00171  *
00172  * @deprecated
00173  * Do not use this function. Applications should use sleep() API which puts the system in deepsleep mode if supported. 
00174  *
00175  * @note This function can be a noop if not implemented by the platform.
00176  * @note This function will be a noop in debug mode (debug build profile when MBED_DEBUG is defined)
00177  * @note This function will be a noop while uVisor is in use.
00178  *
00179  * This processor is setup ready for deep sleep, and sent to sleep. This mode
00180  * has the same sleep features as sleep plus it powers down peripherals and clocks. All state
00181  * is still maintained.
00182  *
00183  * The processor can only be woken up by an external interrupt on a pin or a watchdog timer.
00184  *
00185  * @note
00186  *  The mbed interface semihosting is disconnected as part of going to sleep, and can not be restored.
00187  * Flash re-programming and the USB serial port will remain active, but the mbed program will no longer be
00188  * able to access the LocalFileSystem
00189  */
00190 
00191 MBED_DEPRECATED_SINCE("mbed-os-5.6", "One entry point for an application, use sleep()")
00192 static inline void deepsleep(void)
00193 {
00194 #if !(defined(FEATURE_UVISOR) && defined(TARGET_UVISOR_SUPPORTED))
00195 #if DEVICE_SLEEP
00196     sleep_manager_sleep_auto();
00197 #endif /* DEVICE_SLEEP */
00198 #endif /* !(defined(FEATURE_UVISOR) && defined(TARGET_UVISOR_SUPPORTED)) */
00199 }
00200 
00201 /** Resets the processor and most of the sub-system
00202  *
00203  * @note Does not affect the debug sub-system
00204  */
00205 static inline void system_reset(void)
00206 {
00207     NVIC_SystemReset();
00208 }
00209  
00210 /** Provides the time spent in sleep mode since boot.
00211  *
00212  *  @return  Time spent in sleep
00213  *  @note  Works only if platform supports LP ticker.
00214  */
00215 us_timestamp_t mbed_time_sleep(void);
00216 
00217 /** Provides the time spent in deep sleep mode since boot.
00218  *
00219  *  @return  Time spent in deep sleep
00220  *  @note  Works only if platform supports LP ticker.
00221  */
00222 us_timestamp_t mbed_time_deepsleep(void);
00223 
00224 /** Provides the time spent in idle mode since boot.
00225  *
00226  * @return  Idle thread time.
00227  * @note  Works only if platform supports LP ticker.
00228  */
00229 us_timestamp_t mbed_time_idle(void);
00230 
00231 /** Provides the time since the system is up i.e. boot.
00232  *
00233  * @return  System uptime.
00234  * @note  Works only if platform supports LP ticker.
00235  */
00236 us_timestamp_t mbed_uptime(void);
00237 
00238 #ifdef __cplusplus
00239 }
00240 #endif
00241 
00242 #endif
00243 
00244 /** @}*/
00245 /** @}*/