^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ==================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) Runtime Power Management Framework for I/O Devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ==================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) (C) 2009-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) (C) 2010 Alan Stern <stern@rowland.harvard.edu>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) (C) 2014 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) 1. Introduction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) Support for runtime power management (runtime PM) of I/O devices is provided
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) at the power management core (PM core) level by means of:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) * The power management workqueue pm_wq in which bus types and device drivers can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) put their PM-related work items. It is strongly recommended that pm_wq be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) used for queuing all work items related to runtime PM, because this allows
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) them to be synchronized with system-wide power transitions (suspend to RAM,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) hibernation and resume from system sleep states). pm_wq is declared in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) include/linux/pm_runtime.h and defined in kernel/power/main.c.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) * A number of runtime PM fields in the 'power' member of 'struct device' (which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) is of the type 'struct dev_pm_info', defined in include/linux/pm.h) that can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) be used for synchronizing runtime PM operations with one another.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) * Three device runtime PM callbacks in 'struct dev_pm_ops' (defined in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) include/linux/pm.h).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) * A set of helper functions defined in drivers/base/power/runtime.c that can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) used for carrying out runtime PM operations in such a way that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) synchronization between them is taken care of by the PM core. Bus types and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) device drivers are encouraged to use these functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) The runtime PM callbacks present in 'struct dev_pm_ops', the device runtime PM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) fields of 'struct dev_pm_info' and the core helper functions provided for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) runtime PM are described below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) 2. Device Runtime PM Callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) There are three device runtime PM callbacks defined in 'struct dev_pm_ops'::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) struct dev_pm_ops {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) int (*runtime_suspend)(struct device *dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) int (*runtime_resume)(struct device *dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) int (*runtime_idle)(struct device *dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) The ->runtime_suspend(), ->runtime_resume() and ->runtime_idle() callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) are executed by the PM core for the device's subsystem that may be either of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) the following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) 1. PM domain of the device, if the device's PM domain object, dev->pm_domain,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) is present.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) 2. Device type of the device, if both dev->type and dev->type->pm are present.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) 3. Device class of the device, if both dev->class and dev->class->pm are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) present.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) 4. Bus type of the device, if both dev->bus and dev->bus->pm are present.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) If the subsystem chosen by applying the above rules doesn't provide the relevant
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) callback, the PM core will invoke the corresponding driver callback stored in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) dev->driver->pm directly (if present).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) The PM core always checks which callback to use in the order given above, so the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) priority order of callbacks from high to low is: PM domain, device type, class
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) and bus type. Moreover, the high-priority one will always take precedence over
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) a low-priority one. The PM domain, bus type, device type and class callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) are referred to as subsystem-level callbacks in what follows.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) By default, the callbacks are always invoked in process context with interrupts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) enabled. However, the pm_runtime_irq_safe() helper function can be used to tell
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) the PM core that it is safe to run the ->runtime_suspend(), ->runtime_resume()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) and ->runtime_idle() callbacks for the given device in atomic context with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) interrupts disabled. This implies that the callback routines in question must
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) not block or sleep, but it also means that the synchronous helper functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) listed at the end of Section 4 may be used for that device within an interrupt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) handler or generally in an atomic context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) The subsystem-level suspend callback, if present, is _entirely_ _responsible_
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) for handling the suspend of the device as appropriate, which may, but need not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) include executing the device driver's own ->runtime_suspend() callback (from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) PM core's point of view it is not necessary to implement a ->runtime_suspend()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) callback in a device driver as long as the subsystem-level suspend callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) knows what to do to handle the device).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) * Once the subsystem-level suspend callback (or the driver suspend callback,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) if invoked directly) has completed successfully for the given device, the PM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) core regards the device as suspended, which need not mean that it has been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) put into a low power state. It is supposed to mean, however, that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) device will not process data and will not communicate with the CPU(s) and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) RAM until the appropriate resume callback is executed for it. The runtime
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) PM status of a device after successful execution of the suspend callback is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) 'suspended'.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) * If the suspend callback returns -EBUSY or -EAGAIN, the device's runtime PM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) status remains 'active', which means that the device _must_ be fully
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) operational afterwards.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) * If the suspend callback returns an error code different from -EBUSY and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) -EAGAIN, the PM core regards this as a fatal error and will refuse to run
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) the helper functions described in Section 4 for the device until its status
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) is directly set to either 'active', or 'suspended' (the PM core provides
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) special helper functions for this purpose).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) In particular, if the driver requires remote wakeup capability (i.e. hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) mechanism allowing the device to request a change of its power state, such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) PCI PME) for proper functioning and device_can_wakeup() returns 'false' for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) device, then ->runtime_suspend() should return -EBUSY. On the other hand, if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) device_can_wakeup() returns 'true' for the device and the device is put into a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) low-power state during the execution of the suspend callback, it is expected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) that remote wakeup will be enabled for the device. Generally, remote wakeup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) should be enabled for all input devices put into low-power states at run time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) The subsystem-level resume callback, if present, is **entirely responsible** for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) handling the resume of the device as appropriate, which may, but need not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) include executing the device driver's own ->runtime_resume() callback (from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) PM core's point of view it is not necessary to implement a ->runtime_resume()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) callback in a device driver as long as the subsystem-level resume callback knows
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) what to do to handle the device).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) * Once the subsystem-level resume callback (or the driver resume callback, if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) invoked directly) has completed successfully, the PM core regards the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) as fully operational, which means that the device _must_ be able to complete
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) I/O operations as needed. The runtime PM status of the device is then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) 'active'.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) * If the resume callback returns an error code, the PM core regards this as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) fatal error and will refuse to run the helper functions described in Section
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) 4 for the device, until its status is directly set to either 'active', or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) 'suspended' (by means of special helper functions provided by the PM core
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) for this purpose).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) The idle callback (a subsystem-level one, if present, or the driver one) is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) executed by the PM core whenever the device appears to be idle, which is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) indicated to the PM core by two counters, the device's usage counter and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) counter of 'active' children of the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) * If any of these counters is decreased using a helper function provided by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) the PM core and it turns out to be equal to zero, the other counter is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) checked. If that counter also is equal to zero, the PM core executes the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) idle callback with the device as its argument.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) The action performed by the idle callback is totally dependent on the subsystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) (or driver) in question, but the expected and recommended action is to check
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) if the device can be suspended (i.e. if all of the conditions necessary for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) suspending the device are satisfied) and to queue up a suspend request for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) device in that case. If there is no idle callback, or if the callback returns
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) 0, then the PM core will attempt to carry out a runtime suspend of the device,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) also respecting devices configured for autosuspend. In essence this means a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) call to pm_runtime_autosuspend() (do note that drivers needs to update the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) device last busy mark, pm_runtime_mark_last_busy(), to control the delay under
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) this circumstance). To prevent this (for example, if the callback routine has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) started a delayed suspend), the routine must return a non-zero value. Negative
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) error return codes are ignored by the PM core.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) The helper functions provided by the PM core, described in Section 4, guarantee
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) that the following constraints are met with respect to runtime PM callbacks for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) one device:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) (1) The callbacks are mutually exclusive (e.g. it is forbidden to execute
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) ->runtime_suspend() in parallel with ->runtime_resume() or with another
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) instance of ->runtime_suspend() for the same device) with the exception that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) ->runtime_suspend() or ->runtime_resume() can be executed in parallel with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) ->runtime_idle() (although ->runtime_idle() will not be started while any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) of the other callbacks is being executed for the same device).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) (2) ->runtime_idle() and ->runtime_suspend() can only be executed for 'active'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) devices (i.e. the PM core will only execute ->runtime_idle() or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) ->runtime_suspend() for the devices the runtime PM status of which is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) 'active').
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) (3) ->runtime_idle() and ->runtime_suspend() can only be executed for a device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) the usage counter of which is equal to zero _and_ either the counter of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) 'active' children of which is equal to zero, or the 'power.ignore_children'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) flag of which is set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) (4) ->runtime_resume() can only be executed for 'suspended' devices (i.e. the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) PM core will only execute ->runtime_resume() for the devices the runtime
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) PM status of which is 'suspended').
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) Additionally, the helper functions provided by the PM core obey the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) rules:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) * If ->runtime_suspend() is about to be executed or there's a pending request
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) to execute it, ->runtime_idle() will not be executed for the same device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) * A request to execute or to schedule the execution of ->runtime_suspend()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) will cancel any pending requests to execute ->runtime_idle() for the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) * If ->runtime_resume() is about to be executed or there's a pending request
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) to execute it, the other callbacks will not be executed for the same device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) * A request to execute ->runtime_resume() will cancel any pending or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) scheduled requests to execute the other callbacks for the same device,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) except for scheduled autosuspends.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) 3. Runtime PM Device Fields
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) ===========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) The following device runtime PM fields are present in 'struct dev_pm_info', as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) defined in include/linux/pm.h:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) `struct timer_list suspend_timer;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) - timer used for scheduling (delayed) suspend and autosuspend requests
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) `unsigned long timer_expires;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) - timer expiration time, in jiffies (if this is different from zero, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) timer is running and will expire at that time, otherwise the timer is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) running)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) `struct work_struct work;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) - work structure used for queuing up requests (i.e. work items in pm_wq)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) `wait_queue_head_t wait_queue;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) - wait queue used if any of the helper functions needs to wait for another
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) one to complete
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) `spinlock_t lock;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) - lock used for synchronization
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) `atomic_t usage_count;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) - the usage counter of the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) `atomic_t child_count;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) - the count of 'active' children of the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) `unsigned int ignore_children;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) - if set, the value of child_count is ignored (but still updated)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) `unsigned int disable_depth;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) - used for disabling the helper functions (they work normally if this is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) equal to zero); the initial value of it is 1 (i.e. runtime PM is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) initially disabled for all devices)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) `int runtime_error;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) - if set, there was a fatal error (one of the callbacks returned error code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) as described in Section 2), so the helper functions will not work until
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) this flag is cleared; this is the error code returned by the failing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) `unsigned int idle_notification;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) - if set, ->runtime_idle() is being executed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) `unsigned int request_pending;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) - if set, there's a pending request (i.e. a work item queued up into pm_wq)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) `enum rpm_request request;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) - type of request that's pending (valid if request_pending is set)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) `unsigned int deferred_resume;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) - set if ->runtime_resume() is about to be run while ->runtime_suspend() is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) being executed for that device and it is not practical to wait for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) suspend to complete; means "start a resume as soon as you've suspended"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) `enum rpm_status runtime_status;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) - the runtime PM status of the device; this field's initial value is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) RPM_SUSPENDED, which means that each device is initially regarded by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) PM core as 'suspended', regardless of its real hardware status
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) `unsigned int runtime_auto;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) - if set, indicates that the user space has allowed the device driver to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) power manage the device at run time via the /sys/devices/.../power/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) `interface;` it may only be modified with the help of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) pm_runtime_allow() and pm_runtime_forbid() helper functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) `unsigned int no_callbacks;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) - indicates that the device does not use the runtime PM callbacks (see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) Section 8); it may be modified only by the pm_runtime_no_callbacks()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) helper function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) `unsigned int irq_safe;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) - indicates that the ->runtime_suspend() and ->runtime_resume() callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) will be invoked with the spinlock held and interrupts disabled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) `unsigned int use_autosuspend;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) - indicates that the device's driver supports delayed autosuspend (see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) Section 9); it may be modified only by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) pm_runtime{_dont}_use_autosuspend() helper functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) `unsigned int timer_autosuspends;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) - indicates that the PM core should attempt to carry out an autosuspend
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) when the timer expires rather than a normal suspend
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) `int autosuspend_delay;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) - the delay time (in milliseconds) to be used for autosuspend
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) `unsigned long last_busy;`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) - the time (in jiffies) when the pm_runtime_mark_last_busy() helper
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) function was last called for this device; used in calculating inactivity
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) periods for autosuspend
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) All of the above fields are members of the 'power' member of 'struct device'.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) 4. Runtime PM Device Helper Functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) =====================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) The following runtime PM helper functions are defined in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) drivers/base/power/runtime.c and include/linux/pm_runtime.h:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) `void pm_runtime_init(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) - initialize the device runtime PM fields in 'struct dev_pm_info'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) `void pm_runtime_remove(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) - make sure that the runtime PM of the device will be disabled after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) removing the device from device hierarchy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) `int pm_runtime_idle(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) - execute the subsystem-level idle callback for the device; returns an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) error code on failure, where -EINPROGRESS means that ->runtime_idle() is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) already being executed; if there is no callback or the callback returns 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) then run pm_runtime_autosuspend(dev) and return its result
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) `int pm_runtime_suspend(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) - execute the subsystem-level suspend callback for the device; returns 0 on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) success, 1 if the device's runtime PM status was already 'suspended', or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) error code on failure, where -EAGAIN or -EBUSY means it is safe to attempt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) to suspend the device again in future and -EACCES means that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) 'power.disable_depth' is different from 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) `int pm_runtime_autosuspend(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) - same as pm_runtime_suspend() except that the autosuspend delay is taken
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) `into account;` if pm_runtime_autosuspend_expiration() says the delay has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) not yet expired then an autosuspend is scheduled for the appropriate time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) and 0 is returned
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) `int pm_runtime_resume(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) - execute the subsystem-level resume callback for the device; returns 0 on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) success, 1 if the device's runtime PM status was already 'active' or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) error code on failure, where -EAGAIN means it may be safe to attempt to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) resume the device again in future, but 'power.runtime_error' should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) checked additionally, and -EACCES means that 'power.disable_depth' is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) different from 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) `int pm_request_idle(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) - submit a request to execute the subsystem-level idle callback for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) device (the request is represented by a work item in pm_wq); returns 0 on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) success or error code if the request has not been queued up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) `int pm_request_autosuspend(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) - schedule the execution of the subsystem-level suspend callback for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) device when the autosuspend delay has expired; if the delay has already
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) expired then the work item is queued up immediately
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) `int pm_schedule_suspend(struct device *dev, unsigned int delay);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) - schedule the execution of the subsystem-level suspend callback for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) device in future, where 'delay' is the time to wait before queuing up a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) suspend work item in pm_wq, in milliseconds (if 'delay' is zero, the work
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) item is queued up immediately); returns 0 on success, 1 if the device's PM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) runtime status was already 'suspended', or error code if the request
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) hasn't been scheduled (or queued up if 'delay' is 0); if the execution of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) ->runtime_suspend() is already scheduled and not yet expired, the new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) value of 'delay' will be used as the time to wait
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) `int pm_request_resume(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) - submit a request to execute the subsystem-level resume callback for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) device (the request is represented by a work item in pm_wq); returns 0 on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) success, 1 if the device's runtime PM status was already 'active', or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) error code if the request hasn't been queued up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) `void pm_runtime_get_noresume(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) - increment the device's usage counter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) `int pm_runtime_get(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) - increment the device's usage counter, run pm_request_resume(dev) and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) return its result
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) `int pm_runtime_get_sync(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) - increment the device's usage counter, run pm_runtime_resume(dev) and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) return its result
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) `int pm_runtime_get_if_in_use(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) - return -EINVAL if 'power.disable_depth' is nonzero; otherwise, if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) runtime PM status is RPM_ACTIVE and the runtime PM usage counter is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) nonzero, increment the counter and return 1; otherwise return 0 without
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) changing the counter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) `int pm_runtime_get_if_active(struct device *dev, bool ign_usage_count);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) - return -EINVAL if 'power.disable_depth' is nonzero; otherwise, if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) runtime PM status is RPM_ACTIVE, and either ign_usage_count is true
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) or the device's usage_count is non-zero, increment the counter and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) return 1; otherwise return 0 without changing the counter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) `void pm_runtime_put_noidle(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) - decrement the device's usage counter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) `int pm_runtime_put(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) - decrement the device's usage counter; if the result is 0 then run
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) pm_request_idle(dev) and return its result
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) `int pm_runtime_put_autosuspend(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) - decrement the device's usage counter; if the result is 0 then run
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) pm_request_autosuspend(dev) and return its result
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) `int pm_runtime_put_sync(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) - decrement the device's usage counter; if the result is 0 then run
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) pm_runtime_idle(dev) and return its result
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) `int pm_runtime_put_sync_suspend(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) - decrement the device's usage counter; if the result is 0 then run
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) pm_runtime_suspend(dev) and return its result
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) `int pm_runtime_put_sync_autosuspend(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) - decrement the device's usage counter; if the result is 0 then run
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) pm_runtime_autosuspend(dev) and return its result
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) `void pm_runtime_enable(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) - decrement the device's 'power.disable_depth' field; if that field is equal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) to zero, the runtime PM helper functions can execute subsystem-level
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) callbacks described in Section 2 for the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) `int pm_runtime_disable(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) - increment the device's 'power.disable_depth' field (if the value of that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) field was previously zero, this prevents subsystem-level runtime PM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) callbacks from being run for the device), make sure that all of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423) pending runtime PM operations on the device are either completed or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) canceled; returns 1 if there was a resume request pending and it was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) necessary to execute the subsystem-level resume callback for the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) to satisfy that request, otherwise 0 is returned
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) `int pm_runtime_barrier(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) - check if there's a resume request pending for the device and resume it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) (synchronously) in that case, cancel any other pending runtime PM requests
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) regarding it and wait for all runtime PM operations on it in progress to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) complete; returns 1 if there was a resume request pending and it was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) necessary to execute the subsystem-level resume callback for the device to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) satisfy that request, otherwise 0 is returned
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) `void pm_suspend_ignore_children(struct device *dev, bool enable);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) - set/unset the power.ignore_children flag of the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) `int pm_runtime_set_active(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) - clear the device's 'power.runtime_error' flag, set the device's runtime
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) PM status to 'active' and update its parent's counter of 'active'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) children as appropriate (it is only valid to use this function if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) 'power.runtime_error' is set or 'power.disable_depth' is greater than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) zero); it will fail and return error code if the device has a parent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) which is not active and the 'power.ignore_children' flag of which is unset
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) `void pm_runtime_set_suspended(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) - clear the device's 'power.runtime_error' flag, set the device's runtime
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) PM status to 'suspended' and update its parent's counter of 'active'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) children as appropriate (it is only valid to use this function if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) 'power.runtime_error' is set or 'power.disable_depth' is greater than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) zero)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) `bool pm_runtime_active(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) - return true if the device's runtime PM status is 'active' or its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) 'power.disable_depth' field is not equal to zero, or false otherwise
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) `bool pm_runtime_suspended(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) - return true if the device's runtime PM status is 'suspended' and its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) 'power.disable_depth' field is equal to zero, or false otherwise
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) `bool pm_runtime_status_suspended(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) - return true if the device's runtime PM status is 'suspended'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) `void pm_runtime_allow(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) - set the power.runtime_auto flag for the device and decrease its usage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) counter (used by the /sys/devices/.../power/control interface to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) effectively allow the device to be power managed at run time)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) `void pm_runtime_forbid(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) - unset the power.runtime_auto flag for the device and increase its usage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) counter (used by the /sys/devices/.../power/control interface to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) effectively prevent the device from being power managed at run time)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) `void pm_runtime_no_callbacks(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) - set the power.no_callbacks flag for the device and remove the runtime
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) PM attributes from /sys/devices/.../power (or prevent them from being
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) added when the device is registered)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) `void pm_runtime_irq_safe(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) - set the power.irq_safe flag for the device, causing the runtime-PM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) callbacks to be invoked with interrupts off
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) `bool pm_runtime_is_irq_safe(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) - return true if power.irq_safe flag was set for the device, causing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486) the runtime-PM callbacks to be invoked with interrupts off
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) `void pm_runtime_mark_last_busy(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) - set the power.last_busy field to the current time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) `void pm_runtime_use_autosuspend(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) - set the power.use_autosuspend flag, enabling autosuspend delays; call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) pm_runtime_get_sync if the flag was previously cleared and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) power.autosuspend_delay is negative
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) `void pm_runtime_dont_use_autosuspend(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) - clear the power.use_autosuspend flag, disabling autosuspend delays;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) decrement the device's usage counter if the flag was previously set and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) power.autosuspend_delay is negative; call pm_runtime_idle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) `void pm_runtime_set_autosuspend_delay(struct device *dev, int delay);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) - set the power.autosuspend_delay value to 'delay' (expressed in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) milliseconds); if 'delay' is negative then runtime suspends are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) prevented; if power.use_autosuspend is set, pm_runtime_get_sync may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505) called or the device's usage counter may be decremented and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) pm_runtime_idle called depending on if power.autosuspend_delay is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) changed to or from a negative value; if power.use_autosuspend is clear,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508) pm_runtime_idle is called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) `unsigned long pm_runtime_autosuspend_expiration(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) - calculate the time when the current autosuspend delay period will expire,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) based on power.last_busy and power.autosuspend_delay; if the delay time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513) is 1000 ms or larger then the expiration time is rounded up to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) nearest second; returns 0 if the delay period has already expired or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515) power.use_autosuspend isn't set, otherwise returns the expiration time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) in jiffies
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518) It is safe to execute the following helper functions from interrupt context:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520) - pm_request_idle()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) - pm_request_autosuspend()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) - pm_schedule_suspend()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) - pm_request_resume()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524) - pm_runtime_get_noresume()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) - pm_runtime_get()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) - pm_runtime_put_noidle()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) - pm_runtime_put()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528) - pm_runtime_put_autosuspend()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) - pm_runtime_enable()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530) - pm_suspend_ignore_children()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531) - pm_runtime_set_active()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532) - pm_runtime_set_suspended()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) - pm_runtime_suspended()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534) - pm_runtime_mark_last_busy()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535) - pm_runtime_autosuspend_expiration()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537) If pm_runtime_irq_safe() has been called for a device then the following helper
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538) functions may also be used in interrupt context:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540) - pm_runtime_idle()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) - pm_runtime_suspend()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542) - pm_runtime_autosuspend()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543) - pm_runtime_resume()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544) - pm_runtime_get_sync()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545) - pm_runtime_put_sync()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546) - pm_runtime_put_sync_suspend()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547) - pm_runtime_put_sync_autosuspend()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549) 5. Runtime PM Initialization, Device Probing and Removal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550) ========================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552) Initially, the runtime PM is disabled for all devices, which means that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) majority of the runtime PM helper functions described in Section 4 will return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554) -EAGAIN until pm_runtime_enable() is called for the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) In addition to that, the initial runtime PM status of all devices is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557) 'suspended', but it need not reflect the actual physical state of the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558) Thus, if the device is initially active (i.e. it is able to process I/O), its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559) runtime PM status must be changed to 'active', with the help of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) pm_runtime_set_active(), before pm_runtime_enable() is called for the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562) However, if the device has a parent and the parent's runtime PM is enabled,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563) calling pm_runtime_set_active() for the device will affect the parent, unless
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) the parent's 'power.ignore_children' flag is set. Namely, in that case the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565) parent won't be able to suspend at run time, using the PM core's helper
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566) functions, as long as the child's status is 'active', even if the child's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567) runtime PM is still disabled (i.e. pm_runtime_enable() hasn't been called for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568) the child yet or pm_runtime_disable() has been called for it). For this reason,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569) once pm_runtime_set_active() has been called for the device, pm_runtime_enable()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570) should be called for it too as soon as reasonably possible or its runtime PM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571) status should be changed back to 'suspended' with the help of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572) pm_runtime_set_suspended().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574) If the default initial runtime PM status of the device (i.e. 'suspended')
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) reflects the actual state of the device, its bus type's or its driver's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) ->probe() callback will likely need to wake it up using one of the PM core's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577) helper functions described in Section 4. In that case, pm_runtime_resume()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578) should be used. Of course, for this purpose the device's runtime PM has to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579) enabled earlier by calling pm_runtime_enable().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581) Note, if the device may execute pm_runtime calls during the probe (such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582) if it is registers with a subsystem that may call back in) then the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583) pm_runtime_get_sync() call paired with a pm_runtime_put() call will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) appropriate to ensure that the device is not put back to sleep during the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585) probe. This can happen with systems such as the network device layer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587) It may be desirable to suspend the device once ->probe() has finished.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588) Therefore the driver core uses the asynchronous pm_request_idle() to submit a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589) request to execute the subsystem-level idle callback for the device at that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590) time. A driver that makes use of the runtime autosuspend feature, may want to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) update the last busy mark before returning from ->probe().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593) Moreover, the driver core prevents runtime PM callbacks from racing with the bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594) notifier callback in __device_release_driver(), which is necessary, because the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595) notifier is used by some subsystems to carry out operations affecting the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596) runtime PM functionality. It does so by calling pm_runtime_get_sync() before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597) driver_sysfs_remove() and the BUS_NOTIFY_UNBIND_DRIVER notifications. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598) resumes the device if it's in the suspended state and prevents it from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599) being suspended again while those routines are being executed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601) To allow bus types and drivers to put devices into the suspended state by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602) calling pm_runtime_suspend() from their ->remove() routines, the driver core
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603) executes pm_runtime_put_sync() after running the BUS_NOTIFY_UNBIND_DRIVER
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604) notifications in __device_release_driver(). This requires bus types and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605) drivers to make their ->remove() callbacks avoid races with runtime PM directly,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) but also it allows of more flexibility in the handling of devices during the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607) removal of their drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609) Drivers in ->remove() callback should undo the runtime PM changes done
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610) in ->probe(). Usually this means calling pm_runtime_disable(),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611) pm_runtime_dont_use_autosuspend() etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613) The user space can effectively disallow the driver of the device to power manage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614) it at run time by changing the value of its /sys/devices/.../power/control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615) attribute to "on", which causes pm_runtime_forbid() to be called. In principle,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616) this mechanism may also be used by the driver to effectively turn off the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) runtime power management of the device until the user space turns it on.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618) Namely, during the initialization the driver can make sure that the runtime PM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619) status of the device is 'active' and call pm_runtime_forbid(). It should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 620) noted, however, that if the user space has already intentionally changed the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 621) value of /sys/devices/.../power/control to "auto" to allow the driver to power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 622) manage the device at run time, the driver may confuse it by using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623) pm_runtime_forbid() this way.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625) 6. Runtime PM and System Sleep
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626) ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 628) Runtime PM and system sleep (i.e., system suspend and hibernation, also known
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 629) as suspend-to-RAM and suspend-to-disk) interact with each other in a couple of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 630) ways. If a device is active when a system sleep starts, everything is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 631) straightforward. But what should happen if the device is already suspended?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 632)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 633) The device may have different wake-up settings for runtime PM and system sleep.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 634) For example, remote wake-up may be enabled for runtime suspend but disallowed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 635) for system sleep (device_may_wakeup(dev) returns 'false'). When this happens,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 636) the subsystem-level system suspend callback is responsible for changing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 637) device's wake-up setting (it may leave that to the device driver's system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 638) suspend routine). It may be necessary to resume the device and suspend it again
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 639) in order to do so. The same is true if the driver uses different power levels
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 640) or other settings for runtime suspend and system sleep.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 641)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 642) During system resume, the simplest approach is to bring all devices back to full
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 643) power, even if they had been suspended before the system suspend began. There
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 644) are several reasons for this, including:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 645)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 646) * The device might need to switch power levels, wake-up settings, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 647)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 648) * Remote wake-up events might have been lost by the firmware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 649)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 650) * The device's children may need the device to be at full power in order
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 651) to resume themselves.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 652)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 653) * The driver's idea of the device state may not agree with the device's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 654) physical state. This can happen during resume from hibernation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 655)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 656) * The device might need to be reset.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 657)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 658) * Even though the device was suspended, if its usage counter was > 0 then most
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 659) likely it would need a runtime resume in the near future anyway.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 660)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 661) If the device had been suspended before the system suspend began and it's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 662) brought back to full power during resume, then its runtime PM status will have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 663) to be updated to reflect the actual post-system sleep status. The way to do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 664) this is:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 665)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 666) - pm_runtime_disable(dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 667) - pm_runtime_set_active(dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 668) - pm_runtime_enable(dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 669)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 670) The PM core always increments the runtime usage counter before calling the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 671) ->suspend() callback and decrements it after calling the ->resume() callback.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 672) Hence disabling runtime PM temporarily like this will not cause any runtime
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 673) suspend attempts to be permanently lost. If the usage count goes to zero
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 674) following the return of the ->resume() callback, the ->runtime_idle() callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 675) will be invoked as usual.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 676)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 677) On some systems, however, system sleep is not entered through a global firmware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 678) or hardware operation. Instead, all hardware components are put into low-power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 679) states directly by the kernel in a coordinated way. Then, the system sleep
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 680) state effectively follows from the states the hardware components end up in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 681) and the system is woken up from that state by a hardware interrupt or a similar
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 682) mechanism entirely under the kernel's control. As a result, the kernel never
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 683) gives control away and the states of all devices during resume are precisely
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 684) known to it. If that is the case and none of the situations listed above takes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 685) place (in particular, if the system is not waking up from hibernation), it may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 686) be more efficient to leave the devices that had been suspended before the system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 687) suspend began in the suspended state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 688)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 689) To this end, the PM core provides a mechanism allowing some coordination between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 690) different levels of device hierarchy. Namely, if a system suspend .prepare()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 691) callback returns a positive number for a device, that indicates to the PM core
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 692) that the device appears to be runtime-suspended and its state is fine, so it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 693) may be left in runtime suspend provided that all of its descendants are also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 694) left in runtime suspend. If that happens, the PM core will not execute any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 695) system suspend and resume callbacks for all of those devices, except for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 696) complete callback, which is then entirely responsible for handling the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 697) as appropriate. This only applies to system suspend transitions that are not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 698) related to hibernation (see Documentation/driver-api/pm/devices.rst for more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 699) information).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 700)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 701) The PM core does its best to reduce the probability of race conditions between
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 702) the runtime PM and system suspend/resume (and hibernation) callbacks by carrying
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 703) out the following operations:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 704)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 705) * During system suspend pm_runtime_get_noresume() is called for every device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 706) right before executing the subsystem-level .prepare() callback for it and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 707) pm_runtime_barrier() is called for every device right before executing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 708) subsystem-level .suspend() callback for it. In addition to that the PM core
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 709) calls __pm_runtime_disable() with 'false' as the second argument for every
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 710) device right before executing the subsystem-level .suspend_late() callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 711) for it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 712)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 713) * During system resume pm_runtime_enable() and pm_runtime_put() are called for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 714) every device right after executing the subsystem-level .resume_early()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 715) callback and right after executing the subsystem-level .complete() callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 716) for it, respectively.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 717)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 718) 7. Generic subsystem callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 719)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 720) Subsystems may wish to conserve code space by using the set of generic power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 721) management callbacks provided by the PM core, defined in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 722) driver/base/power/generic_ops.c:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 723)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 724) `int pm_generic_runtime_suspend(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 725) - invoke the ->runtime_suspend() callback provided by the driver of this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 726) device and return its result, or return 0 if not defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 727)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 728) `int pm_generic_runtime_resume(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 729) - invoke the ->runtime_resume() callback provided by the driver of this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 730) device and return its result, or return 0 if not defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 731)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 732) `int pm_generic_suspend(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 733) - if the device has not been suspended at run time, invoke the ->suspend()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 734) callback provided by its driver and return its result, or return 0 if not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 735) defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 736)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 737) `int pm_generic_suspend_noirq(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 738) - if pm_runtime_suspended(dev) returns "false", invoke the ->suspend_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 739) callback provided by the device's driver and return its result, or return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 740) 0 if not defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 741)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 742) `int pm_generic_resume(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 743) - invoke the ->resume() callback provided by the driver of this device and,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 744) if successful, change the device's runtime PM status to 'active'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 745)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 746) `int pm_generic_resume_noirq(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 747) - invoke the ->resume_noirq() callback provided by the driver of this device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 748)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 749) `int pm_generic_freeze(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 750) - if the device has not been suspended at run time, invoke the ->freeze()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 751) callback provided by its driver and return its result, or return 0 if not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 752) defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 753)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 754) `int pm_generic_freeze_noirq(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 755) - if pm_runtime_suspended(dev) returns "false", invoke the ->freeze_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 756) callback provided by the device's driver and return its result, or return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 757) 0 if not defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 758)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 759) `int pm_generic_thaw(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 760) - if the device has not been suspended at run time, invoke the ->thaw()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 761) callback provided by its driver and return its result, or return 0 if not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 762) defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 763)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 764) `int pm_generic_thaw_noirq(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 765) - if pm_runtime_suspended(dev) returns "false", invoke the ->thaw_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 766) callback provided by the device's driver and return its result, or return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 767) 0 if not defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 768)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 769) `int pm_generic_poweroff(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 770) - if the device has not been suspended at run time, invoke the ->poweroff()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 771) callback provided by its driver and return its result, or return 0 if not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 772) defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 773)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 774) `int pm_generic_poweroff_noirq(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 775) - if pm_runtime_suspended(dev) returns "false", run the ->poweroff_noirq()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 776) callback provided by the device's driver and return its result, or return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 777) 0 if not defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 778)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 779) `int pm_generic_restore(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 780) - invoke the ->restore() callback provided by the driver of this device and,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 781) if successful, change the device's runtime PM status to 'active'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 782)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 783) `int pm_generic_restore_noirq(struct device *dev);`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 784) - invoke the ->restore_noirq() callback provided by the device's driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 785)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 786) These functions are the defaults used by the PM core, if a subsystem doesn't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 787) provide its own callbacks for ->runtime_idle(), ->runtime_suspend(),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 788) ->runtime_resume(), ->suspend(), ->suspend_noirq(), ->resume(),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 789) ->resume_noirq(), ->freeze(), ->freeze_noirq(), ->thaw(), ->thaw_noirq(),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 790) ->poweroff(), ->poweroff_noirq(), ->restore(), ->restore_noirq() in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 791) subsystem-level dev_pm_ops structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 792)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 793) Device drivers that wish to use the same function as a system suspend, freeze,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 794) poweroff and runtime suspend callback, and similarly for system resume, thaw,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 795) restore, and runtime resume, can achieve this with the help of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 796) UNIVERSAL_DEV_PM_OPS macro defined in include/linux/pm.h (possibly setting its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 797) last argument to NULL).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 798)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 799) 8. "No-Callback" Devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 800) ========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 801)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 802) Some "devices" are only logical sub-devices of their parent and cannot be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 803) power-managed on their own. (The prototype example is a USB interface. Entire
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 804) USB devices can go into low-power mode or send wake-up requests, but neither is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 805) possible for individual interfaces.) The drivers for these devices have no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 806) need of runtime PM callbacks; if the callbacks did exist, ->runtime_suspend()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 807) and ->runtime_resume() would always return 0 without doing anything else and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 808) ->runtime_idle() would always call pm_runtime_suspend().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 809)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 810) Subsystems can tell the PM core about these devices by calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 811) pm_runtime_no_callbacks(). This should be done after the device structure is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 812) initialized and before it is registered (although after device registration is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 813) also okay). The routine will set the device's power.no_callbacks flag and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 814) prevent the non-debugging runtime PM sysfs attributes from being created.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 815)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 816) When power.no_callbacks is set, the PM core will not invoke the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 817) ->runtime_idle(), ->runtime_suspend(), or ->runtime_resume() callbacks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 818) Instead it will assume that suspends and resumes always succeed and that idle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 819) devices should be suspended.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 820)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 821) As a consequence, the PM core will never directly inform the device's subsystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 822) or driver about runtime power changes. Instead, the driver for the device's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 823) parent must take responsibility for telling the device's driver when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 824) parent's power state changes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 825)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 826) 9. Autosuspend, or automatically-delayed suspends
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 827) =================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 828)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 829) Changing a device's power state isn't free; it requires both time and energy.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 830) A device should be put in a low-power state only when there's some reason to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 831) think it will remain in that state for a substantial time. A common heuristic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 832) says that a device which hasn't been used for a while is liable to remain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 833) unused; following this advice, drivers should not allow devices to be suspended
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 834) at runtime until they have been inactive for some minimum period. Even when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 835) the heuristic ends up being non-optimal, it will still prevent devices from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 836) "bouncing" too rapidly between low-power and full-power states.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 837)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 838) The term "autosuspend" is an historical remnant. It doesn't mean that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 839) device is automatically suspended (the subsystem or driver still has to call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 840) the appropriate PM routines); rather it means that runtime suspends will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 841) automatically be delayed until the desired period of inactivity has elapsed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 842)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 843) Inactivity is determined based on the power.last_busy field. Drivers should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 844) call pm_runtime_mark_last_busy() to update this field after carrying out I/O,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 845) typically just before calling pm_runtime_put_autosuspend(). The desired length
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 846) of the inactivity period is a matter of policy. Subsystems can set this length
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 847) initially by calling pm_runtime_set_autosuspend_delay(), but after device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 848) registration the length should be controlled by user space, using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 849) /sys/devices/.../power/autosuspend_delay_ms attribute.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 850)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 851) In order to use autosuspend, subsystems or drivers must call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 852) pm_runtime_use_autosuspend() (preferably before registering the device), and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 853) thereafter they should use the various `*_autosuspend()` helper functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 854) instead of the non-autosuspend counterparts::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 855)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 856) Instead of: pm_runtime_suspend use: pm_runtime_autosuspend;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 857) Instead of: pm_schedule_suspend use: pm_request_autosuspend;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 858) Instead of: pm_runtime_put use: pm_runtime_put_autosuspend;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 859) Instead of: pm_runtime_put_sync use: pm_runtime_put_sync_autosuspend.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 860)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 861) Drivers may also continue to use the non-autosuspend helper functions; they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 862) will behave normally, which means sometimes taking the autosuspend delay into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 863) account (see pm_runtime_idle).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 864)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 865) Under some circumstances a driver or subsystem may want to prevent a device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 866) from autosuspending immediately, even though the usage counter is zero and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 867) autosuspend delay time has expired. If the ->runtime_suspend() callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 868) returns -EAGAIN or -EBUSY, and if the next autosuspend delay expiration time is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 869) in the future (as it normally would be if the callback invoked
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 870) pm_runtime_mark_last_busy()), the PM core will automatically reschedule the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 871) autosuspend. The ->runtime_suspend() callback can't do this rescheduling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 872) itself because no suspend requests of any kind are accepted while the device is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 873) suspending (i.e., while the callback is running).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 874)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 875) The implementation is well suited for asynchronous use in interrupt contexts.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 876) However such use inevitably involves races, because the PM core can't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 877) synchronize ->runtime_suspend() callbacks with the arrival of I/O requests.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 878) This synchronization must be handled by the driver, using its private lock.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 879) Here is a schematic pseudo-code example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 880)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 881) foo_read_or_write(struct foo_priv *foo, void *data)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 882) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 883) lock(&foo->private_lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 884) add_request_to_io_queue(foo, data);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 885) if (foo->num_pending_requests++ == 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 886) pm_runtime_get(&foo->dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 887) if (!foo->is_suspended)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 888) foo_process_next_request(foo);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 889) unlock(&foo->private_lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 890) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 891)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 892) foo_io_completion(struct foo_priv *foo, void *req)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 893) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 894) lock(&foo->private_lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 895) if (--foo->num_pending_requests == 0) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 896) pm_runtime_mark_last_busy(&foo->dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 897) pm_runtime_put_autosuspend(&foo->dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 898) } else {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 899) foo_process_next_request(foo);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 900) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 901) unlock(&foo->private_lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 902) /* Send req result back to the user ... */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 903) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 904)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 905) int foo_runtime_suspend(struct device *dev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 906) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 907) struct foo_priv foo = container_of(dev, ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 908) int ret = 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 909)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 910) lock(&foo->private_lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 911) if (foo->num_pending_requests > 0) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 912) ret = -EBUSY;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 913) } else {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 914) /* ... suspend the device ... */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 915) foo->is_suspended = 1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 916) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 917) unlock(&foo->private_lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 918) return ret;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 919) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 920)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 921) int foo_runtime_resume(struct device *dev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 922) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 923) struct foo_priv foo = container_of(dev, ...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 924)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 925) lock(&foo->private_lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 926) /* ... resume the device ... */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 927) foo->is_suspended = 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 928) pm_runtime_mark_last_busy(&foo->dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 929) if (foo->num_pending_requests > 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 930) foo_process_next_request(foo);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 931) unlock(&foo->private_lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 932) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 933) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 934)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 935) The important point is that after foo_io_completion() asks for an autosuspend,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 936) the foo_runtime_suspend() callback may race with foo_read_or_write().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 937) Therefore foo_runtime_suspend() has to check whether there are any pending I/O
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 938) requests (while holding the private lock) before allowing the suspend to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 939) proceed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 940)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 941) In addition, the power.autosuspend_delay field can be changed by user space at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 942) any time. If a driver cares about this, it can call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 943) pm_runtime_autosuspend_expiration() from within the ->runtime_suspend()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 944) callback while holding its private lock. If the function returns a nonzero
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 945) value then the delay has not yet expired and the callback should return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 946) -EAGAIN.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags