cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

devices.rst (47362B)


      1.. SPDX-License-Identifier: GPL-2.0
      2.. include:: <isonum.txt>
      3
      4.. _driverapi_pm_devices:
      5
      6==============================
      7Device Power Management Basics
      8==============================
      9
     10:Copyright: |copy| 2010-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc.
     11:Copyright: |copy| 2010 Alan Stern <stern@rowland.harvard.edu>
     12:Copyright: |copy| 2016 Intel Corporation
     13
     14:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
     15
     16
     17Most of the code in Linux is device drivers, so most of the Linux power
     18management (PM) code is also driver-specific.  Most drivers will do very
     19little; others, especially for platforms with small batteries (like cell
     20phones), will do a lot.
     21
     22This writeup gives an overview of how drivers interact with system-wide
     23power management goals, emphasizing the models and interfaces that are
     24shared by everything that hooks up to the driver model core.  Read it as
     25background for the domain-specific work you'd do with any specific driver.
     26
     27
     28Two Models for Device Power Management
     29======================================
     30
     31Drivers will use one or both of these models to put devices into low-power
     32states:
     33
     34    System Sleep model:
     35
     36	Drivers can enter low-power states as part of entering system-wide
     37	low-power states like "suspend" (also known as "suspend-to-RAM"), or
     38	(mostly for systems with disks) "hibernation" (also known as
     39	"suspend-to-disk").
     40
     41	This is something that device, bus, and class drivers collaborate on
     42	by implementing various role-specific suspend and resume methods to
     43	cleanly power down hardware and software subsystems, then reactivate
     44	them without loss of data.
     45
     46	Some drivers can manage hardware wakeup events, which make the system
     47	leave the low-power state.  This feature may be enabled or disabled
     48	using the relevant :file:`/sys/devices/.../power/wakeup` file (for
     49	Ethernet drivers the ioctl interface used by ethtool may also be used
     50	for this purpose); enabling it may cost some power usage, but let the
     51	whole system enter low-power states more often.
     52
     53    Runtime Power Management model:
     54
     55	Devices may also be put into low-power states while the system is
     56	running, independently of other power management activity in principle.
     57	However, devices are not generally independent of each other (for
     58	example, a parent device cannot be suspended unless all of its child
     59	devices have been suspended).  Moreover, depending on the bus type the
     60	device is on, it may be necessary to carry out some bus-specific
     61	operations on the device for this purpose.  Devices put into low power
     62	states at run time may require special handling during system-wide power
     63	transitions (suspend or hibernation).
     64
     65	For these reasons not only the device driver itself, but also the
     66	appropriate subsystem (bus type, device type or device class) driver and
     67	the PM core are involved in runtime power management.  As in the system
     68	sleep power management case, they need to collaborate by implementing
     69	various role-specific suspend and resume methods, so that the hardware
     70	is cleanly powered down and reactivated without data or service loss.
     71
     72There's not a lot to be said about those low-power states except that they are
     73very system-specific, and often device-specific.  Also, that if enough devices
     74have been put into low-power states (at runtime), the effect may be very similar
     75to entering some system-wide low-power state (system sleep) ... and that
     76synergies exist, so that several drivers using runtime PM might put the system
     77into a state where even deeper power saving options are available.
     78
     79Most suspended devices will have quiesced all I/O: no more DMA or IRQs (except
     80for wakeup events), no more data read or written, and requests from upstream
     81drivers are no longer accepted.  A given bus or platform may have different
     82requirements though.
     83
     84Examples of hardware wakeup events include an alarm from a real time clock,
     85network wake-on-LAN packets, keyboard or mouse activity, and media insertion
     86or removal (for PCMCIA, MMC/SD, USB, and so on).
     87
     88Interfaces for Entering System Sleep States
     89===========================================
     90
     91There are programming interfaces provided for subsystems (bus type, device type,
     92device class) and device drivers to allow them to participate in the power
     93management of devices they are concerned with.  These interfaces cover both
     94system sleep and runtime power management.
     95
     96
     97Device Power Management Operations
     98----------------------------------
     99
    100Device power management operations, at the subsystem level as well as at the
    101device driver level, are implemented by defining and populating objects of type
    102struct dev_pm_ops defined in :file:`include/linux/pm.h`.  The roles of the
    103methods included in it will be explained in what follows.  For now, it should be
    104sufficient to remember that the last three methods are specific to runtime power
    105management while the remaining ones are used during system-wide power
    106transitions.
    107
    108There also is a deprecated "old" or "legacy" interface for power management
    109operations available at least for some subsystems.  This approach does not use
    110struct dev_pm_ops objects and it is suitable only for implementing system
    111sleep power management methods in a limited way.  Therefore it is not described
    112in this document, so please refer directly to the source code for more
    113information about it.
    114
    115
    116Subsystem-Level Methods
    117-----------------------
    118
    119The core methods to suspend and resume devices reside in
    120struct dev_pm_ops pointed to by the :c:member:`ops` member of
    121struct dev_pm_domain, or by the :c:member:`pm` member of struct bus_type,
    122struct device_type and struct class.  They are mostly of interest to the
    123people writing infrastructure for platforms and buses, like PCI or USB, or
    124device type and device class drivers.  They also are relevant to the writers of
    125device drivers whose subsystems (PM domains, device types, device classes and
    126bus types) don't provide all power management methods.
    127
    128Bus drivers implement these methods as appropriate for the hardware and the
    129drivers using it; PCI works differently from USB, and so on.  Not many people
    130write subsystem-level drivers; most driver code is a "device driver" that builds
    131on top of bus-specific framework code.
    132
    133For more information on these driver calls, see the description later;
    134they are called in phases for every device, respecting the parent-child
    135sequencing in the driver model tree.
    136
    137
    138:file:`/sys/devices/.../power/wakeup` files
    139-------------------------------------------
    140
    141All device objects in the driver model contain fields that control the handling
    142of system wakeup events (hardware signals that can force the system out of a
    143sleep state).  These fields are initialized by bus or device driver code using
    144:c:func:`device_set_wakeup_capable()` and :c:func:`device_set_wakeup_enable()`,
    145defined in :file:`include/linux/pm_wakeup.h`.
    146
    147The :c:member:`power.can_wakeup` flag just records whether the device (and its
    148driver) can physically support wakeup events.  The
    149:c:func:`device_set_wakeup_capable()` routine affects this flag.  The
    150:c:member:`power.wakeup` field is a pointer to an object of type
    151struct wakeup_source used for controlling whether or not the device should use
    152its system wakeup mechanism and for notifying the PM core of system wakeup
    153events signaled by the device.  This object is only present for wakeup-capable
    154devices (i.e. devices whose :c:member:`can_wakeup` flags are set) and is created
    155(or removed) by :c:func:`device_set_wakeup_capable()`.
    156
    157Whether or not a device is capable of issuing wakeup events is a hardware
    158matter, and the kernel is responsible for keeping track of it.  By contrast,
    159whether or not a wakeup-capable device should issue wakeup events is a policy
    160decision, and it is managed by user space through a sysfs attribute: the
    161:file:`power/wakeup` file.  User space can write the "enabled" or "disabled"
    162strings to it to indicate whether or not, respectively, the device is supposed
    163to signal system wakeup.  This file is only present if the
    164:c:member:`power.wakeup` object exists for the given device and is created (or
    165removed) along with that object, by :c:func:`device_set_wakeup_capable()`.
    166Reads from the file will return the corresponding string.
    167
    168The initial value in the :file:`power/wakeup` file is "disabled" for the
    169majority of devices; the major exceptions are power buttons, keyboards, and
    170Ethernet adapters whose WoL (wake-on-LAN) feature has been set up with ethtool.
    171It should also default to "enabled" for devices that don't generate wakeup
    172requests on their own but merely forward wakeup requests from one bus to another
    173(like PCI Express ports).
    174
    175The :c:func:`device_may_wakeup()` routine returns true only if the
    176:c:member:`power.wakeup` object exists and the corresponding :file:`power/wakeup`
    177file contains the "enabled" string.  This information is used by subsystems,
    178like the PCI bus type code, to see whether or not to enable the devices' wakeup
    179mechanisms.  If device wakeup mechanisms are enabled or disabled directly by
    180drivers, they also should use :c:func:`device_may_wakeup()` to decide what to do
    181during a system sleep transition.  Device drivers, however, are not expected to
    182call :c:func:`device_set_wakeup_enable()` directly in any case.
    183
    184It ought to be noted that system wakeup is conceptually different from "remote
    185wakeup" used by runtime power management, although it may be supported by the
    186same physical mechanism.  Remote wakeup is a feature allowing devices in
    187low-power states to trigger specific interrupts to signal conditions in which
    188they should be put into the full-power state.  Those interrupts may or may not
    189be used to signal system wakeup events, depending on the hardware design.  On
    190some systems it is impossible to trigger them from system sleep states.  In any
    191case, remote wakeup should always be enabled for runtime power management for
    192all devices and drivers that support it.
    193
    194
    195:file:`/sys/devices/.../power/control` files
    196--------------------------------------------
    197
    198Each device in the driver model has a flag to control whether it is subject to
    199runtime power management.  This flag, :c:member:`runtime_auto`, is initialized
    200by the bus type (or generally subsystem) code using :c:func:`pm_runtime_allow()`
    201or :c:func:`pm_runtime_forbid()`; the default is to allow runtime power
    202management.
    203
    204The setting can be adjusted by user space by writing either "on" or "auto" to
    205the device's :file:`power/control` sysfs file.  Writing "auto" calls
    206:c:func:`pm_runtime_allow()`, setting the flag and allowing the device to be
    207runtime power-managed by its driver.  Writing "on" calls
    208:c:func:`pm_runtime_forbid()`, clearing the flag, returning the device to full
    209power if it was in a low-power state, and preventing the
    210device from being runtime power-managed.  User space can check the current value
    211of the :c:member:`runtime_auto` flag by reading that file.
    212
    213The device's :c:member:`runtime_auto` flag has no effect on the handling of
    214system-wide power transitions.  In particular, the device can (and in the
    215majority of cases should and will) be put into a low-power state during a
    216system-wide transition to a sleep state even though its :c:member:`runtime_auto`
    217flag is clear.
    218
    219For more information about the runtime power management framework, refer to
    220Documentation/power/runtime_pm.rst.
    221
    222
    223Calling Drivers to Enter and Leave System Sleep States
    224======================================================
    225
    226When the system goes into a sleep state, each device's driver is asked to
    227suspend the device by putting it into a state compatible with the target
    228system state.  That's usually some version of "off", but the details are
    229system-specific.  Also, wakeup-enabled devices will usually stay partly
    230functional in order to wake the system.
    231
    232When the system leaves that low-power state, the device's driver is asked to
    233resume it by returning it to full power.  The suspend and resume operations
    234always go together, and both are multi-phase operations.
    235
    236For simple drivers, suspend might quiesce the device using class code
    237and then turn its hardware as "off" as possible during suspend_noirq.  The
    238matching resume calls would then completely reinitialize the hardware
    239before reactivating its class I/O queues.
    240
    241More power-aware drivers might prepare the devices for triggering system wakeup
    242events.
    243
    244
    245Call Sequence Guarantees
    246------------------------
    247
    248To ensure that bridges and similar links needing to talk to a device are
    249available when the device is suspended or resumed, the device hierarchy is
    250walked in a bottom-up order to suspend devices.  A top-down order is
    251used to resume those devices.
    252
    253The ordering of the device hierarchy is defined by the order in which devices
    254get registered:  a child can never be registered, probed or resumed before
    255its parent; and can't be removed or suspended after that parent.
    256
    257The policy is that the device hierarchy should match hardware bus topology.
    258[Or at least the control bus, for devices which use multiple busses.]
    259In particular, this means that a device registration may fail if the parent of
    260the device is suspending (i.e. has been chosen by the PM core as the next
    261device to suspend) or has already suspended, as well as after all of the other
    262devices have been suspended.  Device drivers must be prepared to cope with such
    263situations.
    264
    265
    266System Power Management Phases
    267------------------------------
    268
    269Suspending or resuming the system is done in several phases.  Different phases
    270are used for suspend-to-idle, shallow (standby), and deep ("suspend-to-RAM")
    271sleep states and the hibernation state ("suspend-to-disk").  Each phase involves
    272executing callbacks for every device before the next phase begins.  Not all
    273buses or classes support all these callbacks and not all drivers use all the
    274callbacks.  The various phases always run after tasks have been frozen and
    275before they are unfrozen.  Furthermore, the ``*_noirq`` phases run at a time
    276when IRQ handlers have been disabled (except for those marked with the
    277IRQF_NO_SUSPEND flag).
    278
    279All phases use PM domain, bus, type, class or driver callbacks (that is, methods
    280defined in ``dev->pm_domain->ops``, ``dev->bus->pm``, ``dev->type->pm``,
    281``dev->class->pm`` or ``dev->driver->pm``).  These callbacks are regarded by the
    282PM core as mutually exclusive.  Moreover, PM domain callbacks always take
    283precedence over all of the other callbacks and, for example, type callbacks take
    284precedence over bus, class and driver callbacks.  To be precise, the following
    285rules are used to determine which callback to execute in the given phase:
    286
    287    1.	If ``dev->pm_domain`` is present, the PM core will choose the callback
    288	provided by ``dev->pm_domain->ops`` for execution.
    289
    290    2.	Otherwise, if both ``dev->type`` and ``dev->type->pm`` are present, the
    291	callback provided by ``dev->type->pm`` will be chosen for execution.
    292
    293    3.	Otherwise, if both ``dev->class`` and ``dev->class->pm`` are present,
    294	the callback provided by ``dev->class->pm`` will be chosen for
    295	execution.
    296
    297    4.	Otherwise, if both ``dev->bus`` and ``dev->bus->pm`` are present, the
    298	callback provided by ``dev->bus->pm`` will be chosen for execution.
    299
    300This allows PM domains and device types to override callbacks provided by bus
    301types or device classes if necessary.
    302
    303The PM domain, type, class and bus callbacks may in turn invoke device- or
    304driver-specific methods stored in ``dev->driver->pm``, but they don't have to do
    305that.
    306
    307If the subsystem callback chosen for execution is not present, the PM core will
    308execute the corresponding method from the ``dev->driver->pm`` set instead if
    309there is one.
    310
    311
    312Entering System Suspend
    313-----------------------
    314
    315When the system goes into the freeze, standby or memory sleep state,
    316the phases are: ``prepare``, ``suspend``, ``suspend_late``, ``suspend_noirq``.
    317
    318    1.	The ``prepare`` phase is meant to prevent races by preventing new
    319	devices from being registered; the PM core would never know that all the
    320	children of a device had been suspended if new children could be
    321	registered at will.  [By contrast, from the PM core's perspective,
    322	devices may be unregistered at any time.]  Unlike the other
    323	suspend-related phases, during the ``prepare`` phase the device
    324	hierarchy is traversed top-down.
    325
    326	After the ``->prepare`` callback method returns, no new children may be
    327	registered below the device.  The method may also prepare the device or
    328	driver in some way for the upcoming system power transition, but it
    329	should not put the device into a low-power state.  Moreover, if the
    330	device supports runtime power management, the ``->prepare`` callback
    331	method must not update its state in case it is necessary to resume it
    332	from runtime suspend later on.
    333
    334	For devices supporting runtime power management, the return value of the
    335	prepare callback can be used to indicate to the PM core that it may
    336	safely leave the device in runtime suspend (if runtime-suspended
    337	already), provided that all of the device's descendants are also left in
    338	runtime suspend.  Namely, if the prepare callback returns a positive
    339	number and that happens for all of the descendants of the device too,
    340	and all of them (including the device itself) are runtime-suspended, the
    341	PM core will skip the ``suspend``, ``suspend_late`` and
    342	``suspend_noirq`` phases as well as all of the corresponding phases of
    343	the subsequent device resume for all of these devices.	In that case,
    344	the ``->complete`` callback will be the next one invoked after the
    345	``->prepare`` callback and is entirely responsible for putting the
    346	device into a consistent state as appropriate.
    347
    348	Note that this direct-complete procedure applies even if the device is
    349	disabled for runtime PM; only the runtime-PM status matters.  It follows
    350	that if a device has system-sleep callbacks but does not support runtime
    351	PM, then its prepare callback must never return a positive value.  This
    352	is because all such devices are initially set to runtime-suspended with
    353	runtime PM disabled.
    354
    355	This feature also can be controlled by device drivers by using the
    356	``DPM_FLAG_NO_DIRECT_COMPLETE`` and ``DPM_FLAG_SMART_PREPARE`` driver
    357	power management flags.  [Typically, they are set at the time the driver
    358	is probed against the device in question by passing them to the
    359	:c:func:`dev_pm_set_driver_flags` helper function.]  If the first of
    360	these flags is set, the PM core will not apply the direct-complete
    361	procedure described above to the given device and, consequenty, to any
    362	of its ancestors.  The second flag, when set, informs the middle layer
    363	code (bus types, device types, PM domains, classes) that it should take
    364	the return value of the ``->prepare`` callback provided by the driver
    365	into account and it may only return a positive value from its own
    366	``->prepare`` callback if the driver's one also has returned a positive
    367	value.
    368
    369    2.	The ``->suspend`` methods should quiesce the device to stop it from
    370	performing I/O.  They also may save the device registers and put it into
    371	the appropriate low-power state, depending on the bus type the device is
    372	on, and they may enable wakeup events.
    373
    374	However, for devices supporting runtime power management, the
    375	``->suspend`` methods provided by subsystems (bus types and PM domains
    376	in particular) must follow an additional rule regarding what can be done
    377	to the devices before their drivers' ``->suspend`` methods are called.
    378	Namely, they may resume the devices from runtime suspend by
    379	calling :c:func:`pm_runtime_resume` for them, if that is necessary, but
    380	they must not update the state of the devices in any other way at that
    381	time (in case the drivers need to resume the devices from runtime
    382	suspend in their ``->suspend`` methods).  In fact, the PM core prevents
    383	subsystems or drivers from putting devices into runtime suspend at
    384	these times by calling :c:func:`pm_runtime_get_noresume` before issuing
    385	the ``->prepare`` callback (and calling :c:func:`pm_runtime_put` after
    386	issuing the ``->complete`` callback).
    387
    388    3.	For a number of devices it is convenient to split suspend into the
    389	"quiesce device" and "save device state" phases, in which cases
    390	``suspend_late`` is meant to do the latter.  It is always executed after
    391	runtime power management has been disabled for the device in question.
    392
    393    4.	The ``suspend_noirq`` phase occurs after IRQ handlers have been disabled,
    394	which means that the driver's interrupt handler will not be called while
    395	the callback method is running.  The ``->suspend_noirq`` methods should
    396	save the values of the device's registers that weren't saved previously
    397	and finally put the device into the appropriate low-power state.
    398
    399	The majority of subsystems and device drivers need not implement this
    400	callback.  However, bus types allowing devices to share interrupt
    401	vectors, like PCI, generally need it; otherwise a driver might encounter
    402	an error during the suspend phase by fielding a shared interrupt
    403	generated by some other device after its own device had been set to low
    404	power.
    405
    406At the end of these phases, drivers should have stopped all I/O transactions
    407(DMA, IRQs), saved enough state that they can re-initialize or restore previous
    408state (as needed by the hardware), and placed the device into a low-power state.
    409On many platforms they will gate off one or more clock sources; sometimes they
    410will also switch off power supplies or reduce voltages.  [Drivers supporting
    411runtime PM may already have performed some or all of these steps.]
    412
    413If :c:func:`device_may_wakeup()` returns ``true``, the device should be
    414prepared for generating hardware wakeup signals to trigger a system wakeup event
    415when the system is in the sleep state.  For example, :c:func:`enable_irq_wake()`
    416might identify GPIO signals hooked up to a switch or other external hardware,
    417and :c:func:`pci_enable_wake()` does something similar for the PCI PME signal.
    418
    419If any of these callbacks returns an error, the system won't enter the desired
    420low-power state.  Instead, the PM core will unwind its actions by resuming all
    421the devices that were suspended.
    422
    423
    424Leaving System Suspend
    425----------------------
    426
    427When resuming from freeze, standby or memory sleep, the phases are:
    428``resume_noirq``, ``resume_early``, ``resume``, ``complete``.
    429
    430    1.	The ``->resume_noirq`` callback methods should perform any actions
    431	needed before the driver's interrupt handlers are invoked.  This
    432	generally means undoing the actions of the ``suspend_noirq`` phase.  If
    433	the bus type permits devices to share interrupt vectors, like PCI, the
    434	method should bring the device and its driver into a state in which the
    435	driver can recognize if the device is the source of incoming interrupts,
    436	if any, and handle them correctly.
    437
    438	For example, the PCI bus type's ``->pm.resume_noirq()`` puts the device
    439	into the full-power state (D0 in the PCI terminology) and restores the
    440	standard configuration registers of the device.  Then it calls the
    441	device driver's ``->pm.resume_noirq()`` method to perform device-specific
    442	actions.
    443
    444    2.	The ``->resume_early`` methods should prepare devices for the execution
    445	of the resume methods.  This generally involves undoing the actions of
    446	the preceding ``suspend_late`` phase.
    447
    448    3.	The ``->resume`` methods should bring the device back to its operating
    449	state, so that it can perform normal I/O.  This generally involves
    450	undoing the actions of the ``suspend`` phase.
    451
    452    4.	The ``complete`` phase should undo the actions of the ``prepare`` phase.
    453        For this reason, unlike the other resume-related phases, during the
    454        ``complete`` phase the device hierarchy is traversed bottom-up.
    455
    456	Note, however, that new children may be registered below the device as
    457	soon as the ``->resume`` callbacks occur; it's not necessary to wait
    458	until the ``complete`` phase runs.
    459
    460	Moreover, if the preceding ``->prepare`` callback returned a positive
    461	number, the device may have been left in runtime suspend throughout the
    462	whole system suspend and resume (its ``->suspend``, ``->suspend_late``,
    463	``->suspend_noirq``, ``->resume_noirq``,
    464	``->resume_early``, and ``->resume`` callbacks may have been
    465	skipped).  In that case, the ``->complete`` callback is entirely
    466	responsible for putting the device into a consistent state after system
    467	suspend if necessary.  [For example, it may need to queue up a runtime
    468	resume request for the device for this purpose.]  To check if that is
    469	the case, the ``->complete`` callback can consult the device's
    470	``power.direct_complete`` flag.  If that flag is set when the
    471	``->complete`` callback is being run then the direct-complete mechanism
    472	was used, and special actions may be required to make the device work
    473	correctly afterward.
    474
    475At the end of these phases, drivers should be as functional as they were before
    476suspending: I/O can be performed using DMA and IRQs, and the relevant clocks are
    477gated on.
    478
    479However, the details here may again be platform-specific.  For example,
    480some systems support multiple "run" states, and the mode in effect at
    481the end of resume might not be the one which preceded suspension.
    482That means availability of certain clocks or power supplies changed,
    483which could easily affect how a driver works.
    484
    485Drivers need to be able to handle hardware which has been reset since all of the
    486suspend methods were called, for example by complete reinitialization.
    487This may be the hardest part, and the one most protected by NDA'd documents
    488and chip errata.  It's simplest if the hardware state hasn't changed since
    489the suspend was carried out, but that can only be guaranteed if the target
    490system sleep entered was suspend-to-idle.  For the other system sleep states
    491that may not be the case (and usually isn't for ACPI-defined system sleep
    492states, like S3).
    493
    494Drivers must also be prepared to notice that the device has been removed
    495while the system was powered down, whenever that's physically possible.
    496PCMCIA, MMC, USB, Firewire, SCSI, and even IDE are common examples of busses
    497where common Linux platforms will see such removal.  Details of how drivers
    498will notice and handle such removals are currently bus-specific, and often
    499involve a separate thread.
    500
    501These callbacks may return an error value, but the PM core will ignore such
    502errors since there's nothing it can do about them other than printing them in
    503the system log.
    504
    505
    506Entering Hibernation
    507--------------------
    508
    509Hibernating the system is more complicated than putting it into sleep states,
    510because it involves creating and saving a system image.  Therefore there are
    511more phases for hibernation, with a different set of callbacks.  These phases
    512always run after tasks have been frozen and enough memory has been freed.
    513
    514The general procedure for hibernation is to quiesce all devices ("freeze"),
    515create an image of the system memory while everything is stable, reactivate all
    516devices ("thaw"), write the image to permanent storage, and finally shut down
    517the system ("power off").  The phases used to accomplish this are: ``prepare``,
    518``freeze``, ``freeze_late``, ``freeze_noirq``, ``thaw_noirq``, ``thaw_early``,
    519``thaw``, ``complete``, ``prepare``, ``poweroff``, ``poweroff_late``,
    520``poweroff_noirq``.
    521
    522    1.	The ``prepare`` phase is discussed in the "Entering System Suspend"
    523	section above.
    524
    525    2.	The ``->freeze`` methods should quiesce the device so that it doesn't
    526	generate IRQs or DMA, and they may need to save the values of device
    527	registers.  However the device does not have to be put in a low-power
    528	state, and to save time it's best not to do so.  Also, the device should
    529	not be prepared to generate wakeup events.
    530
    531    3.	The ``freeze_late`` phase is analogous to the ``suspend_late`` phase
    532	described earlier, except that the device should not be put into a
    533	low-power state and should not be allowed to generate wakeup events.
    534
    535    4.	The ``freeze_noirq`` phase is analogous to the ``suspend_noirq`` phase
    536	discussed earlier, except again that the device should not be put into
    537	a low-power state and should not be allowed to generate wakeup events.
    538
    539At this point the system image is created.  All devices should be inactive and
    540the contents of memory should remain undisturbed while this happens, so that the
    541image forms an atomic snapshot of the system state.
    542
    543    5.	The ``thaw_noirq`` phase is analogous to the ``resume_noirq`` phase
    544	discussed earlier.  The main difference is that its methods can assume
    545	the device is in the same state as at the end of the ``freeze_noirq``
    546	phase.
    547
    548    6.	The ``thaw_early`` phase is analogous to the ``resume_early`` phase
    549	described above.  Its methods should undo the actions of the preceding
    550	``freeze_late``, if necessary.
    551
    552    7.	The ``thaw`` phase is analogous to the ``resume`` phase discussed
    553	earlier.  Its methods should bring the device back to an operating
    554	state, so that it can be used for saving the image if necessary.
    555
    556    8.	The ``complete`` phase is discussed in the "Leaving System Suspend"
    557	section above.
    558
    559At this point the system image is saved, and the devices then need to be
    560prepared for the upcoming system shutdown.  This is much like suspending them
    561before putting the system into the suspend-to-idle, shallow or deep sleep state,
    562and the phases are similar.
    563
    564    9.	The ``prepare`` phase is discussed above.
    565
    566    10.	The ``poweroff`` phase is analogous to the ``suspend`` phase.
    567
    568    11.	The ``poweroff_late`` phase is analogous to the ``suspend_late`` phase.
    569
    570    12.	The ``poweroff_noirq`` phase is analogous to the ``suspend_noirq`` phase.
    571
    572The ``->poweroff``, ``->poweroff_late`` and ``->poweroff_noirq`` callbacks
    573should do essentially the same things as the ``->suspend``, ``->suspend_late``
    574and ``->suspend_noirq`` callbacks, respectively.  A notable difference is
    575that they need not store the device register values, because the registers
    576should already have been stored during the ``freeze``, ``freeze_late`` or
    577``freeze_noirq`` phases.  Also, on many machines the firmware will power-down
    578the entire system, so it is not necessary for the callback to put the device in
    579a low-power state.
    580
    581
    582Leaving Hibernation
    583-------------------
    584
    585Resuming from hibernation is, again, more complicated than resuming from a sleep
    586state in which the contents of main memory are preserved, because it requires
    587a system image to be loaded into memory and the pre-hibernation memory contents
    588to be restored before control can be passed back to the image kernel.
    589
    590Although in principle the image might be loaded into memory and the
    591pre-hibernation memory contents restored by the boot loader, in practice this
    592can't be done because boot loaders aren't smart enough and there is no
    593established protocol for passing the necessary information.  So instead, the
    594boot loader loads a fresh instance of the kernel, called "the restore kernel",
    595into memory and passes control to it in the usual way.  Then the restore kernel
    596reads the system image, restores the pre-hibernation memory contents, and passes
    597control to the image kernel.  Thus two different kernel instances are involved
    598in resuming from hibernation.  In fact, the restore kernel may be completely
    599different from the image kernel: a different configuration and even a different
    600version.  This has important consequences for device drivers and their
    601subsystems.
    602
    603To be able to load the system image into memory, the restore kernel needs to
    604include at least a subset of device drivers allowing it to access the storage
    605medium containing the image, although it doesn't need to include all of the
    606drivers present in the image kernel.  After the image has been loaded, the
    607devices managed by the boot kernel need to be prepared for passing control back
    608to the image kernel.  This is very similar to the initial steps involved in
    609creating a system image, and it is accomplished in the same way, using
    610``prepare``, ``freeze``, and ``freeze_noirq`` phases.  However, the devices
    611affected by these phases are only those having drivers in the restore kernel;
    612other devices will still be in whatever state the boot loader left them.
    613
    614Should the restoration of the pre-hibernation memory contents fail, the restore
    615kernel would go through the "thawing" procedure described above, using the
    616``thaw_noirq``, ``thaw_early``, ``thaw``, and ``complete`` phases, and then
    617continue running normally.  This happens only rarely.  Most often the
    618pre-hibernation memory contents are restored successfully and control is passed
    619to the image kernel, which then becomes responsible for bringing the system back
    620to the working state.
    621
    622To achieve this, the image kernel must restore the devices' pre-hibernation
    623functionality.  The operation is much like waking up from a sleep state (with
    624the memory contents preserved), although it involves different phases:
    625``restore_noirq``, ``restore_early``, ``restore``, ``complete``.
    626
    627    1.	The ``restore_noirq`` phase is analogous to the ``resume_noirq`` phase.
    628
    629    2.	The ``restore_early`` phase is analogous to the ``resume_early`` phase.
    630
    631    3.	The ``restore`` phase is analogous to the ``resume`` phase.
    632
    633    4.	The ``complete`` phase is discussed above.
    634
    635The main difference from ``resume[_early|_noirq]`` is that
    636``restore[_early|_noirq]`` must assume the device has been accessed and
    637reconfigured by the boot loader or the restore kernel.  Consequently, the state
    638of the device may be different from the state remembered from the ``freeze``,
    639``freeze_late`` and ``freeze_noirq`` phases.  The device may even need to be
    640reset and completely re-initialized.  In many cases this difference doesn't
    641matter, so the ``->resume[_early|_noirq]`` and ``->restore[_early|_norq]``
    642method pointers can be set to the same routines.  Nevertheless, different
    643callback pointers are used in case there is a situation where it actually does
    644matter.
    645
    646
    647Power Management Notifiers
    648==========================
    649
    650There are some operations that cannot be carried out by the power management
    651callbacks discussed above, because the callbacks occur too late or too early.
    652To handle these cases, subsystems and device drivers may register power
    653management notifiers that are called before tasks are frozen and after they have
    654been thawed.  Generally speaking, the PM notifiers are suitable for performing
    655actions that either require user space to be available, or at least won't
    656interfere with user space.
    657
    658For details refer to Documentation/driver-api/pm/notifiers.rst.
    659
    660
    661Device Low-Power (suspend) States
    662=================================
    663
    664Device low-power states aren't standard.  One device might only handle
    665"on" and "off", while another might support a dozen different versions of
    666"on" (how many engines are active?), plus a state that gets back to "on"
    667faster than from a full "off".
    668
    669Some buses define rules about what different suspend states mean.  PCI
    670gives one example: after the suspend sequence completes, a non-legacy
    671PCI device may not perform DMA or issue IRQs, and any wakeup events it
    672issues would be issued through the PME# bus signal.  Plus, there are
    673several PCI-standard device states, some of which are optional.
    674
    675In contrast, integrated system-on-chip processors often use IRQs as the
    676wakeup event sources (so drivers would call :c:func:`enable_irq_wake`) and
    677might be able to treat DMA completion as a wakeup event (sometimes DMA can stay
    678active too, it'd only be the CPU and some peripherals that sleep).
    679
    680Some details here may be platform-specific.  Systems may have devices that
    681can be fully active in certain sleep states, such as an LCD display that's
    682refreshed using DMA while most of the system is sleeping lightly ... and
    683its frame buffer might even be updated by a DSP or other non-Linux CPU while
    684the Linux control processor stays idle.
    685
    686Moreover, the specific actions taken may depend on the target system state.
    687One target system state might allow a given device to be very operational;
    688another might require a hard shut down with re-initialization on resume.
    689And two different target systems might use the same device in different
    690ways; the aforementioned LCD might be active in one product's "standby",
    691but a different product using the same SOC might work differently.
    692
    693
    694Device Power Management Domains
    695===============================
    696
    697Sometimes devices share reference clocks or other power resources.  In those
    698cases it generally is not possible to put devices into low-power states
    699individually.  Instead, a set of devices sharing a power resource can be put
    700into a low-power state together at the same time by turning off the shared
    701power resource.  Of course, they also need to be put into the full-power state
    702together, by turning the shared power resource on.  A set of devices with this
    703property is often referred to as a power domain. A power domain may also be
    704nested inside another power domain. The nested domain is referred to as the
    705sub-domain of the parent domain.
    706
    707Support for power domains is provided through the :c:member:`pm_domain` field of
    708struct device.  This field is a pointer to an object of type
    709struct dev_pm_domain, defined in :file:`include/linux/pm.h`, providing a set
    710of power management callbacks analogous to the subsystem-level and device driver
    711callbacks that are executed for the given device during all power transitions,
    712instead of the respective subsystem-level callbacks.  Specifically, if a
    713device's :c:member:`pm_domain` pointer is not NULL, the ``->suspend()`` callback
    714from the object pointed to by it will be executed instead of its subsystem's
    715(e.g. bus type's) ``->suspend()`` callback and analogously for all of the
    716remaining callbacks.  In other words, power management domain callbacks, if
    717defined for the given device, always take precedence over the callbacks provided
    718by the device's subsystem (e.g. bus type).
    719
    720The support for device power management domains is only relevant to platforms
    721needing to use the same device driver power management callbacks in many
    722different power domain configurations and wanting to avoid incorporating the
    723support for power domains into subsystem-level callbacks, for example by
    724modifying the platform bus type.  Other platforms need not implement it or take
    725it into account in any way.
    726
    727Devices may be defined as IRQ-safe which indicates to the PM core that their
    728runtime PM callbacks may be invoked with disabled interrupts (see
    729Documentation/power/runtime_pm.rst for more information).  If an
    730IRQ-safe device belongs to a PM domain, the runtime PM of the domain will be
    731disallowed, unless the domain itself is defined as IRQ-safe. However, it
    732makes sense to define a PM domain as IRQ-safe only if all the devices in it
    733are IRQ-safe. Moreover, if an IRQ-safe domain has a parent domain, the runtime
    734PM of the parent is only allowed if the parent itself is IRQ-safe too with the
    735additional restriction that all child domains of an IRQ-safe parent must also
    736be IRQ-safe.
    737
    738
    739Runtime Power Management
    740========================
    741
    742Many devices are able to dynamically power down while the system is still
    743running. This feature is useful for devices that are not being used, and
    744can offer significant power savings on a running system.  These devices
    745often support a range of runtime power states, which might use names such
    746as "off", "sleep", "idle", "active", and so on.  Those states will in some
    747cases (like PCI) be partially constrained by the bus the device uses, and will
    748usually include hardware states that are also used in system sleep states.
    749
    750A system-wide power transition can be started while some devices are in low
    751power states due to runtime power management.  The system sleep PM callbacks
    752should recognize such situations and react to them appropriately, but the
    753necessary actions are subsystem-specific.
    754
    755In some cases the decision may be made at the subsystem level while in other
    756cases the device driver may be left to decide.  In some cases it may be
    757desirable to leave a suspended device in that state during a system-wide power
    758transition, but in other cases the device must be put back into the full-power
    759state temporarily, for example so that its system wakeup capability can be
    760disabled.  This all depends on the hardware and the design of the subsystem and
    761device driver in question.
    762
    763If it is necessary to resume a device from runtime suspend during a system-wide
    764transition into a sleep state, that can be done by calling
    765:c:func:`pm_runtime_resume` from the ``->suspend`` callback (or the ``->freeze``
    766or ``->poweroff`` callback for transitions related to hibernation) of either the
    767device's driver or its subsystem (for example, a bus type or a PM domain).
    768However, subsystems must not otherwise change the runtime status of devices
    769from their ``->prepare`` and ``->suspend`` callbacks (or equivalent) *before*
    770invoking device drivers' ``->suspend`` callbacks (or equivalent).
    771
    772.. _smart_suspend_flag:
    773
    774The ``DPM_FLAG_SMART_SUSPEND`` Driver Flag
    775------------------------------------------
    776
    777Some bus types and PM domains have a policy to resume all devices from runtime
    778suspend upfront in their ``->suspend`` callbacks, but that may not be really
    779necessary if the device's driver can cope with runtime-suspended devices.
    780The driver can indicate this by setting ``DPM_FLAG_SMART_SUSPEND`` in
    781:c:member:`power.driver_flags` at probe time, with the assistance of the
    782:c:func:`dev_pm_set_driver_flags` helper routine.
    783
    784Setting that flag causes the PM core and middle-layer code
    785(bus types, PM domains etc.) to skip the ``->suspend_late`` and
    786``->suspend_noirq`` callbacks provided by the driver if the device remains in
    787runtime suspend throughout those phases of the system-wide suspend (and
    788similarly for the "freeze" and "poweroff" parts of system hibernation).
    789[Otherwise the same driver
    790callback might be executed twice in a row for the same device, which would not
    791be valid in general.]  If the middle-layer system-wide PM callbacks are present
    792for the device then they are responsible for skipping these driver callbacks;
    793if not then the PM core skips them.  The subsystem callback routines can
    794determine whether they need to skip the driver callbacks by testing the return
    795value from the :c:func:`dev_pm_skip_suspend` helper function.
    796
    797In addition, with ``DPM_FLAG_SMART_SUSPEND`` set, the driver's ``->thaw_noirq``
    798and ``->thaw_early`` callbacks are skipped in hibernation if the device remained
    799in runtime suspend throughout the preceding "freeze" transition.  Again, if the
    800middle-layer callbacks are present for the device, they are responsible for
    801doing this, otherwise the PM core takes care of it.
    802
    803
    804The ``DPM_FLAG_MAY_SKIP_RESUME`` Driver Flag
    805--------------------------------------------
    806
    807During system-wide resume from a sleep state it's easiest to put devices into
    808the full-power state, as explained in Documentation/power/runtime_pm.rst.
    809[Refer to that document for more information regarding this particular issue as
    810well as for information on the device runtime power management framework in
    811general.]  However, it often is desirable to leave devices in suspend after
    812system transitions to the working state, especially if those devices had been in
    813runtime suspend before the preceding system-wide suspend (or analogous)
    814transition.
    815
    816To that end, device drivers can use the ``DPM_FLAG_MAY_SKIP_RESUME`` flag to
    817indicate to the PM core and middle-layer code that they allow their "noirq" and
    818"early" resume callbacks to be skipped if the device can be left in suspend
    819after system-wide PM transitions to the working state.  Whether or not that is
    820the case generally depends on the state of the device before the given system
    821suspend-resume cycle and on the type of the system transition under way.
    822In particular, the "thaw" and "restore" transitions related to hibernation are
    823not affected by ``DPM_FLAG_MAY_SKIP_RESUME`` at all.  [All callbacks are
    824issued during the "restore" transition regardless of the flag settings,
    825and whether or not any driver callbacks
    826are skipped during the "thaw" transition depends whether or not the
    827``DPM_FLAG_SMART_SUSPEND`` flag is set (see `above <smart_suspend_flag_>`_).
    828In addition, a device is not allowed to remain in runtime suspend if any of its
    829children will be returned to full power.]
    830
    831The ``DPM_FLAG_MAY_SKIP_RESUME`` flag is taken into account in combination with
    832the :c:member:`power.may_skip_resume` status bit set by the PM core during the
    833"suspend" phase of suspend-type transitions.  If the driver or the middle layer
    834has a reason to prevent the driver's "noirq" and "early" resume callbacks from
    835being skipped during the subsequent system resume transition, it should
    836clear :c:member:`power.may_skip_resume` in its ``->suspend``, ``->suspend_late``
    837or ``->suspend_noirq`` callback.  [Note that the drivers setting
    838``DPM_FLAG_SMART_SUSPEND`` need to clear :c:member:`power.may_skip_resume` in
    839their ``->suspend`` callback in case the other two are skipped.]
    840
    841Setting the :c:member:`power.may_skip_resume` status bit along with the
    842``DPM_FLAG_MAY_SKIP_RESUME`` flag is necessary, but generally not sufficient,
    843for the driver's "noirq" and "early" resume callbacks to be skipped.  Whether or
    844not they should be skipped can be determined by evaluating the
    845:c:func:`dev_pm_skip_resume` helper function.
    846
    847If that function returns ``true``, the driver's "noirq" and "early" resume
    848callbacks should be skipped and the device's runtime PM status will be set to
    849"suspended" by the PM core.  Otherwise, if the device was runtime-suspended
    850during the preceding system-wide suspend transition and its
    851``DPM_FLAG_SMART_SUSPEND`` is set, its runtime PM status will be set to
    852"active" by the PM core.  [Hence, the drivers that do not set
    853``DPM_FLAG_SMART_SUSPEND`` should not expect the runtime PM status of their
    854devices to be changed from "suspended" to "active" by the PM core during
    855system-wide resume-type transitions.]
    856
    857If the ``DPM_FLAG_MAY_SKIP_RESUME`` flag is not set for a device, but
    858``DPM_FLAG_SMART_SUSPEND`` is set and the driver's "late" and "noirq" suspend
    859callbacks are skipped, its system-wide "noirq" and "early" resume callbacks, if
    860present, are invoked as usual and the device's runtime PM status is set to
    861"active" by the PM core before enabling runtime PM for it.  In that case, the
    862driver must be prepared to cope with the invocation of its system-wide resume
    863callbacks back-to-back with its ``->runtime_suspend`` one (without the
    864intervening ``->runtime_resume`` and system-wide suspend callbacks) and the
    865final state of the device must reflect the "active" runtime PM status in that
    866case.  [Note that this is not a problem at all if the driver's
    867``->suspend_late`` callback pointer points to the same function as its
    868``->runtime_suspend`` one and its ``->resume_early`` callback pointer points to
    869the same function as the ``->runtime_resume`` one, while none of the other
    870system-wide suspend-resume callbacks of the driver are present, for example.]
    871
    872Likewise, if ``DPM_FLAG_MAY_SKIP_RESUME`` is set for a device, its driver's
    873system-wide "noirq" and "early" resume callbacks may be skipped while its "late"
    874and "noirq" suspend callbacks may have been executed (in principle, regardless
    875of whether or not ``DPM_FLAG_SMART_SUSPEND`` is set).  In that case, the driver
    876needs to be able to cope with the invocation of its ``->runtime_resume``
    877callback back-to-back with its "late" and "noirq" suspend ones.  [For instance,
    878that is not a concern if the driver sets both ``DPM_FLAG_SMART_SUSPEND`` and
    879``DPM_FLAG_MAY_SKIP_RESUME`` and uses the same pair of suspend/resume callback
    880functions for runtime PM and system-wide suspend/resume.]