mbed_sleep.h

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