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  *
00110  * The processor is setup ready for sleep, and sent to sleep using __WFI(). In this mode, the
00111  * system clock to the core is stopped until a reset or an interrupt occurs. This eliminates
00112  * dynamic power used by the processor, memory systems and buses. The processor, peripheral and
00113  * memory state are maintained, and the peripherals continue to work and can generate interrupts.
00114  *
00115  * The processor can be woken up by any internal peripheral interrupt or external pin interrupt.
00116  *
00117  * @note
00118  *  The mbed interface semihosting is disconnected as part of going to sleep, and can not be restored.
00119  * Flash re-programming and the USB serial port will remain active, but the mbed program will no longer be
00120  * able to access the LocalFileSystem
00121  */
00122 __INLINE static void sleep(void)
00123 {
00124 #if !(defined(FEATURE_UVISOR) && defined(TARGET_UVISOR_SUPPORTED))
00125 #if DEVICE_SLEEP
00126     sleep_manager_sleep_auto();
00127 #endif /* DEVICE_SLEEP */
00128 #endif /* !(defined(FEATURE_UVISOR) && defined(TARGET_UVISOR_SUPPORTED)) */
00129 }
00130 
00131 /** Send the microcontroller to deep sleep
00132  *
00133  * @note This function can be a noop if not implemented by the platform.
00134  * @note This function will be a noop in debug mode (debug build profile when MBED_DEBUG is defined)
00135  * @note This function will be a noop while uVisor is in use.
00136  *
00137  * This processor is setup ready for deep sleep, and sent to sleep. This mode
00138  * has the same sleep features as sleep plus it powers down peripherals and clocks. All state
00139  * is still maintained.
00140  *
00141  * The processor can only be woken up by an external interrupt on a pin or a watchdog timer.
00142  *
00143  * @note
00144  *  The mbed interface semihosting is disconnected as part of going to sleep, and can not be restored.
00145  * Flash re-programming and the USB serial port will remain active, but the mbed program will no longer be
00146  * able to access the LocalFileSystem
00147  */
00148 
00149 MBED_DEPRECATED_SINCE("mbed-os-5.6", "One entry point for an application, use sleep()")
00150 __INLINE static void deepsleep(void)
00151 {
00152 #if !(defined(FEATURE_UVISOR) && defined(TARGET_UVISOR_SUPPORTED))
00153 #if DEVICE_SLEEP
00154     sleep_manager_sleep_auto();
00155 #endif /* DEVICE_SLEEP */
00156 #endif /* !(defined(FEATURE_UVISOR) && defined(TARGET_UVISOR_SUPPORTED)) */
00157 }
00158 
00159 #ifdef __cplusplus
00160 }
00161 #endif
00162 
00163 #endif
00164 
00165 /** @}*/