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