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_ */
|
