include/linux/pm.h

1 /* SPDX-License-Identifier: GPL-2.0-or-later */
3  *  pm.h - Power management interface
63  * struct dev_pm_ops - device PM callbacks.
70  *	registration of a child already in progress), it may return -EAGAIN, so
73  *	This method is executed for all kinds of suspend transitions and is
74  *	followed by one of the suspend callbacks: @suspend(), @freeze(), or
75  *	@poweroff().  If the transition is a suspend to memory or standby (that
77  *	used to indicate to the PM core to leave the device in runtime suspend
80  *	runtime-suspended and it may be left in that state during the entire
81  *	transition and during the subsequent resume if all of its descendants
82  *	are left in runtime suspend too.  If that happens, @complete() will be
85  *	The PM core executes subsystem-level @prepare() for all devices before
86  *	starting to invoke suspend callbacks for any of them, so generally
93  *	[To work around these limitations, drivers may register suspend and
99  *	fails before the driver's suspend callback: @suspend(), @freeze() or
100  *	@poweroff(), can be executed (e.g. if the suspend callback fails for one
102  *	suspend earlier).
103  *	The PM core executes subsystem-level @complete() after it has executed
105  *	@prepare() at the beginning of the suspend transition returned a
106  *	positive number and the device was left in runtime suspend (without
107  *	executing any suspend and resume callbacks for it), @complete() will be
108  *	the only callback executed for the device during resume.  In that case,
112  *	learn whether (unset) or not (set) the previous suspend and resume
115  * @suspend: Executed before putting the system into a sleep state in which the
118  *	type), but generally the device must be quiescent after subsystem-level
119  *	@suspend() has returned, so that it doesn't do any I/O or DMA.
120  *	Subsystem-level @suspend() is executed for all devices after invoking
121  *	subsystem-level @prepare() for all of them.
123  * @suspend_late: Continue operations started by @suspend().  For a number of
125  *	runtime suspend callback.
131  *	requests (the device itself may be left in a low-power state, waiting
134  *	the device belongs to.  On most platforms, there are no restrictions on
135  *	availability of resources like clocks during @resume().
136  *	Subsystem-level @resume() is executed for all devices after invoking
137  *	subsystem-level @resume_noirq() for all of them.
143  * @freeze: Hibernation-specific, executed before creating a hibernation image.
144  *	Analogous to @suspend(), but it should not enable the device to signal
146  *	(with the notable exception of the PCI bus type) expect the driver-level
148  *	during the subsequent resume from hibernation.
149  *	Subsystem-level @freeze() is executed for all devices after invoking
150  *	subsystem-level @prepare() for all of them.
156  * @thaw: Hibernation-specific, executed after creating a hibernation image OR
161  *	Subsystem-level @thaw() is executed for all devices after invoking
162  *	subsystem-level @thaw_noirq() for all of them.  It also may be executed
168  * @poweroff: Hibernation-specific, executed after saving a hibernation image.
169  *	Analogous to @suspend(), but it need not save the device's settings in
171  *	Subsystem-level @poweroff() is executed for all devices after invoking
172  *	subsystem-level @prepare() for all of them.
177  * @restore: Hibernation-specific, executed after restoring the contents of main
182  * @suspend_noirq: Complete the actions started by @suspend().  Carry out any
186  *	It generally is expected that the device will be in a low-power state
187  *	(appropriate for the target system sleep state) after subsystem-level
191  *	and device's subsystem, @suspend() or @suspend_late() may be allowed to
192  *	put the device into the low-power state and configure it to generate
224  *	This need not mean that the device should be put into a low-power state.
233  *	necessary, put the device into the full-power state and restore its
237  *	low-power state if all of the necessary conditions are satisfied.
239  *	core queue a suspend request for the device.
244  * internal transitions to various low-power modes which are transparent
251  * domains, device types, classes and bus types.  They are the subsystem-level
254  * have to collaborate with the subsystem-level callbacks to achieve the goals
261  * core to abort the resume transition during which they are returned.  The
277  * (PM domains, device types, classes and bus types) and the subsystem-level
289 	int (*suspend)(struct device *dev);  member
313 	.suspend = pm_sleep_ptr(suspend_fn), \
412  * Use this if you want to use the same suspend and resume callbacks for suspend
446  * (system suspend, hibernation or runtime PM).
447  * NOTE: In general, system suspend callbacks, .suspend() and .resume(), should
450  * quiescent device, while .suspend() should assume that the device may be doing
453  * suspend and "early" resume callback pointers, .suspend_late() and
467  * Use this if you want to have the suspend and resume callbacks be called
482  * core, in order to provide a mechanism allowing the high level suspend and
486  * ON		No transition.
488  * FREEZE	System is going to hibernate, call ->prepare() and ->freeze()
491  * SUSPEND	System is going to suspend, call ->prepare() and ->suspend()
494  * HIBERNATE	Hibernation image has been saved, call ->prepare() and
495  *		->poweroff() for all devices.
498  *		hibernation image, call ->prepare() and ->freeze() for all
501  * RESUME	System is resuming, call ->resume() and ->complete() for all
504  * THAW		Hibernation image has been created, call ->thaw() and
505  *		->complete() for all devices.
508  *		image, call ->restore() and ->complete() for all devices.
512  *		->thaw() and ->complete() for all devices.
517  * USER_SUSPEND		Manual selective suspend was issued by userspace.
521  * REMOTE_WAKEUP	Remote-wakeup request was received from the device.
523  * AUTO_SUSPEND		Automatic (device idle) runtime suspend was
530 #define PM_EVENT_INVALID	(-1)
575  * Device run-time power management status.
583  *			bus type's ->runtime_resume() callback has completed
586  * RPM_SUSPENDED	Device bus type's ->runtime_suspend() callback has
590  * RPM_RESUMING		Device bus type's ->runtime_resume() callback is being
593  * RPM_SUSPENDING	Device bus type's ->runtime_suspend() callback is being
598 	RPM_INVALID = -1,
606  * Device run-time power management request types.
610  * RPM_REQ_IDLE		Run the device bus type's ->runtime_idle() callback
612  * RPM_REQ_SUSPEND	Run the device bus type's ->runtime_suspend() callback
617  * RPM_REQ_RESUME	Run the device bus type's ->runtime_resume() callback
646  * Driver flags to control system suspend/resume behavior.
651  * NO_DIRECT_COMPLETE: Do not apply direct-complete optimization to the device.
652  * SMART_PREPARE: Take the driver ->prepare callback return value into account.
653  * SMART_SUSPEND: Avoid resuming the device from runtime suspend.
656  * See Documentation/driver-api/pm/devices.rst for details.
730  * struct dev_pm_domain - power management domain representation.
740  * Power domains provide callbacks that are executed during system suspend,
741  * hibernation, system resume and during runtime PM transitions instead of
742  * subsystem-level and driver-level callbacks.
756  * suspend framework, based on the ->suspend() and ->resume() callbacks common
757  * for suspend and hibernation transitions, according to the rules below.
764  * One transition is triggered by resume(), after a suspend() call; the
769  *		a power-off reset, or it may have maintained state from the
770  *		previous suspend() which the driver will rely on while
771  *		resuming.  On most platforms, there are no restrictions on
772  *		availability of resources like clocks during resume().
774  * Other transitions are triggered by messages sent using suspend().  All
781  * SUSPEND	Quiesce, enter a low power device state appropriate for
794  *		Some drivers will need to reset their hardware state instead
798  * A minimally power-aware driver treats all messages as SUSPEND, fully
799  * reinitializes its device during resume() -- whether or not it was reset
800  * during the suspend/resume cycle -- and can't issue wakeup events.
802  * More power-aware drivers may also use low power states at runtime as
803  * well as during system sleep states like PM_SUSPEND_STANDBY.  They may
804  * be able to use wakeup events to exit from runtime low-power states,
805  * or from system low-power states such as standby or suspend-to-RAM.