include/linux/pm.h

1 /* SPDX-License-Identifier: GPL-2.0-or-later */
3  *  pm.h - Power management interface
51 	int event;  member
55  * struct dev_pm_ops - device PM callbacks.
62  *	registration of a child already in progress), it may return -EAGAIN, so
72  *	runtime-suspended and it may be left in that state during the entire
77  *	The PM core executes subsystem-level @prepare() for all devices before
95  *	The PM core executes subsystem-level @complete() after it has executed
108  *	contents of main memory are preserved.  The exact action to perform
110  *	type), but generally the device must be quiescent after subsystem-level
112  *	Subsystem-level @suspend() is executed for all devices after invoking
113  *	subsystem-level @prepare() for all of them.
120  *	contents of main memory were preserved.  The exact action to perform
123  *	requests (the device itself may be left in a low-power state, waiting
128  *	Subsystem-level @resume() is executed for all devices after invoking
129  *	subsystem-level @resume_noirq() for all of them.
135  * @freeze: Hibernation-specific, executed before creating a hibernation image.
137  *	wakeup events or change its power state.  The majority of subsystems
138  *	(with the notable exception of the PCI bus type) expect the driver-level
141  *	Subsystem-level @freeze() is executed for all devices after invoking
142  *	subsystem-level @prepare() for all of them.
145  *	@suspend_late(), but it should not enable the device to signal wakeup
148  * @thaw: Hibernation-specific, executed after creating a hibernation image OR
153  *	Subsystem-level @thaw() is executed for all devices after invoking
154  *	subsystem-level @thaw_noirq() for all of them.  It also may be executed
160  * @poweroff: Hibernation-specific, executed after saving a hibernation image.
163  *	Subsystem-level @poweroff() is executed for all devices after invoking
164  *	subsystem-level @prepare() for all of them.
169  * @restore: Hibernation-specific, executed after restoring the contents of main
178  *	It generally is expected that the device will be in a low-power state
179  *	(appropriate for the target system sleep state) after subsystem-level
181  *	system wakeup signals and is enabled to wake up the system, it should be
184  *	put the device into the low-power state and configure it to generate
185  *	wakeup signals, in which case it generally is not necessary to define
199  *	signal system wakeup by any of these callbacks.
216  *	This need not mean that the device should be put into a low-power state.
219  *	power and is capable of generating runtime wakeup events, remote wakeup
224  *	wakeup event generated by hardware or at the request of software.  If
225  *	necessary, put the device into the full-power state and restore its
229  *	low-power state if all of the necessary conditions are satisfied.
236  * internal transitions to various low-power modes which are transparent
243  * domains, device types, classes and bus types.  They are the subsystem-level
246  * have to collaborate with the subsystem-level callbacks to achieve the goals
269  * (PM domains, device types, classes and bus types) and the subsystem-level
393  * FREEZE	System is going to hibernate, call ->prepare() and ->freeze()
396  * SUSPEND	System is going to suspend, call ->prepare() and ->suspend()
399  * HIBERNATE	Hibernation image has been saved, call ->prepare() and
400  *		->poweroff() for all devices.
403  *		hibernation image, call ->prepare() and ->freeze() for all
406  * RESUME	System is resuming, call ->resume() and ->complete() for all
409  * THAW		Hibernation image has been created, call ->thaw() and
410  *		->complete() for all devices.
413  *		image, call ->restore() and ->complete() for all devices.
417  *		->thaw() and ->complete() for all devices.
426  * REMOTE_WAKEUP	Remote-wakeup request was received from the device.
435 #define PM_EVENT_INVALID	(-1)
456 #define PMSG_INVALID	((struct pm_message){ .event = PM_EVENT_INVALID, })
457 #define PMSG_ON		((struct pm_message){ .event = PM_EVENT_ON, })
458 #define PMSG_FREEZE	((struct pm_message){ .event = PM_EVENT_FREEZE, })
459 #define PMSG_QUIESCE	((struct pm_message){ .event = PM_EVENT_QUIESCE, })
460 #define PMSG_SUSPEND	((struct pm_message){ .event = PM_EVENT_SUSPEND, })
461 #define PMSG_HIBERNATE	((struct pm_message){ .event = PM_EVENT_HIBERNATE, })
462 #define PMSG_RESUME	((struct pm_message){ .event = PM_EVENT_RESUME, })
463 #define PMSG_THAW	((struct pm_message){ .event = PM_EVENT_THAW, })
464 #define PMSG_RESTORE	((struct pm_message){ .event = PM_EVENT_RESTORE, })
465 #define PMSG_RECOVER	((struct pm_message){ .event = PM_EVENT_RECOVER, })
467 					{ .event = PM_EVENT_USER_SUSPEND, })
469 					{ .event = PM_EVENT_USER_RESUME, })
471 					{ .event = PM_EVENT_REMOTE_RESUME, })
473 					{ .event = PM_EVENT_AUTO_SUSPEND, })
475 					{ .event = PM_EVENT_AUTO_RESUME, })
477 #define PMSG_IS_AUTO(msg)	(((msg).event & PM_EVENT_AUTO) != 0)
480  * Device run-time power management status.
488  *			bus type's ->runtime_resume() callback has completed
491  * RPM_SUSPENDED	Device bus type's ->runtime_suspend() callback has
495  * RPM_RESUMING		Device bus type's ->runtime_resume() callback is being
498  * RPM_SUSPENDING	Device bus type's ->runtime_suspend() callback is being
510  * Device run-time power management request types.
514  * RPM_REQ_IDLE		Run the device bus type's ->runtime_idle() callback
516  * RPM_REQ_SUSPEND	Run the device bus type's ->runtime_suspend() callback
521  * RPM_REQ_RESUME	Run the device bus type's ->runtime_resume() callback
553  * NO_DIRECT_COMPLETE: Do not apply direct-complete optimization to the device.
554  * SMART_PREPARE: Take the driver ->prepare callback return value into account.
558  * See Documentation/driver-api/pm/devices.rst for details.
582 	struct wakeup_source	*wakeup;  member
629  * struct dev_pm_domain - power management domain representation.
640  * subsystem-level and driver-level callbacks.
653  * suspend framework, based on the ->suspend() and ->resume() callbacks common
666  *		a power-off reset, or it may have maintained state from the
680  *		wakeup events as appropriate.
683  *		state (eg. ACPI S4) and enable wakeup events as appropriate.
687  *		NOT emit system wakeup events.
695  * A minimally power-aware driver treats all messages as SUSPEND, fully
696  * reinitializes its device during resume() -- whether or not it was reset
697  * during the suspend/resume cycle -- and can't issue wakeup events.
699  * More power-aware drivers may also use low power states at runtime as
701  * be able to use wakeup events to exit from runtime low-power states,
702  * or from system low-power states such as standby or suspend-to-RAM.