2 * pm.h - Power management interface
4 * Copyright (C) 2000 Andrew Henroid
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
16 * You should have received a copy of the GNU General Public License
17 * along with this program; if not, write to the Free Software
18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24 #include <linux/list.h>
25 #include <linux/workqueue.h>
26 #include <linux/spinlock.h>
27 #include <linux/mutex.h>
28 #include <linux/wait.h>
29 #include <linux/timer.h>
30 #include <linux/completion.h>
33 * Callbacks for platform drivers to implement.
35 extern void (*pm_idle
)(void);
36 extern void (*pm_power_off
)(void);
37 extern void (*pm_power_off_prepare
)(void);
40 * Device power management
46 extern const char power_group_name
[]; /* = "power" */
48 #define power_group_name NULL
51 typedef struct pm_message
{
56 * struct dev_pm_ops - device PM callbacks
58 * Several driver power state transitions are externally visible, affecting
59 * the state of pending I/O queues and (for drivers that touch hardware)
60 * interrupts, wakeups, DMA, and other hardware state. There may also be
61 * internal transitions to various low power modes, which are transparent
62 * to the rest of the driver stack (such as a driver that's ON gating off
63 * clocks which are not in active use).
65 * The externally visible transitions are handled with the help of the following
66 * callbacks included in this structure:
68 * @prepare: Prepare the device for the upcoming transition, but do NOT change
69 * its hardware state. Prevent new children of the device from being
70 * registered after @prepare() returns (the driver's subsystem and
71 * generally the rest of the kernel is supposed to prevent new calls to the
72 * probe method from being made too once @prepare() has succeeded). If
73 * @prepare() detects a situation it cannot handle (e.g. registration of a
74 * child already in progress), it may return -EAGAIN, so that the PM core
75 * can execute it once again (e.g. after the new child has been registered)
76 * to recover from the race condition. This method is executed for all
77 * kinds of suspend transitions and is followed by one of the suspend
78 * callbacks: @suspend(), @freeze(), or @poweroff().
79 * The PM core executes @prepare() for all devices before starting to
80 * execute suspend callbacks for any of them, so drivers may assume all of
81 * the other devices to be present and functional while @prepare() is being
82 * executed. In particular, it is safe to make GFP_KERNEL memory
83 * allocations from within @prepare(). However, drivers may NOT assume
84 * anything about the availability of the user space at that time and it
85 * is not correct to request firmware from within @prepare() (it's too
86 * late to do that). [To work around this limitation, drivers may
87 * register suspend and hibernation notifiers that are executed before the
90 * @complete: Undo the changes made by @prepare(). This method is executed for
91 * all kinds of resume transitions, following one of the resume callbacks:
92 * @resume(), @thaw(), @restore(). Also called if the state transition
93 * fails before the driver's suspend callback (@suspend(), @freeze(),
94 * @poweroff()) can be executed (e.g. if the suspend callback fails for one
95 * of the other devices that the PM core has unsuccessfully attempted to
97 * The PM core executes @complete() after it has executed the appropriate
98 * resume callback for all devices.
100 * @suspend: Executed before putting the system into a sleep state in which the
101 * contents of main memory are preserved. Quiesce the device, put it into
102 * a low power state appropriate for the upcoming system state (such as
103 * PCI_D3hot), and enable wakeup events as appropriate.
105 * @resume: Executed after waking the system up from a sleep state in which the
106 * contents of main memory were preserved. Put the device into the
107 * appropriate state, according to the information saved in memory by the
108 * preceding @suspend(). The driver starts working again, responding to
109 * hardware events and software requests. The hardware may have gone
110 * through a power-off reset, or it may have maintained state from the
111 * previous suspend() which the driver may rely on while resuming. On most
112 * platforms, there are no restrictions on availability of resources like
113 * clocks during @resume().
115 * @freeze: Hibernation-specific, executed before creating a hibernation image.
116 * Quiesce operations so that a consistent image can be created, but do NOT
117 * otherwise put the device into a low power device state and do NOT emit
118 * system wakeup events. Save in main memory the device settings to be
119 * used by @restore() during the subsequent resume from hibernation or by
120 * the subsequent @thaw(), if the creation of the image or the restoration
121 * of main memory contents from it fails.
123 * @thaw: Hibernation-specific, executed after creating a hibernation image OR
124 * if the creation of the image fails. Also executed after a failing
125 * attempt to restore the contents of main memory from such an image.
126 * Undo the changes made by the preceding @freeze(), so the device can be
127 * operated in the same way as immediately before the call to @freeze().
129 * @poweroff: Hibernation-specific, executed after saving a hibernation image.
130 * Quiesce the device, put it into a low power state appropriate for the
131 * upcoming system state (such as PCI_D3hot), and enable wakeup events as
134 * @restore: Hibernation-specific, executed after restoring the contents of main
135 * memory from a hibernation image. Driver starts working again,
136 * responding to hardware events and software requests. Drivers may NOT
137 * make ANY assumptions about the hardware state right prior to @restore().
138 * On most platforms, there are no restrictions on availability of
139 * resources like clocks during @restore().
141 * @suspend_noirq: Complete the operations of ->suspend() by carrying out any
142 * actions required for suspending the device that need interrupts to be
145 * @resume_noirq: Prepare for the execution of ->resume() by carrying out any
146 * actions required for resuming the device that need interrupts to be
149 * @freeze_noirq: Complete the operations of ->freeze() by carrying out any
150 * actions required for freezing the device that need interrupts to be
153 * @thaw_noirq: Prepare for the execution of ->thaw() by carrying out any
154 * actions required for thawing the device that need interrupts to be
157 * @poweroff_noirq: Complete the operations of ->poweroff() by carrying out any
158 * actions required for handling the device that need interrupts to be
161 * @restore_noirq: Prepare for the execution of ->restore() by carrying out any
162 * actions required for restoring the operations of the device that need
163 * interrupts to be disabled
165 * All of the above callbacks, except for @complete(), return error codes.
166 * However, the error codes returned by the resume operations, @resume(),
167 * @thaw(), @restore(), @resume_noirq(), @thaw_noirq(), and @restore_noirq() do
168 * not cause the PM core to abort the resume transition during which they are
169 * returned. The error codes returned in that cases are only printed by the PM
170 * core to the system logs for debugging purposes. Still, it is recommended
171 * that drivers only return error codes from their resume methods in case of an
172 * unrecoverable failure (i.e. when the device being handled refuses to resume
173 * and becomes unusable) to allow us to modify the PM core in the future, so
174 * that it can avoid attempting to handle devices that failed to resume and
177 * It is allowed to unregister devices while the above callbacks are being
178 * executed. However, it is not allowed to unregister a device from within any
179 * of its own callbacks.
181 * There also are the following callbacks related to run-time power management
184 * @runtime_suspend: Prepare the device for a condition in which it won't be
185 * able to communicate with the CPU(s) and RAM due to power management.
186 * This need not mean that the device should be put into a low power state.
187 * For example, if the device is behind a link which is about to be turned
188 * off, the device may remain at full power. If the device does go to low
189 * power and is capable of generating run-time wake-up events, remote
190 * wake-up (i.e., a hardware mechanism allowing the device to request a
191 * change of its power state via a wake-up event, such as PCI PME) should
194 * @runtime_resume: Put the device into the fully active state in response to a
195 * wake-up event generated by hardware or at the request of software. If
196 * necessary, put the device into the full power state and restore its
197 * registers, so that it is fully operational.
199 * @runtime_idle: Device appears to be inactive and it might be put into a low
200 * power state if all of the necessary conditions are satisfied. Check
201 * these conditions and handle the device as appropriate, possibly queueing
202 * a suspend request for it. The return value is ignored by the PM core.
206 int (*prepare
)(struct device
*dev
);
207 void (*complete
)(struct device
*dev
);
208 int (*suspend
)(struct device
*dev
);
209 int (*resume
)(struct device
*dev
);
210 int (*freeze
)(struct device
*dev
);
211 int (*thaw
)(struct device
*dev
);
212 int (*poweroff
)(struct device
*dev
);
213 int (*restore
)(struct device
*dev
);
214 int (*suspend_noirq
)(struct device
*dev
);
215 int (*resume_noirq
)(struct device
*dev
);
216 int (*freeze_noirq
)(struct device
*dev
);
217 int (*thaw_noirq
)(struct device
*dev
);
218 int (*poweroff_noirq
)(struct device
*dev
);
219 int (*restore_noirq
)(struct device
*dev
);
220 int (*runtime_suspend
)(struct device
*dev
);
221 int (*runtime_resume
)(struct device
*dev
);
222 int (*runtime_idle
)(struct device
*dev
);
225 #ifdef CONFIG_PM_SLEEP
226 #define SET_SYSTEM_SLEEP_PM_OPS(suspend_fn, resume_fn) \
227 .suspend = suspend_fn, \
228 .resume = resume_fn, \
229 .freeze = suspend_fn, \
231 .poweroff = suspend_fn, \
232 .restore = resume_fn,
234 #define SET_SYSTEM_SLEEP_PM_OPS(suspend_fn, resume_fn)
237 #ifdef CONFIG_PM_RUNTIME
238 #define SET_RUNTIME_PM_OPS(suspend_fn, resume_fn, idle_fn) \
239 .runtime_suspend = suspend_fn, \
240 .runtime_resume = resume_fn, \
241 .runtime_idle = idle_fn,
243 #define SET_RUNTIME_PM_OPS(suspend_fn, resume_fn, idle_fn)
247 * Use this if you want to use the same suspend and resume callbacks for suspend
248 * to RAM and hibernation.
250 #define SIMPLE_DEV_PM_OPS(name, suspend_fn, resume_fn) \
251 const struct dev_pm_ops name = { \
252 SET_SYSTEM_SLEEP_PM_OPS(suspend_fn, resume_fn) \
256 * Use this for defining a set of PM operations to be used in all situations
257 * (sustem suspend, hibernation or runtime PM).
259 #define UNIVERSAL_DEV_PM_OPS(name, suspend_fn, resume_fn, idle_fn) \
260 const struct dev_pm_ops name = { \
261 SET_SYSTEM_SLEEP_PM_OPS(suspend_fn, resume_fn) \
262 SET_RUNTIME_PM_OPS(suspend_fn, resume_fn, idle_fn) \
266 * Use this for subsystems (bus types, device types, device classes) that don't
267 * need any special suspend/resume handling in addition to invoking the PM
268 * callbacks provided by device drivers supporting both the system sleep PM and
269 * runtime PM, make the pm member point to generic_subsys_pm_ops.
272 extern struct dev_pm_ops generic_subsys_pm_ops
;
273 #define GENERIC_SUBSYS_PM_OPS (&generic_subsys_pm_ops)
275 #define GENERIC_SUBSYS_PM_OPS NULL
281 * The following PM_EVENT_ messages are defined for the internal use of the PM
282 * core, in order to provide a mechanism allowing the high level suspend and
283 * hibernation code to convey the necessary information to the device PM core
288 * FREEZE System is going to hibernate, call ->prepare() and ->freeze()
291 * SUSPEND System is going to suspend, call ->prepare() and ->suspend()
294 * HIBERNATE Hibernation image has been saved, call ->prepare() and
295 * ->poweroff() for all devices.
297 * QUIESCE Contents of main memory are going to be restored from a (loaded)
298 * hibernation image, call ->prepare() and ->freeze() for all
301 * RESUME System is resuming, call ->resume() and ->complete() for all
304 * THAW Hibernation image has been created, call ->thaw() and
305 * ->complete() for all devices.
307 * RESTORE Contents of main memory have been restored from a hibernation
308 * image, call ->restore() and ->complete() for all devices.
310 * RECOVER Creation of a hibernation image or restoration of the main
311 * memory contents from a hibernation image has failed, call
312 * ->thaw() and ->complete() for all devices.
314 * The following PM_EVENT_ messages are defined for internal use by
315 * kernel subsystems. They are never issued by the PM core.
317 * USER_SUSPEND Manual selective suspend was issued by userspace.
319 * USER_RESUME Manual selective resume was issued by userspace.
321 * REMOTE_WAKEUP Remote-wakeup request was received from the device.
323 * AUTO_SUSPEND Automatic (device idle) runtime suspend was
324 * initiated by the subsystem.
326 * AUTO_RESUME Automatic (device needed) runtime resume was
327 * requested by a driver.
330 #define PM_EVENT_ON 0x0000
331 #define PM_EVENT_FREEZE 0x0001
332 #define PM_EVENT_SUSPEND 0x0002
333 #define PM_EVENT_HIBERNATE 0x0004
334 #define PM_EVENT_QUIESCE 0x0008
335 #define PM_EVENT_RESUME 0x0010
336 #define PM_EVENT_THAW 0x0020
337 #define PM_EVENT_RESTORE 0x0040
338 #define PM_EVENT_RECOVER 0x0080
339 #define PM_EVENT_USER 0x0100
340 #define PM_EVENT_REMOTE 0x0200
341 #define PM_EVENT_AUTO 0x0400
343 #define PM_EVENT_SLEEP (PM_EVENT_SUSPEND | PM_EVENT_HIBERNATE)
344 #define PM_EVENT_USER_SUSPEND (PM_EVENT_USER | PM_EVENT_SUSPEND)
345 #define PM_EVENT_USER_RESUME (PM_EVENT_USER | PM_EVENT_RESUME)
346 #define PM_EVENT_REMOTE_RESUME (PM_EVENT_REMOTE | PM_EVENT_RESUME)
347 #define PM_EVENT_AUTO_SUSPEND (PM_EVENT_AUTO | PM_EVENT_SUSPEND)
348 #define PM_EVENT_AUTO_RESUME (PM_EVENT_AUTO | PM_EVENT_RESUME)
350 #define PMSG_ON ((struct pm_message){ .event = PM_EVENT_ON, })
351 #define PMSG_FREEZE ((struct pm_message){ .event = PM_EVENT_FREEZE, })
352 #define PMSG_QUIESCE ((struct pm_message){ .event = PM_EVENT_QUIESCE, })
353 #define PMSG_SUSPEND ((struct pm_message){ .event = PM_EVENT_SUSPEND, })
354 #define PMSG_HIBERNATE ((struct pm_message){ .event = PM_EVENT_HIBERNATE, })
355 #define PMSG_RESUME ((struct pm_message){ .event = PM_EVENT_RESUME, })
356 #define PMSG_THAW ((struct pm_message){ .event = PM_EVENT_THAW, })
357 #define PMSG_RESTORE ((struct pm_message){ .event = PM_EVENT_RESTORE, })
358 #define PMSG_RECOVER ((struct pm_message){ .event = PM_EVENT_RECOVER, })
359 #define PMSG_USER_SUSPEND ((struct pm_message) \
360 { .event = PM_EVENT_USER_SUSPEND, })
361 #define PMSG_USER_RESUME ((struct pm_message) \
362 { .event = PM_EVENT_USER_RESUME, })
363 #define PMSG_REMOTE_RESUME ((struct pm_message) \
364 { .event = PM_EVENT_REMOTE_RESUME, })
365 #define PMSG_AUTO_SUSPEND ((struct pm_message) \
366 { .event = PM_EVENT_AUTO_SUSPEND, })
367 #define PMSG_AUTO_RESUME ((struct pm_message) \
368 { .event = PM_EVENT_AUTO_RESUME, })
371 * Device run-time power management status.
373 * These status labels are used internally by the PM core to indicate the
374 * current status of a device with respect to the PM core operations. They do
375 * not reflect the actual power state of the device or its status as seen by the
378 * RPM_ACTIVE Device is fully operational. Indicates that the device
379 * bus type's ->runtime_resume() callback has completed
382 * RPM_SUSPENDED Device bus type's ->runtime_suspend() callback has
383 * completed successfully. The device is regarded as
386 * RPM_RESUMING Device bus type's ->runtime_resume() callback is being
389 * RPM_SUSPENDING Device bus type's ->runtime_suspend() callback is being
401 * Device run-time power management request types.
403 * RPM_REQ_NONE Do nothing.
405 * RPM_REQ_IDLE Run the device bus type's ->runtime_idle() callback
407 * RPM_REQ_SUSPEND Run the device bus type's ->runtime_suspend() callback
409 * RPM_REQ_AUTOSUSPEND Same as RPM_REQ_SUSPEND, but not until the device has
410 * been inactive for as long as power.autosuspend_delay
412 * RPM_REQ_RESUME Run the device bus type's ->runtime_resume() callback
423 struct wakeup_source
;
425 struct pm_domain_data
{
426 struct list_head list_node
;
431 struct pm_subsys_data
{
433 unsigned int refcount
;
435 struct list_head clock_list
;
437 #ifdef CONFIG_PM_GENERIC_DOMAINS
438 struct pm_domain_data domain_data
;
443 pm_message_t power_state
;
444 unsigned int can_wakeup
:1;
445 unsigned int async_suspend
:1;
446 bool is_prepared
:1; /* Owned by the PM core */
447 bool is_suspended
:1; /* Ditto */
449 #ifdef CONFIG_PM_SLEEP
450 struct list_head entry
;
451 struct completion completion
;
452 struct wakeup_source
*wakeup
;
454 unsigned int should_wakeup
:1;
456 #ifdef CONFIG_PM_RUNTIME
457 struct timer_list suspend_timer
;
458 unsigned long timer_expires
;
459 struct work_struct work
;
460 wait_queue_head_t wait_queue
;
461 atomic_t usage_count
;
462 atomic_t child_count
;
463 unsigned int disable_depth
:3;
464 unsigned int ignore_children
:1;
465 unsigned int idle_notification
:1;
466 unsigned int request_pending
:1;
467 unsigned int deferred_resume
:1;
468 unsigned int run_wake
:1;
469 unsigned int runtime_auto
:1;
470 unsigned int no_callbacks
:1;
471 unsigned int irq_safe
:1;
472 unsigned int use_autosuspend
:1;
473 unsigned int timer_autosuspends
:1;
474 enum rpm_request request
;
475 enum rpm_status runtime_status
;
477 int autosuspend_delay
;
478 unsigned long last_busy
;
479 unsigned long active_jiffies
;
480 unsigned long suspended_jiffies
;
481 unsigned long accounting_timestamp
;
483 struct pm_subsys_data
*subsys_data
; /* Owned by the subsystem. */
486 extern void update_pm_runtime_accounting(struct device
*dev
);
487 extern int dev_pm_get_subsys_data(struct device
*dev
);
488 extern int dev_pm_put_subsys_data(struct device
*dev
);
491 * Power domains provide callbacks that are executed during system suspend,
492 * hibernation, system resume and during runtime PM transitions along with
493 * subsystem-level and driver-level callbacks.
495 struct dev_pm_domain
{
496 struct dev_pm_ops ops
;
500 * The PM_EVENT_ messages are also used by drivers implementing the legacy
501 * suspend framework, based on the ->suspend() and ->resume() callbacks common
502 * for suspend and hibernation transitions, according to the rules below.
505 /* Necessary, because several drivers use PM_EVENT_PRETHAW */
506 #define PM_EVENT_PRETHAW PM_EVENT_QUIESCE
509 * One transition is triggered by resume(), after a suspend() call; the
510 * message is implicit:
512 * ON Driver starts working again, responding to hardware events
513 * and software requests. The hardware may have gone through
514 * a power-off reset, or it may have maintained state from the
515 * previous suspend() which the driver will rely on while
516 * resuming. On most platforms, there are no restrictions on
517 * availability of resources like clocks during resume().
519 * Other transitions are triggered by messages sent using suspend(). All
520 * these transitions quiesce the driver, so that I/O queues are inactive.
521 * That commonly entails turning off IRQs and DMA; there may be rules
522 * about how to quiesce that are specific to the bus or the device's type.
523 * (For example, network drivers mark the link state.) Other details may
524 * differ according to the message:
526 * SUSPEND Quiesce, enter a low power device state appropriate for
527 * the upcoming system state (such as PCI_D3hot), and enable
528 * wakeup events as appropriate.
530 * HIBERNATE Enter a low power device state appropriate for the hibernation
531 * state (eg. ACPI S4) and enable wakeup events as appropriate.
533 * FREEZE Quiesce operations so that a consistent image can be saved;
534 * but do NOT otherwise enter a low power device state, and do
535 * NOT emit system wakeup events.
537 * PRETHAW Quiesce as if for FREEZE; additionally, prepare for restoring
538 * the system from a snapshot taken after an earlier FREEZE.
539 * Some drivers will need to reset their hardware state instead
540 * of preserving it, to ensure that it's never mistaken for the
541 * state which that earlier snapshot had set up.
543 * A minimally power-aware driver treats all messages as SUSPEND, fully
544 * reinitializes its device during resume() -- whether or not it was reset
545 * during the suspend/resume cycle -- and can't issue wakeup events.
547 * More power-aware drivers may also use low power states at runtime as
548 * well as during system sleep states like PM_SUSPEND_STANDBY. They may
549 * be able to use wakeup events to exit from runtime low-power states,
550 * or from system low-power states such as standby or suspend-to-RAM.
553 #ifdef CONFIG_PM_SLEEP
554 extern void device_pm_lock(void);
555 extern void dpm_resume_noirq(pm_message_t state
);
556 extern void dpm_resume_end(pm_message_t state
);
557 extern void dpm_resume(pm_message_t state
);
558 extern void dpm_complete(pm_message_t state
);
560 extern void device_pm_unlock(void);
561 extern int dpm_suspend_noirq(pm_message_t state
);
562 extern int dpm_suspend_start(pm_message_t state
);
563 extern int dpm_suspend(pm_message_t state
);
564 extern int dpm_prepare(pm_message_t state
);
566 extern void __suspend_report_result(const char *function
, void *fn
, int ret
);
568 #define suspend_report_result(fn, ret) \
570 __suspend_report_result(__func__, fn, ret); \
573 extern int device_pm_wait_for_dev(struct device
*sub
, struct device
*dev
);
575 extern int pm_generic_prepare(struct device
*dev
);
576 extern int pm_generic_suspend_noirq(struct device
*dev
);
577 extern int pm_generic_suspend(struct device
*dev
);
578 extern int pm_generic_resume_noirq(struct device
*dev
);
579 extern int pm_generic_resume(struct device
*dev
);
580 extern int pm_generic_freeze_noirq(struct device
*dev
);
581 extern int pm_generic_freeze(struct device
*dev
);
582 extern int pm_generic_thaw_noirq(struct device
*dev
);
583 extern int pm_generic_thaw(struct device
*dev
);
584 extern int pm_generic_restore_noirq(struct device
*dev
);
585 extern int pm_generic_restore(struct device
*dev
);
586 extern int pm_generic_poweroff_noirq(struct device
*dev
);
587 extern int pm_generic_poweroff(struct device
*dev
);
588 extern void pm_generic_complete(struct device
*dev
);
590 #else /* !CONFIG_PM_SLEEP */
592 #define device_pm_lock() do {} while (0)
593 #define device_pm_unlock() do {} while (0)
595 static inline int dpm_suspend_start(pm_message_t state
)
600 #define suspend_report_result(fn, ret) do {} while (0)
602 static inline int device_pm_wait_for_dev(struct device
*a
, struct device
*b
)
607 #define pm_generic_prepare NULL
608 #define pm_generic_suspend NULL
609 #define pm_generic_resume NULL
610 #define pm_generic_freeze NULL
611 #define pm_generic_thaw NULL
612 #define pm_generic_restore NULL
613 #define pm_generic_poweroff NULL
614 #define pm_generic_complete NULL
615 #endif /* !CONFIG_PM_SLEEP */
617 /* How to reorder dpm_list after device_move() */
620 DPM_ORDER_DEV_AFTER_PARENT
,
621 DPM_ORDER_PARENT_BEFORE_DEV
,
625 #endif /* _LINUX_PM_H */