Lines Matching refs:the

5 An overview of concepts and the Linux kernel's interfaces related to PCI power
9 This document only covers the aspects of power management specific to PCI
10 devices.  For general description of the kernel's interfaces related to device
28 devices into states in which they draw less power (low-power states) at the
32 completely inactive.  However, when it is necessary to use the device once
33 again, it has to be put back into the "fully functional" state (full-power
34 state).  This may happen when there are some data for the device to handle or
35 as a result of an external event requiring the device to be active, which may
36 be signaled by the device itself.
38 PCI devices may be put into low-power states in two ways, by using the device
39 capabilities introduced by the PCI Bus Power Management Interface Specification,
40 or with the help of platform firmware, such as an ACPI BIOS.  In the first
41 approach, that is referred to as the native PCI power management (native PCI PM)
42 in what follows, the device power state is changed as a result of writing a
44 approach requires the platform firmware to provide special methods that may be
45 used by the kernel to change the device's power state.
47 Devices supporting the native PCI PM usually can generate wakeup signals called
48 Power Management Events (PMEs) to let the kernel know about external events
49 requiring the device to be active.  After receiving a PME the kernel is supposed
50 to put the device that sent it into the full-power state.  However, the PCI Bus
52 delivering the PME from the device to the CPU and the operating system kernel.
53 It is assumed that the platform firmware will perform this task and therefore,
55 prepare the platform firmware for notifying the CPU of the PMEs coming from the
58 In turn, if the methods provided by the platform firmware are used for changing
59 the power state of a device, usually the platform also provides a method for
60 preparing the device to generate wakeup signals.  In that case, however, it
61 often also is necessary to prepare the device for generating PMEs using the
62 native PCI PM mechanism, because the method provided by the platform depends on
65 Thus in many situations both the native and the platform-based power management
66 mechanisms have to be used simultaneously to obtain the desired result.
71 introduced between the PCI 2.1 and PCI 2.2 Specifications.  It defined a
75 The implementation of the PCI PM Spec is optional for conventional PCI devices,
76 but it is mandatory for PCI Express devices.  If a device supports the PCI PM
78 configuration space.  This field is used to describe and control the standard
79 features related to the native PCI power management.
82 (B0-B3).  The higher the number, the less power is drawn by the device or bus
83 in that state.  However, the higher the number, the longer the latency for
84 the device or bus to return to the full-power state (D0 or B0, respectively).
86 There are two variants of the D3 state defined by the specification.  The first
87 one is D3hot, referred to as the software accessible D3, because devices can be
88 programmed to go into it.  The second one, D3cold, is the state that PCI devices
89 are in when the supply voltage (Vcc) is removed from them.  It is not possible
91 interface for putting the bus the device is on into a state in which Vcc is
92 removed from all devices on the bus.
94 PCI bus power management, however, is not supported by the Linux kernel at the
97 Note that every PCI device can be in the full-power state (D0) or in D3cold,
98 regardless of whether or not it implements the PCI PM Spec.  In addition to
99 that, if the PCI PM Spec is implemented by the device, it must support D3hot
100 as well as D0.  The support for the D1 and D2 power states is optional.
102 PCI devices supporting the PCI PM Spec can be programmed to go to any of the
103 supported low-power states (except for D3cold).  While in D1-D3hot the
104 standard configuration registers of the device must be accessible to software
105 (i.e. the device is required to respond to PCI configuration accesses), although
106 its I/O and memory spaces are then disabled.  This allows the device to be
107 programmatically put into D0.  Thus the kernel can switch the device back and
108 forth between D0 and the supported low-power states (except for D3cold) and the
109 possible power state transitions the device can undergo are the following:
123 The transition from D3cold to D0 occurs when the supply voltage is provided to
124 the device (i.e. power is restored).  In that case the device returns to D0 with
125 a full power-on reset sequence and the power-on defaults are restored to the
128 PCI devices supporting the PCI PM Spec can be programmed to generate PMEs
130 of generating PMEs from all supported low-power states.  In particular, the
131 capability of generating PMEs from D3cold is optional and depends on the
132 presence of additional voltage (3.3Vaux) allowing the device to remain
137 The platform firmware support for the power management of PCI devices is
138 system-specific.  However, if the system in question is compliant with the
139 Advanced Configuration and Power Interface (ACPI) Specification, like the
141 management interfaces defined by the ACPI standard.
143 For this purpose the ACPI BIOS provides special functions called "control
144 methods" that may be executed by the kernel to perform specific tasks, such as
146 using special byte-code language called the ACPI Machine Language (AML) and
147 stored in the machine's BIOS.  The kernel loads them from the BIOS and executes
148 them as needed using an AML interpreter that translates the AML byte code into
150 writer can provide the kernel with a means to perform actions depending
151 on the system design in a system-specific fashion.
155 to be defined separately for each device supposed to be handled with the help of
156 the platform.  This means, in particular, that ACPI device control methods can
157 only be used to handle devices that the BIOS writer knew about in advance.  The
161 labeled as D0, D1, D2, and D3 that roughly correspond to the native PCI PM
162 D0-D3 states (although the difference between D3hot and D3cold is not taken
164 set of power resources that have to be enabled for the device to be put into
166 with the help of their own control methods, _ON and _OFF, that have to be
169 To put a device into the ACPI power state Dx (where x is a number between 0 and
170 3 inclusive) the kernel is supposed to (1) enable the power resources required
171 by the device in this state using their _ON control methods and (2) execute the
172 _PSx control method defined for the device.  In addition to that, if the device
174 wakeup signals from that state, the _DSW (or _PSW, replaced with _DSW by ACPI
176 resources that are not required by the device in the target power state and are
178 _OFF control methods).  If the current power state of the device is D3, it can
181 However, quite often the power states of devices are changed during a
182 system-wide transition into a sleep state or back into the working state.  ACPI
183 defines four system sleep states, S1, S2, S3, and S4, and denotes the system
184 working state as S0.  In general, the target system sleep (or working) state
185 determines the highest power (lowest number) state the device can be put
186 into and the kernel is supposed to obtain this information by executing the
188 If the device is required to wake up the system from the target sleep state, the
189 lowest power (highest number) state it can be put into is also determined by the
190 target state of the system.  The kernel is then supposed to use the device's
191 _SxW control method to obtain the number of that state.  It also is supposed to
192 use the device's _PRW control method to learn which power resources need to be
193 enabled for the device to be able to generate wakeup signals.
198 a result of the execution of the _DSW (or _PSW) ACPI control method before
199 putting the device into a low-power state, have to be caught and handled as
200 appropriate.  If they are sent while the system is in the working state
201 (ACPI S0), they should be translated into interrupts so that the kernel can
202 put the devices generating them into the full-power state and take care of the
203 events that triggered them.  In turn, if they are sent while the system is
204 sleeping, they should cause the system's core logic to trigger wakeup.
208 from the system core logic generated in response to various events that need to
211 capable of signaling wakeup.  The information on the connections between GPEs
212 and event sources is recorded in the system's ACPI BIOS from where it can be
213 read by the kernel.
215 If a PCI device known to the system's ACPI BIOS signals wakeup, the GPE
217 bridges may also be triggered in response to a wakeup signal from one of the
218 devices below the bridge (this also is the case for root bridges) and, for
219 example, native PCI PMEs from devices unknown to the system's ACPI BIOS may be
222 A GPE may be triggered when the system is sleeping (i.e. when it is in one of
223 the ACPI S1-S4 states), in which case system wakeup is started by its core logic
224 (the device that was the source of the signal causing the system wakeup to occur
228 Usually, however, GPEs are also triggered when the system is in the working
229 state (ACPI S0) and in that case the system's core logic generates a System
230 Control Interrupt (SCI) to notify the kernel of the event.  Then, the SCI
231 handler identifies the GPE that caused the interrupt to be generated which,
232 in turn, allows the kernel to identify the source of the event (that may be
233 a PCI device signaling wakeup).  The GPEs used for notifying the kernel of
234 events occurring while the system is in the working state are referred to as
239 for PCI Express devices.  Namely, the PCI Express Base Specification introduced
243 may be routed directly to the system's core logic), but for PCI Express devices
244 they are in-band messages that have to pass through the PCI Express hierarchy,
245 including the root port on the path from the device to the Root Complex.  Thus
247 interrupt whenever it receives a PME message from one of the devices below it.
248 The PCI Express Requester ID of the device that sent the PME message is then
249 recorded in one of the root port's configuration registers from where it may be
250 read by the interrupt handler allowing the device to be identified.  [PME
251 messages sent by PCI Express endpoints integrated with the Root Complex don't
255 In principle the native PCI Express PME signaling may also be used on ACPI-based
256 systems along with the GPEs, but to use it the kernel has to ask the system's
258 BIOS, however, is not required to allow the kernel to control these registers
259 and if it doesn't do that, the kernel must not modify their contents.  Of course
260 the native PCI Express PME signaling cannot be used by the kernel in that case.
268 The PCI Subsystem participates in the power management of PCI devices in a
270 the device power management core (PM core) and PCI device drivers.
271 Specifically, the pm field of the PCI subsystem's struct bus_type object,
295 These callbacks are executed by the PM core in various situations related to
307 	int		pm_cap;		/* PM capability offset in the
320 They also indirectly use some fields of the struct device that is embedded in
326 prepare the device for power management and initialize the fields of struct
330 The first of these functions checks if the device supports native PCI PM
331 and if that's the case the offset of its power management capability structure
332 in the configuration space is stored in the pm_cap field of the device's struct
333 pci_dev object.  Next, the function checks which PCI low-power states are
334 supported by the device and from which low-power states the device can generate
335 native PCI PMEs.  The power management fields of the device's struct pci_dev and
336 the struct device embedded in it are updated accordingly and the generation of
337 PMEs by the device is disabled.
339 The second function checks if the device can be prepared to signal wakeup with
340 the help of the platform firmware, such as the ACPI BIOS.  If that is the case,
341 the function updates the wakeup fields in struct device embedded in the
342 device's struct pci_dev and uses the firmware-provided method to prevent the
345 At this point the device is ready for power management.  For driverless devices,
347 during system-wide transitions to a sleep state and back to the working state.
351 The PCI subsystem plays a vital role in the runtime power management of PCI
352 devices.  For this purpose it uses the general runtime power management
360 that are executed by the core runtime PM routines.  It also implements the
362 in low-power states, which at the time of this writing works for both the native
363 PCI Express PME signaling and the ACPI GPE-based wakeup signaling described in
366 First, a PCI device is put into a low-power state, or suspended, with the help
368 pci_pm_runtime_suspend() to do the actual job.  For this to work, the device's
370 run by pci_pm_runtime_suspend() as the first action.  If the driver's callback
371 returns successfully, the device's standard configuration registers are saved,
372 the device is prepared to generate wakeup signals and, finally, it is put into
373 the target low-power state.
375 The low-power state to put the device into is the lowest-power (highest number)
377 system-dependent and is determined by the PCI subsystem on the basis of the
378 reported capabilities of the device and the platform firmware.  To prepare the
379 device for signaling wakeup and put it into the selected low-power state, the
380 PCI subsystem can use the platform firmware as well as the device's native PCI
383 It is expected that the device driver's pm->runtime_suspend() callback will
384 not attempt to prepare the device for signaling wakeup or to put it into a
385 low-power state.  The driver ought to leave these tasks to the PCI subsystem
386 that has all of the information necessary to perform them.
388 A suspended device is brought back into the "active" state, or resumed,
389 with the help of pm_request_resume() or pm_runtime_resume() which both call
390 pci_pm_runtime_resume() for PCI devices.  Again, this only works if the device's
392 the driver's callback is executed, pci_pm_runtime_resume() brings the device
393 back into the full-power state, prevents it from signaling wakeup while in that
394 state and restores its standard configuration registers.  Thus the driver's
395 callback need not worry about the PCI-specific aspects of the device resume.
398 situations.  First, it may be called at the request of the device's driver, for
400 as a result of a wakeup signal from the device itself (this sometimes is
401 referred to as "remote wakeup").  Of course, for this purpose the wakeup signal
402 is handled in one of the ways described in Section 1 and finally converted into
403 a notification for the PCI subsystem after the source device has been
407 and pm_request_idle(), executes the device driver's pm->runtime_idle()
409 present at all), suspends the device with the help of pm_runtime_suspend().
410 Sometimes pci_pm_runtime_idle() is called automatically by the PM core (for
411 example, it is called right after the device has just been resumed), in which
412 cases it is expected to suspend the device if that makes sense.  Usually,
413 however, the PCI subsystem doesn't really know if the device really can be
414 suspended, so it lets the device's driver decide by running its
421 in a specific way and the PM core executes subsystem-level power management
423 involves executing the same subsystem-level callback for every device belonging
424 to the given subsystem before the next phase begins.  These phases always run
429 When the system is going into a sleep state in which the contents of memory will
430 be preserved, such as one of the ACPI sleep states S1-S3, the phases are:
440 The pci_pm_prepare() routine first puts the device into the "fully functional"
441 state with the help of pm_runtime_resume().  Then, it executes the device
442 driver's pm->prepare() callback if defined (i.e. if the driver's struct
443 dev_pm_ops object is present and the prepare pointer in that object is valid).
445 The pci_pm_suspend() routine first checks if the device's driver implements
446 legacy PCI suspend routines (see Section 3), in which case the driver's legacy
448 the device's driver doesn't provide a struct dev_pm_ops object (containing
449 pointers to the driver's callbacks), pci_pm_default_suspend() is called, which
450 simply turns off the device's bus master capability and runs
451 pcibios_disable_device() to disable it, unless the device is a bridge (PCI
452 bridges are ignored by this routine).  Next, the device driver's pm->suspend()
455 to the device if necessary.
457 Note that the suspend phase is carried out asynchronously for PCI devices, so
458 the pci_pm_suspend() callback may be executed in parallel for any pair of PCI
459 devices that don't depend on each other in a known way (i.e. none of the paths
460 in the device tree from the root bridge to a leaf device contains both of them).
463 been called, which means that the device driver's interrupt handler won't be
464 invoked while this routine is running.  It first checks if the device's driver
465 implements legacy PCI suspends routines (Section 3), in which case the legacy
466 late suspend routine is called and its result is returned (the standard
467 configuration registers of the device are saved if the driver's callback hasn't
468 done that).  Second, if the device driver's struct dev_pm_ops object is not
469 present, the device's standard configuration registers are saved and the routine
470 returns success.  Otherwise the device driver's pm->suspend_noirq() callback is
471 executed, if present, and its result is returned if it fails.  Next, if the
472 device's standard configuration registers haven't been saved yet (one of the
474 saves them, prepares the device to signal wakeup (if necessary) and puts it into
477 The low-power state to put the device into is the lowest-power (highest number)
478 state from which it can signal wakeup while the system is in the target sleep
479 state.  Just like in the runtime PM case described above, the mechanism of
480 signaling wakeup is system-dependent and determined by the PCI subsystem, which
481 is also responsible for preparing the device to signal wakeup from the system's
486 into low-power states.  However, if one of the driver's suspend callbacks
487 (pm->suspend() or pm->suspend_noirq()) saves the device's standard configuration
488 registers, pci_pm_suspend_noirq() will assume that the device has been prepared
489 to signal wakeup and put into a low-power state by the driver (the driver is
490 then assumed to have used the helper functions provided by the PCI subsystem for
492 rare cases doing that in the driver may be the optimum approach.
496 When the system is undergoing a transition from a sleep state in which the
497 contents of memory have been preserved, such as one of the ACPI sleep states
498 S1-S3, into the working state (ACPI S0), the phases are:
509 The pci_pm_resume_noirq() routine first puts the device into the full-power
511 hardware quirks related to the device, if necessary.  This is done
512 unconditionally, regardless of whether or not the device's driver implements
513 legacy PCI power management callbacks (this way all PCI devices are in the
515 when their interrupt handlers are invoked for the first time during resume,
516 which allows the kernel to avoid problems with the handling of shared interrupts
518 callbacks (see Section 3) are implemented by the device's driver, the legacy
519 early resume callback is executed and its result is returned.  Otherwise, the
523 The pci_pm_resume() routine first checks if the device's standard configuration
524 registers have been restored and restores them if that's not the case (this
525 only is necessary in the error path during a failing suspend).  Next, resume
526 hardware quirks related to the device are applied, if necessary, and if the
528 Section 3), the driver's legacy resume callback is executed and its result is
529 returned.  Otherwise, the device's wakeup signaling mechanisms are blocked and
530 its driver's pm->resume() callback is executed, if defined (the callback's
533 The resume phase is carried out asynchronously for PCI devices, like the
535 on each other in a known way, the pci_pm_resume() routine may be executed for
536 the both of them in parallel.
538 The pci_pm_complete() routine only executes the device driver's pm->complete()
549 the time of this writing the image creation requires at least 50% of system RAM
550 to be free) in the following three phases:
554 that correspond to the PCI bus type's callbacks:
560 This means that the prepare phase is exactly the same as for system suspend.
564 the device driver's pm->freeze() callback, if defined, instead of pm->suspend(),
565 and it doesn't apply the suspend-related hardware quirks.  It is executed
570 pci_pm_suspend_noirq(), but it calls the device driver's pm->freeze_noirq()
571 routine instead of pm->suspend_noirq().  It also doesn't attempt to prepare the
573 the device's standard configuration registers if they haven't been saved by one
574 of the driver's callbacks.
576 Once the image has been created, it has to be saved.  However, at this point all
578 I/O is obviously necessary for the image saving.  Thus they have to be brought
579 back to the fully functional state and this is done in the following phases:
583 using the following PCI bus type's callbacks:
592 but it doesn't put the device into the full power state and doesn't attempt to
593 restore its standard configuration registers.  It also executes the device
596 The pci_pm_thaw() routine is similar to pci_pm_resume(), but it runs the device
601 The complete phase it the same as for system resume.
603 After saving the image, devices need to be powered down before the system can
604 enter the target sleep state (ACPI S4 for ACPI-based systems).  This is done in
609 where the prepare phase is exactly the same as for system suspend.  The other
610 two phases are analogous to the suspend and suspend_noirq phases, respectively.
617 although they don't attempt to save the device's standard configuration
622 System restore requires a hibernation image to be loaded into memory and the
623 pre-hibernation memory contents to be restored before the pre-hibernation system
626 As described in Documentation/power/devices.txt, the hibernation image is loaded
627 into memory by a fresh instance of the kernel, called the boot kernel, which in
628 turn is loaded and run by a boot loader in the usual way.  After the boot kernel
629 has loaded the image, it needs to replace its own code and data with the code
630 and data of the "hibernated" kernel stored within the image, called the image
632 the image during hibernation, in the
636 phases described above.  However, the devices affected by these phases are only
637 those having drivers in the boot kernel; other devices will still be in whatever
638 state the boot loader left them.
640 Should the restoration of the pre-hibernation memory contents fail, the boot
641 kernel would go through the "thawing" procedure described above, using the
642 thaw_noirq, thaw, and complete phases (that will only affect the devices having
643 drivers in the boot kernel), and then continue running normally.
645 If the pre-hibernation memory contents are restored successfully, which is the
646 usual situation, control is passed to the image kernel, which then becomes
647 responsible for bringing the system back to the working state.  To achieve this,
648 it must restore the devices' pre-hibernation functionality, which is done much
649 like waking up from the memory sleep state, although it involves different
654 The first two of these are analogous to the resume_noirq and resume phases
655 described above, respectively, and correspond to the following PCI subsystem
662 respectively, but they execute the device driver's pm->restore_noirq() and
665 The complete phase is carried out in exactly the same way as during system
675 executed by the PCI subsystem's power management routines described above and by
676 controlling the runtime power management of their devices.
678 At the time of this writing there are two ways to define power management
679 callbacks for a PCI device driver, the recommended one, based on using a
680 dev_pm_ops structure described in Documentation/power/devices.txt, and the
681 "legacy" one, in which the .suspend(), .suspend_late(), .resume_early(), and
685 document (refer to the source code to learn more about it).
689 the PCI subsystem's PM routines in various circumstances.  A pointer to the
690 driver's struct dev_pm_ops object has to be assigned to the driver.pm field in
691 its struct pci_driver object.  Once that has happened, the "legacy" PM callbacks
695 defined (i.e. the respective fields of struct dev_pm_ops are unset) the PCI
696 subsystem will handle the device in a simplified default manner.  If they are
697 defined, though, they are expected to behave as described in the following
707 This callback is only necessary if the driver's device has children that in
708 general may be registered at any time.  In that case the role of the prepare()
709 callback is to prevent new children of the device from being registered until
710 one of the resume_noirq(), thaw_noirq(), or restore_noirq() callbacks is run.
712 In addition to that the prepare() callback may carry out some operations
713 preparing the device to be suspended, although it should not allocate memory
714 (if additional memory is required to suspend the device, it has to be
721 callbacks have been executed for all devices in the system.
723 This callback is expected to quiesce the device and prepare it to be put into a
724 low-power state by the PCI subsystem.  It is not required (in fact it even is
725 not recommended) that a PCI driver's suspend() callback save the standard
726 configuration registers of the device, prepare it for waking up the system, or
728 care of by the PCI subsystem, without the driver's participation.
732 pci_set_power_state() should be used to save the device's standard configuration
734 low-power state, respectively.  Moreover, if the driver calls pci_save_state(),
735 the PCI subsystem will not execute either pci_prepare_to_sleep(), or
736 pci_set_power_state() for its device, so the driver is then responsible for
737 handling the device as appropriate.
739 While the suspend() callback is being executed, the driver's interrupt handler
740 can be invoked to handle an interrupt from the device, so all suspend-related
741 operations relying on the driver's ability to handle interrupts should be
747 suspend() callbacks have been executed for all devices in the system and
748 after device interrupts have been disabled by the PM core.
750 The difference between suspend_noirq() and suspend() is that the driver's
759 in preparation for the creation of a system image, and during restore,
760 after a system image has been loaded into memory from persistent storage and the
763 The role of this callback is analogous to the role of the suspend() callback
764 described above.  In fact, they only need to be different in the rare cases when
765 the driver takes the responsibility for putting the device into a low-power
768 In that cases the freeze() callback should not prepare the device system wakeup
770 save the device's standard configuration registers using pci_save_state().
776 devices in preparation for the creation of a system image, and during restore,
779 after device interrupts have been disabled by the PM core.
781 The role of this callback is analogous to the role of the suspend_noirq()
785 The difference between freeze_noirq() and freeze() is analogous to the
790 The poweroff() callback is hibernation-specific.  It is executed when the system
795 The role of this callback is analogous to the role of the suspend() and freeze()
796 callbacks described above, although it does not need to save the contents of
797 the device's registers.  In particular, if the driver wants to put the device
798 into a low-power state itself instead of allowing the PCI subsystem to do that,
799 the poweroff() callback should use pci_prepare_to_sleep() and
800 pci_set_power_state() to prepare the device for system wakeup and to put it
801 into a low-power state, respectively, but it need not save the device's standard
807 poweroff() callbacks have been executed for all devices in the system.
809 The role of this callback is analogous to the role of the suspend_noirq() and
810 freeze_noirq() callbacks described above, but it does not need to save the
811 contents of the device's registers.
813 The difference between poweroff_noirq() and poweroff() is analogous to the
818 The resume_noirq() callback is only executed during system resume, after the
819 PM core has enabled the non-boot CPUs.  The driver's interrupt handler will not
821 operations that might race with the interrupt handler.
823 Since the PCI subsystem unconditionally puts all devices into the full power
824 state in the resume_noirq phase of system resume and restores their standard
832 resume_noirq() callbacks have been executed for all devices in the system and
833 device interrupts have been enabled by the PM core.
835 This callback is responsible for restoring the pre-suspend configuration of the
836 device and bringing it back to the fully functional state.  The device should be
842 system image has been created and the non-boot CPUs have been enabled by the PM
843 core, in the thaw_noirq phase of hibernation.  It also may be executed if the
845 after enabling the non-boot CPUs).  The driver's interrupt handler will not be
848 The role of this callback is analogous to the role of resume_noirq().  The
850 freeze() and freeze_noirq(), so in general it does not need to modify the
851 contents of the device's registers.
856 callbacks have been executed for all devices in the system and after device
857 interrupts have been enabled by the PM core.
859 This callback is responsible for restoring the pre-freeze configuration of
860 the device, so that it will work in a usual way after thaw() has returned.
864 The restore_noirq() callback is hibernation-specific.  It is executed in the
865 restore_noirq phase of hibernation, when the boot kernel has passed control to
866 the image kernel and the non-boot CPUs have been enabled by the image kernel's
869 This callback is analogous to resume_noirq() with the exception that it cannot
870 make any assumption on the previous state of the device, even if the BIOS (or
871 generally the platform firmware) is known to preserve that state over a
874 For the vast majority of PCI device drivers there is no difference between
880 restore_noirq() callbacks have been executed for all devices in the system and
881 after the PM core has enabled device drivers' interrupt handlers to be invoked.
884 to resume_noirq().  Consequently, the difference between restore_noirq() and
885 restore() is analogous to the difference between resume_noirq() and resume().
887 For the vast majority of PCI device drivers there is no difference between
892 The complete() callback is executed in the following situations:
895   - during hibernation, before saving the system image, after thaw() callbacks
897   - during system restore, when the system is going back to its pre-hibernation
899 It also may be executed if the loading of a hibernation image into memory fails
901 devices that have drivers in the boot kernel).
903 This callback is entirely optional, although it may be necessary if the
909 (runtime PM).  It is executed by the PM core's runtime PM framework when the
913 This callback is responsible for freezing the device and preparing it to be
914 put into a low-power state, but it must allow the PCI subsystem to perform all
915 of the PCI-specific actions necessary for suspending the device.
920 by the PM core's runtime PM framework when the device is about to be resumed
921 (i.e. put into the full-power state and programmed to process I/O normally) at
924 This callback is responsible for restoring the normal functionality of the
925 device after it has been put into the full-power state by the PCI subsystem.
926 The device is expected to be able to process I/O in the usual way after
932 by the PM core's runtime PM framework whenever it may be desirable to suspend
933 the device according to the PM core's information.  In particular, it is
934 automatically executed right after runtime_resume() has returned in case the
935 resume of the device has happened as a result of a spurious event.
937 This callback is optional, but if it is not implemented or if it returns 0, the
938 PCI subsystem will call pm_runtime_suspend() for the device, which in turn will
939 cause the driver's runtime_suspend() callback to be executed.
943 Although in principle each of the callbacks described in the previous
945 point two or more members of struct dev_pm_ops to the same routine.  There are
949 suspend routine pointed to by the .suspend(), .freeze(), and .poweroff()
950 members and one resume routine pointed to by the .resume(), .thaw(), and
955 additionally sets the .runtime_resume() pointer to the same value as
956 .resume() (and .thaw(), and .restore()) and the .runtime_suspend() pointer to
957 the same value as .suspend() (and .freeze() and .poweroff()).
960 dev_pm_ops to indicate that one suspend routine is to be pointed to by the
962 be pointed to by the .resume(), .thaw(), and .restore() members.
967 are responsible for controlling the runtime power management (runtime PM) of
971 drivers implement it at least in the cases where there is a reliable way of
972 verifying that the device is not used (like when the network cable is detached
975 To support the PCI runtime PM the driver first needs to implement the
977 the runtime_idle() callback to prevent the device from being suspended again
978 every time right after the runtime_resume() callback has returned
979 (alternatively, the runtime_suspend() callback will have to check if the
980 device should really be suspended and return -EAGAIN if that is not the case).
982 The runtime PM of PCI devices is enabled by default by the PCI core.  PCI
984 However, it is blocked by pci_pm_init() that runs the pm_runtime_forbid()
985 helper function.  In addition to that, the runtime PM usage counter of
986 each PCI device is incremented by local_pci_probe() before executing the
987 probe callback provided by the device's driver.
989 If a PCI driver implements the runtime PM callbacks and intends to use the
990 runtime PM framework provided by the PM core and the PCI subsystem, it needs
991 to decrement the device's runtime PM usage counter in its probe callback
992 function.  If it doesn't do that, the counter will always be different from
993 zero for the device and it will never be runtime-suspended.  The simplest
994 way to do that is by calling pm_runtime_put_noidle(), but if the driver
997 just needs to call a function that decrements the devices usage counter
998 from its probe routine to make runtime PM work for the device.
1000 It is important to remember that the driver's runtime_suspend() callback
1001 may be executed right after the usage counter has been decremented, because
1002 user space may already have cuased the pm_runtime_allow() helper function
1003 unblocking the runtime PM of the device to run via sysfs, so the driver must
1008 do it via sysfs as stated above), but it must be prepared to handle the
1009 runtime PM of the device correctly as soon as pm_runtime_allow() is called
1010 (which may happen at any time, even before the driver is loaded).
1012 When the driver's remove callback runs, it has to balance the decrementation
1013 of the device's runtime PM usage counter at the probe time.  For this reason,
1014 if it has decremented the counter in its probe callback, it must run
1015 pm_runtime_get_noresume() in its remove callback.  [Since the core carries
1016 out a runtime resume of the device and bumps up the device's usage counter
1017 before running the driver's remove callback, the runtime PM of the device
1018 is effectively disabled for the duration of the remove execution and all
1019 runtime PM helper functions incrementing the device's usage counter are
1025 by work items put into the power management workqueue, pm_wq.  Although there
1027 queued by the PM core (for example, after processing a request to resume a
1028 device the PM core automatically queues a request to check if the device is
1030 requests for their devices.  For this purpose they should use the runtime PM
1031 helper functions provided by the PM core, discussed in
1035 request into pm_wq.  In the majority of cases this also is done by their
1036 drivers that use helper functions provided by the PM core for this purpose.
1038 For more information on the runtime PM of devices refer to