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/*.rst`` 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 must be careful to balance their overall changes to the usage 374counter. Unbalanced "get"s will remain in effect when a driver is 375unbound from its interface, preventing the device from going into 376runtime suspend should the interface be bound to a driver again. On 377the other hand, drivers are allowed to achieve this balance by calling 378the ``usb_autopm_*`` functions even after their ``disconnect`` routine 379has returned -- say from within a work-queue routine -- provided they 380retain an active reference to the interface (via ``usb_get_intf`` and 381``usb_put_intf``). 382 383Drivers using the async routines are responsible for their own 384synchronization and mutual exclusion. 385 386 :c:func:`usb_autopm_get_interface` increments the usage counter and 387 does an autoresume if the device is suspended. If the 388 autoresume fails, the counter is decremented back. 389 390 :c:func:`usb_autopm_put_interface` decrements the usage counter and 391 attempts an autosuspend if the new value is = 0. 392 393 :c:func:`usb_autopm_get_interface_async` and 394 :c:func:`usb_autopm_put_interface_async` do almost the same things as 395 their non-async counterparts. The big difference is that they 396 use a workqueue to do the resume or suspend part of their 397 jobs. As a result they can be called in an atomic context, 398 such as an URB's completion handler, but when they return the 399 device will generally not yet be in the desired state. 400 401 :c:func:`usb_autopm_get_interface_no_resume` and 402 :c:func:`usb_autopm_put_interface_no_suspend` merely increment or 403 decrement the usage counter; they do not attempt to carry out 404 an autoresume or an autosuspend. Hence they can be called in 405 an atomic context. 406 407The simplest usage pattern is that a driver calls 408:c:func:`usb_autopm_get_interface` in its open routine and 409:c:func:`usb_autopm_put_interface` in its close or release routine. But other 410patterns are possible. 411 412The autosuspend attempts mentioned above will often fail for one 413reason or another. For example, the ``power/control`` attribute might be 414set to ``on``, or another interface in the same device might not be 415idle. This is perfectly normal. If the reason for failure was that 416the device hasn't been idle for long enough, a timer is scheduled to 417carry out the operation automatically when the autosuspend idle-delay 418has expired. 419 420Autoresume attempts also can fail, although failure would mean that 421the device is no longer present or operating properly. Unlike 422autosuspend, there's no idle-delay for an autoresume. 423 424 425Other parts of the driver interface 426----------------------------------- 427 428Drivers can enable autosuspend for their devices by calling:: 429 430 usb_enable_autosuspend(struct usb_device *udev); 431 432in their :c:func:`probe` routine, if they know that the device is capable of 433suspending and resuming correctly. This is exactly equivalent to 434writing ``auto`` to the device's ``power/control`` attribute. Likewise, 435drivers can disable autosuspend by calling:: 436 437 usb_disable_autosuspend(struct usb_device *udev); 438 439This is exactly the same as writing ``on`` to the ``power/control`` attribute. 440 441Sometimes a driver needs to make sure that remote wakeup is enabled 442during autosuspend. For example, there's not much point 443autosuspending a keyboard if the user can't cause the keyboard to do a 444remote wakeup by typing on it. If the driver sets 445``intf->needs_remote_wakeup`` to 1, the kernel won't autosuspend the 446device if remote wakeup isn't available. (If the device is already 447autosuspended, though, setting this flag won't cause the kernel to 448autoresume it. Normally a driver would set this flag in its ``probe`` 449method, at which time the device is guaranteed not to be 450autosuspended.) 451 452If a driver does its I/O asynchronously in interrupt context, it 453should call :c:func:`usb_autopm_get_interface_async` before starting output and 454:c:func:`usb_autopm_put_interface_async` when the output queue drains. When 455it receives an input event, it should call:: 456 457 usb_mark_last_busy(struct usb_device *udev); 458 459in the event handler. This tells the PM core that the device was just 460busy and therefore the next autosuspend idle-delay expiration should 461be pushed back. Many of the usb_autopm_* routines also make this call, 462so drivers need to worry only when interrupt-driven input arrives. 463 464Asynchronous operation is always subject to races. For example, a 465driver may call the :c:func:`usb_autopm_get_interface_async` routine at a time 466when the core has just finished deciding the device has been idle for 467long enough but not yet gotten around to calling the driver's ``suspend`` 468method. The ``suspend`` method must be responsible for synchronizing with 469the I/O request routine and the URB completion handler; it should 470cause autosuspends to fail with -EBUSY if the driver needs to use the 471device. 472 473External suspend calls should never be allowed to fail in this way, 474only autosuspend calls. The driver can tell them apart by applying 475the :c:func:`PMSG_IS_AUTO` macro to the message argument to the ``suspend`` 476method; it will return True for internal PM events (autosuspend) and 477False for external PM events. 478 479 480Mutual exclusion 481---------------- 482 483For external events -- but not necessarily for autosuspend or 484autoresume -- the device semaphore (udev->dev.sem) will be held when a 485``suspend`` or ``resume`` method is called. This implies that external 486suspend/resume events are mutually exclusive with calls to ``probe``, 487``disconnect``, ``pre_reset``, and ``post_reset``; the USB core guarantees that 488this is true of autosuspend/autoresume events as well. 489 490If a driver wants to block all suspend/resume calls during some 491critical section, the best way is to lock the device and call 492:c:func:`usb_autopm_get_interface` (and do the reverse at the end of the 493critical section). Holding the device semaphore will block all 494external PM calls, and the :c:func:`usb_autopm_get_interface` will prevent any 495internal PM calls, even if it fails. (Exercise: Why?) 496 497 498Interaction between dynamic PM and system PM 499-------------------------------------------- 500 501Dynamic power management and system power management can interact in 502a couple of ways. 503 504Firstly, a device may already be autosuspended when a system suspend 505occurs. Since system suspends are supposed to be as transparent as 506possible, the device should remain suspended following the system 507resume. But this theory may not work out well in practice; over time 508the kernel's behavior in this regard has changed. As of 2.6.37 the 509policy is to resume all devices during a system resume and let them 510handle their own runtime suspends afterward. 511 512Secondly, a dynamic power-management event may occur as a system 513suspend is underway. The window for this is short, since system 514suspends don't take long (a few seconds usually), but it can happen. 515For example, a suspended device may send a remote-wakeup signal while 516the system is suspending. The remote wakeup may succeed, which would 517cause the system suspend to abort. If the remote wakeup doesn't 518succeed, it may still remain active and thus cause the system to 519resume as soon as the system suspend is complete. Or the remote 520wakeup may fail and get lost. Which outcome occurs depends on timing 521and on the hardware and firmware design. 522 523 524xHCI hardware link PM 525--------------------- 526 527xHCI host controller provides hardware link power management to usb2.0 528(xHCI 1.0 feature) and usb3.0 devices which support link PM. By 529enabling hardware LPM, the host can automatically put the device into 530lower power state(L1 for usb2.0 devices, or U1/U2 for usb3.0 devices), 531which state device can enter and resume very quickly. 532 533The user interface for controlling hardware LPM is located in the 534``power/`` subdirectory of each USB device's sysfs directory, that is, in 535``/sys/bus/usb/devices/.../power/`` where "..." is the device's ID. The 536relevant attribute files are ``usb2_hardware_lpm`` and ``usb3_hardware_lpm``. 537 538 ``power/usb2_hardware_lpm`` 539 540 When a USB2 device which support LPM is plugged to a 541 xHCI host root hub which support software LPM, the 542 host will run a software LPM test for it; if the device 543 enters L1 state and resume successfully and the host 544 supports USB2 hardware LPM, this file will show up and 545 driver will enable hardware LPM for the device. You 546 can write y/Y/1 or n/N/0 to the file to enable/disable 547 USB2 hardware LPM manually. This is for test purpose mainly. 548 549 ``power/usb3_hardware_lpm_u1`` 550 ``power/usb3_hardware_lpm_u2`` 551 552 When a USB 3.0 lpm-capable device is plugged in to a 553 xHCI host which supports link PM, it will check if U1 554 and U2 exit latencies have been set in the BOS 555 descriptor; if the check is passed and the host 556 supports USB3 hardware LPM, USB3 hardware LPM will be 557 enabled for the device and these files will be created. 558 The files hold a string value (enable or disable) 559 indicating whether or not USB3 hardware LPM U1 or U2 560 is enabled for the device. 561 562USB Port Power Control 563---------------------- 564 565In addition to suspending endpoint devices and enabling hardware 566controlled link power management, the USB subsystem also has the 567capability to disable power to ports under some conditions. Power is 568controlled through ``Set/ClearPortFeature(PORT_POWER)`` requests to a hub. 569In the case of a root or platform-internal hub the host controller 570driver translates ``PORT_POWER`` requests into platform firmware (ACPI) 571method calls to set the port power state. For more background see the 572Linux Plumbers Conference 2012 slides [#f1]_ and video [#f2]_: 573 574Upon receiving a ``ClearPortFeature(PORT_POWER)`` request a USB port is 575logically off, and may trigger the actual loss of VBUS to the port [#f3]_. 576VBUS may be maintained in the case where a hub gangs multiple ports into 577a shared power well causing power to remain until all ports in the gang 578are turned off. VBUS may also be maintained by hub ports configured for 579a charging application. In any event a logically off port will lose 580connection with its device, not respond to hotplug events, and not 581respond to remote wakeup events. 582 583.. warning:: 584 585 turning off a port may result in the inability to hot add a device. 586 Please see "User Interface for Port Power Control" for details. 587 588As far as the effect on the device itself it is similar to what a device 589goes through during system suspend, i.e. the power session is lost. Any 590USB device or driver that misbehaves with system suspend will be 591similarly affected by a port power cycle event. For this reason the 592implementation shares the same device recovery path (and honors the same 593quirks) as the system resume path for the hub. 594 595.. [#f1] 596 597 http://dl.dropbox.com/u/96820575/sarah-sharp-lpt-port-power-off2-mini.pdf 598 599.. [#f2] 600 601 http://linuxplumbers.ubicast.tv/videos/usb-port-power-off-kerneluserspace-api/ 602 603.. [#f3] 604 605 USB 3.1 Section 10.12 606 607 wakeup note: if a device is configured to send wakeup events the port 608 power control implementation will block poweroff attempts on that 609 port. 610 611 612User Interface for Port Power Control 613------------------------------------- 614 615The port power control mechanism uses the PM runtime system. Poweroff is 616requested by clearing the ``power/pm_qos_no_power_off`` flag of the port device 617(defaults to 1). If the port is disconnected it will immediately receive a 618``ClearPortFeature(PORT_POWER)`` request. Otherwise, it will honor the pm 619runtime rules and require the attached child device and all descendants to be 620suspended. This mechanism is dependent on the hub advertising port power 621switching in its hub descriptor (wHubCharacteristics logical power switching 622mode field). 623 624Note, some interface devices/drivers do not support autosuspend. Userspace may 625need to unbind the interface drivers before the :c:type:`usb_device` will 626suspend. An unbound interface device is suspended by default. When unbinding, 627be careful to unbind interface drivers, not the driver of the parent usb 628device. Also, leave hub interface drivers bound. If the driver for the usb 629device (not interface) is unbound the kernel is no longer able to resume the 630device. If a hub interface driver is unbound, control of its child ports is 631lost and all attached child-devices will disconnect. A good rule of thumb is 632that if the 'driver/module' link for a device points to 633``/sys/module/usbcore`` then unbinding it will interfere with port power 634control. 635 636Example of the relevant files for port power control. Note, in this example 637these files are relative to a usb hub device (prefix):: 638 639 prefix=/sys/devices/pci0000:00/0000:00:14.0/usb3/3-1 640 641 attached child device + 642 hub port device + | 643 hub interface device + | | 644 v v v 645 $prefix/3-1:1.0/3-1-port1/device 646 647 $prefix/3-1:1.0/3-1-port1/power/pm_qos_no_power_off 648 $prefix/3-1:1.0/3-1-port1/device/power/control 649 $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intf0>/driver/unbind 650 $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intf1>/driver/unbind 651 ... 652 $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intfN>/driver/unbind 653 654In addition to these files some ports may have a 'peer' link to a port on 655another hub. The expectation is that all superspeed ports have a 656hi-speed peer:: 657 658 $prefix/3-1:1.0/3-1-port1/peer -> ../../../../usb2/2-1/2-1:1.0/2-1-port1 659 ../../../../usb2/2-1/2-1:1.0/2-1-port1/peer -> ../../../../usb3/3-1/3-1:1.0/3-1-port1 660 661Distinct from 'companion ports', or 'ehci/xhci shared switchover ports' 662peer ports are simply the hi-speed and superspeed interface pins that 663are combined into a single usb3 connector. Peer ports share the same 664ancestor XHCI device. 665 666While a superspeed port is powered off a device may downgrade its 667connection and attempt to connect to the hi-speed pins. The 668implementation takes steps to prevent this: 669 6701. Port suspend is sequenced to guarantee that hi-speed ports are powered-off 671 before their superspeed peer is permitted to power-off. The implication is 672 that the setting ``pm_qos_no_power_off`` to zero on a superspeed port may 673 not cause the port to power-off until its highspeed peer has gone to its 674 runtime suspend state. Userspace must take care to order the suspensions 675 if it wants to guarantee that a superspeed port will power-off. 676 6772. Port resume is sequenced to force a superspeed port to power-on prior to its 678 highspeed peer. 679 6803. Port resume always triggers an attached child device to resume. After a 681 power session is lost the device may have been removed, or need reset. 682 Resuming the child device when the parent port regains power resolves those 683 states and clamps the maximum port power cycle frequency at the rate the 684 child device can suspend (autosuspend-delay) and resume (reset-resume 685 latency). 686 687Sysfs files relevant for port power control: 688 689 ``<hubdev-portX>/power/pm_qos_no_power_off``: 690 This writable flag controls the state of an idle port. 691 Once all children and descendants have suspended the 692 port may suspend/poweroff provided that 693 pm_qos_no_power_off is '0'. If pm_qos_no_power_off is 694 '1' the port will remain active/powered regardless of 695 the stats of descendants. Defaults to 1. 696 697 ``<hubdev-portX>/power/runtime_status``: 698 This file reflects whether the port is 'active' (power is on) 699 or 'suspended' (logically off). There is no indication to 700 userspace whether VBUS is still supplied. 701 702 ``<hubdev-portX>/connect_type``: 703 An advisory read-only flag to userspace indicating the 704 location and connection type of the port. It returns 705 one of four values 'hotplug', 'hardwired', 'not used', 706 and 'unknown'. All values, besides unknown, are set by 707 platform firmware. 708 709 ``hotplug`` indicates an externally connectable/visible 710 port on the platform. Typically userspace would choose 711 to keep such a port powered to handle new device 712 connection events. 713 714 ``hardwired`` refers to a port that is not visible but 715 connectable. Examples are internal ports for USB 716 bluetooth that can be disconnected via an external 717 switch or a port with a hardwired USB camera. It is 718 expected to be safe to allow these ports to suspend 719 provided pm_qos_no_power_off is coordinated with any 720 switch that gates connections. Userspace must arrange 721 for the device to be connected prior to the port 722 powering off, or to activate the port prior to enabling 723 connection via a switch. 724 725 ``not used`` refers to an internal port that is expected 726 to never have a device connected to it. These may be 727 empty internal ports, or ports that are not physically 728 exposed on a platform. Considered safe to be 729 powered-off at all times. 730 731 ``unknown`` means platform firmware does not provide 732 information for this port. Most commonly refers to 733 external hub ports which should be considered 'hotplug' 734 for policy decisions. 735 736 .. note:: 737 738 - since we are relying on the BIOS to get this ACPI 739 information correct, the USB port descriptions may 740 be missing or wrong. 741 742 - Take care in clearing ``pm_qos_no_power_off``. Once 743 power is off this port will 744 not respond to new connect events. 745 746 Once a child device is attached additional constraints are 747 applied before the port is allowed to poweroff. 748 749 ``<child>/power/control``: 750 Must be ``auto``, and the port will not 751 power down until ``<child>/power/runtime_status`` 752 reflects the 'suspended' state. Default 753 value is controlled by child device driver. 754 755 ``<child>/power/persist``: 756 This defaults to ``1`` for most devices and indicates if 757 kernel can persist the device's configuration across a 758 power session loss (suspend / port-power event). When 759 this value is ``0`` (quirky devices), port poweroff is 760 disabled. 761 762 ``<child>/driver/unbind``: 763 Wakeup capable devices will block port poweroff. At 764 this time the only mechanism to clear the usb-internal 765 wakeup-capability for an interface device is to unbind 766 its driver. 767 768Summary of poweroff pre-requisite settings relative to a port device:: 769 770 echo 0 > power/pm_qos_no_power_off 771 echo 0 > peer/power/pm_qos_no_power_off # if it exists 772 echo auto > power/control # this is the default value 773 echo auto > <child>/power/control 774 echo 1 > <child>/power/persist # this is the default value 775 776Suggested Userspace Port Power Policy 777------------------------------------- 778 779As noted above userspace needs to be careful and deliberate about what 780ports are enabled for poweroff. 781 782The default configuration is that all ports start with 783``power/pm_qos_no_power_off`` set to ``1`` causing ports to always remain 784active. 785 786Given confidence in the platform firmware's description of the ports 787(ACPI _PLD record for a port populates 'connect_type') userspace can 788clear pm_qos_no_power_off for all 'not used' ports. The same can be 789done for 'hardwired' ports provided poweroff is coordinated with any 790connection switch for the port. 791 792A more aggressive userspace policy is to enable USB port power off for 793all ports (set ``<hubdev-portX>/power/pm_qos_no_power_off`` to ``0``) when 794some external factor indicates the user has stopped interacting with the 795system. For example, a distro may want to enable power off all USB 796ports when the screen blanks, and re-power them when the screen becomes 797active. Smart phones and tablets may want to power off USB ports when 798the user pushes the power button. 799