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