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 "hal/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 /** Check if the target can deep sleep within a period of time
00126  *
00127  * This function in intended for use in testing. The amount
00128  * of time this functions waits for deeps sleep to be available
00129  * is currently 2ms. This may change in the future depending
00130  * on testing requirements.
00131  *
00132  * @return true if a target can go to deepsleep, false otherwise
00133  */
00134 bool sleep_manager_can_deep_sleep_test_check(void);
00135 
00136 /** Enter auto selected sleep mode. It chooses the sleep or deeepsleep modes based
00137  *  on the deepsleep locking counter
00138  *
00139  * This function is IRQ and thread safe
00140  *
00141  * @note
00142  * If MBED_DEBUG is defined, only hal_sleep is allowed. This ensures the debugger
00143  * to be active for debug modes.
00144  *
00145  */
00146 void sleep_manager_sleep_auto(void);
00147 
00148 /** Send the microcontroller to sleep
00149  *
00150  * @note This function can be a noop if not implemented by the platform.
00151  * @note This function will be a noop in debug mode (debug build profile when MBED_DEBUG is defined).
00152  * @note This function will be a noop if the following conditions are met:
00153  *   - The RTOS is present
00154  *   - The processor turn off the Systick clock during sleep
00155  *   - The target does not implement tickless mode
00156  *
00157  * The processor is setup ready for sleep, and sent to sleep using __WFI(). In this mode, the
00158  * system clock to the core is stopped until a reset or an interrupt occurs. This eliminates
00159  * dynamic power used by the processor, memory systems and buses. The processor, peripheral and
00160  * memory state are maintained, and the peripherals continue to work and can generate interrupts.
00161  *
00162  * The processor can be woken up by any internal peripheral interrupt or external pin interrupt.
00163  *
00164  * @note
00165  *  The mbed interface semihosting is disconnected as part of going to sleep, and can not be restored.
00166  * Flash re-programming and the USB serial port will remain active, but the mbed program will no longer be
00167  * able to access the LocalFileSystem
00168  */
00169 static inline void sleep(void)
00170 {
00171 #if DEVICE_SLEEP
00172 #if (MBED_CONF_RTOS_PRESENT == 0) || (DEVICE_SYSTICK_CLK_OFF_DURING_SLEEP == 0) || defined(MBED_TICKLESS)
00173     sleep_manager_sleep_auto();
00174 #endif /* (MBED_CONF_RTOS_PRESENT == 0) || (DEVICE_SYSTICK_CLK_OFF_DURING_SLEEP == 0) || defined(MBED_TICKLESS) */
00175 #endif /* DEVICE_SLEEP */
00176 }
00177 
00178 /** Send the microcontroller to deep sleep
00179  *
00180  * @deprecated
00181  * Do not use this function. Applications should use sleep() API which puts the system in deepsleep mode if supported.
00182  *
00183  * @note This function can be a noop if not implemented by the platform.
00184  * @note This function will be a noop in debug mode (debug build profile when MBED_DEBUG is defined)
00185  *
00186  * This processor is setup ready for deep sleep, and sent to sleep. This mode
00187  * has the same sleep features as sleep plus it powers down peripherals and clocks. All state
00188  * is still maintained.
00189  *
00190  * The processor can only be woken up by an external interrupt on a pin or a watchdog timer.
00191  *
00192  * @note
00193  *  The mbed interface semihosting is disconnected as part of going to sleep, and can not be restored.
00194  * Flash re-programming and the USB serial port will remain active, but the mbed program will no longer be
00195  * able to access the LocalFileSystem
00196  */
00197 
00198 MBED_DEPRECATED_SINCE("mbed-os-5.6", "One entry point for an application, use sleep()")
00199 static inline void deepsleep(void)
00200 {
00201 #if DEVICE_SLEEP
00202     sleep_manager_sleep_auto();
00203 #endif /* DEVICE_SLEEP */
00204 }
00205 
00206 /** Resets the processor and most of the sub-system
00207  *
00208  * @note Does not affect the debug sub-system
00209  */
00210 static inline void system_reset(void)
00211 {
00212     NVIC_SystemReset();
00213 }
00214 
00215 /** Provides the time spent in sleep mode since boot.
00216  *
00217  *  @return  Time spent in sleep
00218  *  @note  Works only if platform supports LP ticker.
00219  */
00220 us_timestamp_t mbed_time_sleep(void);
00221 
00222 /** Provides the time spent in deep sleep mode since boot.
00223  *
00224  *  @return  Time spent in deep sleep
00225  *  @note  Works only if platform supports LP ticker.
00226  */
00227 us_timestamp_t mbed_time_deepsleep(void);
00228 
00229 /** Provides the time spent in idle mode since boot.
00230  *
00231  * @return  Idle thread time.
00232  * @note  Works only if platform supports LP ticker.
00233  */
00234 us_timestamp_t mbed_time_idle(void);
00235 
00236 /** Provides the time since the system is up i.e. boot.
00237  *
00238  * @return  System uptime.
00239  * @note  Works only if platform supports LP ticker.
00240  */
00241 us_timestamp_t mbed_uptime(void);
00242 
00243 #ifdef __cplusplus
00244 }
00245 #endif
00246 
00247 #endif
00248 
00249 /** @}*/
00250 /** @}*/