include/linux/pm.h

1 /* SPDX-License-Identifier: GPL-2.0-or-later */
3  *  pm.h - Power management interface
56  * struct dev_pm_ops - device PM callbacks.
63  *	registration of a child already in progress), it may return -EAGAIN, so
64  *	that the PM core can execute it once again (e.g. after a new child has
70  *	used to indicate to the PM core to leave the device in runtime suspend
71  *	if applicable.  Namely, if @prepare() returns a positive number, the PM
73  *	runtime-suspended and it may be left in that state during the entire
78  *	The PM core executes subsystem-level @prepare() for all devices before
94  *	of the other devices that the PM core has unsuccessfully attempted to
96  *	The PM core executes subsystem-level @complete() after it has executed
110  *	depends on the device's subsystem (PM domain, device type, class or bus
111  *	type), but generally the device must be quiescent after subsystem-level
113  *	Subsystem-level @suspend() is executed for all devices after invoking
114  *	subsystem-level @prepare() for all of them.
124  *	requests (the device itself may be left in a low-power state, waiting
129  *	Subsystem-level @resume() is executed for all devices after invoking
130  *	subsystem-level @resume_noirq() for all of them.
136  * @freeze: Hibernation-specific, executed before creating a hibernation image.
139  *	(with the notable exception of the PCI bus type) expect the driver-level
142  *	Subsystem-level @freeze() is executed for all devices after invoking
143  *	subsystem-level @prepare() for all of them.
149  * @thaw: Hibernation-specific, executed after creating a hibernation image OR
154  *	Subsystem-level @thaw() is executed for all devices after invoking
155  *	subsystem-level @thaw_noirq() for all of them.  It also may be executed
161  * @poweroff: Hibernation-specific, executed after saving a hibernation image.
164  *	Subsystem-level @poweroff() is executed for all devices after invoking
165  *	subsystem-level @prepare() for all of them.
170  * @restore: Hibernation-specific, executed after restoring the contents of main
179  *	It generally is expected that the device will be in a low-power state
180  *	(appropriate for the target system sleep state) after subsystem-level
185  *	put the device into the low-power state and configure it to generate
217  *	This need not mean that the device should be put into a low-power state.
226  *	necessary, put the device into the full-power state and restore its
230  *	low-power state if all of the necessary conditions are satisfied.
231  *	Check these conditions, and return 0 if it's appropriate to let the PM
237  * internal transitions to various low-power modes which are transparent
243  * callbacks are involved.  First, the PM core executes callbacks provided by PM
244  * domains, device types, classes and bus types.  They are the subsystem-level
247  * have to collaborate with the subsystem-level callbacks to achieve the goals
253  * @resume_noirq(), @thaw_noirq(), and @restore_noirq(), do not cause the PM
259  * allow the PM core to be modified in the future, so that it can avoid
269  * Again, as a rule these callbacks are executed by the PM core for subsystems
270  * (PM domains, device types, classes and bus types) and the subsystem-level
362  * Use this for defining a set of PM operations to be used in all situations
363  * (system suspend, hibernation or runtime PM).
365  * be different from the corresponding runtime PM callbacks, .runtime_suspend(),
389  * The following PM_EVENT_ messages are defined for the internal use of the PM
391  * hibernation code to convey the necessary information to the device PM core
396  * FREEZE	System is going to hibernate, call ->prepare() and ->freeze()
399  * SUSPEND	System is going to suspend, call ->prepare() and ->suspend()
402  * HIBERNATE	Hibernation image has been saved, call ->prepare() and
403  *		->poweroff() for all devices.
406  *		hibernation image, call ->prepare() and ->freeze() for all
409  * RESUME	System is resuming, call ->resume() and ->complete() for all
412  * THAW		Hibernation image has been created, call ->thaw() and
413  *		->complete() for all devices.
416  *		image, call ->restore() and ->complete() for all devices.
420  *		->thaw() and ->complete() for all devices.
423  * kernel subsystems.  They are never issued by the PM core.
429  * REMOTE_WAKEUP	Remote-wakeup request was received from the device.
438 #define PM_EVENT_INVALID	(-1)
483  * Device run-time power management status.
485  * These status labels are used internally by the PM core to indicate the
486  * current status of a device with respect to the PM core operations.  They do
491  *			bus type's ->runtime_resume() callback has completed
494  * RPM_SUSPENDED	Device bus type's ->runtime_suspend() callback has
498  * RPM_RESUMING		Device bus type's ->runtime_resume() callback is being
501  * RPM_SUSPENDING	Device bus type's ->runtime_suspend() callback is being
513  * Device run-time power management request types.
517  * RPM_REQ_IDLE		Run the device bus type's ->runtime_idle() callback
519  * RPM_REQ_SUSPEND	Run the device bus type's ->runtime_suspend() callback
524  * RPM_REQ_RESUME	Run the device bus type's ->runtime_resume() callback
556  * NO_DIRECT_COMPLETE: Do not apply direct-complete optimization to the device.
557  * SMART_PREPARE: Take the driver ->prepare callback return value into account.
561  * See Documentation/driver-api/pm/devices.rst for details.
572 	bool			in_dpm_list:1;	/* Owned by the PM core */
573 	bool			is_prepared:1;	/* Owned by the PM core */
578 	bool			early_init:1;	/* Owned by the PM core */
579 	bool			direct_complete:1;	/* Owned by the PM core */
588 	bool			no_pm_callbacks:1;	/* Owned by the PM core */
589 	unsigned int		must_resume:1;	/* Owned by the PM core */
636  * struct dev_pm_domain - power management domain representation.
641  * @activate: Called before executing probe routines for bus types and drivers.
646  * hibernation, system resume and during runtime PM transitions instead of
647  * subsystem-level and driver-level callbacks.
662  * suspend framework, based on the ->suspend() and ->resume() callbacks common
675  *		a power-off reset, or it may have maintained state from the
683  * about how to quiesce that are specific to the bus or the device's type.
704  * A minimally power-aware driver treats all messages as SUSPEND, fully
705  * reinitializes its device during resume() -- whether or not it was reset
706  * during the suspend/resume cycle -- and can't issue wakeup events.
708  * More power-aware drivers may also use low power states at runtime as
710  * be able to use wakeup events to exit from runtime low-power states,
711  * or from system low-power states such as standby or suspend-to-RAM.