diff options
Diffstat (limited to 'include/linux/pm.h')
-rw-r--r-- | include/linux/pm.h | 229 |
1 files changed, 134 insertions, 95 deletions
diff --git a/include/linux/pm.h b/include/linux/pm.h index 5c4c8b18c8b7..3f3ed83a9aa5 100644 --- a/include/linux/pm.h +++ b/include/linux/pm.h | |||
@@ -54,118 +54,145 @@ typedef struct pm_message { | |||
54 | /** | 54 | /** |
55 | * struct dev_pm_ops - device PM callbacks | 55 | * struct dev_pm_ops - device PM callbacks |
56 | * | 56 | * |
57 | * Several driver power state transitions are externally visible, affecting | 57 | * Several device power state transitions are externally visible, affecting |
58 | * the state of pending I/O queues and (for drivers that touch hardware) | 58 | * the state of pending I/O queues and (for drivers that touch hardware) |
59 | * interrupts, wakeups, DMA, and other hardware state. There may also be | 59 | * interrupts, wakeups, DMA, and other hardware state. There may also be |
60 | * internal transitions to various low power modes, which are transparent | 60 | * internal transitions to various low-power modes which are transparent |
61 | * to the rest of the driver stack (such as a driver that's ON gating off | 61 | * to the rest of the driver stack (such as a driver that's ON gating off |
62 | * clocks which are not in active use). | 62 | * clocks which are not in active use). |
63 | * | 63 | * |
64 | * The externally visible transitions are handled with the help of the following | 64 | * The externally visible transitions are handled with the help of callbacks |
65 | * callbacks included in this structure: | 65 | * included in this structure in such a way that two levels of callbacks are |
66 | * | 66 | * involved. First, the PM core executes callbacks provided by PM domains, |
67 | * @prepare: Prepare the device for the upcoming transition, but do NOT change | 67 | * device types, classes and bus types. They are the subsystem-level callbacks |
68 | * its hardware state. Prevent new children of the device from being | 68 | * supposed to execute callbacks provided by device drivers, although they may |
69 | * registered after @prepare() returns (the driver's subsystem and | 69 | * choose not to do that. If the driver callbacks are executed, they have to |
70 | * generally the rest of the kernel is supposed to prevent new calls to the | 70 | * collaborate with the subsystem-level callbacks to achieve the goals |
71 | * probe method from being made too once @prepare() has succeeded). If | 71 | * appropriate for the given system transition, given transition phase and the |
72 | * @prepare() detects a situation it cannot handle (e.g. registration of a | 72 | * subsystem the device belongs to. |
73 | * child already in progress), it may return -EAGAIN, so that the PM core | 73 | * |
74 | * can execute it once again (e.g. after the new child has been registered) | 74 | * @prepare: The principal role of this callback is to prevent new children of |
75 | * to recover from the race condition. This method is executed for all | 75 | * the device from being registered after it has returned (the driver's |
76 | * kinds of suspend transitions and is followed by one of the suspend | 76 | * subsystem and generally the rest of the kernel is supposed to prevent |
77 | * callbacks: @suspend(), @freeze(), or @poweroff(). | 77 | * new calls to the probe method from being made too once @prepare() has |
78 | * The PM core executes @prepare() for all devices before starting to | 78 | * succeeded). If @prepare() detects a situation it cannot handle (e.g. |
79 | * execute suspend callbacks for any of them, so drivers may assume all of | 79 | * registration of a child already in progress), it may return -EAGAIN, so |
80 | * the other devices to be present and functional while @prepare() is being | 80 | * that the PM core can execute it once again (e.g. after a new child has |
81 | * executed. In particular, it is safe to make GFP_KERNEL memory | 81 | * been registered) to recover from the race condition. |
82 | * allocations from within @prepare(). However, drivers may NOT assume | 82 | * This method is executed for all kinds of suspend transitions and is |
83 | * anything about the availability of the user space at that time and it | 83 | * followed by one of the suspend callbacks: @suspend(), @freeze(), or |
84 | * is not correct to request firmware from within @prepare() (it's too | 84 | * @poweroff(). The PM core executes subsystem-level @prepare() for all |
85 | * late to do that). [To work around this limitation, drivers may | 85 | * devices before starting to invoke suspend callbacks for any of them, so |
86 | * register suspend and hibernation notifiers that are executed before the | 86 | * generally devices may be assumed to be functional or to respond to |
87 | * freezing of tasks.] | 87 | * runtime resume requests while @prepare() is being executed. However, |
88 | * device drivers may NOT assume anything about the availability of user | ||
89 | * space at that time and it is NOT valid to request firmware from within | ||
90 | * @prepare() (it's too late to do that). It also is NOT valid to allocate | ||
91 | * substantial amounts of memory from @prepare() in the GFP_KERNEL mode. | ||
92 | * [To work around these limitations, drivers may register suspend and | ||
93 | * hibernation notifiers to be executed before the freezing of tasks.] | ||
88 | * | 94 | * |
89 | * @complete: Undo the changes made by @prepare(). This method is executed for | 95 | * @complete: Undo the changes made by @prepare(). This method is executed for |
90 | * all kinds of resume transitions, following one of the resume callbacks: | 96 | * all kinds of resume transitions, following one of the resume callbacks: |
91 | * @resume(), @thaw(), @restore(). Also called if the state transition | 97 | * @resume(), @thaw(), @restore(). Also called if the state transition |
92 | * fails before the driver's suspend callback (@suspend(), @freeze(), | 98 | * fails before the driver's suspend callback: @suspend(), @freeze() or |
93 | * @poweroff()) can be executed (e.g. if the suspend callback fails for one | 99 | * @poweroff(), can be executed (e.g. if the suspend callback fails for one |
94 | * of the other devices that the PM core has unsuccessfully attempted to | 100 | * of the other devices that the PM core has unsuccessfully attempted to |
95 | * suspend earlier). | 101 | * suspend earlier). |
96 | * The PM core executes @complete() after it has executed the appropriate | 102 | * The PM core executes subsystem-level @complete() after it has executed |
97 | * resume callback for all devices. | 103 | * the appropriate resume callbacks for all devices. |
98 | * | 104 | * |
99 | * @suspend: Executed before putting the system into a sleep state in which the | 105 | * @suspend: Executed before putting the system into a sleep state in which the |
100 | * contents of main memory are preserved. Quiesce the device, put it into | 106 | * contents of main memory are preserved. The exact action to perform |
101 | * a low power state appropriate for the upcoming system state (such as | 107 | * depends on the device's subsystem (PM domain, device type, class or bus |
102 | * PCI_D3hot), and enable wakeup events as appropriate. | 108 | * type), but generally the device must be quiescent after subsystem-level |
109 | * @suspend() has returned, so that it doesn't do any I/O or DMA. | ||
110 | * Subsystem-level @suspend() is executed for all devices after invoking | ||
111 | * subsystem-level @prepare() for all of them. | ||
103 | * | 112 | * |
104 | * @resume: Executed after waking the system up from a sleep state in which the | 113 | * @resume: Executed after waking the system up from a sleep state in which the |
105 | * contents of main memory were preserved. Put the device into the | 114 | * contents of main memory were preserved. The exact action to perform |
106 | * appropriate state, according to the information saved in memory by the | 115 | * depends on the device's subsystem, but generally the driver is expected |
107 | * preceding @suspend(). The driver starts working again, responding to | 116 | * to start working again, responding to hardware events and software |
108 | * hardware events and software requests. The hardware may have gone | 117 | * requests (the device itself may be left in a low-power state, waiting |
109 | * through a power-off reset, or it may have maintained state from the | 118 | * for a runtime resume to occur). The state of the device at the time its |
110 | * previous suspend() which the driver may rely on while resuming. On most | 119 | * driver's @resume() callback is run depends on the platform and subsystem |
111 | * platforms, there are no restrictions on availability of resources like | 120 | * the device belongs to. On most platforms, there are no restrictions on |
112 | * clocks during @resume(). | 121 | * availability of resources like clocks during @resume(). |
122 | * Subsystem-level @resume() is executed for all devices after invoking | ||
123 | * subsystem-level @resume_noirq() for all of them. | ||
113 | * | 124 | * |
114 | * @freeze: Hibernation-specific, executed before creating a hibernation image. | 125 | * @freeze: Hibernation-specific, executed before creating a hibernation image. |
115 | * Quiesce operations so that a consistent image can be created, but do NOT | 126 | * Analogous to @suspend(), but it should not enable the device to signal |
116 | * otherwise put the device into a low power device state and do NOT emit | 127 | * wakeup events or change its power state. The majority of subsystems |
117 | * system wakeup events. Save in main memory the device settings to be | 128 | * (with the notable exception of the PCI bus type) expect the driver-level |
118 | * used by @restore() during the subsequent resume from hibernation or by | 129 | * @freeze() to save the device settings in memory to be used by @restore() |
119 | * the subsequent @thaw(), if the creation of the image or the restoration | 130 | * during the subsequent resume from hibernation. |
120 | * of main memory contents from it fails. | 131 | * Subsystem-level @freeze() is executed for all devices after invoking |
132 | * subsystem-level @prepare() for all of them. | ||
121 | * | 133 | * |
122 | * @thaw: Hibernation-specific, executed after creating a hibernation image OR | 134 | * @thaw: Hibernation-specific, executed after creating a hibernation image OR |
123 | * if the creation of the image fails. Also executed after a failing | 135 | * if the creation of an image has failed. Also executed after a failing |
124 | * attempt to restore the contents of main memory from such an image. | 136 | * attempt to restore the contents of main memory from such an image. |
125 | * Undo the changes made by the preceding @freeze(), so the device can be | 137 | * Undo the changes made by the preceding @freeze(), so the device can be |
126 | * operated in the same way as immediately before the call to @freeze(). | 138 | * operated in the same way as immediately before the call to @freeze(). |
139 | * Subsystem-level @thaw() is executed for all devices after invoking | ||
140 | * subsystem-level @thaw_noirq() for all of them. It also may be executed | ||
141 | * directly after @freeze() in case of a transition error. | ||
127 | * | 142 | * |
128 | * @poweroff: Hibernation-specific, executed after saving a hibernation image. | 143 | * @poweroff: Hibernation-specific, executed after saving a hibernation image. |
129 | * Quiesce the device, put it into a low power state appropriate for the | 144 | * Analogous to @suspend(), but it need not save the device's settings in |
130 | * upcoming system state (such as PCI_D3hot), and enable wakeup events as | 145 | * memory. |
131 | * appropriate. | 146 | * Subsystem-level @poweroff() is executed for all devices after invoking |
147 | * subsystem-level @prepare() for all of them. | ||
132 | * | 148 | * |
133 | * @restore: Hibernation-specific, executed after restoring the contents of main | 149 | * @restore: Hibernation-specific, executed after restoring the contents of main |
134 | * memory from a hibernation image. Driver starts working again, | 150 | * memory from a hibernation image, analogous to @resume(). |
135 | * responding to hardware events and software requests. Drivers may NOT | 151 | * |
136 | * make ANY assumptions about the hardware state right prior to @restore(). | 152 | * @suspend_noirq: Complete the actions started by @suspend(). Carry out any |
137 | * On most platforms, there are no restrictions on availability of | 153 | * additional operations required for suspending the device that might be |
138 | * resources like clocks during @restore(). | 154 | * racing with its driver's interrupt handler, which is guaranteed not to |
139 | * | 155 | * run while @suspend_noirq() is being executed. |
140 | * @suspend_noirq: Complete the operations of ->suspend() by carrying out any | 156 | * It generally is expected that the device will be in a low-power state |
141 | * actions required for suspending the device that need interrupts to be | 157 | * (appropriate for the target system sleep state) after subsystem-level |
142 | * disabled | 158 | * @suspend_noirq() has returned successfully. If the device can generate |
143 | * | 159 | * system wakeup signals and is enabled to wake up the system, it should be |
144 | * @resume_noirq: Prepare for the execution of ->resume() by carrying out any | 160 | * configured to do so at that time. However, depending on the platform |
145 | * actions required for resuming the device that need interrupts to be | 161 | * and device's subsystem, @suspend() may be allowed to put the device into |
146 | * disabled | 162 | * the low-power state and configure it to generate wakeup signals, in |
147 | * | 163 | * which case it generally is not necessary to define @suspend_noirq(). |
148 | * @freeze_noirq: Complete the operations of ->freeze() by carrying out any | 164 | * |
149 | * actions required for freezing the device that need interrupts to be | 165 | * @resume_noirq: Prepare for the execution of @resume() by carrying out any |
150 | * disabled | 166 | * operations required for resuming the device that might be racing with |
151 | * | 167 | * its driver's interrupt handler, which is guaranteed not to run while |
152 | * @thaw_noirq: Prepare for the execution of ->thaw() by carrying out any | 168 | * @resume_noirq() is being executed. |
153 | * actions required for thawing the device that need interrupts to be | 169 | * |
154 | * disabled | 170 | * @freeze_noirq: Complete the actions started by @freeze(). Carry out any |
155 | * | 171 | * additional operations required for freezing the device that might be |
156 | * @poweroff_noirq: Complete the operations of ->poweroff() by carrying out any | 172 | * racing with its driver's interrupt handler, which is guaranteed not to |
157 | * actions required for handling the device that need interrupts to be | 173 | * run while @freeze_noirq() is being executed. |
158 | * disabled | 174 | * The power state of the device should not be changed by either @freeze() |
159 | * | 175 | * or @freeze_noirq() and it should not be configured to signal system |
160 | * @restore_noirq: Prepare for the execution of ->restore() by carrying out any | 176 | * wakeup by any of these callbacks. |
161 | * actions required for restoring the operations of the device that need | 177 | * |
162 | * interrupts to be disabled | 178 | * @thaw_noirq: Prepare for the execution of @thaw() by carrying out any |
179 | * operations required for thawing the device that might be racing with its | ||
180 | * driver's interrupt handler, which is guaranteed not to run while | ||
181 | * @thaw_noirq() is being executed. | ||
182 | * | ||
183 | * @poweroff_noirq: Complete the actions started by @poweroff(). Analogous to | ||
184 | * @suspend_noirq(), but it need not save the device's settings in memory. | ||
185 | * | ||
186 | * @restore_noirq: Prepare for the execution of @restore() by carrying out any | ||
187 | * operations required for thawing the device that might be racing with its | ||
188 | * driver's interrupt handler, which is guaranteed not to run while | ||
189 | * @restore_noirq() is being executed. Analogous to @resume_noirq(). | ||
163 | * | 190 | * |
164 | * All of the above callbacks, except for @complete(), return error codes. | 191 | * All of the above callbacks, except for @complete(), return error codes. |
165 | * However, the error codes returned by the resume operations, @resume(), | 192 | * However, the error codes returned by the resume operations, @resume(), |
166 | * @thaw(), @restore(), @resume_noirq(), @thaw_noirq(), and @restore_noirq() do | 193 | * @thaw(), @restore(), @resume_noirq(), @thaw_noirq(), and @restore_noirq(), do |
167 | * not cause the PM core to abort the resume transition during which they are | 194 | * not cause the PM core to abort the resume transition during which they are |
168 | * returned. The error codes returned in that cases are only printed by the PM | 195 | * returned. The error codes returned in those cases are only printed by the PM |
169 | * core to the system logs for debugging purposes. Still, it is recommended | 196 | * core to the system logs for debugging purposes. Still, it is recommended |
170 | * that drivers only return error codes from their resume methods in case of an | 197 | * that drivers only return error codes from their resume methods in case of an |
171 | * unrecoverable failure (i.e. when the device being handled refuses to resume | 198 | * unrecoverable failure (i.e. when the device being handled refuses to resume |
@@ -174,31 +201,43 @@ typedef struct pm_message { | |||
174 | * their children. | 201 | * their children. |
175 | * | 202 | * |
176 | * It is allowed to unregister devices while the above callbacks are being | 203 | * It is allowed to unregister devices while the above callbacks are being |
177 | * executed. However, it is not allowed to unregister a device from within any | 204 | * executed. However, a callback routine must NOT try to unregister the device |
178 | * of its own callbacks. | 205 | * it was called for, although it may unregister children of that device (for |
206 | * example, if it detects that a child was unplugged while the system was | ||
207 | * asleep). | ||
208 | * | ||
209 | * Refer to Documentation/power/devices.txt for more information about the role | ||
210 | * of the above callbacks in the system suspend process. | ||
179 | * | 211 | * |
180 | * There also are the following callbacks related to run-time power management | 212 | * There also are callbacks related to runtime power management of devices. |
181 | * of devices: | 213 | * Again, these callbacks are executed by the PM core only for subsystems |
214 | * (PM domains, device types, classes and bus types) and the subsystem-level | ||
215 | * callbacks are supposed to invoke the driver callbacks. Moreover, the exact | ||
216 | * actions to be performed by a device driver's callbacks generally depend on | ||
217 | * the platform and subsystem the device belongs to. | ||
182 | * | 218 | * |
183 | * @runtime_suspend: Prepare the device for a condition in which it won't be | 219 | * @runtime_suspend: Prepare the device for a condition in which it won't be |
184 | * able to communicate with the CPU(s) and RAM due to power management. | 220 | * able to communicate with the CPU(s) and RAM due to power management. |
185 | * This need not mean that the device should be put into a low power state. | 221 | * This need not mean that the device should be put into a low-power state. |
186 | * For example, if the device is behind a link which is about to be turned | 222 | * For example, if the device is behind a link which is about to be turned |
187 | * off, the device may remain at full power. If the device does go to low | 223 | * off, the device may remain at full power. If the device does go to low |
188 | * power and is capable of generating run-time wake-up events, remote | 224 | * power and is capable of generating runtime wakeup events, remote wakeup |
189 | * wake-up (i.e., a hardware mechanism allowing the device to request a | 225 | * (i.e., a hardware mechanism allowing the device to request a change of |
190 | * change of its power state via a wake-up event, such as PCI PME) should | 226 | * its power state via an interrupt) should be enabled for it. |
191 | * be enabled for it. | ||
192 | * | 227 | * |
193 | * @runtime_resume: Put the device into the fully active state in response to a | 228 | * @runtime_resume: Put the device into the fully active state in response to a |
194 | * wake-up event generated by hardware or at the request of software. If | 229 | * wakeup event generated by hardware or at the request of software. If |
195 | * necessary, put the device into the full power state and restore its | 230 | * necessary, put the device into the full-power state and restore its |
196 | * registers, so that it is fully operational. | 231 | * registers, so that it is fully operational. |
197 | * | 232 | * |
198 | * @runtime_idle: Device appears to be inactive and it might be put into a low | 233 | * @runtime_idle: Device appears to be inactive and it might be put into a |
199 | * power state if all of the necessary conditions are satisfied. Check | 234 | * low-power state if all of the necessary conditions are satisfied. Check |
200 | * these conditions and handle the device as appropriate, possibly queueing | 235 | * these conditions and handle the device as appropriate, possibly queueing |
201 | * a suspend request for it. The return value is ignored by the PM core. | 236 | * a suspend request for it. The return value is ignored by the PM core. |
237 | * | ||
238 | * Refer to Documentation/power/runtime_pm.txt for more information about the | ||
239 | * role of the above callbacks in device runtime power management. | ||
240 | * | ||
202 | */ | 241 | */ |
203 | 242 | ||
204 | struct dev_pm_ops { | 243 | struct dev_pm_ops { |