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_callbacks_present(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  */
 384 static inline int pm_runtime_get_sync(struct device *dev)
 385 {
 386         return __pm_runtime_resume(dev, RPM_GET_PUT);
 387 }
 388
 389 /**
 390  * pm_runtime_resume_and_get - Bump up usage counter of a device and resume it.
 391  * @dev: Target device.
 392  *
 393  * Resume @dev synchronously and if that is successful, increment its runtime
 394  * PM usage counter. Return 0 if the runtime PM usage counter of @dev has been
 395  * incremented or a negative error code otherwise.
 396  */
 397 static inline int pm_runtime_resume_and_get(struct device *dev)
 398 {
 399         int ret;
 400
 401         ret = __pm_runtime_resume(dev, RPM_GET_PUT);
 402         if (ret < 0) {
 403                 pm_runtime_put_noidle(dev);
 404                 return ret;
 405         }
 406
 407         return 0;
 408 }
 409
 410 /**
 411  * pm_runtime_put - Drop device usage counter and queue up "idle check" if 0.
 412  * @dev: Target device.
 413  *
 414  * Decrement the runtime PM usage counter of @dev and if it turns out to be
 415  * equal to 0, queue up a work item for @dev like in pm_request_idle().
 416  */
 417 static inline int pm_runtime_put(struct device *dev)
 418 {
 419         return __pm_runtime_idle(dev, RPM_GET_PUT | RPM_ASYNC);
 420 }
 421
 422 /**
 423  * pm_runtime_put_autosuspend - Drop device usage counter and queue autosuspend if 0.
 424  * @dev: Target device.
 425  *
 426  * Decrement the runtime PM usage counter of @dev and if it turns out to be
 427  * equal to 0, queue up a work item for @dev like in pm_request_autosuspend().
 428  */
 429 static inline int pm_runtime_put_autosuspend(struct device *dev)
 430 {
 431         return __pm_runtime_suspend(dev,
 432             RPM_GET_PUT | RPM_ASYNC | RPM_AUTO);
 433 }
 434
 435 /**
 436  * pm_runtime_put_sync - Drop device usage counter and run "idle check" if 0.
 437  * @dev: Target device.
 438  *
 439  * Decrement the runtime PM usage counter of @dev and if it turns out to be
 440  * equal to 0, invoke the "idle check" callback of @dev and, depending on its
 441  * return value, set up autosuspend of @dev or suspend it (depending on whether
 442  * or not autosuspend has been enabled for it).
 443  *
 444  * The possible return values of this function are the same as for
 445  * pm_runtime_idle() and the runtime PM usage counter of @dev remains
 446  * decremented in all cases, even if it returns an error code.
 447  */
 448 static inline int pm_runtime_put_sync(struct device *dev)
 449 {
 450         return __pm_runtime_idle(dev, RPM_GET_PUT);
 451 }
 452
 453 /**
 454  * pm_runtime_put_sync_suspend - Drop device usage counter and suspend if 0.
 455  * @dev: Target device.
 456  *
 457  * Decrement the runtime PM usage counter of @dev and if it turns out to be
 458  * equal to 0, carry out runtime-suspend of @dev synchronously.
 459  *
 460  * The possible return values of this function are the same as for
 461  * pm_runtime_suspend() and the runtime PM usage counter of @dev remains
 462  * decremented in all cases, even if it returns an error code.
 463  */
 464 static inline int pm_runtime_put_sync_suspend(struct device *dev)
 465 {
 466         return __pm_runtime_suspend(dev, RPM_GET_PUT);
 467 }
 468
 469 /**
 470  * pm_runtime_put_sync_autosuspend - Drop device usage counter and autosuspend 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, set up autosuspend of @dev or suspend it synchronously (depending
 475  * on whether or not autosuspend has been enabled for it).
 476  *
 477  * The possible return values of this function are the same as for
 478  * pm_runtime_autosuspend() and the runtime PM usage counter of @dev remains
 479  * decremented in all cases, even if it returns an error code.
 480  */
 481 static inline int pm_runtime_put_sync_autosuspend(struct device *dev)
 482 {
 483         return __pm_runtime_suspend(dev, RPM_GET_PUT | RPM_AUTO);
 484 }
 485
 486 /**
 487  * pm_runtime_set_active - Set runtime PM status to "active".
 488  * @dev: Target device.
 489  *
 490  * Set the runtime PM status of @dev to %RPM_ACTIVE and ensure that dependencies
 491  * of it will be taken into account.
 492  *
 493  * It is not valid to call this function for devices with runtime PM enabled.
 494  */
 495 static inline int pm_runtime_set_active(struct device *dev)
 496 {
 497         return __pm_runtime_set_status(dev, RPM_ACTIVE);
 498 }
 499
 500 /**
 501  * pm_runtime_set_suspended - Set runtime PM status to "suspended".
 502  * @dev: Target device.
 503  *
 504  * Set the runtime PM status of @dev to %RPM_SUSPENDED and ensure that
 505  * dependencies of it will be taken into account.
 506  *
 507  * It is not valid to call this function for devices with runtime PM enabled.
 508  */
 509 static inline int pm_runtime_set_suspended(struct device *dev)
 510 {
 511         return __pm_runtime_set_status(dev, RPM_SUSPENDED);
 512 }
 513
 514 /**
 515  * pm_runtime_disable - Disable runtime PM for a device.
 516  * @dev: Target device.
 517  *
 518  * Prevent the runtime PM framework from working with @dev (by incrementing its
 519  * "blocking" counter).
 520  *
 521  * For each invocation of this function for @dev there must be a matching
 522  * pm_runtime_enable() call in order for runtime PM to be enabled for it.
 523  */
 524 static inline void pm_runtime_disable(struct device *dev)
 525 {
 526         __pm_runtime_disable(dev, true);
 527 }
 528
 529 /**
 530  * pm_runtime_use_autosuspend - Allow autosuspend to be used for a device.
 531  * @dev: Target device.
 532  *
 533  * Allow the runtime PM autosuspend mechanism to be used for @dev whenever
 534  * requested (or "autosuspend" will be handled as direct runtime-suspend for
 535  * it).
 536  */
 537 static inline void pm_runtime_use_autosuspend(struct device *dev)
 538 {
 539         __pm_runtime_use_autosuspend(dev, true);
 540 }
 541
 542 /**
 543  * pm_runtime_dont_use_autosuspend - Prevent autosuspend from being used.
 544  * @dev: Target device.
 545  *
 546  * Prevent the runtime PM autosuspend mechanism from being used for @dev which
 547  * means that "autosuspend" will be handled as direct runtime-suspend for it
 548  * going forward.
 549  */
 550 static inline void pm_runtime_dont_use_autosuspend(struct device *dev)
 551 {
 552         __pm_runtime_use_autosuspend(dev, false);
 553 }
 554
 555 #endif