Lines Matching +full:system +full:- +full:bus
15 Copyright (c) 2010-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc.
20 management (PM) code is also driver-specific. Most drivers will do very
24 This writeup gives an overview of how drivers interact with system-wide
27 background for the domain-specific work you'd do with any specific driver.
33 Drivers will use one or both of these models to put devices into low-power
36 System Sleep model:
38 Drivers can enter low-power states as part of entering system-wide
39 low-power states like "suspend" (also known as "suspend-to-RAM"), or
41 "suspend-to-disk").
43 This is something that device, bus, and class drivers collaborate on
44 by implementing various role-specific suspend and resume methods to
48 Some drivers can manage hardware wakeup events, which make the system
49 leave the low-power state. This feature may be enabled or disabled
53 whole system enter low-power states more often.
57 Devices may also be put into low-power states while the system is
61 devices have been suspended). Moreover, depending on the bus type the
62 device is on, it may be necessary to carry out some bus-specific
64 states at run time may require special handling during system-wide power
68 appropriate subsystem (bus type, device type or device class) driver and
69 the PM core are involved in runtime power management. As in the system
71 various role-specific suspend and resume methods, so that the hardware
74 There's not a lot to be said about those low-power states except that they are
75 very system-specific, and often device-specific. Also, that if enough devices
76 have been put into low-power states (at runtime), the effect may be very similar
77 to entering some system-wide low-power state (system sleep) ... and that
78 synergies exist, so that several drivers using runtime PM might put the system
83 drivers are no longer accepted. A given bus or platform may have different
87 network wake-on-LAN packets, keyboard or mouse activity, and media insertion
90 Interfaces for Entering System Sleep States
93 There are programming interfaces provided for subsystems (bus type, device type,
96 system sleep and runtime power management.
100 ----------------------------------
107 management while the remaining ones are used during system-wide power
112 |struct dev_pm_ops| objects and it is suitable only for implementing system
118 Subsystem-Level Methods
119 -----------------------
128 bus types) don't provide all power management methods.
130 Bus drivers implement these methods as appropriate for the hardware and the
132 write subsystem-level drivers; most driver code is a "device driver" that builds
133 on top of bus-specific framework code.
136 they are called in phases for every device, respecting the parent-child
141 -------------------------------------------
144 of system wakeup events (hardware signals that can force the system out of a
145 sleep state). These fields are initialized by bus or device driver code using
154 its system wakeup mechanism and for notifying the PM core of system wakeup
155 events signaled by the device. This object is only present for wakeup-capable
161 whether or not a wakeup-capable device should issue wakeup events is a policy
165 to signal system wakeup. This file is only present if the
172 Ethernet adapters whose WoL (wake-on-LAN) feature has been set up with ethtool.
174 requests on their own but merely forward wakeup requests from one bus to another
180 like the PCI bus type code, to see whether or not to enable the devices' wakeup
183 during a system sleep transition. Device drivers, however, are not expected to
186 It ought to be noted that system wakeup is conceptually different from "remote
189 low-power states to trigger specific interrupts to signal conditions in which
190 they should be put into the full-power state. Those interrupts may or may not
191 be used to signal system wakeup events, depending on the hardware design. On
192 some systems it is impossible to trigger them from system sleep states. In any
198 --------------------------------------------
202 by the bus type (or generally subsystem) code using :c:func:`pm_runtime_allow()`
209 runtime power-managed by its driver. Writing "on" calls
211 power if it was in a low-power state, and preventing the
212 device from being runtime power-managed. User space can check the current value
216 system-wide power transitions. In particular, the device can (and in the
217 majority of cases should and will) be put into a low-power state during a
218 system-wide transition to a sleep state even though its :c:member:`runtime_auto`
225 Calling Drivers to Enter and Leave System Sleep States
228 When the system goes into a sleep state, each device's driver is asked to
230 system state. That's usually some version of "off", but the details are
231 system-specific. Also, wakeup-enabled devices will usually stay partly
232 functional in order to wake the system.
234 When the system leaves that low-power state, the device's driver is asked to
236 always go together, and both are multi-phase operations.
243 More power-aware drivers might prepare the devices for triggering system wakeup
248 ------------------------
252 walked in a bottom-up order to suspend devices. A top-down order is
259 The policy is that the device hierarchy should match hardware bus topology.
260 [Or at least the control bus, for devices which use multiple busses.]
268 System Power Management Phases
269 ------------------------------
271 Suspending or resuming the system is done in several phases. Different phases
272 are used for suspend-to-idle, shallow (standby), and deep ("suspend-to-RAM")
273 sleep states and the hibernation state ("suspend-to-disk"). Each phase involves
281 All phases use PM domain, bus, type, class or driver callbacks (that is, methods
282 defined in ``dev->pm_domain->ops``, ``dev->bus->pm``, ``dev->type->pm``,
283 ``dev->class->pm`` or ``dev->driver->pm``). These callbacks are regarded by the
286 precedence over bus, class and driver callbacks. To be precise, the following
289 1. If ``dev->pm_domain`` is present, the PM core will choose the callback
290 provided by ``dev->pm_domain->ops`` for execution.
292 2. Otherwise, if both ``dev->type`` and ``dev->type->pm`` are present, the
293 callback provided by ``dev->type->pm`` will be chosen for execution.
295 3. Otherwise, if both ``dev->class`` and ``dev->class->pm`` are present,
296 the callback provided by ``dev->class->pm`` will be chosen for
299 4. Otherwise, if both ``dev->bus`` and ``dev->bus->pm`` are present, the
300 callback provided by ``dev->bus->pm`` will be chosen for execution.
302 This allows PM domains and device types to override callbacks provided by bus
305 The PM domain, type, class and bus callbacks may in turn invoke device- or
306 driver-specific methods stored in ``dev->driver->pm``, but they don't have to do
310 execute the corresponding method from the ``dev->driver->pm`` set instead if
314 Entering System Suspend
315 -----------------------
317 When the system goes into the freeze, standby or memory sleep state,
325 suspend-related phases, during the ``prepare`` phase the device
326 hierarchy is traversed top-down.
328 After the ``->prepare`` callback method returns, no new children may be
330 driver in some way for the upcoming system power transition, but it
331 should not put the device into a low-power state. Moreover, if the
332 device supports runtime power management, the ``->prepare`` callback
338 safely leave the device in runtime suspend (if runtime-suspended
342 and all of them (including the device itself) are runtime-suspended, the
346 the ``->complete`` callback will be invoked directly after the
347 ``->prepare`` callback and is entirely responsible for putting the
350 Note that this direct-complete procedure applies even if the device is
351 disabled for runtime PM; only the runtime-PM status matters. It follows
352 that if a device has system-sleep callbacks but does not support runtime
354 is because all such devices are initially set to runtime-suspended with
362 these flags is set, the PM core will not apply the direct-complete
365 code (bus types, device types, PM domains, classes) that it should take
366 the return value of the ``->prepare`` callback provided by the driver
368 ``->prepare`` callback if the driver's one also has returned a positive
371 2. The ``->suspend`` methods should quiesce the device to stop it from
373 the appropriate low-power state, depending on the bus type the device is
377 ``->suspend`` methods provided by subsystems (bus types and PM domains
379 to the devices before their drivers' ``->suspend`` methods are called.
384 suspend in their ``->suspend`` methods).
393 the callback method is running. The ``->suspend_noirq`` methods should
395 and finally put the device into the appropriate low-power state.
398 callback. However, bus types allowing devices to share interrupt
405 (DMA, IRQs), saved enough state that they can re-initialize or restore previous
406 state (as needed by the hardware), and placed the device into a low-power state.
412 prepared for generating hardware wakeup signals to trigger a system wakeup event
413 when the system is in the sleep state. For example, :c:func:`enable_irq_wake()`
417 If any of these callbacks returns an error, the system won't enter the desired
418 low-power state. Instead, the PM core will unwind its actions by resuming all
422 Leaving System Suspend
423 ----------------------
428 1. The ``->resume_noirq`` callback methods should perform any actions
431 the bus type permits devices to share interrupt vectors, like PCI, the
436 For example, the PCI bus type's ``->pm.resume_noirq()`` puts the device
437 into the full-power state (D0 in the PCI terminology) and restores the
439 device driver's ``->pm.resume_noirq()`` method to perform device-specific
442 2. The ``->resume_early`` methods should prepare devices for the execution
446 3. The ``->resume`` methods should bring the device back to its operating
451 For this reason, unlike the other resume-related phases, during the
452 ``complete`` phase the device hierarchy is traversed bottom-up.
455 soon as the ``->resume`` callbacks occur; it's not necessary to wait
458 Moreover, if the preceding ``->prepare`` callback returned a positive
460 whole system suspend and resume (the ``suspend``, ``suspend_late``,
461 ``suspend_noirq`` phases of system suspend and the ``resume_noirq``,
462 ``resume_early``, ``resume`` phases of system resume may have been
463 skipped for it). In that case, the ``->complete`` callback is entirely
464 responsible for putting the device into a consistent state after system
467 the case, the ``->complete`` callback can consult the device's
469 ``->complete`` callback is being run, it has been called directly after
470 the preceding ``->prepare`` and special actions may be required
477 However, the details here may again be platform-specific. For example,
488 system sleep entered was suspend-to-idle. For the other system sleep states
489 that may not be the case (and usually isn't for ACPI-defined system sleep
493 while the system was powered down, whenever that's physically possible.
496 will notice and handle such removals are currently bus-specific, and often
501 the system log.
505 --------------------
507 Hibernating the system is more complicated than putting it into sleep states,
508 because it involves creating and saving a system image. Therefore there are
513 create an image of the system memory while everything is stable, reactivate all
515 the system ("power off"). The phases used to accomplish this are: ``prepare``,
520 1. The ``prepare`` phase is discussed in the "Entering System Suspend"
523 2. The ``->freeze`` methods should quiesce the device so that it doesn't
525 registers. However the device does not have to be put in a low-power
531 low-power state and should not be allowed to generate wakeup events.
535 a low-power state and should not be allowed to generate wakeup events.
537 At this point the system image is created. All devices should be inactive and
539 image forms an atomic snapshot of the system state.
554 8. The ``complete`` phase is discussed in the "Leaving System Suspend"
557 At this point the system image is saved, and the devices then need to be
558 prepared for the upcoming system shutdown. This is much like suspending them
559 before putting the system into the suspend-to-idle, shallow or deep sleep state,
570 The ``->poweroff``, ``->poweroff_late`` and ``->poweroff_noirq`` callbacks
571 should do essentially the same things as the ``->suspend``, ``->suspend_late``
572 and ``->suspend_noirq`` callbacks, respectively. The only notable difference is
579 -------------------
583 a system image to be loaded into memory and the pre-hibernation memory contents
587 pre-hibernation memory contents restored by the boot loader, in practice this
592 reads the system image, restores the pre-hibernation memory contents, and passes
599 To be able to load the system image into memory, the restore kernel needs to
605 creating a system image, and it is accomplished in the same way, using
610 Should the restoration of the pre-hibernation memory contents fail, the restore
614 pre-hibernation memory contents are restored successfully and control is passed
615 to the image kernel, which then becomes responsible for bringing the system back
618 To achieve this, the image kernel must restore the devices' pre-hibernation
636 reset and completely re-initialized. In many cases this difference doesn't
637 matter, so the ``->resume[_early|_noirq]`` and ``->restore[_early|_norq]``
657 Device Low-Power (suspend) States
660 Device low-power states aren't standard. One device might only handle
666 gives one example: after the suspend sequence completes, a non-legacy
668 issues would be issued through the PME# bus signal. Plus, there are
669 several PCI-standard device states, some of which are optional.
671 In contrast, integrated system-on-chip processors often use IRQs as the
676 Some details here may be platform-specific. Systems may have devices that
678 refreshed using DMA while most of the system is sleeping lightly ... and
679 its frame buffer might even be updated by a DSP or other non-Linux CPU while
682 Moreover, the specific actions taken may depend on the target system state.
683 One target system state might allow a given device to be very operational;
684 another might require a hard shut down with re-initialization on resume.
694 cases it generally is not possible to put devices into low-power states
696 into a low-power state together at the same time by turning off the shared
697 power resource. Of course, they also need to be put into the full-power state
701 sub-domain of the parent domain.
706 of power management callbacks analogous to the subsystem-level and device driver
708 instead of the respective subsystem-level callbacks. Specifically, if a
709 device's :c:member:`pm_domain` pointer is not NULL, the ``->suspend()`` callback
711 (e.g. bus type's) ``->suspend()`` callback and analogously for all of the
714 by the device's subsystem (e.g. bus type).
719 support for power domains into subsystem-level callbacks, for example by
720 modifying the platform bus type. Other platforms need not implement it or take
723 Devices may be defined as IRQ-safe which indicates to the PM core that their
726 IRQ-safe device belongs to a PM domain, the runtime PM of the domain will be
727 disallowed, unless the domain itself is defined as IRQ-safe. However, it
728 makes sense to define a PM domain as IRQ-safe only if all the devices in it
729 are IRQ-safe. Moreover, if an IRQ-safe domain has a parent domain, the runtime
730 PM of the parent is only allowed if the parent itself is IRQ-safe too with the
731 additional restriction that all child domains of an IRQ-safe parent must also
732 be IRQ-safe.
738 Many devices are able to dynamically power down while the system is still
740 can offer significant power savings on a running system. These devices
743 cases (like PCI) be partially constrained by the bus the device uses, and will
744 usually include hardware states that are also used in system sleep states.
746 A system-wide power transition can be started while some devices are in low
747 power states due to runtime power management. The system sleep PM callbacks
749 necessary actions are subsystem-specific.
753 desirable to leave a suspended device in that state during a system-wide power
754 transition, but in other cases the device must be put back into the full-power
755 state temporarily, for example so that its system wakeup capability can be
759 If it is necessary to resume a device from runtime suspend during a system-wide
761 :c:func:`pm_runtime_resume` for it from the ``->suspend`` callback (or its
763 or a subsystem responsible for it (for example, a bus type or a PM domain).
766 from their ``->prepare`` and ``->suspend`` callbacks (or equivalent) *before*
767 invoking device drivers' ``->suspend`` callbacks (or equivalent).
769 Some bus types and PM domains have a policy to resume all devices from runtime
770 suspend upfront in their ``->suspend`` callbacks, but that may not be really
771 necessary if the driver of the device can cope with runtime-suspended devices.
774 :c:func:`dev_pm_set_driver_flags` helper. That also may cause middle-layer code
775 (bus types, PM domains etc.) to skip the ``->suspend_late`` and
776 ``->suspend_noirq`` callbacks provided by the driver if the device remains in
777 runtime suspend at the beginning of the ``suspend_late`` phase of system-wide
780 after that point until the system-wide transition is over (the PM core itself
781 does that for devices whose "noirq", "late" and "early" system-wide PM callbacks
782 are executed directly by it). If that happens, the driver's system-wide resume
783 callbacks, if present, may still be invoked during the subsequent system-wide
786 cope with the invocation of its system-wide resume callbacks back-to-back with
787 its ``->runtime_suspend`` one (without the intervening ``->runtime_resume`` and
791 During system-wide resume from a sleep state it's easiest to put devices into
792 the full-power state, as explained in :file:`Documentation/power/runtime_pm.txt`.
797 However, it often is desirable to leave devices in suspend after system
799 runtime suspend before the preceding system-wide suspend (or analogous)
801 indicate to the PM core (and middle-layer code) that they prefer the specific
803 skipping their system-wide resume callbacks for this reason. Whether or not the
805 given system suspend-resume cycle and on the type of the system transition under
810 The middle-layer code involved in the handling of the device is expected to
813 during the "noirq" phase of the preceding system-wide suspend (or analogous)
817 (except for ``->complete``) will be skipped automatically by the PM core if the
821 directly by the PM core, all of the system-wide resume callbacks are skipped if
824 proper system suspend (rather than anything related to hibernation) and the
826 generate wakeup signals at all or it is allowed to wake up the system from