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
75  *	@poweroff().  If the transition is a suspend to memory or standby (that
80  *	runtime-suspended and it may be left in that state during the entire
85  *	The PM core executes subsystem-level @prepare() for all devices before
103  *	The PM core executes subsystem-level @complete() after it has executed
118  *	type), but generally the device must be quiescent after subsystem-level
120  *	Subsystem-level @suspend() is executed for all devices after invoking
121  *	subsystem-level @prepare() for all of them.
131  *	requests (the device itself may be left in a low-power state, waiting
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.
146  *	(with the notable exception of the PCI bus type) expect the driver-level
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.
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
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
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.
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
277  * (PM domains, device types, classes and bus types) and the subsystem-level
377 #define _EXPORT_PM_OPS(name, license, ns)				\  argument
379 	__EXPORT_SYMBOL(name, license, ns);				\
382 #define _DISCARD_PM_OPS(name, license, ns)				\  argument
386 #define _EXPORT_DEV_PM_OPS(name, license, ns)		_EXPORT_PM_OPS(name, license, ns)  argument
388 #define _EXPORT_DEV_PM_OPS(name, license, ns)		_DISCARD_PM_OPS(name, license, ns)  argument
392 #define _EXPORT_DEV_SLEEP_PM_OPS(name, license, ns)	_EXPORT_PM_OPS(name, license, ns)  argument
394 #define _EXPORT_DEV_SLEEP_PM_OPS(name, license, ns)	_DISCARD_PM_OPS(name, license, ns)  argument
399 #define EXPORT_NS_DEV_PM_OPS(name, ns)			_EXPORT_DEV_PM_OPS(name, "", #ns)  argument
400 #define EXPORT_NS_GPL_DEV_PM_OPS(name, ns)		_EXPORT_DEV_PM_OPS(name, "GPL", #ns)  argument
404 #define EXPORT_NS_DEV_SLEEP_PM_OPS(name, ns)		_EXPORT_DEV_SLEEP_PM_OPS(name, "", #ns)  argument
405 #define EXPORT_NS_GPL_DEV_SLEEP_PM_OPS(name, ns)	_EXPORT_DEV_SLEEP_PM_OPS(name, "GPL", #ns)  argument
425 #define EXPORT_NS_SIMPLE_DEV_PM_OPS(name, suspend_fn, resume_fn, ns)	\  argument
426 	EXPORT_NS_DEV_SLEEP_PM_OPS(name, ns) = { \
429 #define EXPORT_NS_GPL_SIMPLE_DEV_PM_OPS(name, suspend_fn, resume_fn, ns)	\  argument
430 	EXPORT_NS_GPL_DEV_SLEEP_PM_OPS(name, ns) = { \
484  * FREEZE	System is going to hibernate, call ->prepare() and ->freeze()
487  * SUSPEND	System is going to suspend, call ->prepare() and ->suspend()
490  * HIBERNATE	Hibernation image has been saved, call ->prepare() and
491  *		->poweroff() for all devices.
494  *		hibernation image, call ->prepare() and ->freeze() for all
497  * RESUME	System is resuming, call ->resume() and ->complete() for all
500  * THAW		Hibernation image has been created, call ->thaw() and
501  *		->complete() for all devices.
504  *		image, call ->restore() and ->complete() for all devices.
508  *		->thaw() and ->complete() for all devices.
517  * REMOTE_WAKEUP	Remote-wakeup request was received from the device.
519  * AUTO_SUSPEND		Automatic (device idle) runtime suspend was
526 #define PM_EVENT_INVALID	(-1)
572  * Device run-time power management status.
580  *			bus type's ->runtime_resume() callback has completed
583  * RPM_SUSPENDED	Device bus type's ->runtime_suspend() callback has
587  * RPM_RESUMING		Device bus type's ->runtime_resume() callback is being
590  * RPM_SUSPENDING	Device bus type's ->runtime_suspend() callback is being
595 	RPM_INVALID = -1,
604  * Device run-time power management request types.
608  * RPM_REQ_IDLE		Run the device bus type's ->runtime_idle() callback
610  * RPM_REQ_SUSPEND	Run the device bus type's ->runtime_suspend() callback
615  * RPM_REQ_RESUME	Run the device bus type's ->runtime_resume() callback
649  * NO_DIRECT_COMPLETE: Do not apply direct-complete optimization to the device.
650  * SMART_PREPARE: Take the driver ->prepare callback return value into account.
654  * See Documentation/driver-api/pm/devices.rst for details.
729  * struct dev_pm_domain - power management domain representation.
741  * subsystem-level and driver-level callbacks.
755  * suspend framework, based on the ->suspend() and ->resume() callbacks common
768  *		a power-off reset, or it may have maintained state from the
797  * A minimally power-aware driver treats all messages as SUSPEND, fully
798  * reinitializes its device during resume() -- whether or not it was reset
799  * during the suspend/resume cycle -- and can't issue wakeup events.
801  * More power-aware drivers may also use low power states at runtime as
803  * be able to use wakeup events to exit from runtime low-power states,
804  * or from system low-power states such as standby or suspend-to-RAM.