Documentation/power/runtime_pm.rst

17 * The power management workqueue pm_wq in which bus types and device drivers can
24 * A number of runtime PM fields in the 'power' member of 'struct device' (which
28 * Three device runtime PM callbacks in 'struct dev_pm_ops' (defined in
34   device drivers are encouraged to use these functions.
36 The runtime PM callbacks present in 'struct dev_pm_ops', the device runtime PM
40 2. Device Runtime PM Callbacks
43 There are three device runtime PM callbacks defined in 'struct dev_pm_ops'::
47 	int (*runtime_suspend)(struct device *dev);
48 	int (*runtime_resume)(struct device *dev);
49 	int (*runtime_idle)(struct device *dev);
54 are executed by the PM core for the device's subsystem that may be either of
57   1. PM domain of the device, if the device's PM domain object, dev->pm_domain,
60   2. Device type of the device, if both dev->type and dev->type->pm are present.
62   3. Device class of the device, if both dev->class and dev->class->pm are
65   4. Bus type of the device, if both dev->bus and dev->bus->pm are present.
72 priority order of callbacks from high to low is: PM domain, device type, class
74 a low-priority one.  The PM domain, bus type, device type and class callbacks
80 and ->runtime_idle() callbacks for the given device in atomic context with
83 listed at the end of Section 4 may be used for that device within an interrupt
87 for handling the suspend of the device as appropriate, which may, but need not
88 include executing the device driver's own ->runtime_suspend() callback (from the
90 callback in a device driver as long as the subsystem-level suspend callback
91 knows what to do to handle the device).
94     if invoked directly) has completed successfully for the given device, the PM
95     core regards the device as suspended, which need not mean that it has been
97     device will not process data and will not communicate with the CPU(s) and
99     PM status of a device after successful execution of the suspend callback is
102   * If the suspend callback returns -EBUSY or -EAGAIN, the device's runtime PM
103     status remains 'active', which means that the device _must_ be fully
108     the helper functions described in Section 4 for the device until its status
113 mechanism allowing the device to request a change of its power state, such as
115 device, then ->runtime_suspend() should return -EBUSY.  On the other hand, if
116 device_can_wakeup() returns 'true' for the device and the device is put into a
118 that remote wakeup will be enabled for the device.  Generally, remote wakeup
122 handling the resume of the device as appropriate, which may, but need not
123 include executing the device driver's own ->runtime_resume() callback (from the
125 callback in a device driver as long as the subsystem-level resume callback knows
126 what to do to handle the device).
129     invoked directly) has completed successfully, the PM core regards the device
130     as fully operational, which means that the device _must_ be able to complete
131     I/O operations as needed.  The runtime PM status of the device is then
136     4 for the device, until its status is directly set to either 'active', or
141 executed by the PM core whenever the device appears to be idle, which is
142 indicated to the PM core by two counters, the device's usage counter and the
143 counter of 'active' children of the device.
148     idle callback with the device as its argument.
152 if the device can be suspended (i.e. if all of the conditions necessary for
153 suspending the device are satisfied) and to queue up a suspend request for the
154 device in that case.  If there is no idle callback, or if the callback returns
155 0, then the PM core will attempt to carry out a runtime suspend of the device,
158 device last busy mark, pm_runtime_mark_last_busy(), to control the delay under
165 one device:
169     instance of ->runtime_suspend() for the same device) with the exception that
172     of the other callbacks is being executed for the same device).
179 (3) ->runtime_idle() and ->runtime_suspend() can only be executed for a device
192     to execute it, ->runtime_idle() will not be executed for the same device.
196     device.
199     to execute it, the other callbacks will not be executed for the same device.
202     scheduled requests to execute the other callbacks for the same device,
205 3. Runtime PM Device Fields
208 The following device runtime PM fields are present in 'struct dev_pm_info', as
230     - the usage counter of the device
233     - the count of 'active' children of the device
260       being executed for that device and it is not practical to wait for the
264     - the runtime PM status of the device; this field's initial value is
265       RPM_SUSPENDED, which means that each device is initially regarded by the
269     - the last runtime PM status of the device captured before disabling runtime
273     - if set, indicates that the user space has allowed the device driver to
274       power manage the device at run time via the /sys/devices/.../power/control
279     - indicates that the device does not use the runtime PM callbacks (see
288     - indicates that the device's driver supports delayed autosuspend (see
301       function was last called for this device; used in calculating inactivity
304 All of the above fields are members of the 'power' member of 'struct device'.
306 4. Runtime PM Device Helper Functions
312   `void pm_runtime_init(struct device *dev);`
313     - initialize the device runtime PM fields in 'struct dev_pm_info'
315   `void pm_runtime_remove(struct device *dev);`
316     - make sure that the runtime PM of the device will be disabled after
317       removing the device from device hierarchy
319   `int pm_runtime_idle(struct device *dev);`
320     - execute the subsystem-level idle callback for the device; returns an
325   `int pm_runtime_suspend(struct device *dev);`
326     - execute the subsystem-level suspend callback for the device; returns 0 on
327       success, 1 if the device's runtime PM status was already 'suspended', or
329       to suspend the device again in future and -EACCES means that
332   `int pm_runtime_autosuspend(struct device *dev);`
338   `int pm_runtime_resume(struct device *dev);`
339     - execute the subsystem-level resume callback for the device; returns 0 on
340       success, 1 if the device's runtime PM status is already 'active' (also if
343       be safe to attempt to resume the device again in future, but
348   `int pm_runtime_resume_and_get(struct device *dev);`
349     - run pm_runtime_resume(dev) and if successful, increment the device's
352   `int pm_request_idle(struct device *dev);`
354       device (the request is represented by a work item in pm_wq); returns 0 on
357   `int pm_request_autosuspend(struct device *dev);`
359       device when the autosuspend delay has expired; if the delay has already
362   `int pm_schedule_suspend(struct device *dev, unsigned int delay);`
364       device in future, where 'delay' is the time to wait before queuing up a
366       item is queued up immediately); returns 0 on success, 1 if the device's PM
372   `int pm_request_resume(struct device *dev);`
374       device (the request is represented by a work item in pm_wq); returns 0 on
375       success, 1 if the device's runtime PM status was already 'active', or
378   `void pm_runtime_get_noresume(struct device *dev);`
379     - increment the device's usage counter
381   `int pm_runtime_get(struct device *dev);`
382     - increment the device's usage counter, run pm_request_resume(dev) and
385   `int pm_runtime_get_sync(struct device *dev);`
386     - increment the device's usage counter, run pm_runtime_resume(dev) and
388       note that it does not drop the device's usage counter on errors, so
393   `int pm_runtime_get_if_in_use(struct device *dev);`
399   `int pm_runtime_get_if_active(struct device *dev);`
404   `void pm_runtime_put_noidle(struct device *dev);`
405     - decrement the device's usage counter
407   `int pm_runtime_put(struct device *dev);`
408     - decrement the device's usage counter; if the result is 0 then run
411   `int pm_runtime_put_autosuspend(struct device *dev);`
415   `int __pm_runtime_put_autosuspend(struct device *dev);`
416     - decrement the device's usage counter; if the result is 0 then run
419   `int pm_runtime_put_sync(struct device *dev);`
420     - decrement the device's usage counter; if the result is 0 then run
423   `int pm_runtime_put_sync_suspend(struct device *dev);`
424     - decrement the device's usage counter; if the result is 0 then run
427   `int pm_runtime_put_sync_autosuspend(struct device *dev);`
428     - decrement the device's usage counter; if the result is 0 then run
431   `void pm_runtime_enable(struct device *dev);`
432     - decrement the device's 'power.disable_depth' field; if that field is equal
434       callbacks described in Section 2 for the device
436   `int pm_runtime_disable(struct device *dev);`
437     - increment the device's 'power.disable_depth' field (if the value of that
439       callbacks from being run for the device), make sure that all of the
440       pending runtime PM operations on the device are either completed or
442       necessary to execute the subsystem-level resume callback for the device
445   `int pm_runtime_barrier(struct device *dev);`
446     - check if there's a resume request pending for the device and resume it
450       necessary to execute the subsystem-level resume callback for the device to
453   `void pm_suspend_ignore_children(struct device *dev, bool enable);`
454     - set/unset the power.ignore_children flag of the device
456   `int pm_runtime_set_active(struct device *dev);`
457     - clear the device's 'power.runtime_error' flag, set the device's runtime
461       zero); it will fail and return error code if the device has a parent
464   `void pm_runtime_set_suspended(struct device *dev);`
465     - clear the device's 'power.runtime_error' flag, set the device's runtime
471   `bool pm_runtime_active(struct device *dev);`
472     - return true if the device's runtime PM status is 'active' or its
475   `bool pm_runtime_suspended(struct device *dev);`
476     - return true if the device's runtime PM status is 'suspended' and its
479   `bool pm_runtime_status_suspended(struct device *dev);`
480     - return true if the device's runtime PM status is 'suspended'
482   `void pm_runtime_allow(struct device *dev);`
483     - set the power.runtime_auto flag for the device and decrease its usage
485       effectively allow the device to be power managed at run time)
487   `void pm_runtime_forbid(struct device *dev);`
488     - unset the power.runtime_auto flag for the device and increase its usage
490       effectively prevent the device from being power managed at run time)
492   `void pm_runtime_no_callbacks(struct device *dev);`
493     - set the power.no_callbacks flag for the device and remove the runtime
495       added when the device is registered)
497   `void pm_runtime_irq_safe(struct device *dev);`
498     - set the power.irq_safe flag for the device, causing the runtime-PM
501   `bool pm_runtime_is_irq_safe(struct device *dev);`
502     - return true if power.irq_safe flag was set for the device, causing
505   `void pm_runtime_mark_last_busy(struct device *dev);`
508   `void pm_runtime_use_autosuspend(struct device *dev);`
513   `void pm_runtime_dont_use_autosuspend(struct device *dev);`
515       decrement the device's usage counter if the flag was previously set and
518   `void pm_runtime_set_autosuspend_delay(struct device *dev, int delay);`
522       called or the device's usage counter may be decremented and
527   `unsigned long pm_runtime_autosuspend_expiration(struct device *dev);`
555 If pm_runtime_irq_safe() has been called for a device then the following helper
567 5. Runtime PM Initialization, Device Probing and Removal
572 -EAGAIN until pm_runtime_enable() is called for the device.
575 'suspended', but it need not reflect the actual physical state of the device.
576 Thus, if the device is initially active (i.e. it is able to process I/O), its
578 pm_runtime_set_active(), before pm_runtime_enable() is called for the device.
580 However, if the device has a parent and the parent's runtime PM is enabled,
581 calling pm_runtime_set_active() for the device will affect the parent, unless
587 once pm_runtime_set_active() has been called for the device, pm_runtime_enable()
592 If the default initial runtime PM status of the device (i.e. 'suspended')
593 reflects the actual state of the device, its bus type's or its driver's
596 should be used.  Of course, for this purpose the device's runtime PM has to be
599 Note, if the device may execute pm_runtime calls during the probe (such as
602 appropriate to ensure that the device is not put back to sleep during the
603 probe. This can happen with systems such as the network device layer.
605 It may be desirable to suspend the device once ->probe() has finished.
607 request to execute the subsystem-level idle callback for the device at that
616 resumes the device if it's in the suspended state and prevents it from
631 The user space can effectively disallow the driver of the device to power manage
635 runtime power management of the device until the user space turns it on.
637 status of the device is 'active' and call pm_runtime_forbid().  It should be
640 manage the device at run time, the driver may confuse it by using
648 ways.  If a device is active when a system sleep starts, everything is
649 straightforward.  But what should happen if the device is already suspended?
651 The device may have different wake-up settings for runtime PM and system sleep.
655 device's wake-up setting (it may leave that to the device driver's system
656 suspend routine).  It may be necessary to resume the device and suspend it again
664   * The device might need to switch power levels, wake-up settings, etc.
668   * The device's children may need the device to be at full power in order
671   * The driver's idea of the device state may not agree with the device's
674   * The device might need to be reset.
676   * Even though the device was suspended, if its usage counter was > 0 then most
679 If the device had been suspended before the system suspend began and it's
708 different levels of device hierarchy.  Namely, if a system suspend .prepare()
709 callback returns a positive number for a device, that indicates to the PM core
710 that the device appears to be runtime-suspended and its state is fine, so it
714 .complete() callback, which is then entirely responsible for handling the device
723   * During system suspend pm_runtime_get_noresume() is called for every device
725     pm_runtime_barrier() is called for every device right before executing the
728     device right before executing the subsystem-level .suspend_late() callback
732     every device right after executing the subsystem-level .resume_early()
743   `int pm_generic_runtime_suspend(struct device *dev);`
745       device and return its result, or return 0 if not defined
747   `int pm_generic_runtime_resume(struct device *dev);`
749       device and return its result, or return 0 if not defined
751   `int pm_generic_suspend(struct device *dev);`
752     - if the device has not been suspended at run time, invoke the ->suspend()
756   `int pm_generic_suspend_noirq(struct device *dev);`
758       callback provided by the device's driver and return its result, or return
761   `int pm_generic_resume(struct device *dev);`
762     - invoke the ->resume() callback provided by the driver of this device and,
763       if successful, change the device's runtime PM status to 'active'
765   `int pm_generic_resume_noirq(struct device *dev);`
766     - invoke the ->resume_noirq() callback provided by the driver of this device
768   `int pm_generic_freeze(struct device *dev);`
769     - if the device has not been suspended at run time, invoke the ->freeze()
773   `int pm_generic_freeze_noirq(struct device *dev);`
775       callback provided by the device's driver and return its result, or return
778   `int pm_generic_thaw(struct device *dev);`
779     - if the device has not been suspended at run time, invoke the ->thaw()
783   `int pm_generic_thaw_noirq(struct device *dev);`
785       callback provided by the device's driver and return its result, or return
788   `int pm_generic_poweroff(struct device *dev);`
789     - if the device has not been suspended at run time, invoke the ->poweroff()
793   `int pm_generic_poweroff_noirq(struct device *dev);`
795       callback provided by the device's driver and return its result, or return
798   `int pm_generic_restore(struct device *dev);`
799     - invoke the ->restore() callback provided by the driver of this device and,
800       if successful, change the device's runtime PM status to 'active'
802   `int pm_generic_restore_noirq(struct device *dev);`
803     - invoke the ->restore_noirq() callback provided by the device's driver
812 Device drivers that wish to use the same function as a system suspend, freeze,
830 pm_runtime_no_callbacks().  This should be done after the device structure is
831 initialized and before it is registered (although after device registration is
832 also okay).  The routine will set the device's power.no_callbacks flag and
840 As a consequence, the PM core will never directly inform the device's subsystem
841 or driver about runtime power changes.  Instead, the driver for the device's
842 parent must take responsibility for telling the device's driver when the
848 domain could get attached to the device or that the device is power managed
849 through a supplier device link. For these reasons and to avoid boilerplate code
857 Changing a device's power state isn't free; it requires both time and energy.
858 A device should be put in a low-power state only when there's some reason to
860 says that a device which hasn't been used for a while is liable to remain
867 device is automatically suspended (the subsystem or driver still has to call
875 length initially by calling pm_runtime_set_autosuspend_delay(), but after device
880 pm_runtime_use_autosuspend() (preferably before registering the device), and
893 Under some circumstances a driver or subsystem may want to prevent a device
900 itself because no suspend requests of any kind are accepted while the device is
933 	int foo_runtime_suspend(struct device *dev)
942 			/* ... suspend the device ... */
949 	int foo_runtime_resume(struct device *dev)
954 		/* ... resume the device ... */