Line data Source code
1 : /*
2 : * pm.h - Power management interface
3 : *
4 : * Copyright (C) 2000 Andrew Henroid
5 : *
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.
10 : *
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.
15 : *
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
19 : */
20 :
21 : #ifndef _LINUX_PM_H
22 : #define _LINUX_PM_H
23 :
24 : #include <linux/list.h>
25 : #include <linux/workqueue.h>
26 : #include <linux/spinlock.h>
27 : #include <linux/wait.h>
28 : #include <linux/timer.h>
29 :
30 : /*
31 : * Callbacks for platform drivers to implement.
32 : */
33 : extern void (*pm_idle)(void);
34 : extern void (*pm_power_off)(void);
35 : extern void (*pm_power_off_prepare)(void);
36 1 :
37 : /*
38 : * Device power management
39 : */
40 :
41 : struct device;
42 :
43 : typedef struct pm_message {
44 : int event;
45 1 : } pm_message_t;
46 1 :
47 : /**
48 : * struct dev_pm_ops - device PM callbacks
49 : *
50 : * Several driver power state transitions are externally visible, affecting
51 : * the state of pending I/O queues and (for drivers that touch hardware)
52 : * interrupts, wakeups, DMA, and other hardware state. There may also be
53 : * internal transitions to various low power modes, which are transparent
54 : * to the rest of the driver stack (such as a driver that's ON gating off
55 : * clocks which are not in active use).
56 : *
57 : * The externally visible transitions are handled with the help of the following
58 : * callbacks included in this structure:
59 : *
60 : * @prepare: Prepare the device for the upcoming transition, but do NOT change
61 : * its hardware state. Prevent new children of the device from being
62 : * registered after @prepare() returns (the driver's subsystem and
63 : * generally the rest of the kernel is supposed to prevent new calls to the
64 : * probe method from being made too once @prepare() has succeeded). If
65 : * @prepare() detects a situation it cannot handle (e.g. registration of a
66 : * child already in progress), it may return -EAGAIN, so that the PM core
67 : * can execute it once again (e.g. after the new child has been registered)
68 : * to recover from the race condition. This method is executed for all
69 : * kinds of suspend transitions and is followed by one of the suspend
70 : * callbacks: @suspend(), @freeze(), or @poweroff().
71 : * The PM core executes @prepare() for all devices before starting to
72 : * execute suspend callbacks for any of them, so drivers may assume all of
73 : * the other devices to be present and functional while @prepare() is being
74 : * executed. In particular, it is safe to make GFP_KERNEL memory
75 : * allocations from within @prepare(). However, drivers may NOT assume
76 : * anything about the availability of the user space at that time and it
77 : * is not correct to request firmware from within @prepare() (it's too
78 : * late to do that). [To work around this limitation, drivers may
79 : * register suspend and hibernation notifiers that are executed before the
80 : * freezing of tasks.]
81 : *
82 : * @complete: Undo the changes made by @prepare(). This method is executed for
83 : * all kinds of resume transitions, following one of the resume callbacks:
84 : * @resume(), @thaw(), @restore(). Also called if the state transition
85 : * fails before the driver's suspend callback (@suspend(), @freeze(),
86 : * @poweroff()) can be executed (e.g. if the suspend callback fails for one
87 : * of the other devices that the PM core has unsuccessfully attempted to
88 : * suspend earlier).
89 : * The PM core executes @complete() after it has executed the appropriate
90 : * resume callback for all devices.
91 : *
92 : * @suspend: Executed before putting the system into a sleep state in which the
93 : * contents of main memory are preserved. Quiesce the device, put it into
94 : * a low power state appropriate for the upcoming system state (such as
95 : * PCI_D3hot), and enable wakeup events as appropriate.
96 : *
97 : * @resume: Executed after waking the system up from a sleep state in which the
98 : * contents of main memory were preserved. Put the device into the
99 : * appropriate state, according to the information saved in memory by the
100 : * preceding @suspend(). The driver starts working again, responding to
101 : * hardware events and software requests. The hardware may have gone
102 : * through a power-off reset, or it may have maintained state from the
103 : * previous suspend() which the driver may rely on while resuming. On most
104 : * platforms, there are no restrictions on availability of resources like
105 : * clocks during @resume().
106 : *
107 : * @freeze: Hibernation-specific, executed before creating a hibernation image.
108 : * Quiesce operations so that a consistent image can be created, but do NOT
109 : * otherwise put the device into a low power device state and do NOT emit
110 : * system wakeup events. Save in main memory the device settings to be
111 : * used by @restore() during the subsequent resume from hibernation or by
112 : * the subsequent @thaw(), if the creation of the image or the restoration
113 : * of main memory contents from it fails.
114 : *
115 : * @thaw: Hibernation-specific, executed after creating a hibernation image OR
116 : * if the creation of the image fails. Also executed after a failing
117 : * attempt to restore the contents of main memory from such an image.
118 : * Undo the changes made by the preceding @freeze(), so the device can be
119 : * operated in the same way as immediately before the call to @freeze().
120 : *
121 : * @poweroff: Hibernation-specific, executed after saving a hibernation image.
122 : * Quiesce the device, put it into a low power state appropriate for the
123 : * upcoming system state (such as PCI_D3hot), and enable wakeup events as
124 : * appropriate.
125 : *
126 : * @restore: Hibernation-specific, executed after restoring the contents of main
127 : * memory from a hibernation image. Driver starts working again,
128 : * responding to hardware events and software requests. Drivers may NOT
129 : * make ANY assumptions about the hardware state right prior to @restore().
130 : * On most platforms, there are no restrictions on availability of
131 : * resources like clocks during @restore().
132 : *
133 : * @suspend_noirq: Complete the operations of ->suspend() by carrying out any
134 : * actions required for suspending the device that need interrupts to be
135 : * disabled
136 : *
137 : * @resume_noirq: Prepare for the execution of ->resume() by carrying out any
138 : * actions required for resuming the device that need interrupts to be
139 : * disabled
140 : *
141 : * @freeze_noirq: Complete the operations of ->freeze() by carrying out any
142 : * actions required for freezing the device that need interrupts to be
143 : * disabled
144 : *
145 : * @thaw_noirq: Prepare for the execution of ->thaw() by carrying out any
146 : * actions required for thawing the device that need interrupts to be
147 : * disabled
148 : *
149 : * @poweroff_noirq: Complete the operations of ->poweroff() by carrying out any
150 : * actions required for handling the device that need interrupts to be
151 : * disabled
152 : *
153 : * @restore_noirq: Prepare for the execution of ->restore() by carrying out any
154 : * actions required for restoring the operations of the device that need
155 : * interrupts to be disabled
156 : *
157 : * All of the above callbacks, except for @complete(), return error codes.
158 : * However, the error codes returned by the resume operations, @resume(),
159 : * @thaw(), @restore(), @resume_noirq(), @thaw_noirq(), and @restore_noirq() do
160 : * not cause the PM core to abort the resume transition during which they are
161 : * returned. The error codes returned in that cases are only printed by the PM
162 : * core to the system logs for debugging purposes. Still, it is recommended
163 : * that drivers only return error codes from their resume methods in case of an
164 : * unrecoverable failure (i.e. when the device being handled refuses to resume
165 : * and becomes unusable) to allow us to modify the PM core in the future, so
166 : * that it can avoid attempting to handle devices that failed to resume and
167 : * their children.
168 : *
169 : * It is allowed to unregister devices while the above callbacks are being
170 : * executed. However, it is not allowed to unregister a device from within any
171 : * of its own callbacks.
172 : *
173 : * There also are the following callbacks related to run-time power management
174 : * of devices:
175 : *
176 : * @runtime_suspend: Prepare the device for a condition in which it won't be
177 : * able to communicate with the CPU(s) and RAM due to power management.
178 : * This need not mean that the device should be put into a low power state.
179 : * For example, if the device is behind a link which is about to be turned
180 : * off, the device may remain at full power. If the device does go to low
181 : * power and is capable of generating run-time wake-up events, remote
182 : * wake-up (i.e., a hardware mechanism allowing the device to request a
183 : * change of its power state via a wake-up event, such as PCI PME) should
184 : * be enabled for it.
185 : *
186 : * @runtime_resume: Put the device into the fully active state in response to a
187 : * wake-up event generated by hardware or at the request of software. If
188 : * necessary, put the device into the full power state and restore its
189 : * registers, so that it is fully operational.
190 : *
191 : * @runtime_idle: Device appears to be inactive and it might be put into a low
192 : * power state if all of the necessary conditions are satisfied. Check
193 : * these conditions and handle the device as appropriate, possibly queueing
194 : * a suspend request for it. The return value is ignored by the PM core.
195 : */
196 :
197 : struct dev_pm_ops {
198 : int (*prepare)(struct device *dev);
199 : void (*complete)(struct device *dev);
200 : int (*suspend)(struct device *dev);
201 : int (*resume)(struct device *dev);
202 : int (*freeze)(struct device *dev);
203 : int (*thaw)(struct device *dev);
204 : int (*poweroff)(struct device *dev);
205 : int (*restore)(struct device *dev);
206 : int (*suspend_noirq)(struct device *dev);
207 : int (*resume_noirq)(struct device *dev);
208 : int (*freeze_noirq)(struct device *dev);
209 : int (*thaw_noirq)(struct device *dev);
210 : int (*poweroff_noirq)(struct device *dev);
211 : int (*restore_noirq)(struct device *dev);
212 : int (*runtime_suspend)(struct device *dev);
213 : int (*runtime_resume)(struct device *dev);
214 : int (*runtime_idle)(struct device *dev);
215 : };
216 1 :
217 : /*
218 : * Use this if you want to use the same suspend and resume callbacks for suspend
219 : * to RAM and hibernation.
220 : */
221 : #define SIMPLE_DEV_PM_OPS(name, suspend_fn, resume_fn) \
222 : const struct dev_pm_ops name = { \
223 : .suspend = suspend_fn, \
224 : .resume = resume_fn, \
225 : .freeze = suspend_fn, \
226 : .thaw = resume_fn, \
227 : .poweroff = suspend_fn, \
228 : .restore = resume_fn, \
229 : }
230 :
231 : /**
232 : * PM_EVENT_ messages
233 : *
234 : * The following PM_EVENT_ messages are defined for the internal use of the PM
235 : * core, in order to provide a mechanism allowing the high level suspend and
236 : * hibernation code to convey the necessary information to the device PM core
237 : * code:
238 : *
239 : * ON No transition.
240 1 : *
241 : * FREEZE System is going to hibernate, call ->prepare() and ->freeze()
242 : * for all devices.
243 : *
244 : * SUSPEND System is going to suspend, call ->prepare() and ->suspend()
245 : * for all devices.
246 : *
247 : * HIBERNATE Hibernation image has been saved, call ->prepare() and
248 : * ->poweroff() for all devices.
249 : *
250 : * QUIESCE Contents of main memory are going to be restored from a (loaded)
251 : * hibernation image, call ->prepare() and ->freeze() for all
252 : * devices.
253 : *
254 : * RESUME System is resuming, call ->resume() and ->complete() for all
255 : * devices.
256 : *
257 : * THAW Hibernation image has been created, call ->thaw() and
258 : * ->complete() for all devices.
259 : *
260 : * RESTORE Contents of main memory have been restored from a hibernation
261 : * image, call ->restore() and ->complete() for all devices.
262 : *
263 : * RECOVER Creation of a hibernation image or restoration of the main
264 : * memory contents from a hibernation image has failed, call
265 : * ->thaw() and ->complete() for all devices.
266 : *
267 : * The following PM_EVENT_ messages are defined for internal use by
268 : * kernel subsystems. They are never issued by the PM core.
269 : *
270 : * USER_SUSPEND Manual selective suspend was issued by userspace.
271 : *
272 : * USER_RESUME Manual selective resume was issued by userspace.
273 : *
274 : * REMOTE_WAKEUP Remote-wakeup request was received from the device.
275 : *
276 : * AUTO_SUSPEND Automatic (device idle) runtime suspend was
277 : * initiated by the subsystem.
278 : *
279 : * AUTO_RESUME Automatic (device needed) runtime resume was
280 : * requested by a driver.
281 : */
282 :
283 : #define PM_EVENT_ON 0x0000
284 : #define PM_EVENT_FREEZE 0x0001
285 : #define PM_EVENT_SUSPEND 0x0002
286 : #define PM_EVENT_HIBERNATE 0x0004
287 : #define PM_EVENT_QUIESCE 0x0008
288 : #define PM_EVENT_RESUME 0x0010
289 : #define PM_EVENT_THAW 0x0020
290 : #define PM_EVENT_RESTORE 0x0040
291 : #define PM_EVENT_RECOVER 0x0080
292 : #define PM_EVENT_USER 0x0100
293 : #define PM_EVENT_REMOTE 0x0200
294 : #define PM_EVENT_AUTO 0x0400
295 :
296 : #define PM_EVENT_SLEEP (PM_EVENT_SUSPEND | PM_EVENT_HIBERNATE)
297 : #define PM_EVENT_USER_SUSPEND (PM_EVENT_USER | PM_EVENT_SUSPEND)
298 : #define PM_EVENT_USER_RESUME (PM_EVENT_USER | PM_EVENT_RESUME)
299 : #define PM_EVENT_REMOTE_RESUME (PM_EVENT_REMOTE | PM_EVENT_RESUME)
300 : #define PM_EVENT_AUTO_SUSPEND (PM_EVENT_AUTO | PM_EVENT_SUSPEND)
301 : #define PM_EVENT_AUTO_RESUME (PM_EVENT_AUTO | PM_EVENT_RESUME)
302 :
303 : #define PMSG_ON ((struct pm_message){ .event = PM_EVENT_ON, })
304 : #define PMSG_FREEZE ((struct pm_message){ .event = PM_EVENT_FREEZE, })
305 : #define PMSG_QUIESCE ((struct pm_message){ .event = PM_EVENT_QUIESCE, })
306 : #define PMSG_SUSPEND ((struct pm_message){ .event = PM_EVENT_SUSPEND, })
307 : #define PMSG_HIBERNATE ((struct pm_message){ .event = PM_EVENT_HIBERNATE, })
308 : #define PMSG_RESUME ((struct pm_message){ .event = PM_EVENT_RESUME, })
309 : #define PMSG_THAW ((struct pm_message){ .event = PM_EVENT_THAW, })
310 : #define PMSG_RESTORE ((struct pm_message){ .event = PM_EVENT_RESTORE, })
311 : #define PMSG_RECOVER ((struct pm_message){ .event = PM_EVENT_RECOVER, })
312 : #define PMSG_USER_SUSPEND ((struct pm_message) \
313 : { .event = PM_EVENT_USER_SUSPEND, })
314 : #define PMSG_USER_RESUME ((struct pm_message) \
315 : { .event = PM_EVENT_USER_RESUME, })
316 : #define PMSG_REMOTE_RESUME ((struct pm_message) \
317 : { .event = PM_EVENT_REMOTE_RESUME, })
318 : #define PMSG_AUTO_SUSPEND ((struct pm_message) \
319 : { .event = PM_EVENT_AUTO_SUSPEND, })
320 : #define PMSG_AUTO_RESUME ((struct pm_message) \
321 : { .event = PM_EVENT_AUTO_RESUME, })
322 :
323 : /**
324 : * Device power management states
325 : *
326 : * These state labels are used internally by the PM core to indicate the current
327 : * status of a device with respect to the PM core operations.
328 : *
329 : * DPM_ON Device is regarded as operational. Set this way
330 : * initially and when ->complete() is about to be called.
331 : * Also set when ->prepare() fails.
332 : *
333 : * DPM_PREPARING Device is going to be prepared for a PM transition. Set
334 : * when ->prepare() is about to be called.
335 : *
336 : * DPM_RESUMING Device is going to be resumed. Set when ->resume(),
337 : * ->thaw(), or ->restore() is about to be called.
338 : *
339 : * DPM_SUSPENDING Device has been prepared for a power transition. Set
340 : * when ->prepare() has just succeeded.
341 : *
342 : * DPM_OFF Device is regarded as inactive. Set immediately after
343 : * ->suspend(), ->freeze(), or ->poweroff() has succeeded.
344 : * Also set when ->resume()_noirq, ->thaw_noirq(), or
345 : * ->restore_noirq() is about to be called.
346 : *
347 : * DPM_OFF_IRQ Device is in a "deep sleep". Set immediately after
348 : * ->suspend_noirq(), ->freeze_noirq(), or
349 : * ->poweroff_noirq() has just succeeded.
350 : */
351 :
352 : enum dpm_state {
353 : DPM_INVALID,
354 : DPM_ON,
355 : DPM_PREPARING,
356 : DPM_RESUMING,
357 : DPM_SUSPENDING,
358 : DPM_OFF,
359 : DPM_OFF_IRQ,
360 : };
361 :
362 : /**
363 : * Device run-time power management status.
364 : *
365 : * These status labels are used internally by the PM core to indicate the
366 : * current status of a device with respect to the PM core operations. They do
367 : * not reflect the actual power state of the device or its status as seen by the
368 : * driver.
369 : *
370 : * RPM_ACTIVE Device is fully operational. Indicates that the device
371 : * bus type's ->runtime_resume() callback has completed
372 : * successfully.
373 : *
374 : * RPM_SUSPENDED Device bus type's ->runtime_suspend() callback has
375 : * completed successfully. The device is regarded as
376 : * suspended.
377 : *
378 : * RPM_RESUMING Device bus type's ->runtime_resume() callback is being
379 : * executed.
380 : *
381 : * RPM_SUSPENDING Device bus type's ->runtime_suspend() callback is being
382 : * executed.
383 : */
384 :
385 : enum rpm_status {
386 : RPM_ACTIVE = 0,
387 : RPM_RESUMING,
388 : RPM_SUSPENDED,
389 : RPM_SUSPENDING,
390 : };
391 :
392 : /**
393 : * Device run-time power management request types.
394 : *
395 : * RPM_REQ_NONE Do nothing.
396 : *
397 : * RPM_REQ_IDLE Run the device bus type's ->runtime_idle() callback
398 : *
399 : * RPM_REQ_SUSPEND Run the device bus type's ->runtime_suspend() callback
400 : *
401 : * RPM_REQ_RESUME Run the device bus type's ->runtime_resume() callback
402 : */
403 :
404 : enum rpm_request {
405 : RPM_REQ_NONE = 0,
406 : RPM_REQ_IDLE,
407 : RPM_REQ_SUSPEND,
408 : RPM_REQ_RESUME,
409 : };
410 :
411 : struct dev_pm_info {
412 : pm_message_t power_state;
413 : unsigned int can_wakeup:1;
414 : unsigned int should_wakeup:1;
415 : enum dpm_state status; /* Owned by the PM core */
416 : #ifdef CONFIG_PM_SLEEP
417 : struct list_head entry;
418 : #endif
419 : #ifdef CONFIG_PM_RUNTIME
420 : struct timer_list suspend_timer;
421 : unsigned long timer_expires;
422 : struct work_struct work;
423 : wait_queue_head_t wait_queue;
424 : spinlock_t lock;
425 : atomic_t usage_count;
426 : atomic_t child_count;
427 : unsigned int disable_depth:3;
428 : unsigned int ignore_children:1;
429 : unsigned int idle_notification:1;
430 : unsigned int request_pending:1;
431 : unsigned int deferred_resume:1;
432 : unsigned int run_wake:1;
433 : enum rpm_request request;
434 : enum rpm_status runtime_status;
435 : int runtime_error;
436 : #endif
437 : };
438 :
439 : /*
440 : * The PM_EVENT_ messages are also used by drivers implementing the legacy
441 : * suspend framework, based on the ->suspend() and ->resume() callbacks common
442 : * for suspend and hibernation transitions, according to the rules below.
443 : */
444 :
445 : /* Necessary, because several drivers use PM_EVENT_PRETHAW */
446 : #define PM_EVENT_PRETHAW PM_EVENT_QUIESCE
447 :
448 : /*
449 : * One transition is triggered by resume(), after a suspend() call; the
450 : * message is implicit:
451 : *
452 : * ON Driver starts working again, responding to hardware events
453 : * and software requests. The hardware may have gone through
454 : * a power-off reset, or it may have maintained state from the
455 : * previous suspend() which the driver will rely on while
456 : * resuming. On most platforms, there are no restrictions on
457 : * availability of resources like clocks during resume().
458 : *
459 : * Other transitions are triggered by messages sent using suspend(). All
460 : * these transitions quiesce the driver, so that I/O queues are inactive.
461 : * That commonly entails turning off IRQs and DMA; there may be rules
462 : * about how to quiesce that are specific to the bus or the device's type.
463 : * (For example, network drivers mark the link state.) Other details may
464 : * differ according to the message:
465 : *
466 : * SUSPEND Quiesce, enter a low power device state appropriate for
467 : * the upcoming system state (such as PCI_D3hot), and enable
468 : * wakeup events as appropriate.
469 : *
470 : * HIBERNATE Enter a low power device state appropriate for the hibernation
471 : * state (eg. ACPI S4) and enable wakeup events as appropriate.
472 : *
473 : * FREEZE Quiesce operations so that a consistent image can be saved;
474 : * but do NOT otherwise enter a low power device state, and do
475 : * NOT emit system wakeup events.
476 : *
477 : * PRETHAW Quiesce as if for FREEZE; additionally, prepare for restoring
478 : * the system from a snapshot taken after an earlier FREEZE.
479 : * Some drivers will need to reset their hardware state instead
480 : * of preserving it, to ensure that it's never mistaken for the
481 : * state which that earlier snapshot had set up.
482 : *
483 : * A minimally power-aware driver treats all messages as SUSPEND, fully
484 : * reinitializes its device during resume() -- whether or not it was reset
485 : * during the suspend/resume cycle -- and can't issue wakeup events.
486 : *
487 : * More power-aware drivers may also use low power states at runtime as
488 : * well as during system sleep states like PM_SUSPEND_STANDBY. They may
489 : * be able to use wakeup events to exit from runtime low-power states,
490 : * or from system low-power states such as standby or suspend-to-RAM.
491 : */
492 :
493 : #ifdef CONFIG_PM_SLEEP
494 : extern void device_pm_lock(void);
495 : extern int sysdev_resume(void);
496 : extern void dpm_resume_noirq(pm_message_t state);
497 : extern void dpm_resume_end(pm_message_t state);
498 :
499 : extern void device_pm_unlock(void);
500 : extern int sysdev_suspend(pm_message_t state);
501 : extern int dpm_suspend_noirq(pm_message_t state);
502 : extern int dpm_suspend_start(pm_message_t state);
503 :
504 : extern void __suspend_report_result(const char *function, void *fn, int ret);
505 :
506 : #define suspend_report_result(fn, ret) \
507 : do { \
508 : __suspend_report_result(__func__, fn, ret); \
509 : } while (0)
510 :
511 : #else /* !CONFIG_PM_SLEEP */
512 :
513 : #define device_pm_lock() do {} while (0)
514 : #define device_pm_unlock() do {} while (0)
515 :
516 : static inline int dpm_suspend_start(pm_message_t state)
517 : {
518 : return 0;
519 : }
520 :
521 : #define suspend_report_result(fn, ret) do {} while (0)
522 :
523 : #endif /* !CONFIG_PM_SLEEP */
524 :
525 : /* How to reorder dpm_list after device_move() */
526 : enum dpm_order {
527 : DPM_ORDER_NONE,
528 : DPM_ORDER_DEV_AFTER_PARENT,
529 : DPM_ORDER_PARENT_BEFORE_DEV,
530 : DPM_ORDER_DEV_LAST,
531 : };
532 :
533 : /*
534 : * Global Power Management flags
535 : * Used to keep APM and ACPI from both being active
536 : */
537 : extern unsigned int pm_flags;
538 :
539 : #define PM_APM 1
540 : #define PM_ACPI 2
541 :
542 : #endif /* _LINUX_PM_H */
|