Merge tag 'for-linus-5.17-1' of https://github.com/cminyard/linux-ipmi
[linux-2.6-microblaze.git] / include / linux / pm_runtime.h
1 /* SPDX-License-Identifier: GPL-2.0-only */
2 /*
3  * pm_runtime.h - Device run-time power management helper functions.
4  *
5  * Copyright (C) 2009 Rafael J. Wysocki <rjw@sisk.pl>
6  */
7
8 #ifndef _LINUX_PM_RUNTIME_H
9 #define _LINUX_PM_RUNTIME_H
10
11 #include <linux/device.h>
12 #include <linux/notifier.h>
13 #include <linux/pm.h>
14
15 #include <linux/jiffies.h>
16
17 /* Runtime PM flag argument bits */
18 #define RPM_ASYNC               0x01    /* Request is asynchronous */
19 #define RPM_NOWAIT              0x02    /* Don't wait for concurrent
20                                             state change */
21 #define RPM_GET_PUT             0x04    /* Increment/decrement the
22                                             usage_count */
23 #define RPM_AUTO                0x08    /* Use autosuspend_delay */
24
25 /*
26  * Use this for defining a set of PM operations to be used in all situations
27  * (system suspend, hibernation or runtime PM).
28  *
29  * Note that the behaviour differs from the deprecated UNIVERSAL_DEV_PM_OPS()
30  * macro, which uses the provided callbacks for both runtime PM and system
31  * sleep, while DEFINE_RUNTIME_DEV_PM_OPS() uses pm_runtime_force_suspend()
32  * and pm_runtime_force_resume() for its system sleep callbacks.
33  *
34  * If the underlying dev_pm_ops struct symbol has to be exported, use
35  * EXPORT_RUNTIME_DEV_PM_OPS() or EXPORT_GPL_RUNTIME_DEV_PM_OPS() instead.
36  */
37 #define DEFINE_RUNTIME_DEV_PM_OPS(name, suspend_fn, resume_fn, idle_fn) \
38         _DEFINE_DEV_PM_OPS(name, pm_runtime_force_suspend, \
39                            pm_runtime_force_resume, suspend_fn, \
40                            resume_fn, idle_fn)
41
42 #define EXPORT_RUNTIME_DEV_PM_OPS(name, suspend_fn, resume_fn, idle_fn) \
43         _EXPORT_DEV_PM_OPS(name, pm_runtime_force_suspend, pm_runtime_force_resume, \
44                            suspend_fn, resume_fn, idle_fn, "")
45 #define EXPORT_GPL_RUNTIME_DEV_PM_OPS(name, suspend_fn, resume_fn, idle_fn) \
46         _EXPORT_DEV_PM_OPS(name, pm_runtime_force_suspend, pm_runtime_force_resume, \
47                            suspend_fn, resume_fn, idle_fn, "_gpl")
48
49 #ifdef CONFIG_PM
50 extern struct workqueue_struct *pm_wq;
51
52 static inline bool queue_pm_work(struct work_struct *work)
53 {
54         return queue_work(pm_wq, work);
55 }
56
57 extern int pm_generic_runtime_suspend(struct device *dev);
58 extern int pm_generic_runtime_resume(struct device *dev);
59 extern int pm_runtime_force_suspend(struct device *dev);
60 extern int pm_runtime_force_resume(struct device *dev);
61
62 extern int __pm_runtime_idle(struct device *dev, int rpmflags);
63 extern int __pm_runtime_suspend(struct device *dev, int rpmflags);
64 extern int __pm_runtime_resume(struct device *dev, int rpmflags);
65 extern int pm_runtime_get_if_active(struct device *dev, bool ign_usage_count);
66 extern int pm_schedule_suspend(struct device *dev, unsigned int delay);
67 extern int __pm_runtime_set_status(struct device *dev, unsigned int status);
68 extern int pm_runtime_barrier(struct device *dev);
69 extern void pm_runtime_enable(struct device *dev);
70 extern void __pm_runtime_disable(struct device *dev, bool check_resume);
71 extern void pm_runtime_allow(struct device *dev);
72 extern void pm_runtime_forbid(struct device *dev);
73 extern void pm_runtime_no_callbacks(struct device *dev);
74 extern void pm_runtime_irq_safe(struct device *dev);
75 extern void __pm_runtime_use_autosuspend(struct device *dev, bool use);
76 extern void pm_runtime_set_autosuspend_delay(struct device *dev, int delay);
77 extern u64 pm_runtime_autosuspend_expiration(struct device *dev);
78 extern void pm_runtime_update_max_time_suspended(struct device *dev,
79                                                  s64 delta_ns);
80 extern void pm_runtime_set_memalloc_noio(struct device *dev, bool enable);
81 extern void pm_runtime_get_suppliers(struct device *dev);
82 extern void pm_runtime_put_suppliers(struct device *dev);
83 extern void pm_runtime_new_link(struct device *dev);
84 extern void pm_runtime_drop_link(struct device_link *link);
85 extern void pm_runtime_release_supplier(struct device_link *link, bool check_idle);
86
87 extern int devm_pm_runtime_enable(struct device *dev);
88
89 /**
90  * pm_runtime_get_if_in_use - Conditionally bump up runtime PM usage counter.
91  * @dev: Target device.
92  *
93  * Increment the runtime PM usage counter of @dev if its runtime PM status is
94  * %RPM_ACTIVE and its runtime PM usage counter is greater than 0.
95  */
96 static inline int pm_runtime_get_if_in_use(struct device *dev)
97 {
98         return pm_runtime_get_if_active(dev, false);
99 }
100
101 /**
102  * pm_suspend_ignore_children - Set runtime PM behavior regarding children.
103  * @dev: Target device.
104  * @enable: Whether or not to ignore possible dependencies on children.
105  *
106  * The dependencies of @dev on its children will not be taken into account by
107  * the runtime PM framework going forward if @enable is %true, or they will
108  * be taken into account otherwise.
109  */
110 static inline void pm_suspend_ignore_children(struct device *dev, bool enable)
111 {
112         dev->power.ignore_children = enable;
113 }
114
115 /**
116  * pm_runtime_get_noresume - Bump up runtime PM usage counter of a device.
117  * @dev: Target device.
118  */
119 static inline void pm_runtime_get_noresume(struct device *dev)
120 {
121         atomic_inc(&dev->power.usage_count);
122 }
123
124 /**
125  * pm_runtime_put_noidle - Drop runtime PM usage counter of a device.
126  * @dev: Target device.
127  *
128  * Decrement the runtime PM usage counter of @dev unless it is 0 already.
129  */
130 static inline void pm_runtime_put_noidle(struct device *dev)
131 {
132         atomic_add_unless(&dev->power.usage_count, -1, 0);
133 }
134
135 /**
136  * pm_runtime_suspended - Check whether or not a device is runtime-suspended.
137  * @dev: Target device.
138  *
139  * Return %true if runtime PM is enabled for @dev and its runtime PM status is
140  * %RPM_SUSPENDED, or %false otherwise.
141  *
142  * Note that the return value of this function can only be trusted if it is
143  * called under the runtime PM lock of @dev or under conditions in which
144  * runtime PM cannot be either disabled or enabled for @dev and its runtime PM
145  * status cannot change.
146  */
147 static inline bool pm_runtime_suspended(struct device *dev)
148 {
149         return dev->power.runtime_status == RPM_SUSPENDED
150                 && !dev->power.disable_depth;
151 }
152
153 /**
154  * pm_runtime_active - Check whether or not a device is runtime-active.
155  * @dev: Target device.
156  *
157  * Return %true if runtime PM is disabled for @dev or its runtime PM status is
158  * %RPM_ACTIVE, or %false otherwise.
159  *
160  * Note that the return value of this function can only be trusted if it is
161  * called under the runtime PM lock of @dev or under conditions in which
162  * runtime PM cannot be either disabled or enabled for @dev and its runtime PM
163  * status cannot change.
164  */
165 static inline bool pm_runtime_active(struct device *dev)
166 {
167         return dev->power.runtime_status == RPM_ACTIVE
168                 || dev->power.disable_depth;
169 }
170
171 /**
172  * pm_runtime_status_suspended - Check if runtime PM status is "suspended".
173  * @dev: Target device.
174  *
175  * Return %true if the runtime PM status of @dev is %RPM_SUSPENDED, or %false
176  * otherwise, regardless of whether or not runtime PM has been enabled for @dev.
177  *
178  * Note that the return value of this function can only be trusted if it is
179  * called under the runtime PM lock of @dev or under conditions in which the
180  * runtime PM status of @dev cannot change.
181  */
182 static inline bool pm_runtime_status_suspended(struct device *dev)
183 {
184         return dev->power.runtime_status == RPM_SUSPENDED;
185 }
186
187 /**
188  * pm_runtime_enabled - Check if runtime PM is enabled.
189  * @dev: Target device.
190  *
191  * Return %true if runtime PM is enabled for @dev or %false otherwise.
192  *
193  * Note that the return value of this function can only be trusted if it is
194  * called under the runtime PM lock of @dev or under conditions in which
195  * runtime PM cannot be either disabled or enabled for @dev.
196  */
197 static inline bool pm_runtime_enabled(struct device *dev)
198 {
199         return !dev->power.disable_depth;
200 }
201
202 /**
203  * pm_runtime_has_no_callbacks - Check if runtime PM callbacks may be present.
204  * @dev: Target device.
205  *
206  * Return %true if @dev is a special device without runtime PM callbacks or
207  * %false otherwise.
208  */
209 static inline bool pm_runtime_has_no_callbacks(struct device *dev)
210 {
211         return dev->power.no_callbacks;
212 }
213
214 /**
215  * pm_runtime_mark_last_busy - Update the last access time of a device.
216  * @dev: Target device.
217  *
218  * Update the last access time of @dev used by the runtime PM autosuspend
219  * mechanism to the current time as returned by ktime_get_mono_fast_ns().
220  */
221 static inline void pm_runtime_mark_last_busy(struct device *dev)
222 {
223         WRITE_ONCE(dev->power.last_busy, ktime_get_mono_fast_ns());
224 }
225
226 /**
227  * pm_runtime_is_irq_safe - Check if runtime PM can work in interrupt context.
228  * @dev: Target device.
229  *
230  * Return %true if @dev has been marked as an "IRQ-safe" device (with respect
231  * to runtime PM), in which case its runtime PM callabcks can be expected to
232  * work correctly when invoked from interrupt handlers.
233  */
234 static inline bool pm_runtime_is_irq_safe(struct device *dev)
235 {
236         return dev->power.irq_safe;
237 }
238
239 extern u64 pm_runtime_suspended_time(struct device *dev);
240
241 #else /* !CONFIG_PM */
242
243 static inline bool queue_pm_work(struct work_struct *work) { return false; }
244
245 static inline int pm_generic_runtime_suspend(struct device *dev) { return 0; }
246 static inline int pm_generic_runtime_resume(struct device *dev) { return 0; }
247 static inline int pm_runtime_force_suspend(struct device *dev) { return 0; }
248 static inline int pm_runtime_force_resume(struct device *dev) { return 0; }
249
250 static inline int __pm_runtime_idle(struct device *dev, int rpmflags)
251 {
252         return -ENOSYS;
253 }
254 static inline int __pm_runtime_suspend(struct device *dev, int rpmflags)
255 {
256         return -ENOSYS;
257 }
258 static inline int __pm_runtime_resume(struct device *dev, int rpmflags)
259 {
260         return 1;
261 }
262 static inline int pm_schedule_suspend(struct device *dev, unsigned int delay)
263 {
264         return -ENOSYS;
265 }
266 static inline int pm_runtime_get_if_in_use(struct device *dev)
267 {
268         return -EINVAL;
269 }
270 static inline int pm_runtime_get_if_active(struct device *dev,
271                                            bool ign_usage_count)
272 {
273         return -EINVAL;
274 }
275 static inline int __pm_runtime_set_status(struct device *dev,
276                                             unsigned int status) { return 0; }
277 static inline int pm_runtime_barrier(struct device *dev) { return 0; }
278 static inline void pm_runtime_enable(struct device *dev) {}
279 static inline void __pm_runtime_disable(struct device *dev, bool c) {}
280 static inline void pm_runtime_allow(struct device *dev) {}
281 static inline void pm_runtime_forbid(struct device *dev) {}
282
283 static inline int devm_pm_runtime_enable(struct device *dev) { return 0; }
284
285 static inline void pm_suspend_ignore_children(struct device *dev, bool enable) {}
286 static inline void pm_runtime_get_noresume(struct device *dev) {}
287 static inline void pm_runtime_put_noidle(struct device *dev) {}
288 static inline bool pm_runtime_suspended(struct device *dev) { return false; }
289 static inline bool pm_runtime_active(struct device *dev) { return true; }
290 static inline bool pm_runtime_status_suspended(struct device *dev) { return false; }
291 static inline bool pm_runtime_enabled(struct device *dev) { return false; }
292
293 static inline void pm_runtime_no_callbacks(struct device *dev) {}
294 static inline void pm_runtime_irq_safe(struct device *dev) {}
295 static inline bool pm_runtime_is_irq_safe(struct device *dev) { return false; }
296
297 static inline bool pm_runtime_has_no_callbacks(struct device *dev) { return false; }
298 static inline void pm_runtime_mark_last_busy(struct device *dev) {}
299 static inline void __pm_runtime_use_autosuspend(struct device *dev,
300                                                 bool use) {}
301 static inline void pm_runtime_set_autosuspend_delay(struct device *dev,
302                                                 int delay) {}
303 static inline u64 pm_runtime_autosuspend_expiration(
304                                 struct device *dev) { return 0; }
305 static inline void pm_runtime_set_memalloc_noio(struct device *dev,
306                                                 bool enable){}
307 static inline void pm_runtime_get_suppliers(struct device *dev) {}
308 static inline void pm_runtime_put_suppliers(struct device *dev) {}
309 static inline void pm_runtime_new_link(struct device *dev) {}
310 static inline void pm_runtime_drop_link(struct device_link *link) {}
311 static inline void pm_runtime_release_supplier(struct device_link *link,
312                                                bool check_idle) {}
313
314 #endif /* !CONFIG_PM */
315
316 /**
317  * pm_runtime_idle - Conditionally set up autosuspend of a device or suspend it.
318  * @dev: Target device.
319  *
320  * Invoke the "idle check" callback of @dev and, depending on its return value,
321  * set up autosuspend of @dev or suspend it (depending on whether or not
322  * autosuspend has been enabled for it).
323  */
324 static inline int pm_runtime_idle(struct device *dev)
325 {
326         return __pm_runtime_idle(dev, 0);
327 }
328
329 /**
330  * pm_runtime_suspend - Suspend a device synchronously.
331  * @dev: Target device.
332  */
333 static inline int pm_runtime_suspend(struct device *dev)
334 {
335         return __pm_runtime_suspend(dev, 0);
336 }
337
338 /**
339  * pm_runtime_autosuspend - Set up autosuspend of a device or suspend it.
340  * @dev: Target device.
341  *
342  * Set up autosuspend of @dev or suspend it (depending on whether or not
343  * autosuspend is enabled for it) without engaging its "idle check" callback.
344  */
345 static inline int pm_runtime_autosuspend(struct device *dev)
346 {
347         return __pm_runtime_suspend(dev, RPM_AUTO);
348 }
349
350 /**
351  * pm_runtime_resume - Resume a device synchronously.
352  * @dev: Target device.
353  */
354 static inline int pm_runtime_resume(struct device *dev)
355 {
356         return __pm_runtime_resume(dev, 0);
357 }
358
359 /**
360  * pm_request_idle - Queue up "idle check" execution for a device.
361  * @dev: Target device.
362  *
363  * Queue up a work item to run an equivalent of pm_runtime_idle() for @dev
364  * asynchronously.
365  */
366 static inline int pm_request_idle(struct device *dev)
367 {
368         return __pm_runtime_idle(dev, RPM_ASYNC);
369 }
370
371 /**
372  * pm_request_resume - Queue up runtime-resume of a device.
373  * @dev: Target device.
374  */
375 static inline int pm_request_resume(struct device *dev)
376 {
377         return __pm_runtime_resume(dev, RPM_ASYNC);
378 }
379
380 /**
381  * pm_request_autosuspend - Queue up autosuspend of a device.
382  * @dev: Target device.
383  *
384  * Queue up a work item to run an equivalent pm_runtime_autosuspend() for @dev
385  * asynchronously.
386  */
387 static inline int pm_request_autosuspend(struct device *dev)
388 {
389         return __pm_runtime_suspend(dev, RPM_ASYNC | RPM_AUTO);
390 }
391
392 /**
393  * pm_runtime_get - Bump up usage counter and queue up resume of a device.
394  * @dev: Target device.
395  *
396  * Bump up the runtime PM usage counter of @dev and queue up a work item to
397  * carry out runtime-resume of it.
398  */
399 static inline int pm_runtime_get(struct device *dev)
400 {
401         return __pm_runtime_resume(dev, RPM_GET_PUT | RPM_ASYNC);
402 }
403
404 /**
405  * pm_runtime_get_sync - Bump up usage counter of a device and resume it.
406  * @dev: Target device.
407  *
408  * Bump up the runtime PM usage counter of @dev and carry out runtime-resume of
409  * it synchronously.
410  *
411  * The possible return values of this function are the same as for
412  * pm_runtime_resume() and the runtime PM usage counter of @dev remains
413  * incremented in all cases, even if it returns an error code.
414  * Consider using pm_runtime_resume_and_get() instead of it, especially
415  * if its return value is checked by the caller, as this is likely to result
416  * in cleaner code.
417  */
418 static inline int pm_runtime_get_sync(struct device *dev)
419 {
420         return __pm_runtime_resume(dev, RPM_GET_PUT);
421 }
422
423 /**
424  * pm_runtime_resume_and_get - Bump up usage counter of a device and resume it.
425  * @dev: Target device.
426  *
427  * Resume @dev synchronously and if that is successful, increment its runtime
428  * PM usage counter. Return 0 if the runtime PM usage counter of @dev has been
429  * incremented or a negative error code otherwise.
430  */
431 static inline int pm_runtime_resume_and_get(struct device *dev)
432 {
433         int ret;
434
435         ret = __pm_runtime_resume(dev, RPM_GET_PUT);
436         if (ret < 0) {
437                 pm_runtime_put_noidle(dev);
438                 return ret;
439         }
440
441         return 0;
442 }
443
444 /**
445  * pm_runtime_put - Drop device usage counter and queue up "idle check" if 0.
446  * @dev: Target device.
447  *
448  * Decrement the runtime PM usage counter of @dev and if it turns out to be
449  * equal to 0, queue up a work item for @dev like in pm_request_idle().
450  */
451 static inline int pm_runtime_put(struct device *dev)
452 {
453         return __pm_runtime_idle(dev, RPM_GET_PUT | RPM_ASYNC);
454 }
455
456 /**
457  * pm_runtime_put_autosuspend - Drop device usage counter and queue autosuspend if 0.
458  * @dev: Target device.
459  *
460  * Decrement the runtime PM usage counter of @dev and if it turns out to be
461  * equal to 0, queue up a work item for @dev like in pm_request_autosuspend().
462  */
463 static inline int pm_runtime_put_autosuspend(struct device *dev)
464 {
465         return __pm_runtime_suspend(dev,
466             RPM_GET_PUT | RPM_ASYNC | RPM_AUTO);
467 }
468
469 /**
470  * pm_runtime_put_sync - Drop device usage counter and run "idle check" if 0.
471  * @dev: Target device.
472  *
473  * Decrement the runtime PM usage counter of @dev and if it turns out to be
474  * equal to 0, invoke the "idle check" callback of @dev and, depending on its
475  * return value, set up autosuspend of @dev or suspend it (depending on whether
476  * or not autosuspend has been enabled for it).
477  *
478  * The possible return values of this function are the same as for
479  * pm_runtime_idle() and the runtime PM usage counter of @dev remains
480  * decremented in all cases, even if it returns an error code.
481  */
482 static inline int pm_runtime_put_sync(struct device *dev)
483 {
484         return __pm_runtime_idle(dev, RPM_GET_PUT);
485 }
486
487 /**
488  * pm_runtime_put_sync_suspend - Drop device usage counter and suspend if 0.
489  * @dev: Target device.
490  *
491  * Decrement the runtime PM usage counter of @dev and if it turns out to be
492  * equal to 0, carry out runtime-suspend of @dev synchronously.
493  *
494  * The possible return values of this function are the same as for
495  * pm_runtime_suspend() and the runtime PM usage counter of @dev remains
496  * decremented in all cases, even if it returns an error code.
497  */
498 static inline int pm_runtime_put_sync_suspend(struct device *dev)
499 {
500         return __pm_runtime_suspend(dev, RPM_GET_PUT);
501 }
502
503 /**
504  * pm_runtime_put_sync_autosuspend - Drop device usage counter and autosuspend if 0.
505  * @dev: Target device.
506  *
507  * Decrement the runtime PM usage counter of @dev and if it turns out to be
508  * equal to 0, set up autosuspend of @dev or suspend it synchronously (depending
509  * on whether or not autosuspend has been enabled for it).
510  *
511  * The possible return values of this function are the same as for
512  * pm_runtime_autosuspend() and the runtime PM usage counter of @dev remains
513  * decremented in all cases, even if it returns an error code.
514  */
515 static inline int pm_runtime_put_sync_autosuspend(struct device *dev)
516 {
517         return __pm_runtime_suspend(dev, RPM_GET_PUT | RPM_AUTO);
518 }
519
520 /**
521  * pm_runtime_set_active - Set runtime PM status to "active".
522  * @dev: Target device.
523  *
524  * Set the runtime PM status of @dev to %RPM_ACTIVE and ensure that dependencies
525  * of it will be taken into account.
526  *
527  * It is not valid to call this function for devices with runtime PM enabled.
528  */
529 static inline int pm_runtime_set_active(struct device *dev)
530 {
531         return __pm_runtime_set_status(dev, RPM_ACTIVE);
532 }
533
534 /**
535  * pm_runtime_set_suspended - Set runtime PM status to "suspended".
536  * @dev: Target device.
537  *
538  * Set the runtime PM status of @dev to %RPM_SUSPENDED and ensure that
539  * dependencies of it will be taken into account.
540  *
541  * It is not valid to call this function for devices with runtime PM enabled.
542  */
543 static inline int pm_runtime_set_suspended(struct device *dev)
544 {
545         return __pm_runtime_set_status(dev, RPM_SUSPENDED);
546 }
547
548 /**
549  * pm_runtime_disable - Disable runtime PM for a device.
550  * @dev: Target device.
551  *
552  * Prevent the runtime PM framework from working with @dev (by incrementing its
553  * "blocking" counter).
554  *
555  * For each invocation of this function for @dev there must be a matching
556  * pm_runtime_enable() call in order for runtime PM to be enabled for it.
557  */
558 static inline void pm_runtime_disable(struct device *dev)
559 {
560         __pm_runtime_disable(dev, true);
561 }
562
563 /**
564  * pm_runtime_use_autosuspend - Allow autosuspend to be used for a device.
565  * @dev: Target device.
566  *
567  * Allow the runtime PM autosuspend mechanism to be used for @dev whenever
568  * requested (or "autosuspend" will be handled as direct runtime-suspend for
569  * it).
570  *
571  * NOTE: It's important to undo this with pm_runtime_dont_use_autosuspend()
572  * at driver exit time unless your driver initially enabled pm_runtime
573  * with devm_pm_runtime_enable() (which handles it for you).
574  */
575 static inline void pm_runtime_use_autosuspend(struct device *dev)
576 {
577         __pm_runtime_use_autosuspend(dev, true);
578 }
579
580 /**
581  * pm_runtime_dont_use_autosuspend - Prevent autosuspend from being used.
582  * @dev: Target device.
583  *
584  * Prevent the runtime PM autosuspend mechanism from being used for @dev which
585  * means that "autosuspend" will be handled as direct runtime-suspend for it
586  * going forward.
587  */
588 static inline void pm_runtime_dont_use_autosuspend(struct device *dev)
589 {
590         __pm_runtime_use_autosuspend(dev, false);
591 }
592
593 #endif