Documentation/power/runtime_pm.rst

Source file repositories/reference/linux-study-clean/Documentation/power/runtime_pm.rst

File Facts

System
Linux kernel
Corpus path
Documentation/power/runtime_pm.rst
Extension
.rst
Size
47185 bytes
Lines
960
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct dev_pm_ops {
	...
	int (*runtime_suspend)(struct device *dev);
	int (*runtime_resume)(struct device *dev);
	int (*runtime_idle)(struct device *dev);
	...
  };

The ->runtime_suspend(), ->runtime_resume() and ->runtime_idle() callbacks
are executed by the PM core for the device's subsystem that may be either of
the following:

  1. PM domain of the device, if the device's PM domain object, dev->pm_domain,
     is present.

  2. Device type of the device, if both dev->type and dev->type->pm are present.

  3. Device class of the device, if both dev->class and dev->class->pm are
     present.

  4. Bus type of the device, if both dev->bus and dev->bus->pm are present.

If the subsystem chosen by applying the above rules doesn't provide the relevant
callback, the PM core will invoke the corresponding driver callback stored in
dev->driver->pm directly (if present).

The PM core always checks which callback to use in the order given above, so the
priority order of callbacks from high to low is: PM domain, device type, class
and bus type.  Moreover, the high-priority one will always take precedence over
a low-priority one.  The PM domain, bus type, device type and class callbacks
are referred to as subsystem-level callbacks in what follows.

By default, the callbacks are always invoked in process context with interrupts
enabled.  However, the pm_runtime_irq_safe() helper function can be used to tell
the PM core that it is safe to run the ->runtime_suspend(), ->runtime_resume()
and ->runtime_idle() callbacks for the given device in atomic context with
interrupts disabled.  This implies that the callback routines in question must
not block or sleep, but it also means that the synchronous helper functions
listed at the end of Section 4 may be used for that device within an interrupt
handler or generally in an atomic context.

The subsystem-level suspend callback, if present, is _entirely_ _responsible_
for handling the suspend of the device as appropriate, which may, but need not
include executing the device driver's own ->runtime_suspend() callback (from the
PM core's point of view it is not necessary to implement a ->runtime_suspend()
callback in a device driver as long as the subsystem-level suspend callback
knows what to do to handle the device).

  * Once the subsystem-level suspend callback (or the driver suspend callback,
    if invoked directly) has completed successfully for the given device, the PM
    core regards the device as suspended, which need not mean that it has been
    put into a low power state.  It is supposed to mean, however, that the
    device will not process data and will not communicate with the CPU(s) and
    RAM until the appropriate resume callback is executed for it.  The runtime
    PM status of a device after successful execution of the suspend callback is
    'suspended'.

  * If the suspend callback returns -EBUSY or -EAGAIN, the device's runtime PM
    status remains 'active', which means that the device _must_ be fully
    operational afterwards.

  * If the suspend callback returns an error code different from -EBUSY and
    -EAGAIN, the PM core regards this as a fatal error and will refuse to run
    the helper functions described in Section 4 for the device until its status
    is directly set to  either 'active', or 'suspended' (the PM core provides
    special helper functions for this purpose).

In particular, if the driver requires remote wakeup capability (i.e. hardware
mechanism allowing the device to request a change of its power state, such as
PCI PME) for proper functioning and device_can_wakeup() returns 'false' for the

Annotation

Implementation Notes