Marco Zecchini / Mbed OS Example_RTOS

Rtos API example

mbed-os/platform/mbed_sleep.h@0:9fca2b23d0ba, 2019-02-23 (annotated)

Committer:
marcozecchini
Date:
Sat Feb 23 12:13:36 2019 +0000
Revision:
0:9fca2b23d0ba
final commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
marcozecchini 0:9fca2b23d0ba 1
marcozecchini 0:9fca2b23d0ba 2 /** \addtogroup platform */
marcozecchini 0:9fca2b23d0ba 3 /** @{*/
marcozecchini 0:9fca2b23d0ba 4 /**
marcozecchini 0:9fca2b23d0ba 5 * \defgroup platform_sleep Sleep functions
marcozecchini 0:9fca2b23d0ba 6 * @{
marcozecchini 0:9fca2b23d0ba 7 */
marcozecchini 0:9fca2b23d0ba 8
marcozecchini 0:9fca2b23d0ba 9 /* mbed Microcontroller Library
marcozecchini 0:9fca2b23d0ba 10 * Copyright (c) 2006-2017 ARM Limited
marcozecchini 0:9fca2b23d0ba 11 *
marcozecchini 0:9fca2b23d0ba 12 * Licensed under the Apache License, Version 2.0 (the "License");
marcozecchini 0:9fca2b23d0ba 13 * you may not use this file except in compliance with the License.
marcozecchini 0:9fca2b23d0ba 14 * You may obtain a copy of the License at
marcozecchini 0:9fca2b23d0ba 15 *
marcozecchini 0:9fca2b23d0ba 16 * http://www.apache.org/licenses/LICENSE-2.0
marcozecchini 0:9fca2b23d0ba 17 *
marcozecchini 0:9fca2b23d0ba 18 * Unless required by applicable law or agreed to in writing, software
marcozecchini 0:9fca2b23d0ba 19 * distributed under the License is distributed on an "AS IS" BASIS,
marcozecchini 0:9fca2b23d0ba 20 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
marcozecchini 0:9fca2b23d0ba 21 * See the License for the specific language governing permissions and
marcozecchini 0:9fca2b23d0ba 22 * limitations under the License.
marcozecchini 0:9fca2b23d0ba 23 */
marcozecchini 0:9fca2b23d0ba 24 #ifndef MBED_SLEEP_H
marcozecchini 0:9fca2b23d0ba 25 #define MBED_SLEEP_H
marcozecchini 0:9fca2b23d0ba 26
marcozecchini 0:9fca2b23d0ba 27 #include "sleep_api.h"
marcozecchini 0:9fca2b23d0ba 28 #include "mbed_toolchain.h"
marcozecchini 0:9fca2b23d0ba 29 #include <stdbool.h>
marcozecchini 0:9fca2b23d0ba 30
marcozecchini 0:9fca2b23d0ba 31 #ifdef __cplusplus
marcozecchini 0:9fca2b23d0ba 32 extern "C" {
marcozecchini 0:9fca2b23d0ba 33 #endif
marcozecchini 0:9fca2b23d0ba 34
marcozecchini 0:9fca2b23d0ba 35 /** Sleep manager API
marcozecchini 0:9fca2b23d0ba 36 * The sleep manager provides API to automatically select sleep mode.
marcozecchini 0:9fca2b23d0ba 37 *
marcozecchini 0:9fca2b23d0ba 38 * There are two sleep modes:
marcozecchini 0:9fca2b23d0ba 39 * - sleep
marcozecchini 0:9fca2b23d0ba 40 * - deepsleep
marcozecchini 0:9fca2b23d0ba 41 *
marcozecchini 0:9fca2b23d0ba 42 * Use locking/unlocking deepsleep for drivers that depend on features that
marcozecchini 0:9fca2b23d0ba 43 * are not allowed (=disabled) during the deepsleep. For instance, high frequency
marcozecchini 0:9fca2b23d0ba 44 * clocks.
marcozecchini 0:9fca2b23d0ba 45 *
marcozecchini 0:9fca2b23d0ba 46 * Example:
marcozecchini 0:9fca2b23d0ba 47 * @code
marcozecchini 0:9fca2b23d0ba 48 *
marcozecchini 0:9fca2b23d0ba 49 * void driver::handler()
marcozecchini 0:9fca2b23d0ba 50 * {
marcozecchini 0:9fca2b23d0ba 51 * if (_sensor.get_event()) {
marcozecchini 0:9fca2b23d0ba 52 * // any event - we are finished, unlock the deepsleep
marcozecchini 0:9fca2b23d0ba 53 * sleep_manager_unlock_deep_sleep();
marcozecchini 0:9fca2b23d0ba 54 * _callback();
marcozecchini 0:9fca2b23d0ba 55 * }
marcozecchini 0:9fca2b23d0ba 56 * }
marcozecchini 0:9fca2b23d0ba 57 *
marcozecchini 0:9fca2b23d0ba 58 * int driver::measure(event_t event, callback_t& callback)
marcozecchini 0:9fca2b23d0ba 59 * {
marcozecchini 0:9fca2b23d0ba 60 * _callback = callback;
marcozecchini 0:9fca2b23d0ba 61 * sleep_manager_lock_deep_sleep();
marcozecchini 0:9fca2b23d0ba 62 * // start async transaction, we are waiting for an event
marcozecchini 0:9fca2b23d0ba 63 * return _sensor.start(event, callback);
marcozecchini 0:9fca2b23d0ba 64 * }
marcozecchini 0:9fca2b23d0ba 65 * @endcode
marcozecchini 0:9fca2b23d0ba 66 */
marcozecchini 0:9fca2b23d0ba 67
marcozecchini 0:9fca2b23d0ba 68 /** Lock the deep sleep mode
marcozecchini 0:9fca2b23d0ba 69 *
marcozecchini 0:9fca2b23d0ba 70 * This locks the automatic deep mode selection.
marcozecchini 0:9fca2b23d0ba 71 * sleep_manager_sleep_auto() will ignore deepsleep mode if
marcozecchini 0:9fca2b23d0ba 72 * this function is invoked at least once (the internal counter is non-zero)
marcozecchini 0:9fca2b23d0ba 73 *
marcozecchini 0:9fca2b23d0ba 74 * Use this locking mechanism for interrupt driven API that are
marcozecchini 0:9fca2b23d0ba 75 * running in the background and deepsleep could affect their functionality
marcozecchini 0:9fca2b23d0ba 76 *
marcozecchini 0:9fca2b23d0ba 77 * The lock is a counter, can be locked up to USHRT_MAX
marcozecchini 0:9fca2b23d0ba 78 * This function is IRQ and thread safe
marcozecchini 0:9fca2b23d0ba 79 */
marcozecchini 0:9fca2b23d0ba 80 void sleep_manager_lock_deep_sleep(void);
marcozecchini 0:9fca2b23d0ba 81
marcozecchini 0:9fca2b23d0ba 82 /** Unlock the deep sleep mode
marcozecchini 0:9fca2b23d0ba 83 *
marcozecchini 0:9fca2b23d0ba 84 * Use unlocking in pair with sleep_manager_lock_deep_sleep().
marcozecchini 0:9fca2b23d0ba 85 *
marcozecchini 0:9fca2b23d0ba 86 * The lock is a counter, should be equally unlocked as locked
marcozecchini 0:9fca2b23d0ba 87 * This function is IRQ and thread safe
marcozecchini 0:9fca2b23d0ba 88 */
marcozecchini 0:9fca2b23d0ba 89 void sleep_manager_unlock_deep_sleep(void);
marcozecchini 0:9fca2b23d0ba 90
marcozecchini 0:9fca2b23d0ba 91 /** Get the status of deep sleep allowance for a target
marcozecchini 0:9fca2b23d0ba 92 *
marcozecchini 0:9fca2b23d0ba 93 * @return true if a target can go to deepsleep, false otherwise
marcozecchini 0:9fca2b23d0ba 94 */
marcozecchini 0:9fca2b23d0ba 95 bool sleep_manager_can_deep_sleep(void);
marcozecchini 0:9fca2b23d0ba 96
marcozecchini 0:9fca2b23d0ba 97 /** Enter auto selected sleep mode. It chooses the sleep or deeepsleep modes based
marcozecchini 0:9fca2b23d0ba 98 * on the deepsleep locking counter
marcozecchini 0:9fca2b23d0ba 99 *
marcozecchini 0:9fca2b23d0ba 100 * This function is IRQ and thread safe
marcozecchini 0:9fca2b23d0ba 101 *
marcozecchini 0:9fca2b23d0ba 102 * @note
marcozecchini 0:9fca2b23d0ba 103 * If MBED_DEBUG is defined, only hal_sleep is allowed. This ensures the debugger
marcozecchini 0:9fca2b23d0ba 104 * to be active for debug modes.
marcozecchini 0:9fca2b23d0ba 105 *
marcozecchini 0:9fca2b23d0ba 106 */
marcozecchini 0:9fca2b23d0ba 107 void sleep_manager_sleep_auto(void);
marcozecchini 0:9fca2b23d0ba 108
marcozecchini 0:9fca2b23d0ba 109 /** Send the microcontroller to sleep
marcozecchini 0:9fca2b23d0ba 110 *
marcozecchini 0:9fca2b23d0ba 111 * @note This function can be a noop if not implemented by the platform.
marcozecchini 0:9fca2b23d0ba 112 * @note This function will be a noop in debug mode (debug build profile when MBED_DEBUG is defined).
marcozecchini 0:9fca2b23d0ba 113 * @note This function will be a noop while uVisor is in use.
marcozecchini 0:9fca2b23d0ba 114 * @note This function will be a noop if the following conditions are met:
marcozecchini 0:9fca2b23d0ba 115 * - The RTOS is present
marcozecchini 0:9fca2b23d0ba 116 * - The processor turn off the Systick clock during sleep
marcozecchini 0:9fca2b23d0ba 117 * - The target does not implement tickless mode
marcozecchini 0:9fca2b23d0ba 118 *
marcozecchini 0:9fca2b23d0ba 119 * The processor is setup ready for sleep, and sent to sleep using __WFI(). In this mode, the
marcozecchini 0:9fca2b23d0ba 120 * system clock to the core is stopped until a reset or an interrupt occurs. This eliminates
marcozecchini 0:9fca2b23d0ba 121 * dynamic power used by the processor, memory systems and buses. The processor, peripheral and
marcozecchini 0:9fca2b23d0ba 122 * memory state are maintained, and the peripherals continue to work and can generate interrupts.
marcozecchini 0:9fca2b23d0ba 123 *
marcozecchini 0:9fca2b23d0ba 124 * The processor can be woken up by any internal peripheral interrupt or external pin interrupt.
marcozecchini 0:9fca2b23d0ba 125 *
marcozecchini 0:9fca2b23d0ba 126 * @note
marcozecchini 0:9fca2b23d0ba 127 * The mbed interface semihosting is disconnected as part of going to sleep, and can not be restored.
marcozecchini 0:9fca2b23d0ba 128 * Flash re-programming and the USB serial port will remain active, but the mbed program will no longer be
marcozecchini 0:9fca2b23d0ba 129 * able to access the LocalFileSystem
marcozecchini 0:9fca2b23d0ba 130 */
marcozecchini 0:9fca2b23d0ba 131 __INLINE static void sleep(void)
marcozecchini 0:9fca2b23d0ba 132 {
marcozecchini 0:9fca2b23d0ba 133 #if !(defined(FEATURE_UVISOR) && defined(TARGET_UVISOR_SUPPORTED))
marcozecchini 0:9fca2b23d0ba 134 #if DEVICE_SLEEP
marcozecchini 0:9fca2b23d0ba 135 #if (MBED_CONF_RTOS_PRESENT == 0) || (DEVICE_STCLK_OFF_DURING_SLEEP == 0) || defined(MBED_TICKLESS)
marcozecchini 0:9fca2b23d0ba 136 sleep_manager_sleep_auto();
marcozecchini 0:9fca2b23d0ba 137 #endif /* (MBED_CONF_RTOS_PRESENT == 0) || (DEVICE_STCLK_OFF_DURING_SLEEP == 0) || defined(MBED_TICKLESS) */
marcozecchini 0:9fca2b23d0ba 138 #endif /* DEVICE_SLEEP */
marcozecchini 0:9fca2b23d0ba 139 #endif /* !(defined(FEATURE_UVISOR) && defined(TARGET_UVISOR_SUPPORTED)) */
marcozecchini 0:9fca2b23d0ba 140 }
marcozecchini 0:9fca2b23d0ba 141
marcozecchini 0:9fca2b23d0ba 142 /** Send the microcontroller to deep sleep
marcozecchini 0:9fca2b23d0ba 143 *
marcozecchini 0:9fca2b23d0ba 144 * @note This function can be a noop if not implemented by the platform.
marcozecchini 0:9fca2b23d0ba 145 * @note This function will be a noop in debug mode (debug build profile when MBED_DEBUG is defined)
marcozecchini 0:9fca2b23d0ba 146 * @note This function will be a noop while uVisor is in use.
marcozecchini 0:9fca2b23d0ba 147 *
marcozecchini 0:9fca2b23d0ba 148 * This processor is setup ready for deep sleep, and sent to sleep. This mode
marcozecchini 0:9fca2b23d0ba 149 * has the same sleep features as sleep plus it powers down peripherals and clocks. All state
marcozecchini 0:9fca2b23d0ba 150 * is still maintained.
marcozecchini 0:9fca2b23d0ba 151 *
marcozecchini 0:9fca2b23d0ba 152 * The processor can only be woken up by an external interrupt on a pin or a watchdog timer.
marcozecchini 0:9fca2b23d0ba 153 *
marcozecchini 0:9fca2b23d0ba 154 * @note
marcozecchini 0:9fca2b23d0ba 155 * The mbed interface semihosting is disconnected as part of going to sleep, and can not be restored.
marcozecchini 0:9fca2b23d0ba 156 * Flash re-programming and the USB serial port will remain active, but the mbed program will no longer be
marcozecchini 0:9fca2b23d0ba 157 * able to access the LocalFileSystem
marcozecchini 0:9fca2b23d0ba 158 */
marcozecchini 0:9fca2b23d0ba 159
marcozecchini 0:9fca2b23d0ba 160 MBED_DEPRECATED_SINCE("mbed-os-5.6", "One entry point for an application, use sleep()")
marcozecchini 0:9fca2b23d0ba 161 __INLINE static void deepsleep(void)
marcozecchini 0:9fca2b23d0ba 162 {
marcozecchini 0:9fca2b23d0ba 163 #if !(defined(FEATURE_UVISOR) && defined(TARGET_UVISOR_SUPPORTED))
marcozecchini 0:9fca2b23d0ba 164 #if DEVICE_SLEEP
marcozecchini 0:9fca2b23d0ba 165 sleep_manager_sleep_auto();
marcozecchini 0:9fca2b23d0ba 166 #endif /* DEVICE_SLEEP */
marcozecchini 0:9fca2b23d0ba 167 #endif /* !(defined(FEATURE_UVISOR) && defined(TARGET_UVISOR_SUPPORTED)) */
marcozecchini 0:9fca2b23d0ba 168 }
marcozecchini 0:9fca2b23d0ba 169
marcozecchini 0:9fca2b23d0ba 170 #ifdef __cplusplus
marcozecchini 0:9fca2b23d0ba 171 }
marcozecchini 0:9fca2b23d0ba 172 #endif
marcozecchini 0:9fca2b23d0ba 173
marcozecchini 0:9fca2b23d0ba 174 #endif
marcozecchini 0:9fca2b23d0ba 175
marcozecchini 0:9fca2b23d0ba 176 /** @}*/
marcozecchini 0:9fca2b23d0ba 177 /** @}*/