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