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