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