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 37 /* 38 * Device power management 39 */ 40 41 struct device; 42 43 typedef struct pm_message { 44 int event; 45 } pm_message_t; 46 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 if device_may_wakeup(dev) is true, remote wake-up (i.e., a 182 * hardware mechanism allowing the device to request a change of its power 183 * state, such as PCI PME) should be enabled for it. 184 * 185 * @runtime_resume: Put the device into the fully active state in response to a 186 * wake-up event generated by hardware or at the request of software. If 187 * necessary, put the device into the full power state and restore its 188 * registers, so that it is fully operational. 189 * 190 * @runtime_idle: Device appears to be inactive and it might be put into a low 191 * power state if all of the necessary conditions are satisfied. Check 192 * these conditions and handle the device as appropriate, possibly queueing 193 * a suspend request for it. The return value is ignored by the PM core. 194 */ 195 196 struct dev_pm_ops { 197 int (*prepare)(struct device *dev); 198 void (*complete)(struct device *dev); 199 int (*suspend)(struct device *dev); 200 int (*resume)(struct device *dev); 201 int (*freeze)(struct device *dev); 202 int (*thaw)(struct device *dev); 203 int (*poweroff)(struct device *dev); 204 int (*restore)(struct device *dev); 205 int (*suspend_noirq)(struct device *dev); 206 int (*resume_noirq)(struct device *dev); 207 int (*freeze_noirq)(struct device *dev); 208 int (*thaw_noirq)(struct device *dev); 209 int (*poweroff_noirq)(struct device *dev); 210 int (*restore_noirq)(struct device *dev); 211 int (*runtime_suspend)(struct device *dev); 212 int (*runtime_resume)(struct device *dev); 213 int (*runtime_idle)(struct device *dev); 214 }; 215 216 /** 217 * PM_EVENT_ messages 218 * 219 * The following PM_EVENT_ messages are defined for the internal use of the PM 220 * core, in order to provide a mechanism allowing the high level suspend and 221 * hibernation code to convey the necessary information to the device PM core 222 * code: 223 * 224 * ON No transition. 225 * 226 * FREEZE System is going to hibernate, call ->prepare() and ->freeze() 227 * for all devices. 228 * 229 * SUSPEND System is going to suspend, call ->prepare() and ->suspend() 230 * for all devices. 231 * 232 * HIBERNATE Hibernation image has been saved, call ->prepare() and 233 * ->poweroff() for all devices. 234 * 235 * QUIESCE Contents of main memory are going to be restored from a (loaded) 236 * hibernation image, call ->prepare() and ->freeze() for all 237 * devices. 238 * 239 * RESUME System is resuming, call ->resume() and ->complete() for all 240 * devices. 241 * 242 * THAW Hibernation image has been created, call ->thaw() and 243 * ->complete() for all devices. 244 * 245 * RESTORE Contents of main memory have been restored from a hibernation 246 * image, call ->restore() and ->complete() for all devices. 247 * 248 * RECOVER Creation of a hibernation image or restoration of the main 249 * memory contents from a hibernation image has failed, call 250 * ->thaw() and ->complete() for all devices. 251 * 252 * The following PM_EVENT_ messages are defined for internal use by 253 * kernel subsystems. They are never issued by the PM core. 254 * 255 * USER_SUSPEND Manual selective suspend was issued by userspace. 256 * 257 * USER_RESUME Manual selective resume was issued by userspace. 258 * 259 * REMOTE_WAKEUP Remote-wakeup request was received from the device. 260 * 261 * AUTO_SUSPEND Automatic (device idle) runtime suspend was 262 * initiated by the subsystem. 263 * 264 * AUTO_RESUME Automatic (device needed) runtime resume was 265 * requested by a driver. 266 */ 267 268 #define PM_EVENT_ON 0x0000 269 #define PM_EVENT_FREEZE 0x0001 270 #define PM_EVENT_SUSPEND 0x0002 271 #define PM_EVENT_HIBERNATE 0x0004 272 #define PM_EVENT_QUIESCE 0x0008 273 #define PM_EVENT_RESUME 0x0010 274 #define PM_EVENT_THAW 0x0020 275 #define PM_EVENT_RESTORE 0x0040 276 #define PM_EVENT_RECOVER 0x0080 277 #define PM_EVENT_USER 0x0100 278 #define PM_EVENT_REMOTE 0x0200 279 #define PM_EVENT_AUTO 0x0400 280 281 #define PM_EVENT_SLEEP (PM_EVENT_SUSPEND | PM_EVENT_HIBERNATE) 282 #define PM_EVENT_USER_SUSPEND (PM_EVENT_USER | PM_EVENT_SUSPEND) 283 #define PM_EVENT_USER_RESUME (PM_EVENT_USER | PM_EVENT_RESUME) 284 #define PM_EVENT_REMOTE_RESUME (PM_EVENT_REMOTE | PM_EVENT_RESUME) 285 #define PM_EVENT_AUTO_SUSPEND (PM_EVENT_AUTO | PM_EVENT_SUSPEND) 286 #define PM_EVENT_AUTO_RESUME (PM_EVENT_AUTO | PM_EVENT_RESUME) 287 288 #define PMSG_ON ((struct pm_message){ .event = PM_EVENT_ON, }) 289 #define PMSG_FREEZE ((struct pm_message){ .event = PM_EVENT_FREEZE, }) 290 #define PMSG_QUIESCE ((struct pm_message){ .event = PM_EVENT_QUIESCE, }) 291 #define PMSG_SUSPEND ((struct pm_message){ .event = PM_EVENT_SUSPEND, }) 292 #define PMSG_HIBERNATE ((struct pm_message){ .event = PM_EVENT_HIBERNATE, }) 293 #define PMSG_RESUME ((struct pm_message){ .event = PM_EVENT_RESUME, }) 294 #define PMSG_THAW ((struct pm_message){ .event = PM_EVENT_THAW, }) 295 #define PMSG_RESTORE ((struct pm_message){ .event = PM_EVENT_RESTORE, }) 296 #define PMSG_RECOVER ((struct pm_message){ .event = PM_EVENT_RECOVER, }) 297 #define PMSG_USER_SUSPEND ((struct pm_message) \ 298 { .event = PM_EVENT_USER_SUSPEND, }) 299 #define PMSG_USER_RESUME ((struct pm_message) \ 300 { .event = PM_EVENT_USER_RESUME, }) 301 #define PMSG_REMOTE_RESUME ((struct pm_message) \ 302 { .event = PM_EVENT_REMOTE_RESUME, }) 303 #define PMSG_AUTO_SUSPEND ((struct pm_message) \ 304 { .event = PM_EVENT_AUTO_SUSPEND, }) 305 #define PMSG_AUTO_RESUME ((struct pm_message) \ 306 { .event = PM_EVENT_AUTO_RESUME, }) 307 308 /** 309 * Device power management states 310 * 311 * These state labels are used internally by the PM core to indicate the current 312 * status of a device with respect to the PM core operations. 313 * 314 * DPM_ON Device is regarded as operational. Set this way 315 * initially and when ->complete() is about to be called. 316 * Also set when ->prepare() fails. 317 * 318 * DPM_PREPARING Device is going to be prepared for a PM transition. Set 319 * when ->prepare() is about to be called. 320 * 321 * DPM_RESUMING Device is going to be resumed. Set when ->resume(), 322 * ->thaw(), or ->restore() is about to be called. 323 * 324 * DPM_SUSPENDING Device has been prepared for a power transition. Set 325 * when ->prepare() has just succeeded. 326 * 327 * DPM_OFF Device is regarded as inactive. Set immediately after 328 * ->suspend(), ->freeze(), or ->poweroff() has succeeded. 329 * Also set when ->resume()_noirq, ->thaw_noirq(), or 330 * ->restore_noirq() is about to be called. 331 * 332 * DPM_OFF_IRQ Device is in a "deep sleep". Set immediately after 333 * ->suspend_noirq(), ->freeze_noirq(), or 334 * ->poweroff_noirq() has just succeeded. 335 */ 336 337 enum dpm_state { 338 DPM_INVALID, 339 DPM_ON, 340 DPM_PREPARING, 341 DPM_RESUMING, 342 DPM_SUSPENDING, 343 DPM_OFF, 344 DPM_OFF_IRQ, 345 }; 346 347 /** 348 * Device run-time power management status. 349 * 350 * These status labels are used internally by the PM core to indicate the 351 * current status of a device with respect to the PM core operations. They do 352 * not reflect the actual power state of the device or its status as seen by the 353 * driver. 354 * 355 * RPM_ACTIVE Device is fully operational. Indicates that the device 356 * bus type's ->runtime_resume() callback has completed 357 * successfully. 358 * 359 * RPM_SUSPENDED Device bus type's ->runtime_suspend() callback has 360 * completed successfully. The device is regarded as 361 * suspended. 362 * 363 * RPM_RESUMING Device bus type's ->runtime_resume() callback is being 364 * executed. 365 * 366 * RPM_SUSPENDING Device bus type's ->runtime_suspend() callback is being 367 * executed. 368 */ 369 370 enum rpm_status { 371 RPM_ACTIVE = 0, 372 RPM_RESUMING, 373 RPM_SUSPENDED, 374 RPM_SUSPENDING, 375 }; 376 377 /** 378 * Device run-time power management request types. 379 * 380 * RPM_REQ_NONE Do nothing. 381 * 382 * RPM_REQ_IDLE Run the device bus type's ->runtime_idle() callback 383 * 384 * RPM_REQ_SUSPEND Run the device bus type's ->runtime_suspend() callback 385 * 386 * RPM_REQ_RESUME Run the device bus type's ->runtime_resume() callback 387 */ 388 389 enum rpm_request { 390 RPM_REQ_NONE = 0, 391 RPM_REQ_IDLE, 392 RPM_REQ_SUSPEND, 393 RPM_REQ_RESUME, 394 }; 395 396 struct dev_pm_info { 397 pm_message_t power_state; 398 unsigned int can_wakeup:1; 399 unsigned int should_wakeup:1; 400 enum dpm_state status; /* Owned by the PM core */ 401 #ifdef CONFIG_PM_SLEEP 402 struct list_head entry; 403 #endif 404 #ifdef CONFIG_PM_RUNTIME 405 struct timer_list suspend_timer; 406 unsigned long timer_expires; 407 struct work_struct work; 408 wait_queue_head_t wait_queue; 409 spinlock_t lock; 410 atomic_t usage_count; 411 atomic_t child_count; 412 unsigned int disable_depth:3; 413 unsigned int ignore_children:1; 414 unsigned int idle_notification:1; 415 unsigned int request_pending:1; 416 unsigned int deferred_resume:1; 417 enum rpm_request request; 418 enum rpm_status runtime_status; 419 int runtime_error; 420 #endif 421 }; 422 423 /* 424 * The PM_EVENT_ messages are also used by drivers implementing the legacy 425 * suspend framework, based on the ->suspend() and ->resume() callbacks common 426 * for suspend and hibernation transitions, according to the rules below. 427 */ 428 429 /* Necessary, because several drivers use PM_EVENT_PRETHAW */ 430 #define PM_EVENT_PRETHAW PM_EVENT_QUIESCE 431 432 /* 433 * One transition is triggered by resume(), after a suspend() call; the 434 * message is implicit: 435 * 436 * ON Driver starts working again, responding to hardware events 437 * and software requests. The hardware may have gone through 438 * a power-off reset, or it may have maintained state from the 439 * previous suspend() which the driver will rely on while 440 * resuming. On most platforms, there are no restrictions on 441 * availability of resources like clocks during resume(). 442 * 443 * Other transitions are triggered by messages sent using suspend(). All 444 * these transitions quiesce the driver, so that I/O queues are inactive. 445 * That commonly entails turning off IRQs and DMA; there may be rules 446 * about how to quiesce that are specific to the bus or the device's type. 447 * (For example, network drivers mark the link state.) Other details may 448 * differ according to the message: 449 * 450 * SUSPEND Quiesce, enter a low power device state appropriate for 451 * the upcoming system state (such as PCI_D3hot), and enable 452 * wakeup events as appropriate. 453 * 454 * HIBERNATE Enter a low power device state appropriate for the hibernation 455 * state (eg. ACPI S4) and enable wakeup events as appropriate. 456 * 457 * FREEZE Quiesce operations so that a consistent image can be saved; 458 * but do NOT otherwise enter a low power device state, and do 459 * NOT emit system wakeup events. 460 * 461 * PRETHAW Quiesce as if for FREEZE; additionally, prepare for restoring 462 * the system from a snapshot taken after an earlier FREEZE. 463 * Some drivers will need to reset their hardware state instead 464 * of preserving it, to ensure that it's never mistaken for the 465 * state which that earlier snapshot had set up. 466 * 467 * A minimally power-aware driver treats all messages as SUSPEND, fully 468 * reinitializes its device during resume() -- whether or not it was reset 469 * during the suspend/resume cycle -- and can't issue wakeup events. 470 * 471 * More power-aware drivers may also use low power states at runtime as 472 * well as during system sleep states like PM_SUSPEND_STANDBY. They may 473 * be able to use wakeup events to exit from runtime low-power states, 474 * or from system low-power states such as standby or suspend-to-RAM. 475 */ 476 477 #ifdef CONFIG_PM_SLEEP 478 extern void device_pm_lock(void); 479 extern int sysdev_resume(void); 480 extern void dpm_resume_noirq(pm_message_t state); 481 extern void dpm_resume_end(pm_message_t state); 482 483 extern void device_pm_unlock(void); 484 extern int sysdev_suspend(pm_message_t state); 485 extern int dpm_suspend_noirq(pm_message_t state); 486 extern int dpm_suspend_start(pm_message_t state); 487 488 extern void __suspend_report_result(const char *function, void *fn, int ret); 489 490 #define suspend_report_result(fn, ret) \ 491 do { \ 492 __suspend_report_result(__func__, fn, ret); \ 493 } while (0) 494 495 #else /* !CONFIG_PM_SLEEP */ 496 497 #define device_pm_lock() do {} while (0) 498 #define device_pm_unlock() do {} while (0) 499 500 static inline int dpm_suspend_start(pm_message_t state) 501 { 502 return 0; 503 } 504 505 #define suspend_report_result(fn, ret) do {} while (0) 506 507 #endif /* !CONFIG_PM_SLEEP */ 508 509 /* How to reorder dpm_list after device_move() */ 510 enum dpm_order { 511 DPM_ORDER_NONE, 512 DPM_ORDER_DEV_AFTER_PARENT, 513 DPM_ORDER_PARENT_BEFORE_DEV, 514 DPM_ORDER_DEV_LAST, 515 }; 516 517 /* 518 * Global Power Management flags 519 * Used to keep APM and ACPI from both being active 520 */ 521 extern unsigned int pm_flags; 522 523 #define PM_APM 1 524 #define PM_ACPI 2 525 526 #endif /* _LINUX_PM_H */ 527