aboutsummaryrefslogtreecommitdiffstats
path: root/include/linux/pm.h
diff options
context:
space:
mode:
authorRafael J. Wysocki <rjw@sisk.pl>2008-05-20 17:00:01 -0400
committerJesse Barnes <jbarnes@virtuousgeek.org>2008-06-10 13:59:50 -0400
commit1eede070a59e1cc73da51e1aaa00d9ab86572cfc (patch)
treeeafccca4f2a1ae2e8ebb06d2dff9528d5a289da4 /include/linux/pm.h
parentbb71ad880204b79d60331d3384103976e086cb9f (diff)
Introduce new top level suspend and hibernation callbacks
Introduce 'struct pm_ops' and 'struct pm_ext_ops' ('ext' meaning 'extended') representing suspend and hibernation operations for bus types, device classes, device types and device drivers. Modify the PM core to use 'struct pm_ops' and 'struct pm_ext_ops' objects, if defined, instead of the ->suspend(), ->resume(), ->suspend_late(), and ->resume_early() callbacks (the old callbacks will be considered as legacy and gradually phased out). The main purpose of doing this is to separate suspend (aka S2RAM and standby) callbacks from hibernation callbacks in such a way that the new callbacks won't take arguments and the semantics of each of them will be clearly specified. This has been requested for multiple times by many people, including Linus himself, and the reason is that within the current scheme if ->resume() is called, for example, it's difficult to say why it's been called (ie. is it a resume from RAM or from hibernation or a suspend/hibernation failure etc.?). The second purpose is to make the suspend/hibernation callbacks more flexible so that device drivers can handle more than they can within the current scheme. For example, some drivers may need to prevent new children of the device from being registered before their ->suspend() callbacks are executed or they may want to carry out some operations requiring the availability of some other devices, not directly bound via the parent-child relationship, in order to prepare for the execution of ->suspend(), etc. Ultimately, we'd like to stop using the freezing of tasks for suspend and therefore the drivers' suspend/hibernation code will have to take care of the handling of the user space during suspend/hibernation. That, in turn, would be difficult within the current scheme, without the new ->prepare() and ->complete() callbacks. Signed-off-by: Rafael J. Wysocki <rjw@sisk.pl> Acked-by: Pavel Machek <pavel@ucw.cz> Signed-off-by: Jesse Barnes <jbarnes@virtuousgeek.org>
Diffstat (limited to 'include/linux/pm.h')
-rw-r--r--include/linux/pm.h314
1 files changed, 286 insertions, 28 deletions
diff --git a/include/linux/pm.h b/include/linux/pm.h
index 39a7ee859b67..4ad9de94449a 100644
--- a/include/linux/pm.h
+++ b/include/linux/pm.h
@@ -112,7 +112,9 @@ typedef struct pm_message {
112 int event; 112 int event;
113} pm_message_t; 113} pm_message_t;
114 114
115/* 115/**
116 * struct pm_ops - device PM callbacks
117 *
116 * Several driver power state transitions are externally visible, affecting 118 * Several driver power state transitions are externally visible, affecting
117 * the state of pending I/O queues and (for drivers that touch hardware) 119 * the state of pending I/O queues and (for drivers that touch hardware)
118 * interrupts, wakeups, DMA, and other hardware state. There may also be 120 * interrupts, wakeups, DMA, and other hardware state. There may also be
@@ -120,6 +122,284 @@ typedef struct pm_message {
120 * to the rest of the driver stack (such as a driver that's ON gating off 122 * to the rest of the driver stack (such as a driver that's ON gating off
121 * clocks which are not in active use). 123 * clocks which are not in active use).
122 * 124 *
125 * The externally visible transitions are handled with the help of the following
126 * callbacks included in this structure:
127 *
128 * @prepare: Prepare the device for the upcoming transition, but do NOT change
129 * its hardware state. Prevent new children of the device from being
130 * registered after @prepare() returns (the driver's subsystem and
131 * generally the rest of the kernel is supposed to prevent new calls to the
132 * probe method from being made too once @prepare() has succeeded). If
133 * @prepare() detects a situation it cannot handle (e.g. registration of a
134 * child already in progress), it may return -EAGAIN, so that the PM core
135 * can execute it once again (e.g. after the new child has been registered)
136 * to recover from the race condition. This method is executed for all
137 * kinds of suspend transitions and is followed by one of the suspend
138 * callbacks: @suspend(), @freeze(), or @poweroff().
139 * The PM core executes @prepare() for all devices before starting to
140 * execute suspend callbacks for any of them, so drivers may assume all of
141 * the other devices to be present and functional while @prepare() is being
142 * executed. In particular, it is safe to make GFP_KERNEL memory
143 * allocations from within @prepare(). However, drivers may NOT assume
144 * anything about the availability of the user space at that time and it
145 * is not correct to request firmware from within @prepare() (it's too
146 * late to do that). [To work around this limitation, drivers may
147 * register suspend and hibernation notifiers that are executed before the
148 * freezing of tasks.]
149 *
150 * @complete: Undo the changes made by @prepare(). This method is executed for
151 * all kinds of resume transitions, following one of the resume callbacks:
152 * @resume(), @thaw(), @restore(). Also called if the state transition
153 * fails before the driver's suspend callback (@suspend(), @freeze(),
154 * @poweroff()) can be executed (e.g. if the suspend callback fails for one
155 * of the other devices that the PM core has unsuccessfully attempted to
156 * suspend earlier).
157 * The PM core executes @complete() after it has executed the appropriate
158 * resume callback for all devices.
159 *
160 * @suspend: Executed before putting the system into a sleep state in which the
161 * contents of main memory are preserved. Quiesce the device, put it into
162 * a low power state appropriate for the upcoming system state (such as
163 * PCI_D3hot), and enable wakeup events as appropriate.
164 *
165 * @resume: Executed after waking the system up from a sleep state in which the
166 * contents of main memory were preserved. Put the device into the
167 * appropriate state, according to the information saved in memory by the
168 * preceding @suspend(). The driver starts working again, responding to
169 * hardware events and software requests. The hardware may have gone
170 * through a power-off reset, or it may have maintained state from the
171 * previous suspend() which the driver may rely on while resuming. On most
172 * platforms, there are no restrictions on availability of resources like
173 * clocks during @resume().
174 *
175 * @freeze: Hibernation-specific, executed before creating a hibernation image.
176 * Quiesce operations so that a consistent image can be created, but do NOT
177 * otherwise put the device into a low power device state and do NOT emit
178 * system wakeup events. Save in main memory the device settings to be
179 * used by @restore() during the subsequent resume from hibernation or by
180 * the subsequent @thaw(), if the creation of the image or the restoration
181 * of main memory contents from it fails.
182 *
183 * @thaw: Hibernation-specific, executed after creating a hibernation image OR
184 * if the creation of the image fails. Also executed after a failing
185 * attempt to restore the contents of main memory from such an image.
186 * Undo the changes made by the preceding @freeze(), so the device can be
187 * operated in the same way as immediately before the call to @freeze().
188 *
189 * @poweroff: Hibernation-specific, executed after saving a hibernation image.
190 * Quiesce the device, put it into a low power state appropriate for the
191 * upcoming system state (such as PCI_D3hot), and enable wakeup events as
192 * appropriate.
193 *
194 * @restore: Hibernation-specific, executed after restoring the contents of main
195 * memory from a hibernation image. Driver starts working again,
196 * responding to hardware events and software requests. Drivers may NOT
197 * make ANY assumptions about the hardware state right prior to @restore().
198 * On most platforms, there are no restrictions on availability of
199 * resources like clocks during @restore().
200 *
201 * All of the above callbacks, except for @complete(), return error codes.
202 * However, the error codes returned by the resume operations, @resume(),
203 * @thaw(), and @restore(), do not cause the PM core to abort the resume
204 * transition during which they are returned. The error codes returned in
205 * that cases are only printed by the PM core to the system logs for debugging
206 * purposes. Still, it is recommended that drivers only return error codes
207 * from their resume methods in case of an unrecoverable failure (i.e. when the
208 * device being handled refuses to resume and becomes unusable) to allow us to
209 * modify the PM core in the future, so that it can avoid attempting to handle
210 * devices that failed to resume and their children.
211 *
212 * It is allowed to unregister devices while the above callbacks are being
213 * executed. However, it is not allowed to unregister a device from within any
214 * of its own callbacks.
215 */
216
217struct pm_ops {
218 int (*prepare)(struct device *dev);
219 void (*complete)(struct device *dev);
220 int (*suspend)(struct device *dev);
221 int (*resume)(struct device *dev);
222 int (*freeze)(struct device *dev);
223 int (*thaw)(struct device *dev);
224 int (*poweroff)(struct device *dev);
225 int (*restore)(struct device *dev);
226};
227
228/**
229 * struct pm_ext_ops - extended device PM callbacks
230 *
231 * Some devices require certain operations related to suspend and hibernation
232 * to be carried out with interrupts disabled. Thus, 'struct pm_ext_ops' below
233 * is defined, adding callbacks to be executed with interrupts disabled to
234 * 'struct pm_ops'.
235 *
236 * The following callbacks included in 'struct pm_ext_ops' are executed with
237 * the nonboot CPUs switched off and with interrupts disabled on the only
238 * functional CPU. They also are executed with the PM core list of devices
239 * locked, so they must NOT unregister any devices.
240 *
241 * @suspend_noirq: Complete the operations of ->suspend() by carrying out any
242 * actions required for suspending the device that need interrupts to be
243 * disabled
244 *
245 * @resume_noirq: Prepare for the execution of ->resume() by carrying out any
246 * actions required for resuming the device that need interrupts to be
247 * disabled
248 *
249 * @freeze_noirq: Complete the operations of ->freeze() by carrying out any
250 * actions required for freezing the device that need interrupts to be
251 * disabled
252 *
253 * @thaw_noirq: Prepare for the execution of ->thaw() by carrying out any
254 * actions required for thawing the device that need interrupts to be
255 * disabled
256 *
257 * @poweroff_noirq: Complete the operations of ->poweroff() by carrying out any
258 * actions required for handling the device that need interrupts to be
259 * disabled
260 *
261 * @restore_noirq: Prepare for the execution of ->restore() by carrying out any
262 * actions required for restoring the operations of the device that need
263 * interrupts to be disabled
264 *
265 * All of the above callbacks return error codes, but the error codes returned
266 * by the resume operations, @resume_noirq(), @thaw_noirq(), and
267 * @restore_noirq(), do not cause the PM core to abort the resume transition
268 * during which they are returned. The error codes returned in that cases are
269 * only printed by the PM core to the system logs for debugging purposes.
270 * Still, as stated above, it is recommended that drivers only return error
271 * codes from their resume methods if the device being handled fails to resume
272 * and is not usable any more.
273 */
274
275struct pm_ext_ops {
276 struct pm_ops base;
277 int (*suspend_noirq)(struct device *dev);
278 int (*resume_noirq)(struct device *dev);
279 int (*freeze_noirq)(struct device *dev);
280 int (*thaw_noirq)(struct device *dev);
281 int (*poweroff_noirq)(struct device *dev);
282 int (*restore_noirq)(struct device *dev);
283};
284
285/**
286 * PM_EVENT_ messages
287 *
288 * The following PM_EVENT_ messages are defined for the internal use of the PM
289 * core, in order to provide a mechanism allowing the high level suspend and
290 * hibernation code to convey the necessary information to the device PM core
291 * code:
292 *
293 * ON No transition.
294 *
295 * FREEZE System is going to hibernate, call ->prepare() and ->freeze()
296 * for all devices.
297 *
298 * SUSPEND System is going to suspend, call ->prepare() and ->suspend()
299 * for all devices.
300 *
301 * HIBERNATE Hibernation image has been saved, call ->prepare() and
302 * ->poweroff() for all devices.
303 *
304 * QUIESCE Contents of main memory are going to be restored from a (loaded)
305 * hibernation image, call ->prepare() and ->freeze() for all
306 * devices.
307 *
308 * RESUME System is resuming, call ->resume() and ->complete() for all
309 * devices.
310 *
311 * THAW Hibernation image has been created, call ->thaw() and
312 * ->complete() for all devices.
313 *
314 * RESTORE Contents of main memory have been restored from a hibernation
315 * image, call ->restore() and ->complete() for all devices.
316 *
317 * RECOVER Creation of a hibernation image or restoration of the main
318 * memory contents from a hibernation image has failed, call
319 * ->thaw() and ->complete() for all devices.
320 */
321
322#define PM_EVENT_ON 0x0000
323#define PM_EVENT_FREEZE 0x0001
324#define PM_EVENT_SUSPEND 0x0002
325#define PM_EVENT_HIBERNATE 0x0004
326#define PM_EVENT_QUIESCE 0x0008
327#define PM_EVENT_RESUME 0x0010
328#define PM_EVENT_THAW 0x0020
329#define PM_EVENT_RESTORE 0x0040
330#define PM_EVENT_RECOVER 0x0080
331
332#define PM_EVENT_SLEEP (PM_EVENT_SUSPEND | PM_EVENT_HIBERNATE)
333
334#define PMSG_FREEZE ((struct pm_message){ .event = PM_EVENT_FREEZE, })
335#define PMSG_QUIESCE ((struct pm_message){ .event = PM_EVENT_QUIESCE, })
336#define PMSG_SUSPEND ((struct pm_message){ .event = PM_EVENT_SUSPEND, })
337#define PMSG_HIBERNATE ((struct pm_message){ .event = PM_EVENT_HIBERNATE, })
338#define PMSG_RESUME ((struct pm_message){ .event = PM_EVENT_RESUME, })
339#define PMSG_THAW ((struct pm_message){ .event = PM_EVENT_THAW, })
340#define PMSG_RESTORE ((struct pm_message){ .event = PM_EVENT_RESTORE, })
341#define PMSG_RECOVER ((struct pm_message){ .event = PM_EVENT_RECOVER, })
342#define PMSG_ON ((struct pm_message){ .event = PM_EVENT_ON, })
343
344/**
345 * Device power management states
346 *
347 * These state labels are used internally by the PM core to indicate the current
348 * status of a device with respect to the PM core operations.
349 *
350 * DPM_ON Device is regarded as operational. Set this way
351 * initially and when ->complete() is about to be called.
352 * Also set when ->prepare() fails.
353 *
354 * DPM_PREPARING Device is going to be prepared for a PM transition. Set
355 * when ->prepare() is about to be called.
356 *
357 * DPM_RESUMING Device is going to be resumed. Set when ->resume(),
358 * ->thaw(), or ->restore() is about to be called.
359 *
360 * DPM_SUSPENDING Device has been prepared for a power transition. Set
361 * when ->prepare() has just succeeded.
362 *
363 * DPM_OFF Device is regarded as inactive. Set immediately after
364 * ->suspend(), ->freeze(), or ->poweroff() has succeeded.
365 * Also set when ->resume()_noirq, ->thaw_noirq(), or
366 * ->restore_noirq() is about to be called.
367 *
368 * DPM_OFF_IRQ Device is in a "deep sleep". Set immediately after
369 * ->suspend_noirq(), ->freeze_noirq(), or
370 * ->poweroff_noirq() has just succeeded.
371 */
372
373enum dpm_state {
374 DPM_INVALID,
375 DPM_ON,
376 DPM_PREPARING,
377 DPM_RESUMING,
378 DPM_SUSPENDING,
379 DPM_OFF,
380 DPM_OFF_IRQ,
381};
382
383struct dev_pm_info {
384 pm_message_t power_state;
385 unsigned can_wakeup:1;
386 unsigned should_wakeup:1;
387 enum dpm_state status; /* Owned by the PM core */
388#ifdef CONFIG_PM_SLEEP
389 struct list_head entry;
390#endif
391};
392
393/*
394 * The PM_EVENT_ messages are also used by drivers implementing the legacy
395 * suspend framework, based on the ->suspend() and ->resume() callbacks common
396 * for suspend and hibernation transitions, according to the rules below.
397 */
398
399/* Necessary, because several drivers use PM_EVENT_PRETHAW */
400#define PM_EVENT_PRETHAW PM_EVENT_QUIESCE
401
402/*
123 * One transition is triggered by resume(), after a suspend() call; the 403 * One transition is triggered by resume(), after a suspend() call; the
124 * message is implicit: 404 * message is implicit:
125 * 405 *
@@ -164,35 +444,13 @@ typedef struct pm_message {
164 * or from system low-power states such as standby or suspend-to-RAM. 444 * or from system low-power states such as standby or suspend-to-RAM.
165 */ 445 */
166 446
167#define PM_EVENT_ON 0 447#ifdef CONFIG_PM_SLEEP
168#define PM_EVENT_FREEZE 1 448extern void device_pm_lock(void);
169#define PM_EVENT_SUSPEND 2 449extern void device_power_up(pm_message_t state);
170#define PM_EVENT_HIBERNATE 4 450extern void device_resume(pm_message_t state);
171#define PM_EVENT_PRETHAW 8
172
173#define PM_EVENT_SLEEP (PM_EVENT_SUSPEND | PM_EVENT_HIBERNATE)
174
175#define PMSG_FREEZE ((struct pm_message){ .event = PM_EVENT_FREEZE, })
176#define PMSG_PRETHAW ((struct pm_message){ .event = PM_EVENT_PRETHAW, })
177#define PMSG_SUSPEND ((struct pm_message){ .event = PM_EVENT_SUSPEND, })
178#define PMSG_HIBERNATE ((struct pm_message){ .event = PM_EVENT_HIBERNATE, })
179#define PMSG_ON ((struct pm_message){ .event = PM_EVENT_ON, })
180
181struct dev_pm_info {
182 pm_message_t power_state;
183 unsigned can_wakeup:1;
184 unsigned should_wakeup:1;
185 bool sleeping:1; /* Owned by the PM core */
186#ifdef CONFIG_PM_SLEEP
187 struct list_head entry;
188#endif
189};
190 451
452extern void device_pm_unlock(void);
191extern int device_power_down(pm_message_t state); 453extern int device_power_down(pm_message_t state);
192extern void device_power_up(void);
193extern void device_resume(void);
194
195#ifdef CONFIG_PM_SLEEP
196extern int device_suspend(pm_message_t state); 454extern int device_suspend(pm_message_t state);
197extern int device_prepare_suspend(pm_message_t state); 455extern int device_prepare_suspend(pm_message_t state);
198 456