Commit | Line | Data |
---|---|---|
cd38c1e1 AS |
1 | Power Management for USB |
2 | ||
3 | Alan Stern <stern@rowland.harvard.edu> | |
4 | ||
9bbdf1e0 | 5 | December 11, 2009 |
cd38c1e1 AS |
6 | |
7 | ||
8 | ||
9 | What is Power Management? | |
10 | ------------------------- | |
11 | ||
12 | Power Management (PM) is the practice of saving energy by suspending | |
13 | parts of a computer system when they aren't being used. While a | |
14 | component is "suspended" it is in a nonfunctional low-power state; it | |
15 | might even be turned off completely. A suspended component can be | |
16 | "resumed" (returned to a functional full-power state) when the kernel | |
17 | needs to use it. (There also are forms of PM in which components are | |
18 | placed in a less functional but still usable state instead of being | |
19 | suspended; an example would be reducing the CPU's clock rate. This | |
20 | document will not discuss those other forms.) | |
21 | ||
22 | When the parts being suspended include the CPU and most of the rest of | |
23 | the system, we speak of it as a "system suspend". When a particular | |
24 | device is turned off while the system as a whole remains running, we | |
25 | call it a "dynamic suspend" (also known as a "runtime suspend" or | |
26 | "selective suspend"). This document concentrates mostly on how | |
27 | dynamic PM is implemented in the USB subsystem, although system PM is | |
28 | covered to some extent (see Documentation/power/*.txt for more | |
29 | information about system PM). | |
30 | ||
31 | Note: Dynamic PM support for USB is present only if the kernel was | |
9bbdf1e0 AS |
32 | built with CONFIG_USB_SUSPEND enabled (which depends on |
33 | CONFIG_PM_RUNTIME). System PM support is present only if the kernel | |
34 | was built with CONFIG_SUSPEND or CONFIG_HIBERNATION enabled. | |
cd38c1e1 AS |
35 | |
36 | ||
37 | What is Remote Wakeup? | |
38 | ---------------------- | |
39 | ||
40 | When a device has been suspended, it generally doesn't resume until | |
41 | the computer tells it to. Likewise, if the entire computer has been | |
42 | suspended, it generally doesn't resume until the user tells it to, say | |
43 | by pressing a power button or opening the cover. | |
44 | ||
45 | However some devices have the capability of resuming by themselves, or | |
46 | asking the kernel to resume them, or even telling the entire computer | |
47 | to resume. This capability goes by several names such as "Wake On | |
48 | LAN"; we will refer to it generically as "remote wakeup". When a | |
49 | device is enabled for remote wakeup and it is suspended, it may resume | |
50 | itself (or send a request to be resumed) in response to some external | |
51 | event. Examples include a suspended keyboard resuming when a key is | |
52 | pressed, or a suspended USB hub resuming when a device is plugged in. | |
53 | ||
54 | ||
55 | When is a USB device idle? | |
56 | -------------------------- | |
57 | ||
58 | A device is idle whenever the kernel thinks it's not busy doing | |
59 | anything important and thus is a candidate for being suspended. The | |
60 | exact definition depends on the device's driver; drivers are allowed | |
61 | to declare that a device isn't idle even when there's no actual | |
62 | communication taking place. (For example, a hub isn't considered idle | |
63 | unless all the devices plugged into that hub are already suspended.) | |
64 | In addition, a device isn't considered idle so long as a program keeps | |
65 | its usbfs file open, whether or not any I/O is going on. | |
66 | ||
67 | If a USB device has no driver, its usbfs file isn't open, and it isn't | |
68 | being accessed through sysfs, then it definitely is idle. | |
69 | ||
70 | ||
71 | Forms of dynamic PM | |
72 | ------------------- | |
73 | ||
baf67741 AS |
74 | Dynamic suspends occur when the kernel decides to suspend an idle |
75 | device. This is called "autosuspend" for short. In general, a device | |
76 | won't be autosuspended unless it has been idle for some minimum period | |
77 | of time, the so-called idle-delay time. | |
cd38c1e1 AS |
78 | |
79 | Of course, nothing the kernel does on its own initiative should | |
80 | prevent the computer or its devices from working properly. If a | |
81 | device has been autosuspended and a program tries to use it, the | |
82 | kernel will automatically resume the device (autoresume). For the | |
83 | same reason, an autosuspended device will usually have remote wakeup | |
84 | enabled, if the device supports remote wakeup. | |
85 | ||
86 | It is worth mentioning that many USB drivers don't support | |
87 | autosuspend. In fact, at the time of this writing (Linux 2.6.23) the | |
88 | only drivers which do support it are the hub driver, kaweth, asix, | |
89 | usblp, usblcd, and usb-skeleton (which doesn't count). If a | |
90 | non-supporting driver is bound to a device, the device won't be | |
91 | autosuspended. In effect, the kernel pretends the device is never | |
92 | idle. | |
93 | ||
94 | We can categorize power management events in two broad classes: | |
95 | external and internal. External events are those triggered by some | |
96 | agent outside the USB stack: system suspend/resume (triggered by | |
baf67741 AS |
97 | userspace), manual dynamic resume (also triggered by userspace), and |
98 | remote wakeup (triggered by the device). Internal events are those | |
99 | triggered within the USB stack: autosuspend and autoresume. Note that | |
100 | all dynamic suspend events are internal; external agents are not | |
101 | allowed to issue dynamic suspends. | |
cd38c1e1 AS |
102 | |
103 | ||
104 | The user interface for dynamic PM | |
105 | --------------------------------- | |
106 | ||
107 | The user interface for controlling dynamic PM is located in the power/ | |
108 | subdirectory of each USB device's sysfs directory, that is, in | |
109 | /sys/bus/usb/devices/.../power/ where "..." is the device's ID. The | |
110 | relevant attribute files are: wakeup, level, and autosuspend. | |
111 | ||
112 | power/wakeup | |
113 | ||
114 | This file is empty if the device does not support | |
115 | remote wakeup. Otherwise the file contains either the | |
116 | word "enabled" or the word "disabled", and you can | |
117 | write those words to the file. The setting determines | |
118 | whether or not remote wakeup will be enabled when the | |
119 | device is next suspended. (If the setting is changed | |
120 | while the device is suspended, the change won't take | |
121 | effect until the following suspend.) | |
122 | ||
123 | power/level | |
124 | ||
8e4ceb38 AS |
125 | This file contains one of two words: "on" or "auto". |
126 | You can write those words to the file to change the | |
127 | device's setting. | |
cd38c1e1 AS |
128 | |
129 | "on" means that the device should be resumed and | |
130 | autosuspend is not allowed. (Of course, system | |
131 | suspends are still allowed.) | |
132 | ||
133 | "auto" is the normal state in which the kernel is | |
134 | allowed to autosuspend and autoresume the device. | |
135 | ||
8e4ceb38 AS |
136 | (In kernels up to 2.6.32, you could also specify |
137 | "suspend", meaning that the device should remain | |
138 | suspended and autoresume was not allowed. This | |
139 | setting is no longer supported.) | |
cd38c1e1 AS |
140 | |
141 | power/autosuspend | |
142 | ||
143 | This file contains an integer value, which is the | |
144 | number of seconds the device should remain idle before | |
145 | the kernel will autosuspend it (the idle-delay time). | |
146 | The default is 2. 0 means to autosuspend as soon as | |
baf67741 AS |
147 | the device becomes idle, and negative values mean |
148 | never to autosuspend. You can write a number to the | |
149 | file to change the autosuspend idle-delay time. | |
cd38c1e1 AS |
150 | |
151 | Writing "-1" to power/autosuspend and writing "on" to power/level do | |
152 | essentially the same thing -- they both prevent the device from being | |
153 | autosuspended. Yes, this is a redundancy in the API. | |
154 | ||
155 | (In 2.6.21 writing "0" to power/autosuspend would prevent the device | |
156 | from being autosuspended; the behavior was changed in 2.6.22. The | |
157 | power/autosuspend attribute did not exist prior to 2.6.21, and the | |
158 | power/level attribute did not exist prior to 2.6.22.) | |
159 | ||
160 | ||
161 | Changing the default idle-delay time | |
162 | ------------------------------------ | |
163 | ||
164 | The default autosuspend idle-delay time is controlled by a module | |
165 | parameter in usbcore. You can specify the value when usbcore is | |
166 | loaded. For example, to set it to 5 seconds instead of 2 you would | |
167 | do: | |
168 | ||
169 | modprobe usbcore autosuspend=5 | |
170 | ||
171 | Equivalently, you could add to /etc/modprobe.conf a line saying: | |
172 | ||
173 | options usbcore autosuspend=5 | |
174 | ||
175 | Some distributions load the usbcore module very early during the boot | |
176 | process, by means of a program or script running from an initramfs | |
177 | image. To alter the parameter value you would have to rebuild that | |
178 | image. | |
179 | ||
180 | If usbcore is compiled into the kernel rather than built as a loadable | |
181 | module, you can add | |
182 | ||
183 | usbcore.autosuspend=5 | |
184 | ||
185 | to the kernel's boot command line. | |
186 | ||
187 | Finally, the parameter value can be changed while the system is | |
188 | running. If you do: | |
189 | ||
190 | echo 5 >/sys/module/usbcore/parameters/autosuspend | |
191 | ||
192 | then each new USB device will have its autosuspend idle-delay | |
193 | initialized to 5. (The idle-delay values for already existing devices | |
194 | will not be affected.) | |
195 | ||
196 | Setting the initial default idle-delay to -1 will prevent any | |
197 | autosuspend of any USB device. This is a simple alternative to | |
198 | disabling CONFIG_USB_SUSPEND and rebuilding the kernel, and it has the | |
199 | added benefit of allowing you to enable autosuspend for selected | |
200 | devices. | |
201 | ||
202 | ||
203 | Warnings | |
204 | -------- | |
205 | ||
206 | The USB specification states that all USB devices must support power | |
207 | management. Nevertheless, the sad fact is that many devices do not | |
208 | support it very well. You can suspend them all right, but when you | |
209 | try to resume them they disconnect themselves from the USB bus or | |
210 | they stop working entirely. This seems to be especially prevalent | |
211 | among printers and scanners, but plenty of other types of device have | |
212 | the same deficiency. | |
213 | ||
214 | For this reason, by default the kernel disables autosuspend (the | |
215 | power/level attribute is initialized to "on") for all devices other | |
216 | than hubs. Hubs, at least, appear to be reasonably well-behaved in | |
217 | this regard. | |
218 | ||
219 | (In 2.6.21 and 2.6.22 this wasn't the case. Autosuspend was enabled | |
220 | by default for almost all USB devices. A number of people experienced | |
221 | problems as a result.) | |
222 | ||
223 | This means that non-hub devices won't be autosuspended unless the user | |
224 | or a program explicitly enables it. As of this writing there aren't | |
225 | any widespread programs which will do this; we hope that in the near | |
226 | future device managers such as HAL will take on this added | |
227 | responsibility. In the meantime you can always carry out the | |
228 | necessary operations by hand or add them to a udev script. You can | |
229 | also change the idle-delay time; 2 seconds is not the best choice for | |
230 | every device. | |
231 | ||
088f7fec AS |
232 | If a driver knows that its device has proper suspend/resume support, |
233 | it can enable autosuspend all by itself. For example, the video | |
234 | driver for a laptop's webcam might do this, since these devices are | |
235 | rarely used and so should normally be autosuspended. | |
236 | ||
cd38c1e1 AS |
237 | Sometimes it turns out that even when a device does work okay with |
238 | autosuspend there are still problems. For example, there are | |
239 | experimental patches adding autosuspend support to the usbhid driver, | |
240 | which manages keyboards and mice, among other things. Tests with a | |
241 | number of keyboards showed that typing on a suspended keyboard, while | |
242 | causing the keyboard to do a remote wakeup all right, would | |
243 | nonetheless frequently result in lost keystrokes. Tests with mice | |
244 | showed that some of them would issue a remote-wakeup request in | |
245 | response to button presses but not to motion, and some in response to | |
246 | neither. | |
247 | ||
248 | The kernel will not prevent you from enabling autosuspend on devices | |
249 | that can't handle it. It is even possible in theory to damage a | |
250 | device by suspending it at the wrong time -- for example, suspending a | |
251 | USB hard disk might cause it to spin down without parking the heads. | |
252 | (Highly unlikely, but possible.) Take care. | |
253 | ||
254 | ||
255 | The driver interface for Power Management | |
256 | ----------------------------------------- | |
257 | ||
258 | The requirements for a USB driver to support external power management | |
259 | are pretty modest; the driver need only define | |
260 | ||
261 | .suspend | |
262 | .resume | |
263 | .reset_resume | |
264 | ||
265 | methods in its usb_driver structure, and the reset_resume method is | |
266 | optional. The methods' jobs are quite simple: | |
267 | ||
268 | The suspend method is called to warn the driver that the | |
269 | device is going to be suspended. If the driver returns a | |
270 | negative error code, the suspend will be aborted. Normally | |
271 | the driver will return 0, in which case it must cancel all | |
272 | outstanding URBs (usb_kill_urb()) and not submit any more. | |
273 | ||
274 | The resume method is called to tell the driver that the | |
275 | device has been resumed and the driver can return to normal | |
276 | operation. URBs may once more be submitted. | |
277 | ||
278 | The reset_resume method is called to tell the driver that | |
279 | the device has been resumed and it also has been reset. | |
280 | The driver should redo any necessary device initialization, | |
281 | since the device has probably lost most or all of its state | |
282 | (although the interfaces will be in the same altsettings as | |
283 | before the suspend). | |
284 | ||
3c886c50 AS |
285 | If the device is disconnected or powered down while it is suspended, |
286 | the disconnect method will be called instead of the resume or | |
287 | reset_resume method. This is also quite likely to happen when | |
288 | waking up from hibernation, as many systems do not maintain suspend | |
289 | current to the USB host controllers during hibernation. (It's | |
290 | possible to work around the hibernation-forces-disconnect problem by | |
291 | using the USB Persist facility.) | |
292 | ||
cd38c1e1 AS |
293 | The reset_resume method is used by the USB Persist facility (see |
294 | Documentation/usb/persist.txt) and it can also be used under certain | |
295 | circumstances when CONFIG_USB_PERSIST is not enabled. Currently, if a | |
296 | device is reset during a resume and the driver does not have a | |
297 | reset_resume method, the driver won't receive any notification about | |
298 | the resume. Later kernels will call the driver's disconnect method; | |
299 | 2.6.23 doesn't do this. | |
300 | ||
301 | USB drivers are bound to interfaces, so their suspend and resume | |
302 | methods get called when the interfaces are suspended or resumed. In | |
303 | principle one might want to suspend some interfaces on a device (i.e., | |
304 | force the drivers for those interface to stop all activity) without | |
305 | suspending the other interfaces. The USB core doesn't allow this; all | |
306 | interfaces are suspended when the device itself is suspended and all | |
307 | interfaces are resumed when the device is resumed. It isn't possible | |
308 | to suspend or resume some but not all of a device's interfaces. The | |
309 | closest you can come is to unbind the interfaces' drivers. | |
310 | ||
311 | ||
312 | The driver interface for autosuspend and autoresume | |
313 | --------------------------------------------------- | |
314 | ||
315 | To support autosuspend and autoresume, a driver should implement all | |
316 | three of the methods listed above. In addition, a driver indicates | |
317 | that it supports autosuspend by setting the .supports_autosuspend flag | |
318 | in its usb_driver structure. It is then responsible for informing the | |
319 | USB core whenever one of its interfaces becomes busy or idle. The | |
8e4ceb38 | 320 | driver does so by calling these six functions: |
cd38c1e1 AS |
321 | |
322 | int usb_autopm_get_interface(struct usb_interface *intf); | |
323 | void usb_autopm_put_interface(struct usb_interface *intf); | |
9ac39f28 AS |
324 | int usb_autopm_get_interface_async(struct usb_interface *intf); |
325 | void usb_autopm_put_interface_async(struct usb_interface *intf); | |
8e4ceb38 AS |
326 | void usb_autopm_get_interface_no_resume(struct usb_interface *intf); |
327 | void usb_autopm_put_interface_no_suspend(struct usb_interface *intf); | |
cd38c1e1 | 328 | |
9bbdf1e0 AS |
329 | The functions work by maintaining a usage counter in the |
330 | usb_interface's embedded device structure. When the counter is > 0 | |
331 | then the interface is deemed to be busy, and the kernel will not | |
332 | autosuspend the interface's device. When the usage counter is = 0 | |
333 | then the interface is considered to be idle, and the kernel may | |
334 | autosuspend the device. | |
cd38c1e1 | 335 | |
9bbdf1e0 | 336 | (There is a similar usage counter field in struct usb_device, |
cd38c1e1 | 337 | associated with the device itself rather than any of its interfaces. |
9bbdf1e0 AS |
338 | This counter is used only by the USB core.) |
339 | ||
340 | Drivers need not be concerned about balancing changes to the usage | |
341 | counter; the USB core will undo any remaining "get"s when a driver | |
342 | is unbound from its interface. As a corollary, drivers must not call | |
343 | any of the usb_autopm_* functions after their diconnect() routine has | |
344 | returned. | |
345 | ||
346 | Drivers using the async routines are responsible for their own | |
347 | synchronization and mutual exclusion. | |
348 | ||
349 | usb_autopm_get_interface() increments the usage counter and | |
350 | does an autoresume if the device is suspended. If the | |
351 | autoresume fails, the counter is decremented back. | |
352 | ||
353 | usb_autopm_put_interface() decrements the usage counter and | |
354 | attempts an autosuspend if the new value is = 0. | |
cd38c1e1 | 355 | |
9ac39f28 AS |
356 | usb_autopm_get_interface_async() and |
357 | usb_autopm_put_interface_async() do almost the same things as | |
9bbdf1e0 AS |
358 | their non-async counterparts. The big difference is that they |
359 | use a workqueue to do the resume or suspend part of their | |
9ac39f28 AS |
360 | jobs. As a result they can be called in an atomic context, |
361 | such as an URB's completion handler, but when they return the | |
9bbdf1e0 | 362 | device will generally not yet be in the desired state. |
9ac39f28 | 363 | |
8e4ceb38 AS |
364 | usb_autopm_get_interface_no_resume() and |
365 | usb_autopm_put_interface_no_suspend() merely increment or | |
9bbdf1e0 AS |
366 | decrement the usage counter; they do not attempt to carry out |
367 | an autoresume or an autosuspend. Hence they can be called in | |
368 | an atomic context. | |
81ab5b8e | 369 | |
9bbdf1e0 | 370 | The simplest usage pattern is that a driver calls |
cd38c1e1 | 371 | usb_autopm_get_interface() in its open routine and |
9bbdf1e0 AS |
372 | usb_autopm_put_interface() in its close or release routine. But other |
373 | patterns are possible. | |
cd38c1e1 AS |
374 | |
375 | The autosuspend attempts mentioned above will often fail for one | |
376 | reason or another. For example, the power/level attribute might be | |
377 | set to "on", or another interface in the same device might not be | |
378 | idle. This is perfectly normal. If the reason for failure was that | |
9bbdf1e0 AS |
379 | the device hasn't been idle for long enough, a timer is scheduled to |
380 | carry out the operation automatically when the autosuspend idle-delay | |
381 | has expired. | |
cd38c1e1 | 382 | |
baf67741 AS |
383 | Autoresume attempts also can fail, although failure would mean that |
384 | the device is no longer present or operating properly. Unlike | |
9bbdf1e0 | 385 | autosuspend, there's no idle-delay for an autoresume. |
cd38c1e1 AS |
386 | |
387 | ||
388 | Other parts of the driver interface | |
389 | ----------------------------------- | |
390 | ||
088f7fec AS |
391 | Drivers can enable autosuspend for their devices by calling |
392 | ||
393 | usb_enable_autosuspend(struct usb_device *udev); | |
394 | ||
395 | in their probe() routine, if they know that the device is capable of | |
396 | suspending and resuming correctly. This is exactly equivalent to | |
397 | writing "auto" to the device's power/level attribute. Likewise, | |
398 | drivers can disable autosuspend by calling | |
399 | ||
400 | usb_disable_autosuspend(struct usb_device *udev); | |
401 | ||
402 | This is exactly the same as writing "on" to the power/level attribute. | |
403 | ||
cd38c1e1 AS |
404 | Sometimes a driver needs to make sure that remote wakeup is enabled |
405 | during autosuspend. For example, there's not much point | |
406 | autosuspending a keyboard if the user can't cause the keyboard to do a | |
407 | remote wakeup by typing on it. If the driver sets | |
408 | intf->needs_remote_wakeup to 1, the kernel won't autosuspend the | |
409 | device if remote wakeup isn't available or has been disabled through | |
410 | the power/wakeup attribute. (If the device is already autosuspended, | |
411 | though, setting this flag won't cause the kernel to autoresume it. | |
412 | Normally a driver would set this flag in its probe method, at which | |
413 | time the device is guaranteed not to be autosuspended.) | |
414 | ||
9bbdf1e0 AS |
415 | If a driver does its I/O asynchronously in interrupt context, it |
416 | should call usb_autopm_get_interface_async() before starting output and | |
417 | usb_autopm_put_interface_async() when the output queue drains. When | |
418 | it receives an input event, it should call | |
cd38c1e1 AS |
419 | |
420 | usb_mark_last_busy(struct usb_device *udev); | |
421 | ||
9bbdf1e0 AS |
422 | in the event handler. This sets udev->last_busy to the current time. |
423 | udev->last_busy is the field used for idle-delay calculations; | |
424 | updating it will cause any pending autosuspend to be moved back. Most | |
425 | of the usb_autopm_* routines will also set the last_busy field to the | |
426 | current time. | |
427 | ||
428 | Asynchronous operation is always subject to races. For example, a | |
429 | driver may call one of the usb_autopm_*_interface_async() routines at | |
430 | a time when the core has just finished deciding the device has been | |
431 | idle for long enough but not yet gotten around to calling the driver's | |
432 | suspend method. The suspend method must be responsible for | |
433 | synchronizing with the output request routine and the URB completion | |
434 | handler; it should cause autosuspends to fail with -EBUSY if the | |
435 | driver needs to use the device. | |
cd38c1e1 AS |
436 | |
437 | External suspend calls should never be allowed to fail in this way, | |
438 | only autosuspend calls. The driver can tell them apart by checking | |
fb34d537 AS |
439 | the PM_EVENT_AUTO bit in the message.event argument to the suspend |
440 | method; this bit will be set for internal PM events (autosuspend) and | |
441 | clear for external PM events. | |
cd38c1e1 | 442 | |
cd38c1e1 | 443 | |
9bbdf1e0 AS |
444 | Mutual exclusion |
445 | ---------------- | |
cd38c1e1 | 446 | |
9bbdf1e0 AS |
447 | For external events -- but not necessarily for autosuspend or |
448 | autoresume -- the device semaphore (udev->dev.sem) will be held when a | |
449 | suspend or resume method is called. This implies that external | |
450 | suspend/resume events are mutually exclusive with calls to probe, | |
451 | disconnect, pre_reset, and post_reset; the USB core guarantees that | |
452 | this is true of autosuspend/autoresume events as well. | |
cd38c1e1 AS |
453 | |
454 | If a driver wants to block all suspend/resume calls during some | |
9bbdf1e0 AS |
455 | critical section, the best way is to lock the device and call |
456 | usb_autopm_get_interface() (and do the reverse at the end of the | |
457 | critical section). Holding the device semaphore will block all | |
458 | external PM calls, and the usb_autopm_get_interface() will prevent any | |
459 | internal PM calls, even if it fails. (Exercise: Why?) | |
cd38c1e1 AS |
460 | |
461 | ||
462 | Interaction between dynamic PM and system PM | |
463 | -------------------------------------------- | |
464 | ||
465 | Dynamic power management and system power management can interact in | |
466 | a couple of ways. | |
467 | ||
9bbdf1e0 AS |
468 | Firstly, a device may already be autosuspended when a system suspend |
469 | occurs. Since system suspends are supposed to be as transparent as | |
470 | possible, the device should remain suspended following the system | |
471 | resume. But this theory may not work out well in practice; over time | |
472 | the kernel's behavior in this regard has changed. | |
cd38c1e1 AS |
473 | |
474 | Secondly, a dynamic power-management event may occur as a system | |
475 | suspend is underway. The window for this is short, since system | |
476 | suspends don't take long (a few seconds usually), but it can happen. | |
477 | For example, a suspended device may send a remote-wakeup signal while | |
478 | the system is suspending. The remote wakeup may succeed, which would | |
479 | cause the system suspend to abort. If the remote wakeup doesn't | |
480 | succeed, it may still remain active and thus cause the system to | |
481 | resume as soon as the system suspend is complete. Or the remote | |
482 | wakeup may fail and get lost. Which outcome occurs depends on timing | |
483 | and on the hardware and firmware design. |