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