Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 5841eb64 authored by Rafael J. Wysocki's avatar Rafael J. Wysocki
Browse files

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



The current power management documentation in Documentation/power/
either doesn't cover PM domains at all, or gives inaccurate
information about them, so update the relevant files in there to
follow the code.

Signed-off-by: default avatarRafael J. Wysocki <rjw@sisk.pl>
parent bb58dd5d

Documentation/power/devices.txt

+27 −15
Original line number Original line Diff line number Diff line
@@ -123,9 +123,10 @@ please refer directly to the source code for more information about it. 
Subsystem-Level Methods

Subsystem-Level Methods

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

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

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

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

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

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

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

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

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

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

drivers using it; PCI works differently from USB, and so on.  Not many people
@@ -251,18 +252,29 @@ various phases always run after tasks have been frozen and before they are 
unfrozen.  Furthermore, the *_noirq phases run at a time when IRQ handlers have

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

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

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





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

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

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

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

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

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

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

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

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

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

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

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

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

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

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),

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

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

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

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

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

types or classes if necessary).



    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

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

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

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

Documentation/power/runtime_pm.txt

+18 −11
Original line number Original line Diff line number Diff line
@@ -44,17 +44,24 @@ struct dev_pm_ops { 
};

};





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

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

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

are executed by the PM core for the device's subsystem that may be either of

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

the following:

(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'

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

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

     is present.

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

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

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,

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

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

     present.

power domains within a SoC.



  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

By default, the callbacks are always invoked in process context with interrupts

enabled.  However, subsystems can use the pm_runtime_irq_safe() helper function

enabled.  However, subsystems can use the pm_runtime_irq_safe() helper function