PM / Domains: Document how PM domains are used by the PM core

Subsystem-Level Methods

-----------------------

The core methods to suspend and resume devices reside in struct dev_pm_ops

pointed to by the pm member of struct bus_type, struct device_type and

struct class.  They are mostly of interest to the people writing infrastructure

for buses, like PCI or USB, or device type and device class drivers.

pointed to by the ops member of struct dev_pm_domain, or by the pm member of

struct bus_type, struct device_type and struct class.  They are mostly of

interest to the people writing infrastructure for platforms and buses, like PCI

or USB, or device type and device class drivers.

Bus drivers implement these methods as appropriate for the hardware and the

drivers using it; PCI works differently from USB, and so on.  Not many people

unfrozen.  Furthermore, the *_noirq phases run at a time when IRQ handlers have

been disabled (except for those marked with the IRQ_WAKEUP flag).

All phases use bus, type, or class callbacks (that is, methods defined in

dev->bus->pm, dev->type->pm, or dev->class->pm).  These callbacks are mutually

exclusive, so if the device type provides a struct dev_pm_ops object pointed to

by its pm field (i.e. both dev->type and dev->type->pm are defined), the

callbacks included in that object (i.e. dev->type->pm) will be used.  Otherwise,

if the class provides a struct dev_pm_ops object pointed to by its pm field

(i.e. both dev->class and dev->class->pm are defined), the PM core will use the

callbacks from that object (i.e. dev->class->pm).  Finally, if the pm fields of

both the device type and class objects are NULL (or those objects do not exist),

the callbacks provided by the bus (that is, the callbacks from dev->bus->pm)

will be used (this allows device types to override callbacks provided by bus

types or classes if necessary).

All phases use PM domain, bus, type, or class callbacks (that is, methods

defined in dev->pm_domain->ops, dev->bus->pm, dev->type->pm, or dev->class->pm).

These callbacks are regarded by the PM core as mutually exclusive.  Moreover,

PM domain callbacks always take precedence over bus, type and class callbacks,

while type callbacks take precedence over bus and class callbacks, and class

callbacks take precedence over bus callbacks.  To be precise, the following

rules are used to determine which callback to execute in the given phase:

    1.	If dev->pm_domain is present, the PM core will attempt to execute the

	callback included in dev->pm_domain->ops.  If that callback is not

	present, no action will be carried out for the given device.

    2.	Otherwise, if both dev->type and dev->type->pm are present, the callback

	included in dev->type->pm will be executed.

    3.	Otherwise, if both dev->class and dev->class->pm are present, the

	callback included in dev->class->pm will be executed.

    4.	Otherwise, if both dev->bus and dev->bus->pm are present, the callback

	included in dev->bus->pm will be executed.

This allows PM domains and device types to override callbacks provided by bus

types or device classes if necessary.

These callbacks may in turn invoke device- or driver-specific methods stored in

dev->driver->pm, but they don't have to.

};

The ->runtime_suspend(), ->runtime_resume() and ->runtime_idle() callbacks

are executed by the PM core for either the power domain, or the device type

(if the device power domain's struct dev_pm_ops does not exist), or the class

(if the device power domain's and type's struct dev_pm_ops object does not

exist), or the bus type (if the device power domain's, type's and class'

struct dev_pm_ops objects do not exist) of the given device, so the priority

order of callbacks from high to low is that power domain callbacks, device

type callbacks, class callbacks and bus type callbacks, and the high priority

one will take precedence over low priority one. The bus type, device type and

class callbacks are referred to as subsystem-level callbacks in what follows,

and generally speaking, the power domain callbacks are used for representing

power domains within a SoC.

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.

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, subsystems can use the pm_runtime_irq_safe() helper function