Based on kernel version 2.6.34. Page generated on 2010-05-31 16:03 EST.
1 Power Management for USB 2 3 Alan Stern <stern[AT]rowland.harvard[DOT]edu> 4 5 December 11, 2009 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 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 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. 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 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. 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 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. 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 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.) 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 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. 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 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 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 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 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 320 driver does so by calling these six functions: 321 322 int usb_autopm_get_interface(struct usb_interface *intf); 323 void usb_autopm_put_interface(struct usb_interface *intf); 324 int usb_autopm_get_interface_async(struct usb_interface *intf); 325 void usb_autopm_put_interface_async(struct usb_interface *intf); 326 void usb_autopm_get_interface_no_resume(struct usb_interface *intf); 327 void usb_autopm_put_interface_no_suspend(struct usb_interface *intf); 328 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. 335 336 (There is a similar usage counter field in struct usb_device, 337 associated with the device itself rather than any of its interfaces. 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. 355 356 usb_autopm_get_interface_async() and 357 usb_autopm_put_interface_async() do almost the same things 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 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 362 device will generally not yet be in the desired state. 363 364 usb_autopm_get_interface_no_resume() and 365 usb_autopm_put_interface_no_suspend() merely increment or 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. 369 370 The simplest usage pattern is that a driver calls 371 usb_autopm_get_interface() in its open routine and 372 usb_autopm_put_interface() in its close or release routine. But other 373 patterns are possible. 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 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. 382 383 Autoresume attempts also can fail, although failure would mean that 384 the device is no longer present or operating properly. Unlike 385 autosuspend, there's no idle-delay for an autoresume. 386 387 388 Other parts of the driver interface 389 ----------------------------------- 390 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 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 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 419 420 usb_mark_last_busy(struct usb_device *udev); 421 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. 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 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. 442 443 444 Mutual exclusion 445 ---------------- 446 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. 453 454 If a driver wants to block all suspend/resume calls during some 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?) 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 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. 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.