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