Commit | Line | Data |
---|---|---|
1da177e4 LT |
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 | ||
1da177e4 | 24 | #include <linux/list.h> |
1da177e4 | 25 | |
1da177e4 LT |
26 | /* |
27 | * Callbacks for platform drivers to implement. | |
28 | */ | |
29 | extern void (*pm_idle)(void); | |
30 | extern void (*pm_power_off)(void); | |
bd804eba | 31 | extern void (*pm_power_off_prepare)(void); |
1da177e4 | 32 | |
1da177e4 LT |
33 | /* |
34 | * Device power management | |
35 | */ | |
36 | ||
37 | struct device; | |
38 | ||
ca078bae PM |
39 | typedef struct pm_message { |
40 | int event; | |
41 | } pm_message_t; | |
1da177e4 | 42 | |
1eede070 | 43 | /** |
adf09493 | 44 | * struct dev_pm_ops - device PM callbacks |
1eede070 | 45 | * |
82bb67f2 DB |
46 | * Several driver power state transitions are externally visible, affecting |
47 | * the state of pending I/O queues and (for drivers that touch hardware) | |
48 | * interrupts, wakeups, DMA, and other hardware state. There may also be | |
49 | * internal transitions to various low power modes, which are transparent | |
50 | * to the rest of the driver stack (such as a driver that's ON gating off | |
51 | * clocks which are not in active use). | |
1da177e4 | 52 | * |
1eede070 RW |
53 | * The externally visible transitions are handled with the help of the following |
54 | * callbacks included in this structure: | |
55 | * | |
56 | * @prepare: Prepare the device for the upcoming transition, but do NOT change | |
57 | * its hardware state. Prevent new children of the device from being | |
58 | * registered after @prepare() returns (the driver's subsystem and | |
59 | * generally the rest of the kernel is supposed to prevent new calls to the | |
60 | * probe method from being made too once @prepare() has succeeded). If | |
61 | * @prepare() detects a situation it cannot handle (e.g. registration of a | |
62 | * child already in progress), it may return -EAGAIN, so that the PM core | |
63 | * can execute it once again (e.g. after the new child has been registered) | |
64 | * to recover from the race condition. This method is executed for all | |
65 | * kinds of suspend transitions and is followed by one of the suspend | |
66 | * callbacks: @suspend(), @freeze(), or @poweroff(). | |
67 | * The PM core executes @prepare() for all devices before starting to | |
68 | * execute suspend callbacks for any of them, so drivers may assume all of | |
69 | * the other devices to be present and functional while @prepare() is being | |
70 | * executed. In particular, it is safe to make GFP_KERNEL memory | |
71 | * allocations from within @prepare(). However, drivers may NOT assume | |
72 | * anything about the availability of the user space at that time and it | |
73 | * is not correct to request firmware from within @prepare() (it's too | |
74 | * late to do that). [To work around this limitation, drivers may | |
75 | * register suspend and hibernation notifiers that are executed before the | |
76 | * freezing of tasks.] | |
77 | * | |
78 | * @complete: Undo the changes made by @prepare(). This method is executed for | |
79 | * all kinds of resume transitions, following one of the resume callbacks: | |
80 | * @resume(), @thaw(), @restore(). Also called if the state transition | |
81 | * fails before the driver's suspend callback (@suspend(), @freeze(), | |
82 | * @poweroff()) can be executed (e.g. if the suspend callback fails for one | |
83 | * of the other devices that the PM core has unsuccessfully attempted to | |
84 | * suspend earlier). | |
85 | * The PM core executes @complete() after it has executed the appropriate | |
86 | * resume callback for all devices. | |
87 | * | |
88 | * @suspend: Executed before putting the system into a sleep state in which the | |
89 | * contents of main memory are preserved. Quiesce the device, put it into | |
90 | * a low power state appropriate for the upcoming system state (such as | |
91 | * PCI_D3hot), and enable wakeup events as appropriate. | |
92 | * | |
93 | * @resume: Executed after waking the system up from a sleep state in which the | |
94 | * contents of main memory were preserved. Put the device into the | |
95 | * appropriate state, according to the information saved in memory by the | |
96 | * preceding @suspend(). The driver starts working again, responding to | |
97 | * hardware events and software requests. The hardware may have gone | |
98 | * through a power-off reset, or it may have maintained state from the | |
99 | * previous suspend() which the driver may rely on while resuming. On most | |
100 | * platforms, there are no restrictions on availability of resources like | |
101 | * clocks during @resume(). | |
102 | * | |
103 | * @freeze: Hibernation-specific, executed before creating a hibernation image. | |
104 | * Quiesce operations so that a consistent image can be created, but do NOT | |
105 | * otherwise put the device into a low power device state and do NOT emit | |
106 | * system wakeup events. Save in main memory the device settings to be | |
107 | * used by @restore() during the subsequent resume from hibernation or by | |
108 | * the subsequent @thaw(), if the creation of the image or the restoration | |
109 | * of main memory contents from it fails. | |
110 | * | |
111 | * @thaw: Hibernation-specific, executed after creating a hibernation image OR | |
112 | * if the creation of the image fails. Also executed after a failing | |
113 | * attempt to restore the contents of main memory from such an image. | |
114 | * Undo the changes made by the preceding @freeze(), so the device can be | |
115 | * operated in the same way as immediately before the call to @freeze(). | |
116 | * | |
117 | * @poweroff: Hibernation-specific, executed after saving a hibernation image. | |
118 | * Quiesce the device, put it into a low power state appropriate for the | |
119 | * upcoming system state (such as PCI_D3hot), and enable wakeup events as | |
120 | * appropriate. | |
121 | * | |
122 | * @restore: Hibernation-specific, executed after restoring the contents of main | |
123 | * memory from a hibernation image. Driver starts working again, | |
124 | * responding to hardware events and software requests. Drivers may NOT | |
125 | * make ANY assumptions about the hardware state right prior to @restore(). | |
126 | * On most platforms, there are no restrictions on availability of | |
127 | * resources like clocks during @restore(). | |
128 | * | |
1eede070 RW |
129 | * @suspend_noirq: Complete the operations of ->suspend() by carrying out any |
130 | * actions required for suspending the device that need interrupts to be | |
131 | * disabled | |
132 | * | |
133 | * @resume_noirq: Prepare for the execution of ->resume() by carrying out any | |
134 | * actions required for resuming the device that need interrupts to be | |
135 | * disabled | |
136 | * | |
137 | * @freeze_noirq: Complete the operations of ->freeze() by carrying out any | |
138 | * actions required for freezing the device that need interrupts to be | |
139 | * disabled | |
140 | * | |
141 | * @thaw_noirq: Prepare for the execution of ->thaw() by carrying out any | |
142 | * actions required for thawing the device that need interrupts to be | |
143 | * disabled | |
144 | * | |
145 | * @poweroff_noirq: Complete the operations of ->poweroff() by carrying out any | |
146 | * actions required for handling the device that need interrupts to be | |
147 | * disabled | |
148 | * | |
149 | * @restore_noirq: Prepare for the execution of ->restore() by carrying out any | |
150 | * actions required for restoring the operations of the device that need | |
151 | * interrupts to be disabled | |
152 | * | |
adf09493 RW |
153 | * All of the above callbacks, except for @complete(), return error codes. |
154 | * However, the error codes returned by the resume operations, @resume(), | |
155 | * @thaw(), @restore(), @resume_noirq(), @thaw_noirq(), and @restore_noirq() do | |
156 | * not cause the PM core to abort the resume transition during which they are | |
157 | * returned. The error codes returned in that cases are only printed by the PM | |
158 | * core to the system logs for debugging purposes. Still, it is recommended | |
159 | * that drivers only return error codes from their resume methods in case of an | |
160 | * unrecoverable failure (i.e. when the device being handled refuses to resume | |
161 | * and becomes unusable) to allow us to modify the PM core in the future, so | |
162 | * that it can avoid attempting to handle devices that failed to resume and | |
163 | * their children. | |
164 | * | |
165 | * It is allowed to unregister devices while the above callbacks are being | |
166 | * executed. However, it is not allowed to unregister a device from within any | |
167 | * of its own callbacks. | |
1eede070 RW |
168 | */ |
169 | ||
adf09493 RW |
170 | struct dev_pm_ops { |
171 | int (*prepare)(struct device *dev); | |
172 | void (*complete)(struct device *dev); | |
173 | int (*suspend)(struct device *dev); | |
174 | int (*resume)(struct device *dev); | |
175 | int (*freeze)(struct device *dev); | |
176 | int (*thaw)(struct device *dev); | |
177 | int (*poweroff)(struct device *dev); | |
178 | int (*restore)(struct device *dev); | |
1eede070 RW |
179 | int (*suspend_noirq)(struct device *dev); |
180 | int (*resume_noirq)(struct device *dev); | |
181 | int (*freeze_noirq)(struct device *dev); | |
182 | int (*thaw_noirq)(struct device *dev); | |
183 | int (*poweroff_noirq)(struct device *dev); | |
184 | int (*restore_noirq)(struct device *dev); | |
185 | }; | |
186 | ||
187 | /** | |
188 | * PM_EVENT_ messages | |
189 | * | |
190 | * The following PM_EVENT_ messages are defined for the internal use of the PM | |
191 | * core, in order to provide a mechanism allowing the high level suspend and | |
192 | * hibernation code to convey the necessary information to the device PM core | |
193 | * code: | |
194 | * | |
195 | * ON No transition. | |
196 | * | |
197 | * FREEZE System is going to hibernate, call ->prepare() and ->freeze() | |
198 | * for all devices. | |
199 | * | |
200 | * SUSPEND System is going to suspend, call ->prepare() and ->suspend() | |
201 | * for all devices. | |
202 | * | |
203 | * HIBERNATE Hibernation image has been saved, call ->prepare() and | |
204 | * ->poweroff() for all devices. | |
205 | * | |
206 | * QUIESCE Contents of main memory are going to be restored from a (loaded) | |
207 | * hibernation image, call ->prepare() and ->freeze() for all | |
208 | * devices. | |
209 | * | |
210 | * RESUME System is resuming, call ->resume() and ->complete() for all | |
211 | * devices. | |
212 | * | |
213 | * THAW Hibernation image has been created, call ->thaw() and | |
214 | * ->complete() for all devices. | |
215 | * | |
216 | * RESTORE Contents of main memory have been restored from a hibernation | |
217 | * image, call ->restore() and ->complete() for all devices. | |
218 | * | |
219 | * RECOVER Creation of a hibernation image or restoration of the main | |
220 | * memory contents from a hibernation image has failed, call | |
221 | * ->thaw() and ->complete() for all devices. | |
8111d1b5 AS |
222 | * |
223 | * The following PM_EVENT_ messages are defined for internal use by | |
224 | * kernel subsystems. They are never issued by the PM core. | |
225 | * | |
226 | * USER_SUSPEND Manual selective suspend was issued by userspace. | |
227 | * | |
228 | * USER_RESUME Manual selective resume was issued by userspace. | |
229 | * | |
230 | * REMOTE_WAKEUP Remote-wakeup request was received from the device. | |
231 | * | |
232 | * AUTO_SUSPEND Automatic (device idle) runtime suspend was | |
233 | * initiated by the subsystem. | |
234 | * | |
235 | * AUTO_RESUME Automatic (device needed) runtime resume was | |
236 | * requested by a driver. | |
1eede070 RW |
237 | */ |
238 | ||
239 | #define PM_EVENT_ON 0x0000 | |
240 | #define PM_EVENT_FREEZE 0x0001 | |
241 | #define PM_EVENT_SUSPEND 0x0002 | |
242 | #define PM_EVENT_HIBERNATE 0x0004 | |
243 | #define PM_EVENT_QUIESCE 0x0008 | |
244 | #define PM_EVENT_RESUME 0x0010 | |
245 | #define PM_EVENT_THAW 0x0020 | |
246 | #define PM_EVENT_RESTORE 0x0040 | |
247 | #define PM_EVENT_RECOVER 0x0080 | |
8111d1b5 AS |
248 | #define PM_EVENT_USER 0x0100 |
249 | #define PM_EVENT_REMOTE 0x0200 | |
250 | #define PM_EVENT_AUTO 0x0400 | |
1eede070 | 251 | |
8111d1b5 AS |
252 | #define PM_EVENT_SLEEP (PM_EVENT_SUSPEND | PM_EVENT_HIBERNATE) |
253 | #define PM_EVENT_USER_SUSPEND (PM_EVENT_USER | PM_EVENT_SUSPEND) | |
254 | #define PM_EVENT_USER_RESUME (PM_EVENT_USER | PM_EVENT_RESUME) | |
7f4f5d45 | 255 | #define PM_EVENT_REMOTE_RESUME (PM_EVENT_REMOTE | PM_EVENT_RESUME) |
8111d1b5 AS |
256 | #define PM_EVENT_AUTO_SUSPEND (PM_EVENT_AUTO | PM_EVENT_SUSPEND) |
257 | #define PM_EVENT_AUTO_RESUME (PM_EVENT_AUTO | PM_EVENT_RESUME) | |
1eede070 | 258 | |
8111d1b5 | 259 | #define PMSG_ON ((struct pm_message){ .event = PM_EVENT_ON, }) |
1eede070 RW |
260 | #define PMSG_FREEZE ((struct pm_message){ .event = PM_EVENT_FREEZE, }) |
261 | #define PMSG_QUIESCE ((struct pm_message){ .event = PM_EVENT_QUIESCE, }) | |
262 | #define PMSG_SUSPEND ((struct pm_message){ .event = PM_EVENT_SUSPEND, }) | |
263 | #define PMSG_HIBERNATE ((struct pm_message){ .event = PM_EVENT_HIBERNATE, }) | |
264 | #define PMSG_RESUME ((struct pm_message){ .event = PM_EVENT_RESUME, }) | |
265 | #define PMSG_THAW ((struct pm_message){ .event = PM_EVENT_THAW, }) | |
266 | #define PMSG_RESTORE ((struct pm_message){ .event = PM_EVENT_RESTORE, }) | |
267 | #define PMSG_RECOVER ((struct pm_message){ .event = PM_EVENT_RECOVER, }) | |
7f4f5d45 | 268 | #define PMSG_USER_SUSPEND ((struct pm_message) \ |
8111d1b5 | 269 | { .event = PM_EVENT_USER_SUSPEND, }) |
7f4f5d45 | 270 | #define PMSG_USER_RESUME ((struct pm_message) \ |
8111d1b5 | 271 | { .event = PM_EVENT_USER_RESUME, }) |
7f4f5d45 | 272 | #define PMSG_REMOTE_RESUME ((struct pm_message) \ |
8111d1b5 | 273 | { .event = PM_EVENT_REMOTE_RESUME, }) |
7f4f5d45 | 274 | #define PMSG_AUTO_SUSPEND ((struct pm_message) \ |
8111d1b5 | 275 | { .event = PM_EVENT_AUTO_SUSPEND, }) |
7f4f5d45 | 276 | #define PMSG_AUTO_RESUME ((struct pm_message) \ |
8111d1b5 | 277 | { .event = PM_EVENT_AUTO_RESUME, }) |
1eede070 RW |
278 | |
279 | /** | |
280 | * Device power management states | |
281 | * | |
282 | * These state labels are used internally by the PM core to indicate the current | |
283 | * status of a device with respect to the PM core operations. | |
284 | * | |
285 | * DPM_ON Device is regarded as operational. Set this way | |
286 | * initially and when ->complete() is about to be called. | |
287 | * Also set when ->prepare() fails. | |
288 | * | |
289 | * DPM_PREPARING Device is going to be prepared for a PM transition. Set | |
290 | * when ->prepare() is about to be called. | |
291 | * | |
292 | * DPM_RESUMING Device is going to be resumed. Set when ->resume(), | |
293 | * ->thaw(), or ->restore() is about to be called. | |
294 | * | |
295 | * DPM_SUSPENDING Device has been prepared for a power transition. Set | |
296 | * when ->prepare() has just succeeded. | |
297 | * | |
298 | * DPM_OFF Device is regarded as inactive. Set immediately after | |
299 | * ->suspend(), ->freeze(), or ->poweroff() has succeeded. | |
300 | * Also set when ->resume()_noirq, ->thaw_noirq(), or | |
301 | * ->restore_noirq() is about to be called. | |
302 | * | |
303 | * DPM_OFF_IRQ Device is in a "deep sleep". Set immediately after | |
304 | * ->suspend_noirq(), ->freeze_noirq(), or | |
305 | * ->poweroff_noirq() has just succeeded. | |
306 | */ | |
307 | ||
308 | enum dpm_state { | |
309 | DPM_INVALID, | |
310 | DPM_ON, | |
311 | DPM_PREPARING, | |
312 | DPM_RESUMING, | |
313 | DPM_SUSPENDING, | |
314 | DPM_OFF, | |
315 | DPM_OFF_IRQ, | |
316 | }; | |
317 | ||
318 | struct dev_pm_info { | |
319 | pm_message_t power_state; | |
320 | unsigned can_wakeup:1; | |
321 | unsigned should_wakeup:1; | |
322 | enum dpm_state status; /* Owned by the PM core */ | |
323 | #ifdef CONFIG_PM_SLEEP | |
324 | struct list_head entry; | |
325 | #endif | |
326 | }; | |
327 | ||
328 | /* | |
329 | * The PM_EVENT_ messages are also used by drivers implementing the legacy | |
330 | * suspend framework, based on the ->suspend() and ->resume() callbacks common | |
331 | * for suspend and hibernation transitions, according to the rules below. | |
332 | */ | |
333 | ||
334 | /* Necessary, because several drivers use PM_EVENT_PRETHAW */ | |
335 | #define PM_EVENT_PRETHAW PM_EVENT_QUIESCE | |
336 | ||
337 | /* | |
82bb67f2 DB |
338 | * One transition is triggered by resume(), after a suspend() call; the |
339 | * message is implicit: | |
340 | * | |
341 | * ON Driver starts working again, responding to hardware events | |
342 | * and software requests. The hardware may have gone through | |
343 | * a power-off reset, or it may have maintained state from the | |
344 | * previous suspend() which the driver will rely on while | |
345 | * resuming. On most platforms, there are no restrictions on | |
346 | * availability of resources like clocks during resume(). | |
347 | * | |
348 | * Other transitions are triggered by messages sent using suspend(). All | |
349 | * these transitions quiesce the driver, so that I/O queues are inactive. | |
350 | * That commonly entails turning off IRQs and DMA; there may be rules | |
351 | * about how to quiesce that are specific to the bus or the device's type. | |
352 | * (For example, network drivers mark the link state.) Other details may | |
353 | * differ according to the message: | |
354 | * | |
355 | * SUSPEND Quiesce, enter a low power device state appropriate for | |
356 | * the upcoming system state (such as PCI_D3hot), and enable | |
357 | * wakeup events as appropriate. | |
358 | * | |
3a2d5b70 RW |
359 | * HIBERNATE Enter a low power device state appropriate for the hibernation |
360 | * state (eg. ACPI S4) and enable wakeup events as appropriate. | |
361 | * | |
82bb67f2 DB |
362 | * FREEZE Quiesce operations so that a consistent image can be saved; |
363 | * but do NOT otherwise enter a low power device state, and do | |
364 | * NOT emit system wakeup events. | |
365 | * | |
366 | * PRETHAW Quiesce as if for FREEZE; additionally, prepare for restoring | |
367 | * the system from a snapshot taken after an earlier FREEZE. | |
368 | * Some drivers will need to reset their hardware state instead | |
369 | * of preserving it, to ensure that it's never mistaken for the | |
370 | * state which that earlier snapshot had set up. | |
371 | * | |
372 | * A minimally power-aware driver treats all messages as SUSPEND, fully | |
373 | * reinitializes its device during resume() -- whether or not it was reset | |
374 | * during the suspend/resume cycle -- and can't issue wakeup events. | |
375 | * | |
376 | * More power-aware drivers may also use low power states at runtime as | |
377 | * well as during system sleep states like PM_SUSPEND_STANDBY. They may | |
378 | * be able to use wakeup events to exit from runtime low-power states, | |
379 | * or from system low-power states such as standby or suspend-to-RAM. | |
1da177e4 LT |
380 | */ |
381 | ||
1eede070 RW |
382 | #ifdef CONFIG_PM_SLEEP |
383 | extern void device_pm_lock(void); | |
384 | extern void device_power_up(pm_message_t state); | |
385 | extern void device_resume(pm_message_t state); | |
1da177e4 | 386 | |
1eede070 | 387 | extern void device_pm_unlock(void); |
1da177e4 | 388 | extern int device_power_down(pm_message_t state); |
620b0327 | 389 | extern int device_suspend(pm_message_t state); |
7c8265f5 | 390 | extern int device_prepare_suspend(pm_message_t state); |
0ac85241 | 391 | |
02669492 AM |
392 | extern void __suspend_report_result(const char *function, void *fn, int ret); |
393 | ||
394 | #define suspend_report_result(fn, ret) \ | |
395 | do { \ | |
d5c003b4 | 396 | __suspend_report_result(__func__, fn, ret); \ |
02669492 | 397 | } while (0) |
9a7834d0 | 398 | |
d288e47c AS |
399 | #else /* !CONFIG_PM_SLEEP */ |
400 | ||
401 | static inline int device_suspend(pm_message_t state) | |
402 | { | |
403 | return 0; | |
404 | } | |
405 | ||
9a3df1f7 | 406 | #define suspend_report_result(fn, ret) do {} while (0) |
d288e47c AS |
407 | |
408 | #endif /* !CONFIG_PM_SLEEP */ | |
409 | ||
9f9adecd LB |
410 | /* |
411 | * Global Power Management flags | |
412 | * Used to keep APM and ACPI from both being active | |
413 | */ | |
414 | extern unsigned int pm_flags; | |
415 | ||
416 | #define PM_APM 1 | |
417 | #define PM_ACPI 2 | |
418 | ||
1da177e4 | 419 | #endif /* _LINUX_PM_H */ |