PCI Power Management¶
Copyright (c) 2010 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc.
An overview of concepts and the Linux kernel’s interfaces related to PCI power management. Based on previous work by Patrick Mochel <mochel@transmeta.com> (and others).
This document only covers the aspects of power management specific to PCI devices. For general description of the kernel’s interfaces related to device power management refer to Documentation/driver-api/pm/devices.rst and Documentation/power/runtime_pm.rst.
1. Hardware and Platform Support for PCI Power Management¶
1.1. Native and Platform-Based Power Management¶
In general, power management is a feature allowing one to save energy by putting devices into states in which they draw less power (low-power states) at the price of reduced functionality or performance.
Usually, a device is put into a low-power state when it is underutilized or completely inactive. However, when it is necessary to use the device once again, it has to be put back into the “fully functional” state (full-power state). This may happen when there are some data for the device to handle or as a result of an external event requiring the device to be active, which may be signaled by the device itself.
PCI devices may be put into low-power states in two ways, by using the device capabilities introduced by the PCI Bus Power Management Interface Specification, or with the help of platform firmware, such as an ACPI BIOS. In the first approach, that is referred to as the native PCI power management (native PCI PM) in what follows, the device power state is changed as a result of writing a specific value into one of its standard configuration registers. The second approach requires the platform firmware to provide special methods that may be used by the kernel to change the device’s power state.
Devices supporting the native PCI PM usually can generate wakeup signals called Power Management Events (PMEs) to let the kernel know about external events requiring the device to be active. After receiving a PME the kernel is supposed to put the device that sent it into the full-power state. However, the PCI Bus Power Management Interface Specification doesn’t define any standard method of delivering the PME from the device to the CPU and the operating system kernel. It is assumed that the platform firmware will perform this task and therefore, even though a PCI device is set up to generate PMEs, it also may be necessary to prepare the platform firmware for notifying the CPU of the PMEs coming from the device (e.g. by generating interrupts).
In turn, if the methods provided by the platform firmware are used for changing the power state of a device, usually the platform also provides a method for preparing the device to generate wakeup signals. In that case, however, it often also is necessary to prepare the device for generating PMEs using the native PCI PM mechanism, because the method provided by the platform depends on that.
Thus in many situations both the native and the platform-based power management mechanisms have to be used simultaneously to obtain the desired result.
1.2. Native PCI Power Management¶
The PCI Bus Power Management Interface Specification (PCI PM Spec) was introduced between the PCI 2.1 and PCI 2.2 Specifications. It defined a standard interface for performing various operations related to power management.
The implementation of the PCI PM Spec is optional for conventional PCI devices, but it is mandatory for PCI Express devices. If a device supports the PCI PM Spec, it has an 8 byte power management capability field in its PCI configuration space. This field is used to describe and control the standard features related to the native PCI power management.
The PCI PM Spec defines 4 operating states for devices (D0-D3) and for buses (B0-B3). The higher the number, the less power is drawn by the device or bus in that state. However, the higher the number, the longer the latency for the device or bus to return to the full-power state (D0 or B0, respectively).
There are two variants of the D3 state defined by the specification. The first one is D3hot, referred to as the software accessible D3, because devices can be programmed to go into it. The second one, D3cold, is the state that PCI devices are in when the supply voltage (Vcc) is removed from them. It is not possible to program a PCI device to go into D3cold, although there may be a programmable interface for putting the bus the device is on into a state in which Vcc is removed from all devices on the bus.
PCI bus power management, however, is not supported by the Linux kernel at the time of this writing and therefore it is not covered by this document.
Note that every PCI device can be in the full-power state (D0) or in D3cold, regardless of whether or not it implements the PCI PM Spec. In addition to that, if the PCI PM Spec is implemented by the device, it must support D3hot as well as D0. The support for the D1 and D2 power states is optional.
PCI devices supporting the PCI PM Spec can be programmed to go to any of the supported low-power states (except for D3cold). While in D1-D3hot the standard configuration registers of the device must be accessible to software (i.e. the device is required to respond to PCI configuration accesses), although its I/O and memory spaces are then disabled. This allows the device to be programmatically put into D0. Thus the kernel can switch the device back and forth between D0 and the supported low-power states (except for D3cold) and the possible power state transitions the device can undergo are the following:
Current State | New State |
D0 | D1, D2, D3 |
D1 | D2, D3 |
D2 | D3 |
D1, D2, D3 | D0 |
The transition from D3cold to D0 occurs when the supply voltage is provided to the device (i.e. power is restored). In that case the device returns to D0 with a full power-on reset sequence and the power-on defaults are restored to the device by hardware just as at initial power up.
PCI devices supporting the PCI PM Spec can be programmed to generate PMEs while in any power state (D0-D3), but they are not required to be capable of generating PMEs from all supported power states. In particular, the capability of generating PMEs from D3cold is optional and depends on the presence of additional voltage (3.3Vaux) allowing the device to remain sufficiently active to generate a wakeup signal.
1.3. ACPI Device Power Management¶
The platform firmware support for the power management of PCI devices is system-specific. However, if the system in question is compliant with the Advanced Configuration and Power Interface (ACPI) Specification, like the majority of x86-based systems, it is supposed to implement device power management interfaces defined by the ACPI standard.
For this purpose the ACPI BIOS provides special functions called “control methods” that may be executed by the kernel to perform specific tasks, such as putting a device into a low-power state. These control methods are encoded using special byte-code language called the ACPI Machine Language (AML) and stored in the machine’s BIOS. The kernel loads them from the BIOS and executes them as needed using an AML interpreter that translates the AML byte code into computations and memory or I/O space accesses. This way, in theory, a BIOS writer can provide the kernel with a means to perform actions depending on the system design in a system-specific fashion.
ACPI control methods may be divided into global control methods, that are not associated with any particular devices, and device control methods, that have to be defined separately for each device supposed to be handled with the help of the platform. This means, in particular, that ACPI device control methods can only be used to handle devices that the BIOS writer knew about in advance. The ACPI methods used for device power management fall into that category.
The ACPI specification assumes that devices can be in one of four power states labeled as D0, D1, D2, and D3 that roughly correspond to the native PCI PM D0-D3 states (although the difference between D3hot and D3cold is not taken into account by ACPI). Moreover, for each power state of a device there is a set of power resources that have to be enabled for the device to be put into that state. These power resources are controlled (i.e. enabled or disabled) with the help of their own control methods, _ON and _OFF, that have to be defined individually for each of them.
To put a device into the ACPI power state Dx (where x is a number between 0 and 3 inclusive) the kernel is supposed to (1) enable the power resources required by the device in this state using their _ON control methods and (2) execute the _PSx control method defined for the device. In addition to that, if the device is going to be put into a low-power state (D1-D3) and is supposed to generate wakeup signals from that state, the _DSW (or _PSW, replaced with _DSW by ACPI 3.0) control method defined for it has to be executed before _PSx. Power resources that are not required by the device in the target power state and are not required any more by any other device should be disabled (by executing their _OFF control methods). If the current power state of the device is D3, it can only be put into D0 this way.
However, quite often the power states of devices are changed during a system-wide transition into a sleep state or back into the working state. ACPI defines four system sleep states, S1, S2, S3, and S4, and denotes the system working state as S0. In general, the target system sleep (or working) state determines the highest power (lowest number) state the device can be put into and the kernel is supposed to obtain this information by executing the device’s _SxD control method (where x is a number between 0 and 4 inclusive). If the device is required to wake up the system from the target sleep state, the lowest power (highest number) state it can be put into is also determined by the target state of the system. The kernel is then supposed to use the device’s _SxW control method to obtain the number of that state. It also is supposed to use the device’s _PRW control method to learn which power resources need to be enabled for the device to be able to generate wakeup signals.
1.4. Wakeup Signaling¶
Wakeup signals generated by PCI devices, either as native PCI PMEs, or as a result of the execution of the _DSW (or _PSW) ACPI control method before putting the device into a low-power state, have to be caught and handled as appropriate. If they are sent while the system is in the working state (ACPI S0), they should be translated into interrupts so that the kernel can put the devices generating them into the full-power state and take care of the events that triggered them. In turn, if they are sent while the system is sleeping, they should cause the system’s core logic to trigger wakeup.
On ACPI-based systems wakeup signals sent by conventional PCI devices are converted into ACPI General-Purpose Events (GPEs) which are hardware signals from the system core logic generated in response to various events that need to be acted upon. Every GPE is associated with one or more sources of potentially interesting events. In particular, a GPE may be associated with a PCI device capable of signaling wakeup. The information on the connections between GPEs and event sources is recorded in the system’s ACPI BIOS from where it can be read by the kernel.
If a PCI device known to the system’s ACPI BIOS signals wakeup, the GPE associated with it (if there is one) is triggered. The GPEs associated with PCI bridges may also be triggered in response to a wakeup signal from one of the devices below the bridge (this also is the case for root bridges) and, for example, native PCI PMEs from devices unknown to the system’s ACPI BIOS may be handled this way.
A GPE may be triggered when the system is sleeping (i.e. when it is in one of the ACPI S1-S4 states), in which case system wakeup is started by its core logic (the device that was the source of the signal causing the system wakeup to occur may be identified later). The GPEs used in such situations are referred to as wakeup GPEs.
Usually, however, GPEs are also triggered when the system is in the working state (ACPI S0) and in that case the system’s core logic generates a System Control Interrupt (SCI) to notify the kernel of the event. Then, the SCI handler identifies the GPE that caused the interrupt to be generated which, in turn, allows the kernel to identify the source of the event (that may be a PCI device signaling wakeup). The GPEs used for notifying the kernel of events occurring while the system is in the working state are referred to as runtime GPEs.
Unfortunately, there is no standard way of handling wakeup signals sent by conventional PCI devices on systems that are not ACPI-based, but there is one for PCI Express devices. Namely, the PCI Express Base Specification introduced a native mechanism for converting native PCI PMEs into interrupts generated by root ports. For conventional PCI devices native PMEs are out-of-band, so they are routed separately and they need not pass through bridges (in principle they may be routed directly to the system’s core logic), but for PCI Express devices they are in-band messages that have to pass through the PCI Express hierarchy, including the root port on the path from the device to the Root Complex. Thus it was possible to introduce a mechanism by which a root port generates an interrupt whenever it receives a PME message from one of the devices below it. The PCI Express Requester ID of the device that sent the PME message is then recorded in one of the root port’s configuration registers from where it may be read by the interrupt handler allowing the device to be identified. [PME messages sent by PCI Express endpoints integrated with the Root Complex don’t pass through root ports, but instead they cause a Root Complex Event Collector (if there is one) to generate interrupts.]
In principle the native PCI Express PME signaling may also be used on ACPI-based systems along with the GPEs, but to use it the kernel has to ask the system’s ACPI BIOS to release control of root port configuration registers. The ACPI BIOS, however, is not required to allow the kernel to control these registers and if it doesn’t do that, the kernel must not modify their contents. Of course the native PCI Express PME signaling cannot be used by the kernel in that case.
2. PCI Subsystem and Device Power Management¶
2.1. Device Power Management Callbacks¶
The PCI Subsystem participates in the power management of PCI devices in a number of ways. First of all, it provides an intermediate code layer between the device power management core (PM core) and PCI device drivers. Specifically, the pm field of the PCI subsystem’s struct bus_type object, pci_bus_type, points to a struct dev_pm_ops object, pci_dev_pm_ops, containing pointers to several device power management callbacks:
const struct dev_pm_ops pci_dev_pm_ops = {
.prepare = pci_pm_prepare,
.complete = pci_pm_complete,
.suspend = pci_pm_suspend,
.resume = pci_pm_resume,
.freeze = pci_pm_freeze,
.thaw = pci_pm_thaw,
.poweroff = pci_pm_poweroff,
.restore = pci_pm_restore,
.suspend_noirq = pci_pm_suspend_noirq,
.resume_noirq = pci_pm_resume_noirq,
.freeze_noirq = pci_pm_freeze_noirq,
.thaw_noirq = pci_pm_thaw_noirq,
.poweroff_noirq = pci_pm_poweroff_noirq,
.restore_noirq = pci_pm_restore_noirq,
.runtime_suspend = pci_pm_runtime_suspend,
.runtime_resume = pci_pm_runtime_resume,
.runtime_idle = pci_pm_runtime_idle,
};
These callbacks are executed by the PM core in various situations related to device power management and they, in turn, execute power management callbacks provided by PCI device drivers. They also perform power management operations involving some standard configuration registers of PCI devices that device drivers need not know or care about.
The structure representing a PCI device, struct pci_dev, contains several fields that these callbacks operate on:
struct pci_dev {
...
pci_power_t current_state; /* Current operating state. */
int pm_cap; /* PM capability offset in the
configuration space */
unsigned int pme_support:5; /* Bitmask of states from which PME#
can be generated */
unsigned int pme_interrupt:1;/* Is native PCIe PME signaling used? */
unsigned int d1_support:1; /* Low power state D1 is supported */
unsigned int d2_support:1; /* Low power state D2 is supported */
unsigned int no_d1d2:1; /* D1 and D2 are forbidden */
unsigned int wakeup_prepared:1; /* Device prepared for wake up */
unsigned int d3_delay; /* D3->D0 transition time in ms */
...
};
They also indirectly use some fields of the struct device that is embedded in struct pci_dev.
2.2. Device Initialization¶
The PCI subsystem’s first task related to device power management is to prepare the device for power management and initialize the fields of struct pci_dev used for this purpose. This happens in two functions defined in drivers/pci/pci.c, pci_pm_init() and platform_pci_wakeup_init().
The first of these functions checks if the device supports native PCI PM and if that’s the case the offset of its power management capability structure in the configuration space is stored in the pm_cap field of the device’s struct pci_dev object. Next, the function checks which PCI low-power states are supported by the device and from which low-power states the device can generate native PCI PMEs. The power management fields of the device’s struct pci_dev and the struct device embedded in it are updated accordingly and the generation of PMEs by the device is disabled.
The second function checks if the device can be prepared to signal wakeup with the help of the platform firmware, such as the ACPI BIOS. If that is the case, the function updates the wakeup fields in struct device embedded in the device’s struct pci_dev and uses the firmware-provided method to prevent the device from signaling wakeup.
At this point the device is ready for power management. For driverless devices, however, this functionality is limited to a few basic operations carried out during system-wide transitions to a sleep state and back to the working state.
2.3. Runtime Device Power Management¶
The PCI subsystem plays a vital role in the runtime power management of PCI devices. For this purpose it uses the general runtime power management (runtime PM) framework described in Documentation/power/runtime_pm.rst. Namely, it provides subsystem-level callbacks:
pci_pm_runtime_suspend()
pci_pm_runtime_resume()
pci_pm_runtime_idle()
that are executed by the core runtime PM routines. It also implements the entire mechanics necessary for handling runtime wakeup signals from PCI devices in low-power states, which at the time of this writing works for both the native PCI Express PME signaling and the ACPI GPE-based wakeup signaling described in Section 1.
First, a PCI device is put into a low-power state, or suspended, with the help of pm_schedule_suspend() or pm_runtime_suspend() which for PCI devices call pci_pm_runtime_suspend() to do the actual job. For this to work, the device’s driver has to provide a pm->runtime_suspend() callback (see below), which is run by pci_pm_runtime_suspend() as the first action. If the driver’s callback returns successfully, the device’s standard configuration registers are saved, the device is prepared to generate wakeup signals and, finally, it is put into the target low-power state.
The low-power state to put the device into is the lowest-power (highest number) state from which it can signal wakeup. The exact method of signaling wakeup is system-dependent and is determined by the PCI subsystem on the basis of the reported capabilities of the device and the platform firmware. To prepare the device for signaling wakeup and put it into the selected low-power state, the PCI subsystem can use the platform firmware as well as the device’s native PCI PM capabilities, if supported.
It is expected that the device driver’s pm->runtime_suspend() callback will not attempt to prepare the device for signaling wakeup or to put it into a low-power state. The driver ought to leave these tasks to the PCI subsystem that has all of the information necessary to perform them.
A suspended device is brought back into the “active” state, or resumed, with the help of pm_request_resume() or pm_runtime_resume() which both call pci_pm_runtime_resume() for PCI devices. Again, this only works if the device’s driver provides a pm->runtime_resume() callback (see below). However, before the driver’s callback is executed, pci_pm_runtime_resume() brings the device back into the full-power state, prevents it from signaling wakeup while in that state and restores its standard configuration registers. Thus the driver’s callback need not worry about the PCI-specific aspects of the device resume.
Note that generally pci_pm_runtime_resume() may be called in two different situations. First, it may be called at the request of the device’s driver, for example if there are some data for it to process. Second, it may be called as a result of a wakeup signal from the device itself (this sometimes is referred to as “remote wakeup”). Of course, for this purpose the wakeup signal is handled in one of the ways described in Section 1 and finally converted into a notification for the PCI subsystem after the source device has been identified.
The pci_pm_runtime_idle() function, called for PCI devices by pm_runtime_idle() and pm_request_idle(), executes the device driver’s pm->runtime_idle() callback, if defined, and if that callback doesn’t return error code (or is not present at all), suspends the device with the help of pm_runtime_suspend(). Sometimes pci_pm_runtime_idle() is called automatically by the PM core (for example, it is called right after the device has just been resumed), in which cases it is expected to suspend the device if that makes sense. Usually, however, the PCI subsystem doesn’t really know if the device really can be suspended, so it lets the device’s driver decide by running its pm->runtime_idle() callback.
2.4. System-Wide Power Transitions¶
There are a few different types of system-wide power transitions, described in Documentation/driver-api/pm/devices.rst. Each of them requires devices to be handled in a specific way and the PM core executes subsystem-level power management callbacks for this purpose. They are executed in phases such that each phase involves executing the same subsystem-level callback for every device belonging to the given subsystem before the next phase begins. These phases always run after tasks have been frozen.
2.4.1. System Suspend¶
When the system is going into a sleep state in which the contents of memory will be preserved, such as one of the ACPI sleep states S1-S3, the phases are:
prepare, suspend, suspend_noirq.
The following PCI bus type’s callbacks, respectively, are used in these phases:
pci_pm_prepare()
pci_pm_suspend()
pci_pm_suspend_noirq()
The pci_pm_prepare() routine first puts the device into the “fully functional” state with the help of pm_runtime_resume(). Then, it executes the device driver’s pm->prepare() callback if defined (i.e. if the driver’s struct dev_pm_ops object is present and the prepare pointer in that object is valid).
The pci_pm_suspend() routine first checks if the device’s driver implements legacy PCI suspend routines (see Section 3), in which case the driver’s legacy suspend callback is executed, if present, and its result is returned. Next, if the device’s driver doesn’t provide a struct dev_pm_ops object (containing pointers to the driver’s callbacks), pci_pm_default_suspend() is called, which simply turns off the device’s bus master capability and runs pcibios_disable_device() to disable it, unless the device is a bridge (PCI bridges are ignored by this routine). Next, the device driver’s pm->suspend() callback is executed, if defined, and its result is returned if it fails. Finally, pci_fixup_device() is called to apply hardware suspend quirks related to the device if necessary.
Note that the suspend phase is carried out asynchronously for PCI devices, so the pci_pm_suspend() callback may be executed in parallel for any pair of PCI devices that don’t depend on each other in a known way (i.e. none of the paths in the device tree from the root bridge to a leaf device contains both of them).
The pci_pm_suspend_noirq() routine is executed after suspend_device_irqs() has been called, which means that the device driver’s interrupt handler won’t be invoked while this routine is running. It first checks if the device’s driver implements legacy PCI suspends routines (Section 3), in which case the legacy late suspend routine is called and its result is returned (the standard configuration registers of the device are saved if the driver’s callback hasn’t done that). Second, if the device driver’s struct dev_pm_ops object is not present, the device’s standard configuration registers are saved and the routine returns success. Otherwise the device driver’s pm->suspend_noirq() callback is executed, if present, and its result is returned if it fails. Next, if the device’s standard configuration registers haven’t been saved yet (one of the device driver’s callbacks executed before might do that), pci_pm_suspend_noirq() saves them, prepares the device to signal wakeup (if necessary) and puts it into a low-power state.
The low-power state to put the device into is the lowest-power (highest number) state from which it can signal wakeup while the system is in the target sleep state. Just like in the runtime PM case described above, the mechanism of signaling wakeup is system-dependent and determined by the PCI subsystem, which is also responsible for preparing the device to signal wakeup from the system’s target sleep state as appropriate.
PCI device drivers (that don’t implement legacy power management callbacks) are generally not expected to prepare devices for signaling wakeup or to put them into low-power states. However, if one of the driver’s suspend callbacks (pm->suspend() or pm->suspend_noirq()) saves the device’s standard configuration registers, pci_pm_suspend_noirq() will assume that the device has been prepared to signal wakeup and put into a low-power state by the driver (the driver is then assumed to have used the helper functions provided by the PCI subsystem for this purpose). PCI device drivers are not encouraged to do that, but in some rare cases doing that in the driver may be the optimum approach.
2.4.2. System Resume¶
When the system is undergoing a transition from a sleep state in which the contents of memory have been preserved, such as one of the ACPI sleep states S1-S3, into the working state (ACPI S0), the phases are:
resume_noirq, resume, complete.
The following PCI bus type’s callbacks, respectively, are executed in these phases:
pci_pm_resume_noirq()
pci_pm_resume()
pci_pm_complete()
The pci_pm_resume_noirq() routine first puts the device into the full-power state, restores its standard configuration registers and applies early resume hardware quirks related to the device, if necessary. This is done unconditionally, regardless of whether or not the device’s driver implements legacy PCI power management callbacks (this way all PCI devices are in the full-power state and their standard configuration registers have been restored when their interrupt handlers are invoked for the first time during resume, which allows the kernel to avoid problems with the handling of shared interrupts by drivers whose devices are still suspended). If legacy PCI power management callbacks (see Section 3) are implemented by the device’s driver, the legacy early resume callback is executed and its result is returned. Otherwise, the device driver’s pm->resume_noirq() callback is executed, if defined, and its result is returned.
The pci_pm_resume() routine first checks if the device’s standard configuration registers have been restored and restores them if that’s not the case (this only is necessary in the error path during a failing suspend). Next, resume hardware quirks related to the device are applied, if necessary, and if the device’s driver implements legacy PCI power management callbacks (see Section 3), the driver’s legacy resume callback is executed and its result is returned. Otherwise, the device’s wakeup signaling mechanisms are blocked and its driver’s pm->resume() callback is executed, if defined (the callback’s result is then returned).
The resume phase is carried out asynchronously for PCI devices, like the suspend phase described above, which means that if two PCI devices don’t depend on each other in a known way, the pci_pm_resume() routine may be executed for the both of them in parallel.
The pci_pm_complete() routine only executes the device driver’s pm->complete() callback, if defined.
2.4.3. System Hibernation¶
System hibernation is more complicated than system suspend, because it requires a system image to be created and written into a persistent storage medium. The image is created atomically and all devices are quiesced, or frozen, before that happens.
The freezing of devices is carried out after enough memory has been freed (at the time of this writing the image creation requires at least 50% of system RAM to be free) in the following three phases:
prepare, freeze, freeze_noirq
that correspond to the PCI bus type’s callbacks:
pci_pm_prepare()
pci_pm_freeze()
pci_pm_freeze_noirq()
This means that the prepare phase is exactly the same as for system suspend. The other two phases, however, are different.
The pci_pm_freeze() routine is quite similar to pci_pm_suspend(), but it runs the device driver’s pm->freeze() callback, if defined, instead of pm->suspend(), and it doesn’t apply the suspend-related hardware quirks. It is executed asynchronously for different PCI devices that don’t depend on each other in a known way.
The pci_pm_freeze_noirq() routine, in turn, is similar to pci_pm_suspend_noirq(), but it calls the device driver’s pm->freeze_noirq() routine instead of pm->suspend_noirq(). It also doesn’t attempt to prepare the device for signaling wakeup and put it into a low-power state. Still, it saves the device’s standard configuration registers if they haven’t been saved by one of the driver’s callbacks.
Once the image has been created, it has to be saved. However, at this point all devices are frozen and they cannot handle I/O, while their ability to handle I/O is obviously necessary for the image saving. Thus they have to be brought back to the fully functional state and this is done in the following phases:
thaw_noirq, thaw, complete
using the following PCI bus type’s callbacks:
pci_pm_thaw_noirq()
pci_pm_thaw()
pci_pm_complete()
respectively.
The first of them, pci_pm_thaw_noirq(), is analogous to pci_pm_resume_noirq(). It puts the device into the full power state and restores its standard configuration registers. It also executes the device driver’s pm->thaw_noirq() callback, if defined, instead of pm->resume_noirq().
The pci_pm_thaw() routine is similar to pci_pm_resume(), but it runs the device driver’s pm->thaw() callback instead of pm->resume(). It is executed asynchronously for different PCI devices that don’t depend on each other in a known way.
The complete phase is the same as for system resume.
After saving the image, devices need to be powered down before the system can enter the target sleep state (ACPI S4 for ACPI-based systems). This is done in three phases:
prepare, poweroff, poweroff_noirq
where the prepare phase is exactly the same as for system suspend. The other two phases are analogous to the suspend and suspend_noirq phases, respectively. The PCI subsystem-level callbacks they correspond to:
pci_pm_poweroff()
pci_pm_poweroff_noirq()
work in analogy with pci_pm_suspend() and pci_pm_poweroff_noirq(), respectively, although they don’t attempt to save the device’s standard configuration registers.
2.4.4. System Restore¶
System restore requires a hibernation image to be loaded into memory and the pre-hibernation memory contents to be restored before the pre-hibernation system activity can be resumed.
As described in Documentation/driver-api/pm/devices.rst, the hibernation image is loaded into memory by a fresh instance of the kernel, called the boot kernel, which in turn is loaded and run by a boot loader in the usual way. After the boot kernel has loaded the image, it needs to replace its own code and data with the code and data of the “hibernated” kernel stored within the image, called the image kernel. For this purpose all devices are frozen just like before creating the image during hibernation, in the
prepare, freeze, freeze_noirq
phases described above. However, the devices affected by these phases are only those having drivers in the boot kernel; other devices will still be in whatever state the boot loader left them.
Should the restoration of the pre-hibernation memory contents fail, the boot kernel would go through the “thawing” procedure described above, using the thaw_noirq, thaw, and complete phases (that will only affect the devices having drivers in the boot kernel), and then continue running normally.
If the pre-hibernation memory contents are restored successfully, which is the usual situation, control is passed to the image kernel, which then becomes responsible for bringing the system back to the working state. To achieve this, it must restore the devices’ pre-hibernation functionality, which is done much like waking up from the memory sleep state, although it involves different phases:
restore_noirq, restore, complete
The first two of these are analogous to the resume_noirq and resume phases described above, respectively, and correspond to the following PCI subsystem callbacks:
pci_pm_restore_noirq()
pci_pm_restore()
These callbacks work in analogy with pci_pm_resume_noirq() and pci_pm_resume(), respectively, but they execute the device driver’s pm->restore_noirq() and pm->restore() callbacks, if available.
The complete phase is carried out in exactly the same way as during system resume.
3. PCI Device Drivers and Power Management¶
3.1. Power Management Callbacks¶
PCI device drivers participate in power management by providing callbacks to be executed by the PCI subsystem’s power management routines described above and by controlling the runtime power management of their devices.
At the time of this writing there are two ways to define power management callbacks for a PCI device driver, the recommended one, based on using a dev_pm_ops structure described in Documentation/driver-api/pm/devices.rst, and the “legacy” one, in which the .suspend() and .resume() callbacks from struct pci_driver are used. The legacy approach, however, doesn’t allow one to define runtime power management callbacks and is not really suitable for any new drivers. Therefore it is not covered by this document (refer to the source code to learn more about it).
It is recommended that all PCI device drivers define a struct dev_pm_ops object containing pointers to power management (PM) callbacks that will be executed by the PCI subsystem’s PM routines in various circumstances. A pointer to the driver’s struct dev_pm_ops object has to be assigned to the driver.pm field in its struct pci_driver object. Once that has happened, the “legacy” PM callbacks in struct pci_driver are ignored (even if they are not NULL).
The PM callbacks in struct dev_pm_ops are not mandatory and if they are not defined (i.e. the respective fields of struct dev_pm_ops are unset) the PCI subsystem will handle the device in a simplified default manner. If they are defined, though, they are expected to behave as described in the following subsections.
3.1.1. prepare()¶
The prepare() callback is executed during system suspend, during hibernation (when a hibernation image is about to be created), during power-off after saving a hibernation image and during system restore, when a hibernation image has just been loaded into memory.
This callback is only necessary if the driver’s device has children that in general may be registered at any time. In that case the role of the prepare() callback is to prevent new children of the device from being registered until one of the resume_noirq(), thaw_noirq(), or restore_noirq() callbacks is run.
In addition to that the prepare() callback may carry out some operations preparing the device to be suspended, although it should not allocate memory (if additional memory is required to suspend the device, it has to be preallocated earlier, for example in a suspend/hibernate notifier as described in Documentation/driver-api/pm/notifiers.rst).
3.1.2. suspend()¶
The suspend() callback is only executed during system suspend, after prepare() callbacks have been executed for all devices in the system.
This callback is expected to quiesce the device and prepare it to be put into a low-power state by the PCI subsystem. It is not required (in fact it even is not recommended) that a PCI driver’s suspend() callback save the standard configuration registers of the device, prepare it for waking up the system, or put it into a low-power state. All of these operations can very well be taken care of by the PCI subsystem, without the driver’s participation.
However, in some rare case it is convenient to carry out these operations in
a PCI driver. Then, pci_save_state(), pci_prepare_to_sleep(), and
pci_set_power_state() should be used to save the device’s standard configuration
registers, to prepare it for system wakeup (if necessary), and to put it into a
low-power state, respectively. Moreover, if the driver calls pci_save_state(),
the PCI subsystem will not execute either pci_prepare_to_sleep(), or
pci_set_power_state() for its device, so the driver is then responsible for
handling the device as appropriate.
While the suspend() callback is being executed, the driver’s interrupt handler can be invoked to handle an interrupt from the device, so all suspend-related operations relying on the driver’s ability to handle interrupts should be carried out in this callback.
3.1.3. suspend_noirq()¶
The suspend_noirq() callback is only executed during system suspend, after suspend() callbacks have been executed for all devices in the system and after device interrupts have been disabled by the PM core.
The difference between suspend_noirq() and suspend() is that the driver’s interrupt handler will not be invoked while suspend_noirq() is running. Thus suspend_noirq() can carry out operations that would cause race conditions to arise if they were performed in suspend().
3.1.4. freeze()¶
The freeze() callback is hibernation-specific and is executed in two situations, during hibernation, after prepare() callbacks have been executed for all devices in preparation for the creation of a system image, and during restore, after a system image has been loaded into memory from persistent storage and the prepare() callbacks have been executed for all devices.
The role of this callback is analogous to the role of the suspend() callback described above. In fact, they only need to be different in the rare cases when the driver takes the responsibility for putting the device into a low-power state.
In that cases the freeze() callback should not prepare the device system wakeup
or put it into a low-power state. Still, either it or freeze_noirq() should
save the device’s standard configuration registers using pci_save_state().
3.1.5. freeze_noirq()¶
The freeze_noirq() callback is hibernation-specific. It is executed during hibernation, after prepare() and freeze() callbacks have been executed for all devices in preparation for the creation of a system image, and during restore, after a system image has been loaded into memory and after prepare() and freeze() callbacks have been executed for all devices. It is always executed after device interrupts have been disabled by the PM core.
The role of this callback is analogous to the role of the suspend_noirq() callback described above and it very rarely is necessary to define freeze_noirq().
The difference between freeze_noirq() and freeze() is analogous to the difference between suspend_noirq() and suspend().
3.1.6. poweroff()¶
The poweroff() callback is hibernation-specific. It is executed when the system is about to be powered off after saving a hibernation image to a persistent storage. prepare() callbacks are executed for all devices before poweroff() is called.
The role of this callback is analogous to the role of the suspend() and freeze()
callbacks described above, although it does not need to save the contents of
the device’s registers. In particular, if the driver wants to put the device
into a low-power state itself instead of allowing the PCI subsystem to do that,
the poweroff() callback should use pci_prepare_to_sleep() and
pci_set_power_state() to prepare the device for system wakeup and to put it
into a low-power state, respectively, but it need not save the device’s standard
configuration registers.
3.1.7. poweroff_noirq()¶
The poweroff_noirq() callback is hibernation-specific. It is executed after poweroff() callbacks have been executed for all devices in the system.
The role of this callback is analogous to the role of the suspend_noirq() and freeze_noirq() callbacks described above, but it does not need to save the contents of the device’s registers.
The difference between poweroff_noirq() and poweroff() is analogous to the difference between suspend_noirq() and suspend().
3.1.8. resume_noirq()¶
The resume_noirq() callback is only executed during system resume, after the PM core has enabled the non-boot CPUs. The driver’s interrupt handler will not be invoked while resume_noirq() is running, so this callback can carry out operations that might race with the interrupt handler.
Since the PCI subsystem unconditionally puts all devices into the full power state in the resume_noirq phase of system resume and restores their standard configuration registers, resume_noirq() is usually not necessary. In general it should only be used for performing operations that would lead to race conditions if carried out by resume().
3.1.9. resume()¶
The resume() callback is only executed during system resume, after resume_noirq() callbacks have been executed for all devices in the system and device interrupts have been enabled by the PM core.
This callback is responsible for restoring the pre-suspend configuration of the device and bringing it back to the fully functional state. The device should be able to process I/O in a usual way after resume() has returned.
3.1.10. thaw_noirq()¶
The thaw_noirq() callback is hibernation-specific. It is executed after a system image has been created and the non-boot CPUs have been enabled by the PM core, in the thaw_noirq phase of hibernation. It also may be executed if the loading of a hibernation image fails during system restore (it is then executed after enabling the non-boot CPUs). The driver’s interrupt handler will not be invoked while thaw_noirq() is running.
The role of this callback is analogous to the role of resume_noirq(). The difference between these two callbacks is that thaw_noirq() is executed after freeze() and freeze_noirq(), so in general it does not need to modify the contents of the device’s registers.
3.1.11. thaw()¶
The thaw() callback is hibernation-specific. It is executed after thaw_noirq() callbacks have been executed for all devices in the system and after device interrupts have been enabled by the PM core.
This callback is responsible for restoring the pre-freeze configuration of the device, so that it will work in a usual way after thaw() has returned.
3.1.12. restore_noirq()¶
The restore_noirq() callback is hibernation-specific. It is executed in the restore_noirq phase of hibernation, when the boot kernel has passed control to the image kernel and the non-boot CPUs have been enabled by the image kernel’s PM core.
This callback is analogous to resume_noirq() with the exception that it cannot make any assumption on the previous state of the device, even if the BIOS (or generally the platform firmware) is known to preserve that state over a suspend-resume cycle.
For the vast majority of PCI device drivers there is no difference between resume_noirq() and restore_noirq().
3.1.13. restore()¶
The restore() callback is hibernation-specific. It is executed after restore_noirq() callbacks have been executed for all devices in the system and after the PM core has enabled device drivers’ interrupt handlers to be invoked.
This callback is analogous to resume(), just like restore_noirq() is analogous to resume_noirq(). Consequently, the difference between restore_noirq() and restore() is analogous to the difference between resume_noirq() and resume().
For the vast majority of PCI device drivers there is no difference between resume() and restore().
3.1.14. complete()¶
The complete() callback is executed in the following situations:
during system resume, after resume() callbacks have been executed for all devices,
during hibernation, before saving the system image, after thaw() callbacks have been executed for all devices,
during system restore, when the system is going back to its pre-hibernation state, after restore() callbacks have been executed for all devices.
It also may be executed if the loading of a hibernation image into memory fails (in that case it is run after thaw() callbacks have been executed for all devices that have drivers in the boot kernel).
This callback is entirely optional, although it may be necessary if the prepare() callback performs operations that need to be reversed.
3.1.15. runtime_suspend()¶
The runtime_suspend() callback is specific to device runtime power management (runtime PM). It is executed by the PM core’s runtime PM framework when the device is about to be suspended (i.e. quiesced and put into a low-power state) at run time.
This callback is responsible for freezing the device and preparing it to be put into a low-power state, but it must allow the PCI subsystem to perform all of the PCI-specific actions necessary for suspending the device.
3.1.16. runtime_resume()¶
The runtime_resume() callback is specific to device runtime PM. It is executed by the PM core’s runtime PM framework when the device is about to be resumed (i.e. put into the full-power state and programmed to process I/O normally) at run time.
This callback is responsible for restoring the normal functionality of the device after it has been put into the full-power state by the PCI subsystem. The device is expected to be able to process I/O in the usual way after runtime_resume() has returned.
3.1.17. runtime_idle()¶
The runtime_idle() callback is specific to device runtime PM. It is executed by the PM core’s runtime PM framework whenever it may be desirable to suspend the device according to the PM core’s information. In particular, it is automatically executed right after runtime_resume() has returned in case the resume of the device has happened as a result of a spurious event.
This callback is optional, but if it is not implemented or if it returns 0, the PCI subsystem will call pm_runtime_suspend() for the device, which in turn will cause the driver’s runtime_suspend() callback to be executed.
3.1.18. Pointing Multiple Callback Pointers to One Routine¶
Although in principle each of the callbacks described in the previous subsections can be defined as a separate function, it often is convenient to point two or more members of struct dev_pm_ops to the same routine. There are a few convenience macros that can be used for this purpose.
The SIMPLE_DEV_PM_OPS macro declares a struct dev_pm_ops object with one suspend routine pointed to by the .suspend(), .freeze(), and .poweroff() members and one resume routine pointed to by the .resume(), .thaw(), and .restore() members. The other function pointers in this struct dev_pm_ops are unset.
The UNIVERSAL_DEV_PM_OPS macro is similar to SIMPLE_DEV_PM_OPS, but it additionally sets the .runtime_resume() pointer to the same value as .resume() (and .thaw(), and .restore()) and the .runtime_suspend() pointer to the same value as .suspend() (and .freeze() and .poweroff()).
The SET_SYSTEM_SLEEP_PM_OPS can be used inside of a declaration of struct dev_pm_ops to indicate that one suspend routine is to be pointed to by the .suspend(), .freeze(), and .poweroff() members and one resume routine is to be pointed to by the .resume(), .thaw(), and .restore() members.
3.1.19. Driver Flags for Power Management¶
The PM core allows device drivers to set flags that influence the handling of power management for the devices by the core itself and by middle layer code including the PCI bus type. The flags should be set once at the driver probe time with the help of the dev_pm_set_driver_flags() function and they should not be updated directly afterwards.
The DPM_FLAG_NEVER_SKIP flag prevents the PM core from using the direct-complete mechanism allowing device suspend/resume callbacks to be skipped if the device is in runtime suspend when the system suspend starts. That also affects all of the ancestors of the device, so this flag should only be used if absolutely necessary.
The DPM_FLAG_SMART_PREPARE flag instructs the PCI bus type to only return a positive value from pci_pm_prepare() if the ->prepare callback provided by the driver of the device returns a positive value. That allows the driver to opt out from using the direct-complete mechanism dynamically.
The DPM_FLAG_SMART_SUSPEND flag tells the PCI bus type that from the driver’s perspective the device can be safely left in runtime suspend during system suspend. That causes pci_pm_suspend(), pci_pm_freeze() and pci_pm_poweroff() to skip resuming the device from runtime suspend unless there are PCI-specific reasons for doing that. Also, it causes pci_pm_suspend_late/noirq(), pci_pm_freeze_late/noirq() and pci_pm_poweroff_late/noirq() to return early if the device remains in runtime suspend in the beginning of the “late” phase of the system-wide transition under way. Moreover, if the device is in runtime suspend in pci_pm_resume_noirq() or pci_pm_restore_noirq(), its runtime power management status will be changed to “active” (as it is going to be put into D0 going forward), but if it is in runtime suspend in pci_pm_thaw_noirq(), the function will set the power.direct_complete flag for it (to make the PM core skip the subsequent “thaw” callbacks for it) and return.
Setting the DPM_FLAG_LEAVE_SUSPENDED flag means that the driver prefers the device to be left in suspend after system-wide transitions to the working state. This flag is checked by the PM core, but the PCI bus type informs the PM core which devices may be left in suspend from its perspective (that happens during the “noirq” phase of system-wide suspend and analogous transitions) and next it uses the dev_pm_may_skip_resume() helper to decide whether or not to return from pci_pm_resume_noirq() early, as the PM core will skip the remaining resume callbacks for the device during the transition under way and will set its runtime PM status to “suspended” if dev_pm_may_skip_resume() returns “true” for it.
3.2. Device Runtime Power Management¶
In addition to providing device power management callbacks PCI device drivers are responsible for controlling the runtime power management (runtime PM) of their devices.
The PCI device runtime PM is optional, but it is recommended that PCI device drivers implement it at least in the cases where there is a reliable way of verifying that the device is not used (like when the network cable is detached from an Ethernet adapter or there are no devices attached to a USB controller).
To support the PCI runtime PM the driver first needs to implement the runtime_suspend() and runtime_resume() callbacks. It also may need to implement the runtime_idle() callback to prevent the device from being suspended again every time right after the runtime_resume() callback has returned (alternatively, the runtime_suspend() callback will have to check if the device should really be suspended and return -EAGAIN if that is not the case).
The runtime PM of PCI devices is enabled by default by the PCI core. PCI device drivers do not need to enable it and should not attempt to do so. However, it is blocked by pci_pm_init() that runs the pm_runtime_forbid() helper function. In addition to that, the runtime PM usage counter of each PCI device is incremented by local_pci_probe() before executing the probe callback provided by the device’s driver.
If a PCI driver implements the runtime PM callbacks and intends to use the runtime PM framework provided by the PM core and the PCI subsystem, it needs to decrement the device’s runtime PM usage counter in its probe callback function. If it doesn’t do that, the counter will always be different from zero for the device and it will never be runtime-suspended. The simplest way to do that is by calling pm_runtime_put_noidle(), but if the driver wants to schedule an autosuspend right away, for example, it may call pm_runtime_put_autosuspend() instead for this purpose. Generally, it just needs to call a function that decrements the devices usage counter from its probe routine to make runtime PM work for the device.
It is important to remember that the driver’s runtime_suspend() callback may be executed right after the usage counter has been decremented, because user space may already have caused the pm_runtime_allow() helper function unblocking the runtime PM of the device to run via sysfs, so the driver must be prepared to cope with that.
The driver itself should not call pm_runtime_allow(), though. Instead, it should let user space or some platform-specific code do that (user space can do it via sysfs as stated above), but it must be prepared to handle the runtime PM of the device correctly as soon as pm_runtime_allow() is called (which may happen at any time, even before the driver is loaded).
When the driver’s remove callback runs, it has to balance the decrementation of the device’s runtime PM usage counter at the probe time. For this reason, if it has decremented the counter in its probe callback, it must run pm_runtime_get_noresume() in its remove callback. [Since the core carries out a runtime resume of the device and bumps up the device’s usage counter before running the driver’s remove callback, the runtime PM of the device is effectively disabled for the duration of the remove execution and all runtime PM helper functions incrementing the device’s usage counter are then effectively equivalent to pm_runtime_get_noresume().]
The runtime PM framework works by processing requests to suspend or resume devices, or to check if they are idle (in which cases it is reasonable to subsequently request that they be suspended). These requests are represented by work items put into the power management workqueue, pm_wq. Although there are a few situations in which power management requests are automatically queued by the PM core (for example, after processing a request to resume a device the PM core automatically queues a request to check if the device is idle), device drivers are generally responsible for queuing power management requests for their devices. For this purpose they should use the runtime PM helper functions provided by the PM core, discussed in Documentation/power/runtime_pm.rst.
Devices can also be suspended and resumed synchronously, without placing a request into pm_wq. In the majority of cases this also is done by their drivers that use helper functions provided by the PM core for this purpose.
For more information on the runtime PM of devices refer to Documentation/power/runtime_pm.rst.
4. Resources¶
PCI Local Bus Specification, Rev. 3.0
PCI Bus Power Management Interface Specification, Rev. 1.2
Advanced Configuration and Power Interface (ACPI) Specification, Rev. 3.0b
PCI Express Base Specification, Rev. 2.0
Documentation/driver-api/pm/devices.rst
Documentation/power/runtime_pm.rst