Commit | Line | Data |
---|---|---|
5e928f77 RW |
1 | Run-time Power Management Framework for I/O Devices |
2 | ||
3 | (C) 2009 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. | |
4 | ||
5 | 1. Introduction | |
6 | ||
7 | Support for run-time power management (run-time PM) of I/O devices is provided | |
8 | at the power management core (PM core) level by means of: | |
9 | ||
10 | * The power management workqueue pm_wq in which bus types and device drivers can | |
11 | put their PM-related work items. It is strongly recommended that pm_wq be | |
12 | used for queuing all work items related to run-time PM, because this allows | |
13 | them to be synchronized with system-wide power transitions (suspend to RAM, | |
14 | hibernation and resume from system sleep states). pm_wq is declared in | |
15 | include/linux/pm_runtime.h and defined in kernel/power/main.c. | |
16 | ||
17 | * A number of run-time PM fields in the 'power' member of 'struct device' (which | |
18 | is of the type 'struct dev_pm_info', defined in include/linux/pm.h) that can | |
19 | be used for synchronizing run-time PM operations with one another. | |
20 | ||
21 | * Three device run-time PM callbacks in 'struct dev_pm_ops' (defined in | |
22 | include/linux/pm.h). | |
23 | ||
24 | * A set of helper functions defined in drivers/base/power/runtime.c that can be | |
25 | used for carrying out run-time PM operations in such a way that the | |
26 | synchronization between them is taken care of by the PM core. Bus types and | |
27 | device drivers are encouraged to use these functions. | |
28 | ||
29 | The run-time PM callbacks present in 'struct dev_pm_ops', the device run-time PM | |
30 | fields of 'struct dev_pm_info' and the core helper functions provided for | |
31 | run-time PM are described below. | |
32 | ||
33 | 2. Device Run-time PM Callbacks | |
34 | ||
35 | There are three device run-time PM callbacks defined in 'struct dev_pm_ops': | |
36 | ||
37 | struct dev_pm_ops { | |
38 | ... | |
39 | int (*runtime_suspend)(struct device *dev); | |
40 | int (*runtime_resume)(struct device *dev); | |
e1b1903e | 41 | int (*runtime_idle)(struct device *dev); |
5e928f77 RW |
42 | ... |
43 | }; | |
44 | ||
45 | The ->runtime_suspend() callback is executed by the PM core for the bus type of | |
46 | the device being suspended. The bus type's callback is then _entirely_ | |
47 | _responsible_ for handling the device as appropriate, which may, but need not | |
48 | include executing the device driver's own ->runtime_suspend() callback (from the | |
49 | PM core's point of view it is not necessary to implement a ->runtime_suspend() | |
50 | callback in a device driver as long as the bus type's ->runtime_suspend() knows | |
51 | what to do to handle the device). | |
52 | ||
53 | * Once the bus type's ->runtime_suspend() callback has completed successfully | |
54 | for given device, the PM core regards the device as suspended, which need | |
55 | not mean that the device has been put into a low power state. It is | |
56 | supposed to mean, however, that the device will not process data and will | |
57 | not communicate with the CPU(s) and RAM until its bus type's | |
58 | ->runtime_resume() callback is executed for it. The run-time PM status of | |
59 | a device after successful execution of its bus type's ->runtime_suspend() | |
60 | callback is 'suspended'. | |
61 | ||
62 | * If the bus type's ->runtime_suspend() callback returns -EBUSY or -EAGAIN, | |
63 | the device's run-time PM status is supposed to be 'active', which means that | |
64 | the device _must_ be fully operational afterwards. | |
65 | ||
66 | * If the bus type's ->runtime_suspend() callback returns an error code | |
67 | different from -EBUSY or -EAGAIN, the PM core regards this as a fatal | |
68 | error and will refuse to run the helper functions described in Section 4 | |
69 | for the device, until the status of it is directly set either to 'active' | |
70 | or to 'suspended' (the PM core provides special helper functions for this | |
71 | purpose). | |
72 | ||
73 | In particular, if the driver requires remote wakeup capability for proper | |
7a1a8eb5 | 74 | functioning and device_run_wake() returns 'false' for the device, then |
5e928f77 | 75 | ->runtime_suspend() should return -EBUSY. On the other hand, if |
7a1a8eb5 | 76 | device_run_wake() returns 'true' for the device and the device is put |
5e928f77 RW |
77 | into a low power state during the execution of its bus type's |
78 | ->runtime_suspend(), it is expected that remote wake-up (i.e. hardware mechanism | |
79 | allowing the device to request a change of its power state, such as PCI PME) | |
80 | will be enabled for the device. Generally, remote wake-up should be enabled | |
81 | for all input devices put into a low power state at run time. | |
82 | ||
83 | The ->runtime_resume() callback is executed by the PM core for the bus type of | |
84 | the device being woken up. The bus type's callback is then _entirely_ | |
85 | _responsible_ for handling the device as appropriate, which may, but need not | |
86 | include executing the device driver's own ->runtime_resume() callback (from the | |
87 | PM core's point of view it is not necessary to implement a ->runtime_resume() | |
88 | callback in a device driver as long as the bus type's ->runtime_resume() knows | |
89 | what to do to handle the device). | |
90 | ||
91 | * Once the bus type's ->runtime_resume() callback has completed successfully, | |
92 | the PM core regards the device as fully operational, which means that the | |
93 | device _must_ be able to complete I/O operations as needed. The run-time | |
94 | PM status of the device is then 'active'. | |
95 | ||
96 | * If the bus type's ->runtime_resume() callback returns an error code, the PM | |
97 | core regards this as a fatal error and will refuse to run the helper | |
98 | functions described in Section 4 for the device, until its status is | |
99 | directly set either to 'active' or to 'suspended' (the PM core provides | |
100 | special helper functions for this purpose). | |
101 | ||
102 | The ->runtime_idle() callback is executed by the PM core for the bus type of | |
103 | given device whenever the device appears to be idle, which is indicated to the | |
104 | PM core by two counters, the device's usage counter and the counter of 'active' | |
105 | children of the device. | |
106 | ||
107 | * If any of these counters is decreased using a helper function provided by | |
108 | the PM core and it turns out to be equal to zero, the other counter is | |
109 | checked. If that counter also is equal to zero, the PM core executes the | |
110 | device bus type's ->runtime_idle() callback (with the device as an | |
111 | argument). | |
112 | ||
113 | The action performed by a bus type's ->runtime_idle() callback is totally | |
114 | dependent on the bus type in question, but the expected and recommended action | |
115 | is to check if the device can be suspended (i.e. if all of the conditions | |
116 | necessary for suspending the device are satisfied) and to queue up a suspend | |
e1b1903e RW |
117 | request for the device in that case. The value returned by this callback is |
118 | ignored by the PM core. | |
5e928f77 RW |
119 | |
120 | The helper functions provided by the PM core, described in Section 4, guarantee | |
121 | that the following constraints are met with respect to the bus type's run-time | |
122 | PM callbacks: | |
123 | ||
124 | (1) The callbacks are mutually exclusive (e.g. it is forbidden to execute | |
125 | ->runtime_suspend() in parallel with ->runtime_resume() or with another | |
126 | instance of ->runtime_suspend() for the same device) with the exception that | |
127 | ->runtime_suspend() or ->runtime_resume() can be executed in parallel with | |
128 | ->runtime_idle() (although ->runtime_idle() will not be started while any | |
129 | of the other callbacks is being executed for the same device). | |
130 | ||
131 | (2) ->runtime_idle() and ->runtime_suspend() can only be executed for 'active' | |
132 | devices (i.e. the PM core will only execute ->runtime_idle() or | |
133 | ->runtime_suspend() for the devices the run-time PM status of which is | |
134 | 'active'). | |
135 | ||
136 | (3) ->runtime_idle() and ->runtime_suspend() can only be executed for a device | |
137 | the usage counter of which is equal to zero _and_ either the counter of | |
138 | 'active' children of which is equal to zero, or the 'power.ignore_children' | |
139 | flag of which is set. | |
140 | ||
141 | (4) ->runtime_resume() can only be executed for 'suspended' devices (i.e. the | |
142 | PM core will only execute ->runtime_resume() for the devices the run-time | |
143 | PM status of which is 'suspended'). | |
144 | ||
145 | Additionally, the helper functions provided by the PM core obey the following | |
146 | rules: | |
147 | ||
148 | * If ->runtime_suspend() is about to be executed or there's a pending request | |
149 | to execute it, ->runtime_idle() will not be executed for the same device. | |
150 | ||
151 | * A request to execute or to schedule the execution of ->runtime_suspend() | |
152 | will cancel any pending requests to execute ->runtime_idle() for the same | |
153 | device. | |
154 | ||
155 | * If ->runtime_resume() is about to be executed or there's a pending request | |
156 | to execute it, the other callbacks will not be executed for the same device. | |
157 | ||
158 | * A request to execute ->runtime_resume() will cancel any pending or | |
159 | scheduled requests to execute the other callbacks for the same device. | |
160 | ||
161 | 3. Run-time PM Device Fields | |
162 | ||
163 | The following device run-time PM fields are present in 'struct dev_pm_info', as | |
164 | defined in include/linux/pm.h: | |
165 | ||
166 | struct timer_list suspend_timer; | |
167 | - timer used for scheduling (delayed) suspend request | |
168 | ||
169 | unsigned long timer_expires; | |
170 | - timer expiration time, in jiffies (if this is different from zero, the | |
171 | timer is running and will expire at that time, otherwise the timer is not | |
172 | running) | |
173 | ||
174 | struct work_struct work; | |
175 | - work structure used for queuing up requests (i.e. work items in pm_wq) | |
176 | ||
177 | wait_queue_head_t wait_queue; | |
178 | - wait queue used if any of the helper functions needs to wait for another | |
179 | one to complete | |
180 | ||
181 | spinlock_t lock; | |
182 | - lock used for synchronisation | |
183 | ||
184 | atomic_t usage_count; | |
185 | - the usage counter of the device | |
186 | ||
187 | atomic_t child_count; | |
188 | - the count of 'active' children of the device | |
189 | ||
190 | unsigned int ignore_children; | |
191 | - if set, the value of child_count is ignored (but still updated) | |
192 | ||
193 | unsigned int disable_depth; | |
194 | - used for disabling the helper funcions (they work normally if this is | |
195 | equal to zero); the initial value of it is 1 (i.e. run-time PM is | |
196 | initially disabled for all devices) | |
197 | ||
198 | unsigned int runtime_error; | |
199 | - if set, there was a fatal error (one of the callbacks returned error code | |
200 | as described in Section 2), so the helper funtions will not work until | |
201 | this flag is cleared; this is the error code returned by the failing | |
202 | callback | |
203 | ||
204 | unsigned int idle_notification; | |
205 | - if set, ->runtime_idle() is being executed | |
206 | ||
207 | unsigned int request_pending; | |
208 | - if set, there's a pending request (i.e. a work item queued up into pm_wq) | |
209 | ||
210 | enum rpm_request request; | |
211 | - type of request that's pending (valid if request_pending is set) | |
212 | ||
213 | unsigned int deferred_resume; | |
214 | - set if ->runtime_resume() is about to be run while ->runtime_suspend() is | |
215 | being executed for that device and it is not practical to wait for the | |
216 | suspend to complete; means "start a resume as soon as you've suspended" | |
217 | ||
7a1a8eb5 RW |
218 | unsigned int run_wake; |
219 | - set if the device is capable of generating run-time wake-up events | |
220 | ||
5e928f77 RW |
221 | enum rpm_status runtime_status; |
222 | - the run-time PM status of the device; this field's initial value is | |
223 | RPM_SUSPENDED, which means that each device is initially regarded by the | |
224 | PM core as 'suspended', regardless of its real hardware status | |
225 | ||
226 | All of the above fields are members of the 'power' member of 'struct device'. | |
227 | ||
228 | 4. Run-time PM Device Helper Functions | |
229 | ||
230 | The following run-time PM helper functions are defined in | |
231 | drivers/base/power/runtime.c and include/linux/pm_runtime.h: | |
232 | ||
233 | void pm_runtime_init(struct device *dev); | |
234 | - initialize the device run-time PM fields in 'struct dev_pm_info' | |
235 | ||
236 | void pm_runtime_remove(struct device *dev); | |
237 | - make sure that the run-time PM of the device will be disabled after | |
238 | removing the device from device hierarchy | |
239 | ||
240 | int pm_runtime_idle(struct device *dev); | |
241 | - execute ->runtime_idle() for the device's bus type; returns 0 on success | |
242 | or error code on failure, where -EINPROGRESS means that ->runtime_idle() | |
243 | is already being executed | |
244 | ||
245 | int pm_runtime_suspend(struct device *dev); | |
246 | - execute ->runtime_suspend() for the device's bus type; returns 0 on | |
247 | success, 1 if the device's run-time PM status was already 'suspended', or | |
248 | error code on failure, where -EAGAIN or -EBUSY means it is safe to attempt | |
249 | to suspend the device again in future | |
250 | ||
251 | int pm_runtime_resume(struct device *dev); | |
252 | - execute ->runtime_resume() for the device's bus type; returns 0 on | |
253 | success, 1 if the device's run-time PM status was already 'active' or | |
254 | error code on failure, where -EAGAIN means it may be safe to attempt to | |
255 | resume the device again in future, but 'power.runtime_error' should be | |
256 | checked additionally | |
257 | ||
258 | int pm_request_idle(struct device *dev); | |
259 | - submit a request to execute ->runtime_idle() for the device's bus type | |
260 | (the request is represented by a work item in pm_wq); returns 0 on success | |
261 | or error code if the request has not been queued up | |
262 | ||
263 | int pm_schedule_suspend(struct device *dev, unsigned int delay); | |
264 | - schedule the execution of ->runtime_suspend() for the device's bus type | |
265 | in future, where 'delay' is the time to wait before queuing up a suspend | |
266 | work item in pm_wq, in milliseconds (if 'delay' is zero, the work item is | |
267 | queued up immediately); returns 0 on success, 1 if the device's PM | |
268 | run-time status was already 'suspended', or error code if the request | |
269 | hasn't been scheduled (or queued up if 'delay' is 0); if the execution of | |
270 | ->runtime_suspend() is already scheduled and not yet expired, the new | |
271 | value of 'delay' will be used as the time to wait | |
272 | ||
273 | int pm_request_resume(struct device *dev); | |
274 | - submit a request to execute ->runtime_resume() for the device's bus type | |
275 | (the request is represented by a work item in pm_wq); returns 0 on | |
276 | success, 1 if the device's run-time PM status was already 'active', or | |
277 | error code if the request hasn't been queued up | |
278 | ||
279 | void pm_runtime_get_noresume(struct device *dev); | |
280 | - increment the device's usage counter | |
281 | ||
282 | int pm_runtime_get(struct device *dev); | |
283 | - increment the device's usage counter, run pm_request_resume(dev) and | |
284 | return its result | |
285 | ||
286 | int pm_runtime_get_sync(struct device *dev); | |
287 | - increment the device's usage counter, run pm_runtime_resume(dev) and | |
288 | return its result | |
289 | ||
290 | void pm_runtime_put_noidle(struct device *dev); | |
291 | - decrement the device's usage counter | |
292 | ||
293 | int pm_runtime_put(struct device *dev); | |
294 | - decrement the device's usage counter, run pm_request_idle(dev) and return | |
295 | its result | |
296 | ||
297 | int pm_runtime_put_sync(struct device *dev); | |
298 | - decrement the device's usage counter, run pm_runtime_idle(dev) and return | |
299 | its result | |
300 | ||
301 | void pm_runtime_enable(struct device *dev); | |
302 | - enable the run-time PM helper functions to run the device bus type's | |
303 | run-time PM callbacks described in Section 2 | |
304 | ||
305 | int pm_runtime_disable(struct device *dev); | |
306 | - prevent the run-time PM helper functions from running the device bus | |
307 | type's run-time PM callbacks, make sure that all of the pending run-time | |
308 | PM operations on the device are either completed or canceled; returns | |
309 | 1 if there was a resume request pending and it was necessary to execute | |
310 | ->runtime_resume() for the device's bus type to satisfy that request, | |
311 | otherwise 0 is returned | |
312 | ||
313 | void pm_suspend_ignore_children(struct device *dev, bool enable); | |
314 | - set/unset the power.ignore_children flag of the device | |
315 | ||
316 | int pm_runtime_set_active(struct device *dev); | |
317 | - clear the device's 'power.runtime_error' flag, set the device's run-time | |
318 | PM status to 'active' and update its parent's counter of 'active' | |
319 | children as appropriate (it is only valid to use this function if | |
320 | 'power.runtime_error' is set or 'power.disable_depth' is greater than | |
321 | zero); it will fail and return error code if the device has a parent | |
322 | which is not active and the 'power.ignore_children' flag of which is unset | |
323 | ||
324 | void pm_runtime_set_suspended(struct device *dev); | |
325 | - clear the device's 'power.runtime_error' flag, set the device's run-time | |
326 | PM status to 'suspended' and update its parent's counter of 'active' | |
327 | children as appropriate (it is only valid to use this function if | |
328 | 'power.runtime_error' is set or 'power.disable_depth' is greater than | |
329 | zero) | |
330 | ||
331 | It is safe to execute the following helper functions from interrupt context: | |
332 | ||
333 | pm_request_idle() | |
334 | pm_schedule_suspend() | |
335 | pm_request_resume() | |
336 | pm_runtime_get_noresume() | |
337 | pm_runtime_get() | |
338 | pm_runtime_put_noidle() | |
339 | pm_runtime_put() | |
340 | pm_suspend_ignore_children() | |
341 | pm_runtime_set_active() | |
342 | pm_runtime_set_suspended() | |
343 | pm_runtime_enable() | |
344 | ||
345 | 5. Run-time PM Initialization, Device Probing and Removal | |
346 | ||
347 | Initially, the run-time PM is disabled for all devices, which means that the | |
348 | majority of the run-time PM helper funtions described in Section 4 will return | |
349 | -EAGAIN until pm_runtime_enable() is called for the device. | |
350 | ||
351 | In addition to that, the initial run-time PM status of all devices is | |
352 | 'suspended', but it need not reflect the actual physical state of the device. | |
353 | Thus, if the device is initially active (i.e. it is able to process I/O), its | |
354 | run-time PM status must be changed to 'active', with the help of | |
355 | pm_runtime_set_active(), before pm_runtime_enable() is called for the device. | |
356 | ||
357 | However, if the device has a parent and the parent's run-time PM is enabled, | |
358 | calling pm_runtime_set_active() for the device will affect the parent, unless | |
359 | the parent's 'power.ignore_children' flag is set. Namely, in that case the | |
360 | parent won't be able to suspend at run time, using the PM core's helper | |
361 | functions, as long as the child's status is 'active', even if the child's | |
362 | run-time PM is still disabled (i.e. pm_runtime_enable() hasn't been called for | |
363 | the child yet or pm_runtime_disable() has been called for it). For this reason, | |
364 | once pm_runtime_set_active() has been called for the device, pm_runtime_enable() | |
365 | should be called for it too as soon as reasonably possible or its run-time PM | |
366 | status should be changed back to 'suspended' with the help of | |
367 | pm_runtime_set_suspended(). | |
368 | ||
369 | If the default initial run-time PM status of the device (i.e. 'suspended') | |
370 | reflects the actual state of the device, its bus type's or its driver's | |
371 | ->probe() callback will likely need to wake it up using one of the PM core's | |
372 | helper functions described in Section 4. In that case, pm_runtime_resume() | |
373 | should be used. Of course, for this purpose the device's run-time PM has to be | |
374 | enabled earlier by calling pm_runtime_enable(). | |
375 | ||
376 | If the device bus type's or driver's ->probe() or ->remove() callback runs | |
377 | pm_runtime_suspend() or pm_runtime_idle() or their asynchronous counterparts, | |
378 | they will fail returning -EAGAIN, because the device's usage counter is | |
379 | incremented by the core before executing ->probe() and ->remove(). Still, it | |
380 | may be desirable to suspend the device as soon as ->probe() or ->remove() has | |
381 | finished, so the PM core uses pm_runtime_idle_sync() to invoke the device bus | |
382 | type's ->runtime_idle() callback at that time. |