Commit | Line | Data |
---|---|---|
cd38c1e1 AS |
1 | Power Management for USB |
2 | ||
3 | Alan Stern <stern@rowland.harvard.edu> | |
4 | ||
f64c5197 LT |
5 | Last-updated: February 2014 |
6 | ||
7 | ||
8 | Contents: | |
9 | --------- | |
10 | * What is Power Management? | |
11 | * What is Remote Wakeup? | |
12 | * When is a USB device idle? | |
13 | * Forms of dynamic PM | |
14 | * The user interface for dynamic PM | |
15 | * Changing the default idle-delay time | |
16 | * Warnings | |
17 | * The driver interface for Power Management | |
18 | * The driver interface for autosuspend and autoresume | |
19 | * Other parts of the driver interface | |
20 | * Mutual exclusion | |
21 | * Interaction between dynamic PM and system PM | |
22 | * xHCI hardware link PM | |
23 | * USB Port Power Control | |
24 | * User Interface for Port Power Control | |
25 | * Suggested Userspace Port Power Policy | |
cd38c1e1 AS |
26 | |
27 | ||
28 | What is Power Management? | |
29 | ------------------------- | |
30 | ||
31 | Power Management (PM) is the practice of saving energy by suspending | |
32 | parts of a computer system when they aren't being used. While a | |
33 | component is "suspended" it is in a nonfunctional low-power state; it | |
34 | might even be turned off completely. A suspended component can be | |
35 | "resumed" (returned to a functional full-power state) when the kernel | |
36 | needs to use it. (There also are forms of PM in which components are | |
37 | placed in a less functional but still usable state instead of being | |
38 | suspended; an example would be reducing the CPU's clock rate. This | |
39 | document will not discuss those other forms.) | |
40 | ||
41 | When the parts being suspended include the CPU and most of the rest of | |
42 | the system, we speak of it as a "system suspend". When a particular | |
43 | device is turned off while the system as a whole remains running, we | |
44 | call it a "dynamic suspend" (also known as a "runtime suspend" or | |
45 | "selective suspend"). This document concentrates mostly on how | |
46 | dynamic PM is implemented in the USB subsystem, although system PM is | |
47 | covered to some extent (see Documentation/power/*.txt for more | |
48 | information about system PM). | |
49 | ||
50 | Note: Dynamic PM support for USB is present only if the kernel was | |
9bbdf1e0 AS |
51 | built with CONFIG_USB_SUSPEND enabled (which depends on |
52 | CONFIG_PM_RUNTIME). System PM support is present only if the kernel | |
53 | was built with CONFIG_SUSPEND or CONFIG_HIBERNATION enabled. | |
cd38c1e1 | 54 | |
4e9c8e5c AS |
55 | (Starting with the 3.10 kernel release, dynamic PM support for USB is |
56 | present whenever the kernel was built with CONFIG_PM_RUNTIME enabled. | |
57 | The CONFIG_USB_SUSPEND option has been eliminated.) | |
58 | ||
cd38c1e1 AS |
59 | |
60 | What is Remote Wakeup? | |
61 | ---------------------- | |
62 | ||
63 | When a device has been suspended, it generally doesn't resume until | |
64 | the computer tells it to. Likewise, if the entire computer has been | |
65 | suspended, it generally doesn't resume until the user tells it to, say | |
66 | by pressing a power button or opening the cover. | |
67 | ||
68 | However some devices have the capability of resuming by themselves, or | |
69 | asking the kernel to resume them, or even telling the entire computer | |
70 | to resume. This capability goes by several names such as "Wake On | |
71 | LAN"; we will refer to it generically as "remote wakeup". When a | |
72 | device is enabled for remote wakeup and it is suspended, it may resume | |
73 | itself (or send a request to be resumed) in response to some external | |
74 | event. Examples include a suspended keyboard resuming when a key is | |
75 | pressed, or a suspended USB hub resuming when a device is plugged in. | |
76 | ||
77 | ||
78 | When is a USB device idle? | |
79 | -------------------------- | |
80 | ||
81 | A device is idle whenever the kernel thinks it's not busy doing | |
82 | anything important and thus is a candidate for being suspended. The | |
83 | exact definition depends on the device's driver; drivers are allowed | |
84 | to declare that a device isn't idle even when there's no actual | |
85 | communication taking place. (For example, a hub isn't considered idle | |
86 | unless all the devices plugged into that hub are already suspended.) | |
87 | In addition, a device isn't considered idle so long as a program keeps | |
88 | its usbfs file open, whether or not any I/O is going on. | |
89 | ||
90 | If a USB device has no driver, its usbfs file isn't open, and it isn't | |
91 | being accessed through sysfs, then it definitely is idle. | |
92 | ||
93 | ||
94 | Forms of dynamic PM | |
95 | ------------------- | |
96 | ||
baf67741 AS |
97 | Dynamic suspends occur when the kernel decides to suspend an idle |
98 | device. This is called "autosuspend" for short. In general, a device | |
99 | won't be autosuspended unless it has been idle for some minimum period | |
100 | of time, the so-called idle-delay time. | |
cd38c1e1 AS |
101 | |
102 | Of course, nothing the kernel does on its own initiative should | |
103 | prevent the computer or its devices from working properly. If a | |
104 | device has been autosuspended and a program tries to use it, the | |
105 | kernel will automatically resume the device (autoresume). For the | |
106 | same reason, an autosuspended device will usually have remote wakeup | |
107 | enabled, if the device supports remote wakeup. | |
108 | ||
109 | It is worth mentioning that many USB drivers don't support | |
110 | autosuspend. In fact, at the time of this writing (Linux 2.6.23) the | |
111 | only drivers which do support it are the hub driver, kaweth, asix, | |
112 | usblp, usblcd, and usb-skeleton (which doesn't count). If a | |
113 | non-supporting driver is bound to a device, the device won't be | |
114 | autosuspended. In effect, the kernel pretends the device is never | |
115 | idle. | |
116 | ||
117 | We can categorize power management events in two broad classes: | |
118 | external and internal. External events are those triggered by some | |
119 | agent outside the USB stack: system suspend/resume (triggered by | |
baf67741 AS |
120 | userspace), manual dynamic resume (also triggered by userspace), and |
121 | remote wakeup (triggered by the device). Internal events are those | |
122 | triggered within the USB stack: autosuspend and autoresume. Note that | |
123 | all dynamic suspend events are internal; external agents are not | |
124 | allowed to issue dynamic suspends. | |
cd38c1e1 AS |
125 | |
126 | ||
127 | The user interface for dynamic PM | |
128 | --------------------------------- | |
129 | ||
130 | The user interface for controlling dynamic PM is located in the power/ | |
131 | subdirectory of each USB device's sysfs directory, that is, in | |
132 | /sys/bus/usb/devices/.../power/ where "..." is the device's ID. The | |
fcc4a01e AS |
133 | relevant attribute files are: wakeup, control, and |
134 | autosuspend_delay_ms. (There may also be a file named "level"; this | |
135 | file was deprecated as of the 2.6.35 kernel and replaced by the | |
136 | "control" file. In 2.6.38 the "autosuspend" file will be deprecated | |
137 | and replaced by the "autosuspend_delay_ms" file. The only difference | |
138 | is that the newer file expresses the delay in milliseconds whereas the | |
139 | older file uses seconds. Confusingly, both files are present in 2.6.37 | |
140 | but only "autosuspend" works.) | |
cd38c1e1 AS |
141 | |
142 | power/wakeup | |
143 | ||
144 | This file is empty if the device does not support | |
145 | remote wakeup. Otherwise the file contains either the | |
146 | word "enabled" or the word "disabled", and you can | |
147 | write those words to the file. The setting determines | |
148 | whether or not remote wakeup will be enabled when the | |
149 | device is next suspended. (If the setting is changed | |
150 | while the device is suspended, the change won't take | |
151 | effect until the following suspend.) | |
152 | ||
a9030986 | 153 | power/control |
cd38c1e1 | 154 | |
8e4ceb38 AS |
155 | This file contains one of two words: "on" or "auto". |
156 | You can write those words to the file to change the | |
157 | device's setting. | |
cd38c1e1 AS |
158 | |
159 | "on" means that the device should be resumed and | |
160 | autosuspend is not allowed. (Of course, system | |
161 | suspends are still allowed.) | |
162 | ||
163 | "auto" is the normal state in which the kernel is | |
164 | allowed to autosuspend and autoresume the device. | |
165 | ||
8e4ceb38 AS |
166 | (In kernels up to 2.6.32, you could also specify |
167 | "suspend", meaning that the device should remain | |
168 | suspended and autoresume was not allowed. This | |
169 | setting is no longer supported.) | |
cd38c1e1 | 170 | |
fcc4a01e | 171 | power/autosuspend_delay_ms |
cd38c1e1 AS |
172 | |
173 | This file contains an integer value, which is the | |
fcc4a01e AS |
174 | number of milliseconds the device should remain idle |
175 | before the kernel will autosuspend it (the idle-delay | |
176 | time). The default is 2000. 0 means to autosuspend | |
177 | as soon as the device becomes idle, and negative | |
178 | values mean never to autosuspend. You can write a | |
179 | number to the file to change the autosuspend | |
180 | idle-delay time. | |
181 | ||
182 | Writing "-1" to power/autosuspend_delay_ms and writing "on" to | |
183 | power/control do essentially the same thing -- they both prevent the | |
184 | device from being autosuspended. Yes, this is a redundancy in the | |
185 | API. | |
cd38c1e1 AS |
186 | |
187 | (In 2.6.21 writing "0" to power/autosuspend would prevent the device | |
188 | from being autosuspended; the behavior was changed in 2.6.22. The | |
189 | power/autosuspend attribute did not exist prior to 2.6.21, and the | |
a9030986 | 190 | power/level attribute did not exist prior to 2.6.22. power/control |
fcc4a01e AS |
191 | was added in 2.6.34, and power/autosuspend_delay_ms was added in |
192 | 2.6.37 but did not become functional until 2.6.38.) | |
cd38c1e1 AS |
193 | |
194 | ||
195 | Changing the default idle-delay time | |
196 | ------------------------------------ | |
197 | ||
fcc4a01e AS |
198 | The default autosuspend idle-delay time (in seconds) is controlled by |
199 | a module parameter in usbcore. You can specify the value when usbcore | |
200 | is loaded. For example, to set it to 5 seconds instead of 2 you would | |
cd38c1e1 AS |
201 | do: |
202 | ||
203 | modprobe usbcore autosuspend=5 | |
204 | ||
970e2486 LDM |
205 | Equivalently, you could add to a configuration file in /etc/modprobe.d |
206 | a line saying: | |
cd38c1e1 AS |
207 | |
208 | options usbcore autosuspend=5 | |
209 | ||
210 | Some distributions load the usbcore module very early during the boot | |
211 | process, by means of a program or script running from an initramfs | |
212 | image. To alter the parameter value you would have to rebuild that | |
213 | image. | |
214 | ||
215 | If usbcore is compiled into the kernel rather than built as a loadable | |
216 | module, you can add | |
217 | ||
218 | usbcore.autosuspend=5 | |
219 | ||
220 | to the kernel's boot command line. | |
221 | ||
222 | Finally, the parameter value can be changed while the system is | |
223 | running. If you do: | |
224 | ||
225 | echo 5 >/sys/module/usbcore/parameters/autosuspend | |
226 | ||
227 | then each new USB device will have its autosuspend idle-delay | |
228 | initialized to 5. (The idle-delay values for already existing devices | |
229 | will not be affected.) | |
230 | ||
231 | Setting the initial default idle-delay to -1 will prevent any | |
4e9c8e5c AS |
232 | autosuspend of any USB device. This has the benefit of allowing you |
233 | then to enable autosuspend for selected devices. | |
cd38c1e1 AS |
234 | |
235 | ||
236 | Warnings | |
237 | -------- | |
238 | ||
239 | The USB specification states that all USB devices must support power | |
240 | management. Nevertheless, the sad fact is that many devices do not | |
241 | support it very well. You can suspend them all right, but when you | |
242 | try to resume them they disconnect themselves from the USB bus or | |
243 | they stop working entirely. This seems to be especially prevalent | |
244 | among printers and scanners, but plenty of other types of device have | |
245 | the same deficiency. | |
246 | ||
247 | For this reason, by default the kernel disables autosuspend (the | |
a9030986 | 248 | power/control attribute is initialized to "on") for all devices other |
cd38c1e1 AS |
249 | than hubs. Hubs, at least, appear to be reasonably well-behaved in |
250 | this regard. | |
251 | ||
252 | (In 2.6.21 and 2.6.22 this wasn't the case. Autosuspend was enabled | |
253 | by default for almost all USB devices. A number of people experienced | |
254 | problems as a result.) | |
255 | ||
256 | This means that non-hub devices won't be autosuspended unless the user | |
257 | or a program explicitly enables it. As of this writing there aren't | |
258 | any widespread programs which will do this; we hope that in the near | |
259 | future device managers such as HAL will take on this added | |
260 | responsibility. In the meantime you can always carry out the | |
261 | necessary operations by hand or add them to a udev script. You can | |
262 | also change the idle-delay time; 2 seconds is not the best choice for | |
263 | every device. | |
264 | ||
088f7fec AS |
265 | If a driver knows that its device has proper suspend/resume support, |
266 | it can enable autosuspend all by itself. For example, the video | |
fcc4a01e AS |
267 | driver for a laptop's webcam might do this (in recent kernels they |
268 | do), since these devices are rarely used and so should normally be | |
269 | autosuspended. | |
088f7fec | 270 | |
cd38c1e1 | 271 | Sometimes it turns out that even when a device does work okay with |
fcc4a01e AS |
272 | autosuspend there are still problems. For example, the usbhid driver, |
273 | which manages keyboards and mice, has autosuspend support. Tests with | |
274 | a number of keyboards show that typing on a suspended keyboard, while | |
275 | causing the keyboard to do a remote wakeup all right, will nonetheless | |
276 | frequently result in lost keystrokes. Tests with mice show that some | |
277 | of them will issue a remote-wakeup request in response to button | |
278 | presses but not to motion, and some in response to neither. | |
cd38c1e1 AS |
279 | |
280 | The kernel will not prevent you from enabling autosuspend on devices | |
281 | that can't handle it. It is even possible in theory to damage a | |
fcc4a01e AS |
282 | device by suspending it at the wrong time. (Highly unlikely, but |
283 | possible.) Take care. | |
cd38c1e1 AS |
284 | |
285 | ||
286 | The driver interface for Power Management | |
287 | ----------------------------------------- | |
288 | ||
289 | The requirements for a USB driver to support external power management | |
290 | are pretty modest; the driver need only define | |
291 | ||
292 | .suspend | |
293 | .resume | |
294 | .reset_resume | |
295 | ||
296 | methods in its usb_driver structure, and the reset_resume method is | |
297 | optional. The methods' jobs are quite simple: | |
298 | ||
299 | The suspend method is called to warn the driver that the | |
300 | device is going to be suspended. If the driver returns a | |
301 | negative error code, the suspend will be aborted. Normally | |
302 | the driver will return 0, in which case it must cancel all | |
303 | outstanding URBs (usb_kill_urb()) and not submit any more. | |
304 | ||
305 | The resume method is called to tell the driver that the | |
306 | device has been resumed and the driver can return to normal | |
307 | operation. URBs may once more be submitted. | |
308 | ||
309 | The reset_resume method is called to tell the driver that | |
310 | the device has been resumed and it also has been reset. | |
311 | The driver should redo any necessary device initialization, | |
312 | since the device has probably lost most or all of its state | |
313 | (although the interfaces will be in the same altsettings as | |
314 | before the suspend). | |
315 | ||
3c886c50 AS |
316 | If the device is disconnected or powered down while it is suspended, |
317 | the disconnect method will be called instead of the resume or | |
318 | reset_resume method. This is also quite likely to happen when | |
319 | waking up from hibernation, as many systems do not maintain suspend | |
320 | current to the USB host controllers during hibernation. (It's | |
321 | possible to work around the hibernation-forces-disconnect problem by | |
322 | using the USB Persist facility.) | |
323 | ||
cd38c1e1 AS |
324 | The reset_resume method is used by the USB Persist facility (see |
325 | Documentation/usb/persist.txt) and it can also be used under certain | |
326 | circumstances when CONFIG_USB_PERSIST is not enabled. Currently, if a | |
327 | device is reset during a resume and the driver does not have a | |
328 | reset_resume method, the driver won't receive any notification about | |
329 | the resume. Later kernels will call the driver's disconnect method; | |
330 | 2.6.23 doesn't do this. | |
331 | ||
332 | USB drivers are bound to interfaces, so their suspend and resume | |
333 | methods get called when the interfaces are suspended or resumed. In | |
334 | principle one might want to suspend some interfaces on a device (i.e., | |
335 | force the drivers for those interface to stop all activity) without | |
336 | suspending the other interfaces. The USB core doesn't allow this; all | |
337 | interfaces are suspended when the device itself is suspended and all | |
338 | interfaces are resumed when the device is resumed. It isn't possible | |
339 | to suspend or resume some but not all of a device's interfaces. The | |
340 | closest you can come is to unbind the interfaces' drivers. | |
341 | ||
342 | ||
343 | The driver interface for autosuspend and autoresume | |
344 | --------------------------------------------------- | |
345 | ||
346 | To support autosuspend and autoresume, a driver should implement all | |
347 | three of the methods listed above. In addition, a driver indicates | |
348 | that it supports autosuspend by setting the .supports_autosuspend flag | |
349 | in its usb_driver structure. It is then responsible for informing the | |
350 | USB core whenever one of its interfaces becomes busy or idle. The | |
8e4ceb38 | 351 | driver does so by calling these six functions: |
cd38c1e1 AS |
352 | |
353 | int usb_autopm_get_interface(struct usb_interface *intf); | |
354 | void usb_autopm_put_interface(struct usb_interface *intf); | |
9ac39f28 AS |
355 | int usb_autopm_get_interface_async(struct usb_interface *intf); |
356 | void usb_autopm_put_interface_async(struct usb_interface *intf); | |
8e4ceb38 AS |
357 | void usb_autopm_get_interface_no_resume(struct usb_interface *intf); |
358 | void usb_autopm_put_interface_no_suspend(struct usb_interface *intf); | |
cd38c1e1 | 359 | |
9bbdf1e0 AS |
360 | The functions work by maintaining a usage counter in the |
361 | usb_interface's embedded device structure. When the counter is > 0 | |
362 | then the interface is deemed to be busy, and the kernel will not | |
363 | autosuspend the interface's device. When the usage counter is = 0 | |
364 | then the interface is considered to be idle, and the kernel may | |
365 | autosuspend the device. | |
cd38c1e1 | 366 | |
9bbdf1e0 AS |
367 | Drivers need not be concerned about balancing changes to the usage |
368 | counter; the USB core will undo any remaining "get"s when a driver | |
369 | is unbound from its interface. As a corollary, drivers must not call | |
45f31226 | 370 | any of the usb_autopm_* functions after their disconnect() routine has |
9bbdf1e0 AS |
371 | returned. |
372 | ||
373 | Drivers using the async routines are responsible for their own | |
374 | synchronization and mutual exclusion. | |
375 | ||
376 | usb_autopm_get_interface() increments the usage counter and | |
377 | does an autoresume if the device is suspended. If the | |
378 | autoresume fails, the counter is decremented back. | |
379 | ||
380 | usb_autopm_put_interface() decrements the usage counter and | |
381 | attempts an autosuspend if the new value is = 0. | |
cd38c1e1 | 382 | |
9ac39f28 AS |
383 | usb_autopm_get_interface_async() and |
384 | usb_autopm_put_interface_async() do almost the same things as | |
9bbdf1e0 AS |
385 | their non-async counterparts. The big difference is that they |
386 | use a workqueue to do the resume or suspend part of their | |
9ac39f28 AS |
387 | jobs. As a result they can be called in an atomic context, |
388 | such as an URB's completion handler, but when they return the | |
9bbdf1e0 | 389 | device will generally not yet be in the desired state. |
9ac39f28 | 390 | |
8e4ceb38 AS |
391 | usb_autopm_get_interface_no_resume() and |
392 | usb_autopm_put_interface_no_suspend() merely increment or | |
9bbdf1e0 AS |
393 | decrement the usage counter; they do not attempt to carry out |
394 | an autoresume or an autosuspend. Hence they can be called in | |
395 | an atomic context. | |
81ab5b8e | 396 | |
9bbdf1e0 | 397 | The simplest usage pattern is that a driver calls |
cd38c1e1 | 398 | usb_autopm_get_interface() in its open routine and |
9bbdf1e0 AS |
399 | usb_autopm_put_interface() in its close or release routine. But other |
400 | patterns are possible. | |
cd38c1e1 AS |
401 | |
402 | The autosuspend attempts mentioned above will often fail for one | |
a9030986 | 403 | reason or another. For example, the power/control attribute might be |
cd38c1e1 AS |
404 | set to "on", or another interface in the same device might not be |
405 | idle. This is perfectly normal. If the reason for failure was that | |
9bbdf1e0 AS |
406 | the device hasn't been idle for long enough, a timer is scheduled to |
407 | carry out the operation automatically when the autosuspend idle-delay | |
408 | has expired. | |
cd38c1e1 | 409 | |
baf67741 AS |
410 | Autoresume attempts also can fail, although failure would mean that |
411 | the device is no longer present or operating properly. Unlike | |
9bbdf1e0 | 412 | autosuspend, there's no idle-delay for an autoresume. |
cd38c1e1 AS |
413 | |
414 | ||
415 | Other parts of the driver interface | |
416 | ----------------------------------- | |
417 | ||
088f7fec AS |
418 | Drivers can enable autosuspend for their devices by calling |
419 | ||
420 | usb_enable_autosuspend(struct usb_device *udev); | |
421 | ||
422 | in their probe() routine, if they know that the device is capable of | |
423 | suspending and resuming correctly. This is exactly equivalent to | |
a9030986 | 424 | writing "auto" to the device's power/control attribute. Likewise, |
088f7fec AS |
425 | drivers can disable autosuspend by calling |
426 | ||
427 | usb_disable_autosuspend(struct usb_device *udev); | |
428 | ||
a9030986 | 429 | This is exactly the same as writing "on" to the power/control attribute. |
088f7fec | 430 | |
cd38c1e1 AS |
431 | Sometimes a driver needs to make sure that remote wakeup is enabled |
432 | during autosuspend. For example, there's not much point | |
433 | autosuspending a keyboard if the user can't cause the keyboard to do a | |
434 | remote wakeup by typing on it. If the driver sets | |
435 | intf->needs_remote_wakeup to 1, the kernel won't autosuspend the | |
fcc4a01e AS |
436 | device if remote wakeup isn't available. (If the device is already |
437 | autosuspended, though, setting this flag won't cause the kernel to | |
438 | autoresume it. Normally a driver would set this flag in its probe | |
439 | method, at which time the device is guaranteed not to be | |
440 | autosuspended.) | |
cd38c1e1 | 441 | |
9bbdf1e0 AS |
442 | If a driver does its I/O asynchronously in interrupt context, it |
443 | should call usb_autopm_get_interface_async() before starting output and | |
444 | usb_autopm_put_interface_async() when the output queue drains. When | |
445 | it receives an input event, it should call | |
cd38c1e1 AS |
446 | |
447 | usb_mark_last_busy(struct usb_device *udev); | |
448 | ||
fcc4a01e AS |
449 | in the event handler. This tells the PM core that the device was just |
450 | busy and therefore the next autosuspend idle-delay expiration should | |
451 | be pushed back. Many of the usb_autopm_* routines also make this call, | |
452 | so drivers need to worry only when interrupt-driven input arrives. | |
9bbdf1e0 AS |
453 | |
454 | Asynchronous operation is always subject to races. For example, a | |
fcc4a01e AS |
455 | driver may call the usb_autopm_get_interface_async() routine at a time |
456 | when the core has just finished deciding the device has been idle for | |
457 | long enough but not yet gotten around to calling the driver's suspend | |
458 | method. The suspend method must be responsible for synchronizing with | |
459 | the I/O request routine and the URB completion handler; it should | |
460 | cause autosuspends to fail with -EBUSY if the driver needs to use the | |
461 | device. | |
cd38c1e1 AS |
462 | |
463 | External suspend calls should never be allowed to fail in this way, | |
5b1b0b81 AS |
464 | only autosuspend calls. The driver can tell them apart by applying |
465 | the PMSG_IS_AUTO() macro to the message argument to the suspend | |
466 | method; it will return True for internal PM events (autosuspend) and | |
467 | False for external PM events. | |
cd38c1e1 | 468 | |
cd38c1e1 | 469 | |
9bbdf1e0 AS |
470 | Mutual exclusion |
471 | ---------------- | |
cd38c1e1 | 472 | |
9bbdf1e0 AS |
473 | For external events -- but not necessarily for autosuspend or |
474 | autoresume -- the device semaphore (udev->dev.sem) will be held when a | |
475 | suspend or resume method is called. This implies that external | |
476 | suspend/resume events are mutually exclusive with calls to probe, | |
477 | disconnect, pre_reset, and post_reset; the USB core guarantees that | |
478 | this is true of autosuspend/autoresume events as well. | |
cd38c1e1 AS |
479 | |
480 | If a driver wants to block all suspend/resume calls during some | |
9bbdf1e0 AS |
481 | critical section, the best way is to lock the device and call |
482 | usb_autopm_get_interface() (and do the reverse at the end of the | |
483 | critical section). Holding the device semaphore will block all | |
484 | external PM calls, and the usb_autopm_get_interface() will prevent any | |
485 | internal PM calls, even if it fails. (Exercise: Why?) | |
cd38c1e1 AS |
486 | |
487 | ||
488 | Interaction between dynamic PM and system PM | |
489 | -------------------------------------------- | |
490 | ||
491 | Dynamic power management and system power management can interact in | |
492 | a couple of ways. | |
493 | ||
9bbdf1e0 AS |
494 | Firstly, a device may already be autosuspended when a system suspend |
495 | occurs. Since system suspends are supposed to be as transparent as | |
496 | possible, the device should remain suspended following the system | |
497 | resume. But this theory may not work out well in practice; over time | |
fcc4a01e AS |
498 | the kernel's behavior in this regard has changed. As of 2.6.37 the |
499 | policy is to resume all devices during a system resume and let them | |
500 | handle their own runtime suspends afterward. | |
cd38c1e1 AS |
501 | |
502 | Secondly, a dynamic power-management event may occur as a system | |
503 | suspend is underway. The window for this is short, since system | |
504 | suspends don't take long (a few seconds usually), but it can happen. | |
505 | For example, a suspended device may send a remote-wakeup signal while | |
506 | the system is suspending. The remote wakeup may succeed, which would | |
507 | cause the system suspend to abort. If the remote wakeup doesn't | |
508 | succeed, it may still remain active and thus cause the system to | |
509 | resume as soon as the system suspend is complete. Or the remote | |
510 | wakeup may fail and get lost. Which outcome occurs depends on timing | |
511 | and on the hardware and firmware design. | |
c1045e87 AX |
512 | |
513 | ||
514 | xHCI hardware link PM | |
515 | --------------------- | |
516 | ||
517 | xHCI host controller provides hardware link power management to usb2.0 | |
518 | (xHCI 1.0 feature) and usb3.0 devices which support link PM. By | |
519 | enabling hardware LPM, the host can automatically put the device into | |
520 | lower power state(L1 for usb2.0 devices, or U1/U2 for usb3.0 devices), | |
521 | which state device can enter and resume very quickly. | |
522 | ||
523 | The user interface for controlling USB2 hardware LPM is located in the | |
524 | power/ subdirectory of each USB device's sysfs directory, that is, in | |
525 | /sys/bus/usb/devices/.../power/ where "..." is the device's ID. The | |
526 | relevant attribute files is usb2_hardware_lpm. | |
527 | ||
528 | power/usb2_hardware_lpm | |
529 | ||
530 | When a USB2 device which support LPM is plugged to a | |
531 | xHCI host root hub which support software LPM, the | |
532 | host will run a software LPM test for it; if the device | |
533 | enters L1 state and resume successfully and the host | |
534 | supports USB2 hardware LPM, this file will show up and | |
535 | driver will enable hardware LPM for the device. You | |
536 | can write y/Y/1 or n/N/0 to the file to enable/disable | |
537 | USB2 hardware LPM manually. This is for test purpose mainly. | |
f64c5197 LT |
538 | |
539 | ||
540 | USB Port Power Control | |
541 | ---------------------- | |
542 | ||
543 | In addition to suspending endpoint devices and enabling hardware | |
544 | controlled link power management, the USB subsystem also has the | |
545 | capability to disable power to ports under some conditions. Power is | |
546 | controlled through Set/ClearPortFeature(PORT_POWER) requests to a hub. | |
547 | In the case of a root or platform-internal hub the host controller | |
548 | driver translates PORT_POWER requests into platform firmware (ACPI) | |
549 | method calls to set the port power state. For more background see the | |
550 | Linux Plumbers Conference 2012 slides [1] and video [2]: | |
551 | ||
552 | Upon receiving a ClearPortFeature(PORT_POWER) request a USB port is | |
553 | logically off, and may trigger the actual loss of VBUS to the port [3]. | |
554 | VBUS may be maintained in the case where a hub gangs multiple ports into | |
555 | a shared power well causing power to remain until all ports in the gang | |
556 | are turned off. VBUS may also be maintained by hub ports configured for | |
557 | a charging application. In any event a logically off port will lose | |
558 | connection with its device, not respond to hotplug events, and not | |
559 | respond to remote wakeup events*. | |
560 | ||
561 | WARNING: turning off a port may result in the inability to hot add a device. | |
562 | Please see "User Interface for Port Power Control" for details. | |
563 | ||
564 | As far as the effect on the device itself it is similar to what a device | |
565 | goes through during system suspend, i.e. the power session is lost. Any | |
566 | USB device or driver that misbehaves with system suspend will be | |
567 | similarly affected by a port power cycle event. For this reason the | |
568 | implementation shares the same device recovery path (and honors the same | |
569 | quirks) as the system resume path for the hub. | |
570 | ||
571 | [1]: http://dl.dropbox.com/u/96820575/sarah-sharp-lpt-port-power-off2-mini.pdf | |
572 | [2]: http://linuxplumbers.ubicast.tv/videos/usb-port-power-off-kerneluserspace-api/ | |
573 | [3]: USB 3.1 Section 10.12 | |
574 | * wakeup note: if a device is configured to send wakeup events the port | |
575 | power control implementation will block poweroff attempts on that | |
576 | port. | |
577 | ||
578 | ||
579 | User Interface for Port Power Control | |
580 | ------------------------------------- | |
581 | ||
582 | The port power control mechanism uses the PM runtime system. Poweroff is | |
583 | requested by clearing the power/pm_qos_no_power_off flag of the port device | |
584 | (defaults to 1). If the port is disconnected it will immediately receive a | |
585 | ClearPortFeature(PORT_POWER) request. Otherwise, it will honor the pm runtime | |
586 | rules and require the attached child device and all descendants to be suspended. | |
587 | This mechanism is dependent on the hub advertising port power switching in its | |
588 | hub descriptor (wHubCharacteristics logical power switching mode field). | |
589 | ||
590 | Note, some interface devices/drivers do not support autosuspend. Userspace may | |
591 | need to unbind the interface drivers before the usb_device will suspend. An | |
592 | unbound interface device is suspended by default. When unbinding, be careful | |
593 | to unbind interface drivers, not the driver of the parent usb device. Also, | |
594 | leave hub interface drivers bound. If the driver for the usb device (not | |
595 | interface) is unbound the kernel is no longer able to resume the device. If a | |
596 | hub interface driver is unbound, control of its child ports is lost and all | |
597 | attached child-devices will disconnect. A good rule of thumb is that if the | |
598 | 'driver/module' link for a device points to /sys/module/usbcore then unbinding | |
599 | it will interfere with port power control. | |
600 | ||
601 | Example of the relevant files for port power control. Note, in this example | |
602 | these files are relative to a usb hub device (prefix). | |
603 | ||
604 | prefix=/sys/devices/pci0000:00/0000:00:14.0/usb3/3-1 | |
605 | ||
606 | attached child device + | |
607 | hub port device + | | |
608 | hub interface device + | | | |
609 | v v v | |
610 | $prefix/3-1:1.0/3-1-port1/device | |
611 | ||
612 | $prefix/3-1:1.0/3-1-port1/power/pm_qos_no_power_off | |
613 | $prefix/3-1:1.0/3-1-port1/device/power/control | |
614 | $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intf0>/driver/unbind | |
615 | $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intf1>/driver/unbind | |
616 | ... | |
617 | $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intfN>/driver/unbind | |
618 | ||
619 | In addition to these files some ports may have a 'peer' link to a port on | |
620 | another hub. The expectation is that all superspeed ports have a | |
621 | hi-speed peer. | |
622 | ||
623 | $prefix/3-1:1.0/3-1-port1/peer -> ../../../../usb2/2-1/2-1:1.0/2-1-port1 | |
624 | ../../../../usb2/2-1/2-1:1.0/2-1-port1/peer -> ../../../../usb3/3-1/3-1:1.0/3-1-port1 | |
625 | ||
626 | Distinct from 'companion ports', or 'ehci/xhci shared switchover ports' | |
627 | peer ports are simply the hi-speed and superspeed interface pins that | |
628 | are combined into a single usb3 connector. Peer ports share the same | |
629 | ancestor XHCI device. | |
630 | ||
631 | While a superspeed port is powered off a device may downgrade its | |
632 | connection and attempt to connect to the hi-speed pins. The | |
633 | implementation takes steps to prevent this: | |
634 | ||
635 | 1/ Port suspend is sequenced to guarantee that hi-speed ports are powered-off | |
636 | before their superspeed peer is permitted to power-off. The implication is | |
637 | that the setting pm_qos_no_power_off to zero on a superspeed port may not cause | |
638 | the port to power-off until its highspeed peer has gone to its runtime suspend | |
639 | state. Userspace must take care to order the suspensions if it wants to | |
640 | guarantee that a superspeed port will power-off. | |
641 | ||
642 | 2/ Port resume is sequenced to force a superspeed port to power-on prior to its | |
643 | highspeed peer. | |
644 | ||
645 | 3/ Port resume always triggers an attached child device to resume. After a | |
646 | power session is lost the device may have been removed, or need reset. | |
647 | Resuming the child device when the parent port regains power resolves those | |
648 | states and clamps the maximum port power cycle frequency at the rate the child | |
649 | device can suspend (autosuspend-delay) and resume (reset-resume latency). | |
650 | ||
651 | Sysfs files relevant for port power control: | |
652 | <hubdev-portX>/power/pm_qos_no_power_off: | |
653 | This writable flag controls the state of an idle port. | |
654 | Once all children and descendants have suspended the | |
655 | port may suspend/poweroff provided that | |
656 | pm_qos_no_power_off is '0'. If pm_qos_no_power_off is | |
657 | '1' the port will remain active/powered regardless of | |
658 | the stats of descendants. Defaults to 1. | |
659 | ||
660 | <hubdev-portX>/power/runtime_status: | |
661 | This file reflects whether the port is 'active' (power is on) | |
662 | or 'suspended' (logically off). There is no indication to | |
663 | userspace whether VBUS is still supplied. | |
664 | ||
665 | <hubdev-portX>/connect_type: | |
666 | An advisory read-only flag to userspace indicating the | |
667 | location and connection type of the port. It returns | |
668 | one of four values 'hotplug', 'hardwired', 'not used', | |
669 | and 'unknown'. All values, besides unknown, are set by | |
670 | platform firmware. | |
671 | ||
672 | "hotplug" indicates an externally connectable/visible | |
673 | port on the platform. Typically userspace would choose | |
674 | to keep such a port powered to handle new device | |
675 | connection events. | |
676 | ||
677 | "hardwired" refers to a port that is not visible but | |
678 | connectable. Examples are internal ports for USB | |
679 | bluetooth that can be disconnected via an external | |
680 | switch or a port with a hardwired USB camera. It is | |
681 | expected to be safe to allow these ports to suspend | |
682 | provided pm_qos_no_power_off is coordinated with any | |
683 | switch that gates connections. Userspace must arrange | |
684 | for the device to be connected prior to the port | |
685 | powering off, or to activate the port prior to enabling | |
686 | connection via a switch. | |
687 | ||
688 | "not used" refers to an internal port that is expected | |
689 | to never have a device connected to it. These may be | |
690 | empty internal ports, or ports that are not physically | |
691 | exposed on a platform. Considered safe to be | |
692 | powered-off at all times. | |
693 | ||
694 | "unknown" means platform firmware does not provide | |
695 | information for this port. Most commonly refers to | |
696 | external hub ports which should be considered 'hotplug' | |
697 | for policy decisions. | |
698 | ||
699 | NOTE1: since we are relying on the BIOS to get this ACPI | |
700 | information correct, the USB port descriptions may be | |
701 | missing or wrong. | |
702 | ||
703 | NOTE2: Take care in clearing pm_qos_no_power_off. Once | |
704 | power is off this port will | |
705 | not respond to new connect events. | |
706 | ||
707 | Once a child device is attached additional constraints are | |
708 | applied before the port is allowed to poweroff. | |
709 | ||
710 | <child>/power/control: | |
711 | Must be 'auto', and the port will not | |
712 | power down until <child>/power/runtime_status | |
713 | reflects the 'suspended' state. Default | |
714 | value is controlled by child device driver. | |
715 | ||
716 | <child>/power/persist: | |
717 | This defaults to '1' for most devices and indicates if | |
718 | kernel can persist the device's configuration across a | |
719 | power session loss (suspend / port-power event). When | |
720 | this value is '0' (quirky devices), port poweroff is | |
721 | disabled. | |
722 | ||
723 | <child>/driver/unbind: | |
724 | Wakeup capable devices will block port poweroff. At | |
725 | this time the only mechanism to clear the usb-internal | |
726 | wakeup-capability for an interface device is to unbind | |
727 | its driver. | |
728 | ||
729 | Summary of poweroff pre-requisite settings relative to a port device: | |
730 | ||
731 | echo 0 > power/pm_qos_no_power_off | |
732 | echo 0 > peer/power/pm_qos_no_power_off # if it exists | |
733 | echo auto > power/control # this is the default value | |
734 | echo auto > <child>/power/control | |
735 | echo 1 > <child>/power/persist # this is the default value | |
736 | ||
737 | Suggested Userspace Port Power Policy | |
738 | ------------------------------------- | |
739 | ||
740 | As noted above userspace needs to be careful and deliberate about what | |
741 | ports are enabled for poweroff. | |
742 | ||
743 | The default configuration is that all ports start with | |
744 | power/pm_qos_no_power_off set to '1' causing ports to always remain | |
745 | active. | |
746 | ||
747 | Given confidence in the platform firmware's description of the ports | |
748 | (ACPI _PLD record for a port populates 'connect_type') userspace can | |
749 | clear pm_qos_no_power_off for all 'not used' ports. The same can be | |
750 | done for 'hardwired' ports provided poweroff is coordinated with any | |
751 | connection switch for the port. | |
752 | ||
753 | A more aggressive userspace policy is to enable USB port power off for | |
754 | all ports (set <hubdev-portX>/power/pm_qos_no_power_off to '0') when | |
755 | some external factor indicates the user has stopped interacting with the | |
756 | system. For example, a distro may want to enable power off all USB | |
757 | ports when the screen blanks, and re-power them when the screen becomes | |
758 | active. Smart phones and tablets may want to power off USB ports when | |
759 | the user pushes the power button. |