Documentation/power/pci.rst

13 power management refer to Documentation/driver-api/pm/devices.rst and
27 1.1. Native and Platform-Based Power Management
28 -----------------------------------------------
31 devices into states in which they draw less power (low-power states) at the
34 Usually, a device is put into a low-power state when it is underutilized or
36 again, it has to be put back into the "fully functional" state (full-power
41 PCI devices may be put into low-power states in two ways, by using the device
42 capabilities introduced by the PCI Bus Power Management Interface Specification,
44 approach, that is referred to as the native PCI power management (native PCI PM)
50 Devices supporting the native PCI PM usually can generate wakeup signals called
53 to put the device that sent it into the full-power state.  However, the PCI Bus
65 native PCI PM mechanism, because the method provided by the platform depends on
68 Thus in many situations both the native and the platform-based power management
72 --------------------------------
74 The PCI Bus Power Management Interface Specification (PCI PM Spec) was
79 The implementation of the PCI PM Spec is optional for conventional PCI devices,
80 but it is mandatory for PCI Express devices.  If a device supports the PCI PM
85 The PCI PM Spec defines 4 operating states for devices (D0-D3) and for buses
86 (B0-B3).  The higher the number, the less power is drawn by the device or bus
88 the device or bus to return to the full-power state (D0 or B0, respectively).
95 interface for putting the bus the device is on into a state in which Vcc is
96 removed from all devices on the bus.
98 PCI bus power management, however, is not supported by the Linux kernel at the
101 Note that every PCI device can be in the full-power state (D0) or in D3cold,
102 regardless of whether or not it implements the PCI PM Spec.  In addition to
103 that, if the PCI PM Spec is implemented by the device, it must support D3hot
106 PCI devices supporting the PCI PM Spec can be programmed to go to any of the
107 supported low-power states (except for D3cold).  While in D1-D3hot the
112 forth between D0 and the supported low-power states (except for D3cold) and the
115 +----------------------------+
117 +----------------------------+
119 +----------------------------+
121 +----------------------------+
123 +----------------------------+
125 +----------------------------+
129 a full power-on reset sequence and the power-on defaults are restored to the
132 PCI devices supporting the PCI PM Spec can be programmed to generate PMEs
133 while in any power state (D0-D3), but they are not required to be capable
140 ---------------------------------
143 system-specific.  However, if the system in question is compliant with the
145 majority of x86-based systems, it is supposed to implement device power
150 putting a device into a low-power state.  These control methods are encoded
151 using special byte-code language called the ACPI Machine Language (AML) and
156 on the system design in a system-specific fashion.
166 labeled as D0, D1, D2, and D3 that roughly correspond to the native PCI PM
167 D0-D3 states (although the difference between D3hot and D3cold is not taken
178 is going to be put into a low-power state (D1-D3) and is supposed to generate
187 system-wide transition into a sleep state or back into the working state.  ACPI
201 ---------------------
205 putting the device into a low-power state, have to be caught and handled as
208 put the devices generating them into the full-power state and take care of the
212 On ACPI-based systems wakeup signals sent by conventional PCI devices are
213 converted into ACPI General-Purpose Events (GPEs) which are hardware signals
229 the ACPI S1-S4 states), in which case system wakeup is started by its core logic
244 conventional PCI devices on systems that are not ACPI-based, but there is one
247 root ports.  For conventional PCI devices native PMEs are out-of-band, so they
250 they are in-band messages that have to pass through the PCI Express hierarchy,
261 In principle the native PCI Express PME signaling may also be used on ACPI-based
273 --------------------------------------
277 the device power management core (PM core) and PCI device drivers.
278 Specifically, the pm field of the PCI subsystem's struct bus_type object,
302 These callbacks are executed by the PM core in various situations related to
314 	int		pm_cap;		/* PM capability offset in the
323 	unsigned int	d3hot_delay;	/* D3hot->D0 transition time in ms */
331 --------------------------
338 The first of these functions checks if the device supports native PCI PM
341 pci_dev object.  Next, the function checks which PCI low-power states are
342 supported by the device and from which low-power states the device can generate
350 device's struct pci_dev and uses the firmware-provided method to prevent the
355 during system-wide transitions to a sleep state and back to the working state.
358 ------------------------------------
362 (runtime PM) framework described in Documentation/power/runtime_pm.rst.
363 Namely, it provides subsystem-level callbacks::
369 that are executed by the core runtime PM routines.  It also implements the
371 in low-power states, which at the time of this writing works for both the native
372 PCI Express PME signaling and the ACPI GPE-based wakeup signaling described in
375 First, a PCI device is put into a low-power state, or suspended, with the help
378 driver has to provide a pm->runtime_suspend() callback (see below), which is
382 the target low-power state.
384 The low-power state to put the device into is the lowest-power (highest number)
386 system-dependent and is determined by the PCI subsystem on the basis of the
388 device for signaling wakeup and put it into the selected low-power state, the
390 PM capabilities, if supported.
392 It is expected that the device driver's pm->runtime_suspend() callback will
394 low-power state.  The driver ought to leave these tasks to the PCI subsystem
400 driver provides a pm->runtime_resume() callback (see below).  However, before
402 back into the full-power state, prevents it from signaling wakeup while in that
404 callback need not worry about the PCI-specific aspects of the device resume.
416 and pm_request_idle(), executes the device driver's pm->runtime_idle()
419 Sometimes pci_pm_runtime_idle() is called automatically by the PM core (for
424 pm->runtime_idle() callback.
426 2.4. System-Wide Power Transitions
427 ----------------------------------
428 There are a few different types of system-wide power transitions, described in
429 Documentation/driver-api/pm/devices.rst.  Each of them requires devices to be
430 handled in a specific way and the PM core executes subsystem-level power
432 each phase involves executing the same subsystem-level callback for every device
440 be preserved, such as one of the ACPI sleep states S1-S3, the phases are:
444 The following PCI bus type's callbacks, respectively, are used in these phases::
452 driver's pm->prepare() callback if defined (i.e. if the driver's struct
460 simply turns off the device's bus master capability and runs
462 bridges are ignored by this routine).  Next, the device driver's pm->suspend()
480 returns success.  Otherwise the device driver's pm->suspend_noirq() callback is
485 a low-power state.
487 The low-power state to put the device into is the lowest-power (highest number)
489 state.  Just like in the runtime PM case described above, the mechanism of
490 signaling wakeup is system-dependent and determined by the PCI subsystem, which
496 into low-power states.  However, if one of the driver's suspend callbacks
497 (pm->suspend() or pm->suspend_noirq()) saves the device's standard configuration
499 to signal wakeup and put into a low-power state by the driver (the driver is
509 S1-S3, into the working state (ACPI S0), the phases are:
513 The following PCI bus type's callbacks, respectively, are executed in these
520 The pci_pm_resume_noirq() routine first puts the device into the full-power
525 full-power state and their standard configuration registers have been restored
531 device driver's pm->resume_noirq() callback is executed, if defined, and its
541 its driver's pm->resume() callback is executed, if defined (the callback's
549 The pci_pm_complete() routine only executes the device driver's pm->complete()
566 that correspond to the PCI bus type's callbacks::
576 the device driver's pm->freeze() callback, if defined, instead of pm->suspend(),
577 and it doesn't apply the suspend-related hardware quirks.  It is executed
582 pci_pm_suspend_noirq(), but it calls the device driver's pm->freeze_noirq()
583 routine instead of pm->suspend_noirq().  It also doesn't attempt to prepare the
584 device for signaling wakeup and put it into a low-power state.  Still, it saves
595 using the following PCI bus type's callbacks::
605 configuration registers.  It also executes the device driver's pm->thaw_noirq()
606 callback, if defined, instead of pm->resume_noirq().
609 driver's pm->thaw() callback instead of pm->resume().  It is executed
616 enter the target sleep state (ACPI S4 for ACPI-based systems).  This is done in
623 The PCI subsystem-level callbacks they correspond to::
636 pre-hibernation memory contents to be restored before the pre-hibernation system
639 As described in Documentation/driver-api/pm/devices.rst, the hibernation image
653 Should the restoration of the pre-hibernation memory contents fail, the boot
658 If the pre-hibernation memory contents are restored successfully, which is the
661 it must restore the devices' pre-hibernation functionality, which is done much
675 respectively, but they execute the device driver's pm->restore_noirq() and
676 pm->restore() callbacks, if available.
686 -------------------------------
694 dev_pm_ops structure described in Documentation/driver-api/pm/devices.rst, and
702 containing pointers to power management (PM) callbacks that will be executed by
703 the PCI subsystem's PM routines in various circumstances.  A pointer to the
704 driver's struct dev_pm_ops object has to be assigned to the driver.pm field in
705 its struct pci_driver object.  Once that has happened, the "legacy" PM callbacks
708 The PM callbacks in struct dev_pm_ops are not mandatory and if they are not
718 (when a hibernation image is about to be created), during power-off after
731 in Documentation/driver-api/pm/notifiers.rst).
740 low-power state by the PCI subsystem.  It is not required (in fact it even is
743 put it into a low-power state.  All of these operations can very well be taken
750 low-power state, respectively.  Moreover, if the driver calls pci_save_state(),
756 can be invoked to handle an interrupt from the device, so all suspend-related
765 after device interrupts have been disabled by the PM core.
775 The freeze() callback is hibernation-specific and is executed in two situations,
783 the driver takes the responsibility for putting the device into a low-power
787 or put it into a low-power state.  Still, either it or freeze_noirq() should
793 The freeze_noirq() callback is hibernation-specific.  It is executed during
798 after device interrupts have been disabled by the PM core.
810 The poweroff() callback is hibernation-specific.  It is executed when the system
818 into a low-power state itself instead of allowing the PCI subsystem to do that,
821 into a low-power state, respectively, but it need not save the device's standard
827 The poweroff_noirq() callback is hibernation-specific.  It is executed after
841 PM core has enabled the non-boot CPUs.  The driver's interrupt handler will not
856 device interrupts have been enabled by the PM core.
858 This callback is responsible for restoring the pre-suspend configuration of the
865 The thaw_noirq() callback is hibernation-specific.  It is executed after a
866 system image has been created and the non-boot CPUs have been enabled by the PM
869 after enabling the non-boot CPUs).  The driver's interrupt handler will not be
880 The thaw() callback is hibernation-specific.  It is executed after thaw_noirq()
882 interrupts have been enabled by the PM core.
884 This callback is responsible for restoring the pre-freeze configuration of
890 The restore_noirq() callback is hibernation-specific.  It is executed in the
892 the image kernel and the non-boot CPUs have been enabled by the image kernel's
893 PM core.
898 suspend-resume cycle.
906 The restore() callback is hibernation-specific.  It is executed after
908 after the PM core has enabled device drivers' interrupt handlers to be invoked.
922   - during system resume, after resume() callbacks have been executed for all
924   - during hibernation, before saving the system image, after thaw() callbacks
926   - during system restore, when the system is going back to its pre-hibernation
940 (runtime PM).  It is executed by the PM core's runtime PM framework when the
941 device is about to be suspended (i.e. quiesced and put into a low-power state)
945 put into a low-power state, but it must allow the PCI subsystem to perform all
946 of the PCI-specific actions necessary for suspending the device.
951 The runtime_resume() callback is specific to device runtime PM.  It is executed
952 by the PM core's runtime PM framework when the device is about to be resumed
953 (i.e. put into the full-power state and programmed to process I/O normally) at
957 device after it has been put into the full-power state by the PCI subsystem.
964 The runtime_idle() callback is specific to device runtime PM.  It is executed
965 by the PM core's runtime PM framework whenever it may be desirable to suspend
966 the device according to the PM core's information.  In particular, it is
1001 The PM core allows device drivers to set flags that influence the handling of
1003 including the PCI bus type.  The flags should be set once at the driver probe
1007 The DPM_FLAG_NO_DIRECT_COMPLETE flag prevents the PM core from using the
1008 direct-complete mechanism allowing device suspend/resume callbacks to be skipped
1013 The DPM_FLAG_SMART_PREPARE flag causes the PCI bus type to return a positive
1014 value from pci_pm_prepare() only if the ->prepare callback provided by the
1016 out from using the direct-complete mechanism dynamically (whereas setting
1017 DPM_FLAG_NO_DIRECT_COMPLETE means permanent opt-out).
1019 The DPM_FLAG_SMART_SUSPEND flag tells the PCI bus type that from the driver's
1022 to avoid resuming the device from runtime suspend unless there are PCI-specific
1025 suspend during the "late" phase of the system-wide transition under way.
1027 pci_pm_restore_noirq(), its runtime PM status will be changed to "active" (as it
1032 in suspend after a system-wide transition into the working state.  This flag is
1033 taken into consideration by the PM core along with the power.may_skip_resume
1035 situations.  If the PM core determines that the driver's "noirq" and "early"
1042 ------------------------------------
1045 are responsible for controlling the runtime power management (runtime PM) of
1048 The PCI device runtime PM is optional, but it is recommended that PCI device
1053 To support the PCI runtime PM the driver first needs to implement the
1058 device should really be suspended and return -EAGAIN if that is not the case).
1060 The runtime PM of PCI devices is enabled by default by the PCI core.  PCI
1063 helper function.  In addition to that, the runtime PM usage counter of
1067 If a PCI driver implements the runtime PM callbacks and intends to use the
1068 runtime PM framework provided by the PM core and the PCI subsystem, it needs
1069 to decrement the device's runtime PM usage counter in its probe callback
1071 zero for the device and it will never be runtime-suspended.  The simplest
1076 from its probe routine to make runtime PM work for the device.
1081 unblocking the runtime PM of the device to run via sysfs, so the driver must
1085 should let user space or some platform-specific code do that (user space can
1087 runtime PM of the device correctly as soon as pm_runtime_allow() is called
1091 of the device's runtime PM usage counter at the probe time.  For this reason,
1095 before running the driver's remove callback, the runtime PM of the device
1097 runtime PM helper functions incrementing the device's usage counter are
1100 The runtime PM framework works by processing requests to suspend or resume
1105 queued by the PM core (for example, after processing a request to resume a
1106 device the PM core automatically queues a request to check if the device is
1108 requests for their devices.  For this purpose they should use the runtime PM
1109 helper functions provided by the PM core, discussed in
1114 drivers that use helper functions provided by the PM core for this purpose.
1116 For more information on the runtime PM of devices refer to
1123 PCI Local Bus Specification, Rev. 3.0
1125 PCI Bus Power Management Interface Specification, Rev. 1.2
1131 Documentation/driver-api/pm/devices.rst