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 <[email protected]> 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 static inline void pm_runtime_use_autosuspend(struct device *dev) 572 { 573 __pm_runtime_use_autosuspend(dev, true); 574 } 575 576 /** 577 * pm_runtime_dont_use_autosuspend - Prevent autosuspend from being used. 578 * @dev: Target device. 579 * 580 * Prevent the runtime PM autosuspend mechanism from being used for @dev which 581 * means that "autosuspend" will be handled as direct runtime-suspend for it 582 * going forward. 583 */ 584 static inline void pm_runtime_dont_use_autosuspend(struct device *dev) 585 { 586 __pm_runtime_use_autosuspend(dev, false); 587 } 588 589 #endif 590