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