Lines Matching refs:to

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
11 power management refer to Documentation/power/devices.txt and
27 In general, power management is a feature allowing one to save energy by putting
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
41 approach, that is referred to as the native PCI power management (native PCI PM)
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.
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.
54 even though a PCI device is set up to generate PMEs, it also may be necessary to
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
66 mechanisms have to be used simultaneously to obtain the desired result.
72 standard interface for performing various operations related to power
78 configuration space.  This field is used to describe and control the standard
79 features related to the native PCI power management.
84 the device or bus to return to the full-power state (D0 or B0, respectively).
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
90 to program a PCI device to go into D3cold, although there may be a programmable
98 regardless of whether or not it implements the PCI PM Spec.  In addition to
102 PCI devices supporting the PCI PM Spec can be programmed to go to any of 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
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
129 while in a low-power state (D1-D3), but they are not required to be capable
132 presence of additional voltage (3.3Vaux) allowing the device to remain
133 sufficiently active to generate a wakeup signal.
140 majority of x86-based systems, it is supposed to implement device power
144 methods" that may be executed by the kernel to perform specific tasks, such as
150 writer can provide the kernel with a means to perform actions depending
155 to be defined separately for each device supposed to be handled with the help of
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
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
170 3 inclusive) the kernel is supposed to (1) enable the power resources required
172 _PSx control method defined for the device.  In addition to that, if the device
173 is going to be put into a low-power state (D1-D3) and is supposed to generate
175 3.0) control method defined for it has to be executed before _PSx.  Power
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
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.
199 putting the device into a low-power state, have to be caught and handled as
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
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
219 example, native PCI PMEs from devices unknown to the system's ACPI BIOS may be
224 (the device that was the source of the signal causing the system wakeup to occur
225 may be identified later).  The GPEs used in such situations are referred to as
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
234 events occurring while the system is in the working state are referred to as
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
246 it was possible to introduce a mechanism by which a root port generates an
250 read by the interrupt handler allowing the device to be identified.  [PME
253 (if there is one) to generate interrupts.]
256 systems along with the GPEs, but to use it the kernel has to ask the system's
257 ACPI BIOS to release control of root port configuration registers.  The ACPI
258 BIOS, however, is not required to allow the kernel to control these registers
272 pci_bus_type, points to a struct dev_pm_ops object, pci_dev_pm_ops, containing
273 pointers to several device power management callbacks:
295 These callbacks are executed by the PM core in various situations related to
325 The PCI subsystem's first task related to device power management is to
339 The second function checks if the device can be prepared to signal wakeup with
342 device's struct pci_dev and uses the firmware-provided method to prevent the
346 however, this functionality is limited to a few basic operations carried out
347 during system-wide transitions to a sleep state and back to the working state.
368 pci_pm_runtime_suspend() to do the actual job.  For this to work, the device's
369 driver has to provide a pm->runtime_suspend() callback (see below), which is
372 the device is prepared to generate wakeup signals and, finally, it is put into
375 The low-power state to put the device into is the lowest-power (highest number)
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.
399 example if there are some data for it to process.  Second, it may be called
401 referred to as "remote wakeup").  Of course, for this purpose the wakeup signal
412 cases it is expected to suspend the device if that makes sense.  Usually,
420 Documentation/power/devices.txt.  Each of them requires devices to be handled
424 to the given subsystem before the next phase begins.  These phases always run
449 pointers to the driver's callbacks), pci_pm_default_suspend() is called, which
451 pcibios_disable_device() to disable it, unless the device is a bridge (PCI
454 Finally, pci_fixup_device() is called to apply hardware suspend quirks related
455 to the device if necessary.
460 in the device tree from the root bridge to a leaf device contains both of them).
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)
481 is also responsible for preparing the device to signal wakeup from the system's
485 generally not expected to prepare devices for signaling wakeup or to put them
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
491 this purpose).  PCI device drivers are not encouraged to do that, but in some
511 hardware quirks related to the device, if necessary.  This is done
516 which allows the kernel to avoid problems with the handling of shared interrupts
526 hardware quirks related to the device are applied, if necessary, and if the
544 a system image to be created and written into a persistent storage medium.  The
550 to be free) in the following three phases:
554 that correspond to the PCI bus type's callbacks:
563 The pci_pm_freeze() routine is quite similar to pci_pm_suspend(), but it runs
569 The pci_pm_freeze_noirq() routine, in turn, is similar to
571 routine instead of pm->suspend_noirq().  It also doesn't attempt to prepare the
576 Once the image has been created, it has to be saved.  However, at this point all
577 devices are frozen and they cannot handle I/O, while their ability to handle
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:
591 The first of them, pci_pm_thaw_noirq(), is analogous to pci_pm_resume_noirq(),
592 but it doesn't put the device into the full power state and doesn't attempt to
596 The pci_pm_thaw() routine is similar to pci_pm_resume(), but it runs the device
603 After saving the image, devices need to be powered down before the system can
610 two phases are analogous to the suspend and suspend_noirq phases, respectively.
611 The PCI subsystem-level callbacks they correspond to
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
629 has loaded the image, it needs to replace its own code and data with the code
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,
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
674 PCI device drivers participate in power management by providing callbacks to be
678 At the time of this writing there are two ways to define power management
683 however, doesn't allow one to define runtime power management callbacks and is
685 document (refer to the source code to learn more about it).
688 containing pointers to power management (PM) callbacks that will be executed by
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
697 defined, though, they are expected to behave as described in the following
703 (when a hibernation image is about to be created), during power-off after
709 callback is to prevent new children of the device from being registered until
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
723 This callback is expected to quiesce the device and prepare it to be put into a
730 However, in some rare case it is convenient to carry out these operations in
732 pci_set_power_state() should be used to save the device's standard configuration
733 registers, to prepare it for system wakeup (if necessary), and to put it into a
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
752 suspend_noirq() can carry out operations that would cause race conditions to
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
781 The role of this callback is analogous to the role of the suspend_noirq()
782 callback described above and it very rarely is necessary to define
785 The difference between freeze_noirq() and freeze() is analogous to the
791 is about to be powered off after saving a hibernation image to a persistent
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,
800 pci_set_power_state() to prepare the device for system wakeup and to put it
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
813 The difference between poweroff_noirq() and poweroff() is analogous to the
826 it should only be used for performing operations that would lead to race
836 device and bringing it back to the fully functional state.  The device should be
837 able to process I/O in a usual way after resume() has returned.
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
865 restore_noirq phase of hibernation, when the boot kernel has passed control to
869 This callback is analogous to resume_noirq() with the exception that it cannot
871 generally the platform firmware) is known to preserve that state over a
881 after the PM core has enabled device drivers' interrupt handlers to be invoked.
883 This callback is analogous to resume(), just like restore_noirq() is analogous
884 to resume_noirq().  Consequently, the difference between restore_noirq() and
885 restore() is analogous to the difference between resume_noirq() and resume().
897   - during system restore, when the system is going back to its pre-hibernation
904 prepare() callback performs operations that need to be reversed.
908 The runtime_suspend() callback is specific to device runtime power management
910 device is about to be suspended (i.e. quiesced and put into a low-power state)
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
919 The runtime_resume() callback is specific to device runtime PM.  It is executed
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
926 The device is expected to be able to process I/O in the usual way after
931 The runtime_idle() callback is specific to device runtime PM.  It is executed
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
939 cause the driver's runtime_suspend() callback to be executed.
941 3.1.18. Pointing Multiple Callback Pointers to One Routine
944 subsections can be defined as a separate function, it often is convenient to
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
954 The UNIVERSAL_DEV_PM_OPS macro is similar to SIMPLE_DEV_PM_OPS, but it
955 additionally sets the .runtime_resume() pointer to the same value as
956 .resume() (and .thaw(), and .restore()) and the .runtime_suspend() pointer to
960 dev_pm_ops to indicate that one suspend routine is to be pointed to by the
961 .suspend(), .freeze(), and .poweroff() members and one resume routine is to
962 be pointed to by the .resume(), .thaw(), and .restore() members.
966 In addition to providing device power management callbacks PCI device drivers
973 from an Ethernet adapter or there are no devices attached to a USB controller).
975 To support the PCI runtime PM the driver first needs to implement the
976 runtime_suspend() and runtime_resume() callbacks.  It also may need to implement
977 the runtime_idle() callback to prevent the device from being suspended again
979 (alternatively, the runtime_suspend() callback will have to check if the
983 device drivers do not need to enable it and should not attempt to do so.
985 helper function.  In addition to that, the runtime PM usage counter of
989 If a PCI driver implements the runtime PM callbacks and intends to use the
991 to decrement the device's runtime PM usage counter in its probe callback
994 way to do that is by calling pm_runtime_put_noidle(), but if the driver
995 wants to schedule an autosuspend right away, for example, it may call
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
1003 unblocking the runtime PM of the device to run via sysfs, so the driver must
1004 be prepared to cope with that.
1008 do it via sysfs as stated above), but it must be prepared to handle the
1012 When the driver's remove callback runs, it has to balance the decrementation
1020 then effectively equivalent to pm_runtime_get_noresume().]
1022 The runtime PM framework works by processing requests to suspend or resume
1023 devices, or to check if they are idle (in which cases it is reasonable to
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
1038 For more information on the runtime PM of devices refer to