799 lines · plain
1.. _usb-power-management:2 3Power Management for USB4~~~~~~~~~~~~~~~~~~~~~~~~5 6:Author: Alan Stern <stern@rowland.harvard.edu>7:Date: Last-updated: February 20148 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 PM16 * The user interface for dynamic PM17 * Changing the default idle-delay time18 * Warnings19 * The driver interface for Power Management20 * The driver interface for autosuspend and autoresume21 * Other parts of the driver interface22 * Mutual exclusion23 * Interaction between dynamic PM and system PM24 * xHCI hardware link PM25 * USB Port Power Control26 * User Interface for Port Power Control27 * Suggested Userspace Port Power Policy28 29 30What is Power Management?31-------------------------32 33Power Management (PM) is the practice of saving energy by suspending34parts of a computer system when they aren't being used. While a35component is ``suspended`` it is in a nonfunctional low-power state; it36might even be turned off completely. A suspended component can be37``resumed`` (returned to a functional full-power state) when the kernel38needs to use it. (There also are forms of PM in which components are39placed in a less functional but still usable state instead of being40suspended; an example would be reducing the CPU's clock rate. This41document will not discuss those other forms.)42 43When the parts being suspended include the CPU and most of the rest of44the system, we speak of it as a "system suspend". When a particular45device is turned off while the system as a whole remains running, we46call it a "dynamic suspend" (also known as a "runtime suspend" or47"selective suspend"). This document concentrates mostly on how48dynamic PM is implemented in the USB subsystem, although system PM is49covered to some extent (see ``Documentation/power/*.rst`` for more50information about system PM).51 52System PM support is present only if the kernel was built with53``CONFIG_SUSPEND`` or ``CONFIG_HIBERNATION`` enabled. Dynamic PM support54 55for USB is present whenever56the kernel was built with ``CONFIG_PM`` enabled.57 58[Historically, dynamic PM support for USB was present only if the59kernel had been built with ``CONFIG_USB_SUSPEND`` enabled (which depended on60``CONFIG_PM_RUNTIME``). Starting with the 3.10 kernel release, dynamic PM61support for USB was present whenever the kernel was built with62``CONFIG_PM_RUNTIME`` enabled. The ``CONFIG_USB_SUSPEND`` option had been63eliminated.]64 65 66What is Remote Wakeup?67----------------------68 69When a device has been suspended, it generally doesn't resume until70the computer tells it to. Likewise, if the entire computer has been71suspended, it generally doesn't resume until the user tells it to, say72by pressing a power button or opening the cover.73 74However some devices have the capability of resuming by themselves, or75asking the kernel to resume them, or even telling the entire computer76to resume. This capability goes by several names such as "Wake On77LAN"; we will refer to it generically as "remote wakeup". When a78device is enabled for remote wakeup and it is suspended, it may resume79itself (or send a request to be resumed) in response to some external80event. Examples include a suspended keyboard resuming when a key is81pressed, 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 doing88anything important and thus is a candidate for being suspended. The89exact definition depends on the device's driver; drivers are allowed90to declare that a device isn't idle even when there's no actual91communication taking place. (For example, a hub isn't considered idle92unless all the devices plugged into that hub are already suspended.)93In addition, a device isn't considered idle so long as a program keeps94its 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't97being accessed through sysfs, then it definitely is idle.98 99 100Forms of dynamic PM101-------------------102 103Dynamic suspends occur when the kernel decides to suspend an idle104device. This is called ``autosuspend`` for short. In general, a device105won't be autosuspended unless it has been idle for some minimum period106of time, the so-called idle-delay time.107 108Of course, nothing the kernel does on its own initiative should109prevent the computer or its devices from working properly. If a110device has been autosuspended and a program tries to use it, the111kernel will automatically resume the device (autoresume). For the112same reason, an autosuspended device will usually have remote wakeup113enabled, if the device supports remote wakeup.114 115It is worth mentioning that many USB drivers don't support116autosuspend. In fact, at the time of this writing (Linux 2.6.23) the117only drivers which do support it are the hub driver, kaweth, asix,118usblp, usblcd, and usb-skeleton (which doesn't count). If a119non-supporting driver is bound to a device, the device won't be120autosuspended. In effect, the kernel pretends the device is never121idle.122 123We can categorize power management events in two broad classes:124external and internal. External events are those triggered by some125agent outside the USB stack: system suspend/resume (triggered by126userspace), manual dynamic resume (also triggered by userspace), and127remote wakeup (triggered by the device). Internal events are those128triggered within the USB stack: autosuspend and autoresume. Note that129all dynamic suspend events are internal; external agents are not130allowed to issue dynamic suspends.131 132 133The user interface for dynamic PM134---------------------------------135 136The user interface for controlling dynamic PM is located in the ``power/``137subdirectory of each USB device's sysfs directory, that is, in138``/sys/bus/usb/devices/.../power/`` where "..." is the device's ID. The139relevant attribute files are: wakeup, control, and140``autosuspend_delay_ms``. (There may also be a file named ``level``; this141file was deprecated as of the 2.6.35 kernel and replaced by the142``control`` file. In 2.6.38 the ``autosuspend`` file will be deprecated143and replaced by the ``autosuspend_delay_ms`` file. The only difference144is that the newer file expresses the delay in milliseconds whereas the145older file uses seconds. Confusingly, both files are present in 2.6.37146but only ``autosuspend`` works.)147 148 ``power/wakeup``149 150 This file is empty if the device does not support151 remote wakeup. Otherwise the file contains either the152 word ``enabled`` or the word ``disabled``, and you can153 write those words to the file. The setting determines154 whether or not remote wakeup will be enabled when the155 device is next suspended. (If the setting is changed156 while the device is suspended, the change won't take157 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 the163 device's setting.164 165 - ``on`` means that the device should be resumed and166 autosuspend is not allowed. (Of course, system167 suspends are still allowed.)168 169 - ``auto`` is the normal state in which the kernel is170 allowed to autosuspend and autoresume the device.171 172 (In kernels up to 2.6.32, you could also specify173 ``suspend``, meaning that the device should remain174 suspended and autoresume was not allowed. This175 setting is no longer supported.)176 177 ``power/autosuspend_delay_ms``178 179 This file contains an integer value, which is the180 number of milliseconds the device should remain idle181 before the kernel will autosuspend it (the idle-delay182 time). The default is 2000. 0 means to autosuspend183 as soon as the device becomes idle, and negative184 values mean never to autosuspend. You can write a185 number to the file to change the autosuspend186 idle-delay time.187 188Writing ``-1`` to ``power/autosuspend_delay_ms`` and writing ``on`` to189``power/control`` do essentially the same thing -- they both prevent the190device from being autosuspended. Yes, this is a redundancy in the191API.192 193(In 2.6.21 writing ``0`` to ``power/autosuspend`` would prevent the device194from being autosuspended; the behavior was changed in 2.6.22. The195``power/autosuspend`` attribute did not exist prior to 2.6.21, and the196``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 in1982.6.37 but did not become functional until 2.6.38.)199 200 201Changing the default idle-delay time202------------------------------------203 204The default autosuspend idle-delay time (in seconds) is controlled by205a module parameter in usbcore. You can specify the value when usbcore206is loaded. For example, to set it to 5 seconds instead of 2 you would207do::208 209 modprobe usbcore autosuspend=5210 211Equivalently, you could add to a configuration file in /etc/modprobe.d212a line saying::213 214 options usbcore autosuspend=5215 216Some distributions load the usbcore module very early during the boot217process, by means of a program or script running from an initramfs218image. To alter the parameter value you would have to rebuild that219image.220 221If usbcore is compiled into the kernel rather than built as a loadable222module, you can add::223 224 usbcore.autosuspend=5225 226to the kernel's boot command line.227 228Finally, the parameter value can be changed while the system is229running. If you do::230 231 echo 5 >/sys/module/usbcore/parameters/autosuspend232 233then each new USB device will have its autosuspend idle-delay234initialized to 5. (The idle-delay values for already existing devices235will not be affected.)236 237Setting the initial default idle-delay to -1 will prevent any238autosuspend of any USB device. This has the benefit of allowing you239then to enable autosuspend for selected devices.240 241 242Warnings243--------244 245The USB specification states that all USB devices must support power246management. Nevertheless, the sad fact is that many devices do not247support it very well. You can suspend them all right, but when you248try to resume them they disconnect themselves from the USB bus or249they stop working entirely. This seems to be especially prevalent250among printers and scanners, but plenty of other types of device have251the same deficiency.252 253For this reason, by default the kernel disables autosuspend (the254``power/control`` attribute is initialized to ``on``) for all devices other255than hubs. Hubs, at least, appear to be reasonably well-behaved in256this regard.257 258(In 2.6.21 and 2.6.22 this wasn't the case. Autosuspend was enabled259by default for almost all USB devices. A number of people experienced260problems as a result.)261 262This means that non-hub devices won't be autosuspended unless the user263or a program explicitly enables it. As of this writing there aren't264any widespread programs which will do this; we hope that in the near265future device managers such as HAL will take on this added266responsibility. In the meantime you can always carry out the267necessary operations by hand or add them to a udev script. You can268also change the idle-delay time; 2 seconds is not the best choice for269every device.270 271If a driver knows that its device has proper suspend/resume support,272it can enable autosuspend all by itself. For example, the video273driver for a laptop's webcam might do this (in recent kernels they274do), since these devices are rarely used and so should normally be275autosuspended.276 277Sometimes it turns out that even when a device does work okay with278autosuspend there are still problems. For example, the usbhid driver,279which manages keyboards and mice, has autosuspend support. Tests with280a number of keyboards show that typing on a suspended keyboard, while281causing the keyboard to do a remote wakeup all right, will nonetheless282frequently result in lost keystrokes. Tests with mice show that some283of them will issue a remote-wakeup request in response to button284presses but not to motion, and some in response to neither.285 286The kernel will not prevent you from enabling autosuspend on devices287that can't handle it. It is even possible in theory to damage a288device by suspending it at the wrong time. (Highly unlikely, but289possible.) Take care.290 291 292The driver interface for Power Management293-----------------------------------------294 295The requirements for a USB driver to support external power management296are pretty modest; the driver need only define::297 298 .suspend299 .resume300 .reset_resume301 302methods in its :c:type:`usb_driver` structure, and the ``reset_resume`` method303is optional. The methods' jobs are quite simple:304 305 - The ``suspend`` method is called to warn the driver that the306 device is going to be suspended. If the driver returns a307 negative error code, the suspend will be aborted. Normally308 the driver will return 0, in which case it must cancel all309 outstanding URBs (:c:func:`usb_kill_urb`) and not submit any more.310 311 - The ``resume`` method is called to tell the driver that the312 device has been resumed and the driver can return to normal313 operation. URBs may once more be submitted.314 315 - The ``reset_resume`` method is called to tell the driver that316 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 state319 (although the interfaces will be in the same altsettings as320 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`` or324``reset_resume`` method. This is also quite likely to happen when325waking up from hibernation, as many systems do not maintain suspend326current to the USB host controllers during hibernation. (It's327possible to work around the hibernation-forces-disconnect problem by328using the USB Persist facility.)329 330The ``reset_resume`` method is used by the USB Persist facility (see331:ref:`usb-persist`) and it can also be used under certain332circumstances when ``CONFIG_USB_PERSIST`` is not enabled. Currently, if a333device is reset during a resume and the driver does not have a334``reset_resume`` method, the driver won't receive any notification about335the 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. In340principle one might want to suspend some interfaces on a device (i.e.,341force the drivers for those interface to stop all activity) without342suspending the other interfaces. The USB core doesn't allow this; all343interfaces are suspended when the device itself is suspended and all344interfaces are resumed when the device is resumed. It isn't possible345to suspend or resume some but not all of a device's interfaces. The346closest you can come is to unbind the interfaces' drivers.347 348 349The driver interface for autosuspend and autoresume350---------------------------------------------------351 352To support autosuspend and autoresume, a driver should implement all353three of the methods listed above. In addition, a driver indicates354that it supports autosuspend by setting the ``.supports_autosuspend`` flag355in its usb_driver structure. It is then responsible for informing the356USB core whenever one of its interfaces becomes busy or idle. The357driver 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 the367usb_interface's embedded device structure. When the counter is > 0368then the interface is deemed to be busy, and the kernel will not369autosuspend the interface's device. When the usage counter is = 0370then the interface is considered to be idle, and the kernel may371autosuspend the device.372 373Drivers must be careful to balance their overall changes to the usage374counter. Unbalanced "get"s will remain in effect when a driver is375unbound from its interface, preventing the device from going into376runtime suspend should the interface be bound to a driver again. On377the other hand, drivers are allowed to achieve this balance by calling378the ``usb_autopm_*`` functions even after their ``disconnect`` routine379has returned -- say from within a work-queue routine -- provided they380retain an active reference to the interface (via ``usb_get_intf`` and381``usb_put_intf``).382 383Drivers using the async routines are responsible for their own384synchronization and mutual exclusion.385 386 :c:func:`usb_autopm_get_interface` increments the usage counter and387 does an autoresume if the device is suspended. If the388 autoresume fails, the counter is decremented back.389 390 :c:func:`usb_autopm_put_interface` decrements the usage counter and391 attempts an autosuspend if the new value is = 0.392 393 :c:func:`usb_autopm_get_interface_async` and394 :c:func:`usb_autopm_put_interface_async` do almost the same things as395 their non-async counterparts. The big difference is that they396 use a workqueue to do the resume or suspend part of their397 jobs. As a result they can be called in an atomic context,398 such as an URB's completion handler, but when they return the399 device will generally not yet be in the desired state.400 401 :c:func:`usb_autopm_get_interface_no_resume` and402 :c:func:`usb_autopm_put_interface_no_suspend` merely increment or403 decrement the usage counter; they do not attempt to carry out404 an autoresume or an autosuspend. Hence they can be called in405 an atomic context.406 407The simplest usage pattern is that a driver calls408:c:func:`usb_autopm_get_interface` in its open routine and409:c:func:`usb_autopm_put_interface` in its close or release routine. But other410patterns are possible.411 412The autosuspend attempts mentioned above will often fail for one413reason or another. For example, the ``power/control`` attribute might be414set to ``on``, or another interface in the same device might not be415idle. This is perfectly normal. If the reason for failure was that416the device hasn't been idle for long enough, a timer is scheduled to417carry out the operation automatically when the autosuspend idle-delay418has expired.419 420Autoresume attempts also can fail, although failure would mean that421the device is no longer present or operating properly. Unlike422autosuspend, there's no idle-delay for an autoresume.423 424 425Other parts of the driver interface426-----------------------------------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 of433suspending and resuming correctly. This is exactly equivalent to434writing ``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 enabled442during autosuspend. For example, there's not much point443autosuspending a keyboard if the user can't cause the keyboard to do a444remote wakeup by typing on it. If the driver sets445``intf->needs_remote_wakeup`` to 1, the kernel won't autosuspend the446device if remote wakeup isn't available. (If the device is already447autosuspended, though, setting this flag won't cause the kernel to448autoresume it. Normally a driver would set this flag in its ``probe``449method, at which time the device is guaranteed not to be450autosuspended.)451 452If a driver does its I/O asynchronously in interrupt context, it453should call :c:func:`usb_autopm_get_interface_async` before starting output and454:c:func:`usb_autopm_put_interface_async` when the output queue drains. When455it 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 just460busy and therefore the next autosuspend idle-delay expiration should461be 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, a465driver may call the :c:func:`usb_autopm_get_interface_async` routine at a time466when the core has just finished deciding the device has been idle for467long enough but not yet gotten around to calling the driver's ``suspend``468method. The ``suspend`` method must be responsible for synchronizing with469the I/O request routine and the URB completion handler; it should470cause autosuspends to fail with -EBUSY if the driver needs to use the471device.472 473External suspend calls should never be allowed to fail in this way,474only autosuspend calls. The driver can tell them apart by applying475the :c:func:`PMSG_IS_AUTO` macro to the message argument to the ``suspend``476method; it will return True for internal PM events (autosuspend) and477False for external PM events.478 479 480Mutual exclusion481----------------482 483For external events -- but not necessarily for autosuspend or484autoresume -- the device semaphore (udev->dev.sem) will be held when a485``suspend`` or ``resume`` method is called. This implies that external486suspend/resume events are mutually exclusive with calls to ``probe``,487``disconnect``, ``pre_reset``, and ``post_reset``; the USB core guarantees that488this is true of autosuspend/autoresume events as well.489 490If a driver wants to block all suspend/resume calls during some491critical section, the best way is to lock the device and call492:c:func:`usb_autopm_get_interface` (and do the reverse at the end of the493critical section). Holding the device semaphore will block all494external PM calls, and the :c:func:`usb_autopm_get_interface` will prevent any495internal PM calls, even if it fails. (Exercise: Why?)496 497 498Interaction between dynamic PM and system PM499--------------------------------------------500 501Dynamic power management and system power management can interact in502a couple of ways.503 504Firstly, a device may already be autosuspended when a system suspend505occurs. Since system suspends are supposed to be as transparent as506possible, the device should remain suspended following the system507resume. But this theory may not work out well in practice; over time508the kernel's behavior in this regard has changed. As of 2.6.37 the509policy is to resume all devices during a system resume and let them510handle their own runtime suspends afterward.511 512Secondly, a dynamic power-management event may occur as a system513suspend is underway. The window for this is short, since system514suspends don't take long (a few seconds usually), but it can happen.515For example, a suspended device may send a remote-wakeup signal while516the system is suspending. The remote wakeup may succeed, which would517cause the system suspend to abort. If the remote wakeup doesn't518succeed, it may still remain active and thus cause the system to519resume as soon as the system suspend is complete. Or the remote520wakeup may fail and get lost. Which outcome occurs depends on timing521and on the hardware and firmware design.522 523 524xHCI hardware link PM525---------------------526 527xHCI host controller provides hardware link power management to usb2.0528(xHCI 1.0 feature) and usb3.0 devices which support link PM. By529enabling hardware LPM, the host can automatically put the device into530lower 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 the534``power/`` subdirectory of each USB device's sysfs directory, that is, in535``/sys/bus/usb/devices/.../power/`` where "..." is the device's ID. The536relevant 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 a541 xHCI host root hub which support software LPM, the542 host will run a software LPM test for it; if the device543 enters L1 state and resume successfully and the host544 supports USB2 hardware LPM, this file will show up and545 driver will enable hardware LPM for the device. You546 can write y/Y/1 or n/N/0 to the file to enable/disable547 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 a553 xHCI host which supports link PM, it will check if U1554 and U2 exit latencies have been set in the BOS555 descriptor; if the check is passed and the host556 supports USB3 hardware LPM, USB3 hardware LPM will be557 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 U2560 is enabled for the device.561 562USB Port Power Control563----------------------564 565In addition to suspending endpoint devices and enabling hardware566controlled link power management, the USB subsystem also has the567capability to disable power to ports under some conditions. Power is568controlled through ``Set/ClearPortFeature(PORT_POWER)`` requests to a hub.569In the case of a root or platform-internal hub the host controller570driver translates ``PORT_POWER`` requests into platform firmware (ACPI)571method calls to set the port power state. For more background see the572Linux Plumbers Conference 2012 slides [#f1]_ and video [#f2]_:573 574Upon receiving a ``ClearPortFeature(PORT_POWER)`` request a USB port is575logically 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 into577a shared power well causing power to remain until all ports in the gang578are turned off. VBUS may also be maintained by hub ports configured for579a charging application. In any event a logically off port will lose580connection with its device, not respond to hotplug events, and not581respond 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 device589goes through during system suspend, i.e. the power session is lost. Any590USB device or driver that misbehaves with system suspend will be591similarly affected by a port power cycle event. For this reason the592implementation shares the same device recovery path (and honors the same593quirks) 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.pdf598 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.12606 607 wakeup note: if a device is configured to send wakeup events the port608 power control implementation will block poweroff attempts on that609 port.610 611 612User Interface for Port Power Control613-------------------------------------614 615The port power control mechanism uses the PM runtime system. Poweroff is616requested by clearing the ``power/pm_qos_no_power_off`` flag of the port device617(defaults to 1). If the port is disconnected it will immediately receive a618``ClearPortFeature(PORT_POWER)`` request. Otherwise, it will honor the pm619runtime rules and require the attached child device and all descendants to be620suspended. This mechanism is dependent on the hub advertising port power621switching in its hub descriptor (wHubCharacteristics logical power switching622mode field).623 624Note, some interface devices/drivers do not support autosuspend. Userspace may625need to unbind the interface drivers before the :c:type:`usb_device` will626suspend. An unbound interface device is suspended by default. When unbinding,627be careful to unbind interface drivers, not the driver of the parent usb628device. Also, leave hub interface drivers bound. If the driver for the usb629device (not interface) is unbound the kernel is no longer able to resume the630device. If a hub interface driver is unbound, control of its child ports is631lost and all attached child-devices will disconnect. A good rule of thumb is632that if the 'driver/module' link for a device points to633``/sys/module/usbcore`` then unbinding it will interfere with port power634control.635 636Example of the relevant files for port power control. Note, in this example637these files are relative to a usb hub device (prefix)::638 639 prefix=/sys/devices/pci0000:00/0000:00:14.0/usb3/3-1640 641 attached child device +642 hub port device + |643 hub interface device + | |644 v v v645 $prefix/3-1:1.0/3-1-port1/device646 647 $prefix/3-1:1.0/3-1-port1/power/pm_qos_no_power_off648 $prefix/3-1:1.0/3-1-port1/device/power/control649 $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intf0>/driver/unbind650 $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intf1>/driver/unbind651 ...652 $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intfN>/driver/unbind653 654In addition to these files some ports may have a 'peer' link to a port on655another hub. The expectation is that all superspeed ports have a656hi-speed peer::657 658 $prefix/3-1:1.0/3-1-port1/peer -> ../../../../usb2/2-1/2-1:1.0/2-1-port1659 ../../../../usb2/2-1/2-1:1.0/2-1-port1/peer -> ../../../../usb3/3-1/3-1:1.0/3-1-port1660 661Distinct from 'companion ports', or 'ehci/xhci shared switchover ports'662peer ports are simply the hi-speed and superspeed interface pins that663are combined into a single usb3 connector. Peer ports share the same664ancestor XHCI device.665 666While a superspeed port is powered off a device may downgrade its667connection and attempt to connect to the hi-speed pins. The668implementation takes steps to prevent this:669 6701. Port suspend is sequenced to guarantee that hi-speed ports are powered-off671 before their superspeed peer is permitted to power-off. The implication is672 that the setting ``pm_qos_no_power_off`` to zero on a superspeed port may673 not cause the port to power-off until its highspeed peer has gone to its674 runtime suspend state. Userspace must take care to order the suspensions675 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 its678 highspeed peer.679 6803. Port resume always triggers an attached child device to resume. After a681 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 those683 states and clamps the maximum port power cycle frequency at the rate the684 child device can suspend (autosuspend-delay) and resume (reset-resume685 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 the692 port may suspend/poweroff provided that693 pm_qos_no_power_off is '0'. If pm_qos_no_power_off is694 '1' the port will remain active/powered regardless of695 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 to700 userspace whether VBUS is still supplied.701 702 ``<hubdev-portX>/connect_type``:703 An advisory read-only flag to userspace indicating the704 location and connection type of the port. It returns705 one of four values 'hotplug', 'hardwired', 'not used',706 and 'unknown'. All values, besides unknown, are set by707 platform firmware.708 709 ``hotplug`` indicates an externally connectable/visible710 port on the platform. Typically userspace would choose711 to keep such a port powered to handle new device712 connection events.713 714 ``hardwired`` refers to a port that is not visible but715 connectable. Examples are internal ports for USB716 bluetooth that can be disconnected via an external717 switch or a port with a hardwired USB camera. It is718 expected to be safe to allow these ports to suspend719 provided pm_qos_no_power_off is coordinated with any720 switch that gates connections. Userspace must arrange721 for the device to be connected prior to the port722 powering off, or to activate the port prior to enabling723 connection via a switch.724 725 ``not used`` refers to an internal port that is expected726 to never have a device connected to it. These may be727 empty internal ports, or ports that are not physically728 exposed on a platform. Considered safe to be729 powered-off at all times.730 731 ``unknown`` means platform firmware does not provide732 information for this port. Most commonly refers to733 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 ACPI739 information correct, the USB port descriptions may740 be missing or wrong.741 742 - Take care in clearing ``pm_qos_no_power_off``. Once743 power is off this port will744 not respond to new connect events.745 746 Once a child device is attached additional constraints are747 applied before the port is allowed to poweroff.748 749 ``<child>/power/control``:750 Must be ``auto``, and the port will not751 power down until ``<child>/power/runtime_status``752 reflects the 'suspended' state. Default753 value is controlled by child device driver.754 755 ``<child>/power/persist``:756 This defaults to ``1`` for most devices and indicates if757 kernel can persist the device's configuration across a758 power session loss (suspend / port-power event). When759 this value is ``0`` (quirky devices), port poweroff is760 disabled.761 762 ``<child>/driver/unbind``:763 Wakeup capable devices will block port poweroff. At764 this time the only mechanism to clear the usb-internal765 wakeup-capability for an interface device is to unbind766 its driver.767 768Summary of poweroff pre-requisite settings relative to a port device::769 770 echo 0 > power/pm_qos_no_power_off771 echo 0 > peer/power/pm_qos_no_power_off # if it exists772 echo auto > power/control # this is the default value773 echo auto > <child>/power/control774 echo 1 > <child>/power/persist # this is the default value775 776Suggested Userspace Port Power Policy777-------------------------------------778 779As noted above userspace needs to be careful and deliberate about what780ports are enabled for poweroff.781 782The default configuration is that all ports start with783``power/pm_qos_no_power_off`` set to ``1`` causing ports to always remain784active.785 786Given confidence in the platform firmware's description of the ports787(ACPI _PLD record for a port populates 'connect_type') userspace can788clear pm_qos_no_power_off for all 'not used' ports. The same can be789done for 'hardwired' ports provided poweroff is coordinated with any790connection switch for the port.791 792A more aggressive userspace policy is to enable USB port power off for793all ports (set ``<hubdev-portX>/power/pm_qos_no_power_off`` to ``0``) when794some external factor indicates the user has stopped interacting with the795system. For example, a distro may want to enable power off all USB796ports when the screen blanks, and re-power them when the screen becomes797active. Smart phones and tablets may want to power off USB ports when798the user pushes the power button.799