Device Power Management Data Types¶
- struct
dev_pm_ops¶ device PM callbacks.
Definition
struct dev_pm_ops { int (*prepare)(struct device *dev); void (*complete)(struct device *dev); int (*suspend)(struct device *dev); int (*resume)(struct device *dev); int (*freeze)(struct device *dev); int (*thaw)(struct device *dev); int (*poweroff)(struct device *dev); int (*restore)(struct device *dev); int (*suspend_late)(struct device *dev); int (*resume_early)(struct device *dev); int (*freeze_late)(struct device *dev); int (*thaw_early)(struct device *dev); int (*poweroff_late)(struct device *dev); int (*restore_early)(struct device *dev); int (*suspend_noirq)(struct device *dev); int (*resume_noirq)(struct device *dev); int (*freeze_noirq)(struct device *dev); int (*thaw_noirq)(struct device *dev); int (*poweroff_noirq)(struct device *dev); int (*restore_noirq)(struct device *dev); int (*runtime_suspend)(struct device *dev); int (*runtime_resume)(struct device *dev); int (*runtime_idle)(struct device *dev);};Members
prepare- The principal role of this callback is to prevent new children ofthe device from being registered after it has returned (the driver’ssubsystem and generally the rest of the kernel is supposed to preventnew calls to the probe method from being made too onceprepare() hassucceeded). Ifprepare() detects a situation it cannot handle (e.g.registration of a child already in progress), it may return -EAGAIN, sothat the PM core can execute it once again (e.g. after a new child hasbeen registered) to recover from the race condition.This method is executed for all kinds of suspend transitions and isfollowed by one of the suspend callbacks:suspend(),freeze(), orpoweroff(). If the transition is a suspend to memory or standby (thatis, not related to hibernation), the return value ofprepare() may beused to indicate to the PM core to leave the device in runtime suspendif applicable. Namely, ifprepare() returns a positive number, the PMcore will understand that as a declaration that the device appears to beruntime-suspended and it may be left in that state during the entiretransition and during the subsequent resume if all of its descendantsare left in runtime suspend too. If that happens,complete() will beexecuted directly afterprepare() and it must ensure the properfunctioning of the device after the system resume.The PM core executes subsystem-levelprepare() for all devices beforestarting to invoke suspend callbacks for any of them, so generallydevices may be assumed to be functional or to respond to runtime resumerequests whileprepare() is being executed. However, device driversmay NOT assume anything about the availability of user space at thattime and it is NOT valid to request firmware from withinprepare()(it’s too late to do that). It also is NOT valid to allocatesubstantial amounts of memory fromprepare() in the GFP_KERNEL mode.[To work around these limitations, drivers may register suspend andhibernation notifiers to be executed before the freezing of tasks.]
complete- Undo the changes made byprepare(). This method is executed forall kinds of resume transitions, following one of the resume callbacks:resume(),thaw(),restore(). Also called if the state transitionfails before the driver’s suspend callback:suspend(),freeze() orpoweroff(), can be executed (e.g. if the suspend callback fails for oneof the other devices that the PM core has unsuccessfully attempted tosuspend earlier).The PM core executes subsystem-levelcomplete() after it has executedthe appropriate resume callbacks for all devices. If the correspondingprepare() at the beginning of the suspend transition returned apositive number and the device was left in runtime suspend (withoutexecuting any suspend and resume callbacks for it),complete() will bethe only callback executed for the device during resume. In that case,complete() must be prepared to do whatever is necessary to ensure theproper functioning of the device after the system resume. To this end,complete() can check the power.direct_complete flag of the device tolearn whether (unset) or not (set) the previous suspend and resumecallbacks have been executed for it.
suspend- Executed before putting the system into a sleep state in which thecontents of main memory are preserved. The exact action to performdepends on the device’s subsystem (PM domain, device type, class or bustype), but generally the device must be quiescent after subsystem-levelsuspend() has returned, so that it doesn’t do any I/O or DMA.Subsystem-levelsuspend() is executed for all devices after invokingsubsystem-levelprepare() for all of them.
resume- Executed after waking the system up from a sleep state in which thecontents of main memory were preserved. The exact action to performdepends on the device’s subsystem, but generally the driver is expectedto start working again, responding to hardware events and softwarerequests (the device itself may be left in a low-power state, waitingfor a runtime resume to occur). The state of the device at the time itsdriver’sresume() callback is run depends on the platform and subsystemthe device belongs to. On most platforms, there are no restrictions onavailability of resources like clocks duringresume().Subsystem-levelresume() is executed for all devices after invokingsubsystem-levelresume_noirq() for all of them.
freeze- Hibernation-specific, executed before creating a hibernation image.Analogous tosuspend(), but it should not enable the device to signalwakeup events or change its power state. The majority of subsystems(with the notable exception of the PCI bus type) expect the driver-levelfreeze() to save the device settings in memory to be used byrestore()during the subsequent resume from hibernation.Subsystem-levelfreeze() is executed for all devices after invokingsubsystem-levelprepare() for all of them.
thaw- Hibernation-specific, executed after creating a hibernation image ORif the creation of an image has failed. Also executed after a failingattempt to restore the contents of main memory from such an image.Undo the changes made by the precedingfreeze(), so the device can beoperated in the same way as immediately before the call tofreeze().Subsystem-levelthaw() is executed for all devices after invokingsubsystem-levelthaw_noirq() for all of them. It also may be executeddirectly afterfreeze() in case of a transition error.
poweroff- Hibernation-specific, executed after saving a hibernation image.Analogous tosuspend(), but it need not save the device’s settings inmemory.Subsystem-levelpoweroff() is executed for all devices after invokingsubsystem-levelprepare() for all of them.
restore- Hibernation-specific, executed after restoring the contents of mainmemory from a hibernation image, analogous toresume().
suspend_late- Continue operations started bysuspend(). For a number ofdevicessuspend_late() may point to the same callback routine as theruntime suspend callback.
resume_early- Prepare to executeresume(). For a number of devicesresume_early() may point to the same callback routine as the runtimeresume callback.
freeze_late- Continue operations started byfreeze(). Analogous tosuspend_late(), but it should not enable the device to signal wakeupevents or change its power state.
thaw_early- Prepare to executethaw(). Undo the changes made by theprecedingfreeze_late().
poweroff_late- Continue operations started bypoweroff(). Analogous tosuspend_late(), but it need not save the device’s settings in memory.
restore_early- Prepare to executerestore(), analogous toresume_early().
suspend_noirq- Complete the actions started bysuspend(). Carry out anyadditional operations required for suspending the device that might beracing with its driver’s interrupt handler, which is guaranteed not torun whilesuspend_noirq() is being executed.It generally is expected that the device will be in a low-power state(appropriate for the target system sleep state) after subsystem-levelsuspend_noirq() has returned successfully. If the device can generatesystem wakeup signals and is enabled to wake up the system, it should beconfigured to do so at that time. However, depending on the platformand device’s subsystem,suspend() orsuspend_late() may be allowed toput the device into the low-power state and configure it to generatewakeup signals, in which case it generally is not necessary to definesuspend_noirq().
resume_noirq- Prepare for the execution ofresume() by carrying out anyoperations required for resuming the device that might be racing withits driver’s interrupt handler, which is guaranteed not to run whileresume_noirq() is being executed.
freeze_noirq- Complete the actions started byfreeze(). Carry out anyadditional operations required for freezing the device that might beracing with its driver’s interrupt handler, which is guaranteed not torun whilefreeze_noirq() is being executed.The power state of the device should not be changed by eitherfreeze(),orfreeze_late(), orfreeze_noirq() and it should not be configured tosignal system wakeup by any of these callbacks.
thaw_noirq- Prepare for the execution ofthaw() by carrying out anyoperations required for thawing the device that might be racing with itsdriver’s interrupt handler, which is guaranteed not to run whilethaw_noirq() is being executed.
poweroff_noirq- Complete the actions started bypoweroff(). Analogous tosuspend_noirq(), but it need not save the device’s settings in memory.
restore_noirq- Prepare for the execution ofrestore() by carrying out anyoperations required for thawing the device that might be racing with itsdriver’s interrupt handler, which is guaranteed not to run whilerestore_noirq() is being executed. Analogous toresume_noirq().
runtime_suspend- Prepare the device for a condition in which it won’t beable to communicate with the CPU(s) and RAM due to power management.This need not mean that the device should be put into a low-power state.For example, if the device is behind a link which is about to be turnedoff, the device may remain at full power. If the device does go to lowpower and is capable of generating runtime wakeup events, remote wakeup(i.e., a hardware mechanism allowing the device to request a change ofits power state via an interrupt) should be enabled for it.
runtime_resume- Put the device into the fully active state in response to awakeup event generated by hardware or at the request of software. Ifnecessary, put the device into the full-power state and restore itsregisters, so that it is fully operational.
runtime_idle- Device appears to be inactive and it might be put into alow-power state if all of the necessary conditions are satisfied.Check these conditions, and return 0 if it’s appropriate to let the PMcore queue a suspend request for the device.
Description
Several device power state transitions are externally visible, affectingthe state of pending I/O queues and (for drivers that touch hardware)interrupts, wakeups, DMA, and other hardware state. There may also beinternal transitions to various low-power modes which are transparentto the rest of the driver stack (such as a driver that’s ON gating offclocks which are not in active use).
The externally visible transitions are handled with the help of callbacksincluded in this structure in such a way that, typically, two levels ofcallbacks are involved. First, the PM core executes callbacks provided by PMdomains, device types, classes and bus types. They are the subsystem-levelcallbacks expected to execute callbacks provided by device drivers, althoughthey may choose not to do that. If the driver callbacks are executed, theyhave to collaborate with the subsystem-level callbacks to achieve the goalsappropriate for the given system transition, given transition phase and thesubsystem the device belongs to.
All of the above callbacks, except forcomplete(), return error codes.However, the error codes returned byresume(),thaw(),restore(),resume_noirq(),thaw_noirq(), andrestore_noirq(), do not cause the PMcore to abort the resume transition during which they are returned. Theerror codes returned in those cases are only printed to the system logs fordebugging purposes. Still, it is recommended that drivers only return errorcodes from their resume methods in case of an unrecoverable failure (i.e.when the device being handled refuses to resume and becomes unusable) toallow the PM core to be modified in the future, so that it can avoidattempting to handle devices that failed to resume and their children.
It is allowed to unregister devices while the above callbacks are beingexecuted. However, a callback routine MUST NOT try to unregister the deviceit was called for, although it may unregister children of that device (forexample, if it detects that a child was unplugged while the system wasasleep).
There also are callbacks related to runtime power management of devices.Again, as a rule these callbacks are executed by the PM core for subsystems(PM domains, device types, classes and bus types) and the subsystem-levelcallbacks are expected to invoke the driver callbacks. Moreover, the exactactions to be performed by a device driver’s callbacks generally depend onthe platform and subsystem the device belongs to.
Refer to Documentation/power/runtime_pm.rst for more information about therole of theruntime_suspend(),runtime_resume() andruntime_idle()callbacks in device runtime power management.
- struct
dev_pm_domain¶ power management domain representation.
Definition
struct dev_pm_domain { struct dev_pm_ops ops; int (*start)(struct device *dev); void (*detach)(struct device *dev, bool power_off); int (*activate)(struct device *dev); void (*sync)(struct device *dev); void (*dismiss)(struct device *dev);};Members
ops- Power management operations associated with this domain.
start- Called when a user needs to start the device via the domain.
detach- Called when removing a device from the domain.
activate- Called before executing probe routines for bus types and drivers.
sync- Called after successful driver probe.
dismiss- Called after unsuccessful driver probe and after driver removal.
Description
Power domains provide callbacks that are executed during system suspend,hibernation, system resume and during runtime PM transitions instead ofsubsystem-level and driver-level callbacks.