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.txt.
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 signalsand, 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 itfrom 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.