Line data Source code
1 0 : /* 2 : * Copyright (c) 2015 Intel Corporation. 3 : * Copyright (c) 2021 Nordic Semiconductor ASA 4 : * 5 : * SPDX-License-Identifier: Apache-2.0 6 : */ 7 : 8 : #ifndef ZEPHYR_INCLUDE_PM_DEVICE_RUNTIME_H_ 9 : #define ZEPHYR_INCLUDE_PM_DEVICE_RUNTIME_H_ 10 : 11 : #include <zephyr/device.h> 12 : #include <zephyr/kernel.h> 13 : 14 : #ifdef __cplusplus 15 : extern "C" { 16 : #endif 17 : 18 : /** 19 : * @brief Device Runtime Power Management API 20 : * @defgroup subsys_pm_device_runtime Device Runtime 21 : * @ingroup subsys_pm 22 : * @{ 23 : */ 24 : 25 : #if defined(CONFIG_PM_DEVICE_RUNTIME) || defined(__DOXYGEN__) 26 : /** 27 : * @brief Automatically enable device runtime based on devicetree properties 28 : * 29 : * @note Must not be called from application code. See the 30 : * zephyr,pm-device-runtime-auto property in pm.yaml and z_sys_init_run_level. 31 : * 32 : * @param dev Device instance. 33 : * 34 : * @retval 0 If the device runtime PM is enabled successfully or it has not 35 : * been requested for this device in devicetree. 36 : * @retval -errno Other negative errno, result of enabled device runtime PM. 37 : */ 38 1 : int pm_device_runtime_auto_enable(const struct device *dev); 39 : 40 : /** 41 : * @brief Enable device runtime PM 42 : * 43 : * This function will enable runtime PM on the given device. If the device is 44 : * in #PM_DEVICE_STATE_ACTIVE state, the device will be suspended. 45 : * 46 : * @funcprops \pre_kernel_ok 47 : * 48 : * @param dev Device instance. 49 : * 50 : * @retval 0 If the device runtime PM is enabled successfully. 51 : * @retval -EBUSY If device is busy. 52 : * @retval -ENOTSUP If the device does not support PM. 53 : * @retval -errno Other negative errno, result of suspending the device. 54 : * 55 : * @see pm_device_init_suspended() 56 : */ 57 1 : int pm_device_runtime_enable(const struct device *dev); 58 : 59 : /** 60 : * @brief Disable device runtime PM 61 : * 62 : * If the device is currently suspended it will be resumed. 63 : * 64 : * @funcprops \pre_kernel_ok 65 : * 66 : * @param dev Device instance. 67 : * 68 : * @retval 0 If the device runtime PM is disabled successfully. 69 : * @retval -ENOTSUP If the device does not support PM. 70 : * @retval -errno Other negative errno, result of resuming the device. 71 : */ 72 1 : int pm_device_runtime_disable(const struct device *dev); 73 : 74 : /** 75 : * @brief Resume a device based on usage count. 76 : * 77 : * This function will resume the device if the device is suspended (usage count 78 : * equal to 0). In case of a resume failure, usage count and device state will 79 : * be left unchanged. In all other cases, usage count will be incremented. 80 : * 81 : * If the device is still being suspended as a result of calling 82 : * pm_device_runtime_put_async(), this function will wait for the operation to 83 : * finish to then resume the device. 84 : * 85 : * @note It is safe to use this function in contexts where blocking is not 86 : * allowed, e.g. ISR, provided the device PM implementation does not block. 87 : * 88 : * @funcprops \pre_kernel_ok 89 : * 90 : * @param dev Device instance. 91 : * 92 : * @retval 0 If it succeeds. In case device runtime PM is not enabled or not 93 : * available this function will be a no-op and will also return 0. 94 : * @retval -EWOUDBLOCK If call would block but it is not allowed (e.g. in ISR). 95 : * @retval -errno Other negative errno, result of the PM action callback. 96 : */ 97 1 : int pm_device_runtime_get(const struct device *dev); 98 : 99 : /** 100 : * @brief Suspend a device based on usage count. 101 : * 102 : * This function will suspend the device if the device is no longer required 103 : * (usage count equal to 0). In case of suspend failure, usage count and device 104 : * state will be left unchanged. In all other cases, usage count will be 105 : * decremented (down to 0). 106 : * 107 : * @funcprops \pre_kernel_ok 108 : * 109 : * @param dev Device instance. 110 : * 111 : * @retval 0 If it succeeds. In case device runtime PM is not enabled or not 112 : * available this function will be a no-op and will also return 0. 113 : * @retval -EALREADY If device is already suspended (can only happen if get/put 114 : * calls are unbalanced). 115 : * @retval -errno Other negative errno, result of the action callback. 116 : * 117 : * @see pm_device_runtime_put_async() 118 : */ 119 1 : int pm_device_runtime_put(const struct device *dev); 120 : 121 : /** 122 : * @brief Suspend a device based on usage count (asynchronously). 123 : * 124 : * This function will schedule the device suspension if the device is no longer 125 : * required (usage count equal to 0). In all other cases, usage count will be 126 : * decremented (down to 0). 127 : * 128 : * @note Asynchronous operations are not supported when in pre-kernel mode. In 129 : * this case, the function will be blocking (equivalent to 130 : * pm_device_runtime_put()). 131 : * 132 : * @funcprops \pre_kernel_ok, \async, \isr_ok 133 : * 134 : * @param dev Device instance. 135 : * @param delay Minimum amount of time before triggering the action. 136 : * 137 : * @retval 0 If it succeeds. In case device runtime PM is not enabled or not 138 : * available this function will be a no-op and will also return 0. 139 : * @retval -EBUSY If the device is busy. 140 : * @retval -EALREADY If device is already suspended (can only happen if get/put 141 : * calls are unbalanced). 142 : * 143 : * @see pm_device_runtime_put() 144 : */ 145 1 : int pm_device_runtime_put_async(const struct device *dev, k_timeout_t delay); 146 : 147 : /** 148 : * @brief Check if device runtime is enabled for a given device. 149 : * 150 : * @funcprops \pre_kernel_ok 151 : * 152 : * @param dev Device instance. 153 : * 154 : * @retval true If device has device runtime PM enabled. 155 : * @retval false If the device has device runtime PM disabled. 156 : * 157 : * @see pm_device_runtime_enable() 158 : */ 159 1 : bool pm_device_runtime_is_enabled(const struct device *dev); 160 : 161 : /** 162 : * @brief Return the current device usage counter. 163 : * 164 : * @param dev Device instance. 165 : * 166 : * @returns the current usage counter. 167 : * @retval -ENOTSUP If the device is not using runtime PM. 168 : * @retval -ENOSYS If the runtime PM is not enabled at all. 169 : */ 170 1 : int pm_device_runtime_usage(const struct device *dev); 171 : 172 : #else 173 : 174 : static inline int pm_device_runtime_auto_enable(const struct device *dev) 175 : { 176 : ARG_UNUSED(dev); 177 : return 0; 178 : } 179 : 180 : static inline int pm_device_runtime_enable(const struct device *dev) 181 : { 182 : ARG_UNUSED(dev); 183 : return 0; 184 : } 185 : 186 : static inline int pm_device_runtime_disable(const struct device *dev) 187 : { 188 : ARG_UNUSED(dev); 189 : return 0; 190 : } 191 : 192 : static inline int pm_device_runtime_get(const struct device *dev) 193 : { 194 : ARG_UNUSED(dev); 195 : return 0; 196 : } 197 : 198 : static inline int pm_device_runtime_put(const struct device *dev) 199 : { 200 : ARG_UNUSED(dev); 201 : return 0; 202 : } 203 : 204 : static inline int pm_device_runtime_put_async(const struct device *dev, 205 : k_timeout_t delay) 206 : { 207 : ARG_UNUSED(dev); 208 : ARG_UNUSED(delay); 209 : return 0; 210 : } 211 : 212 : static inline bool pm_device_runtime_is_enabled(const struct device *dev) 213 : { 214 : ARG_UNUSED(dev); 215 : return false; 216 : } 217 : 218 : static inline int pm_device_runtime_usage(const struct device *dev) 219 : { 220 : ARG_UNUSED(dev); 221 : return -ENOSYS; 222 : } 223 : 224 : #endif 225 : 226 : /** @} */ 227 : 228 : #ifdef __cplusplus 229 : } 230 : #endif 231 : 232 : #endif /* ZEPHYR_INCLUDE_PM_DEVICE_RUNTIME_H_ */
