mirror of
https://github.com/edk2-porting/linux-next.git
synced 2024-12-26 06:04:14 +08:00
4e9c8e5c58
An earlier patch removed the CONFIG_USB_SUSPEND symbol but forgot to update the Documentation files. This patch (as1676) rectifies that omission. Signed-off-by: Alan Stern <stern@rowland.harvard.edu> Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
519 lines
22 KiB
Plaintext
519 lines
22 KiB
Plaintext
Power Management for USB
|
|
|
|
Alan Stern <stern@rowland.harvard.edu>
|
|
|
|
October 28, 2010
|
|
|
|
|
|
|
|
What is Power Management?
|
|
-------------------------
|
|
|
|
Power Management (PM) is the practice of saving energy by suspending
|
|
parts of a computer system when they aren't being used. While a
|
|
component is "suspended" it is in a nonfunctional low-power state; it
|
|
might even be turned off completely. A suspended component can be
|
|
"resumed" (returned to a functional full-power state) when the kernel
|
|
needs to use it. (There also are forms of PM in which components are
|
|
placed in a less functional but still usable state instead of being
|
|
suspended; an example would be reducing the CPU's clock rate. This
|
|
document will not discuss those other forms.)
|
|
|
|
When the parts being suspended include the CPU and most of the rest of
|
|
the system, we speak of it as a "system suspend". When a particular
|
|
device is turned off while the system as a whole remains running, we
|
|
call it a "dynamic suspend" (also known as a "runtime suspend" or
|
|
"selective suspend"). This document concentrates mostly on how
|
|
dynamic PM is implemented in the USB subsystem, although system PM is
|
|
covered to some extent (see Documentation/power/*.txt for more
|
|
information about system PM).
|
|
|
|
Note: Dynamic PM support for USB is present only if the kernel was
|
|
built with CONFIG_USB_SUSPEND enabled (which depends on
|
|
CONFIG_PM_RUNTIME). System PM support is present only if the kernel
|
|
was built with CONFIG_SUSPEND or CONFIG_HIBERNATION enabled.
|
|
|
|
(Starting with the 3.10 kernel release, dynamic PM support for USB is
|
|
present whenever the kernel was built with CONFIG_PM_RUNTIME enabled.
|
|
The CONFIG_USB_SUSPEND option has been eliminated.)
|
|
|
|
|
|
What is Remote Wakeup?
|
|
----------------------
|
|
|
|
When a device has been suspended, it generally doesn't resume until
|
|
the computer tells it to. Likewise, if the entire computer has been
|
|
suspended, it generally doesn't resume until the user tells it to, say
|
|
by pressing a power button or opening the cover.
|
|
|
|
However some devices have the capability of resuming by themselves, or
|
|
asking the kernel to resume them, or even telling the entire computer
|
|
to resume. This capability goes by several names such as "Wake On
|
|
LAN"; we will refer to it generically as "remote wakeup". When a
|
|
device is enabled for remote wakeup and it is suspended, it may resume
|
|
itself (or send a request to be resumed) in response to some external
|
|
event. Examples include a suspended keyboard resuming when a key is
|
|
pressed, or a suspended USB hub resuming when a device is plugged in.
|
|
|
|
|
|
When is a USB device idle?
|
|
--------------------------
|
|
|
|
A device is idle whenever the kernel thinks it's not busy doing
|
|
anything important and thus is a candidate for being suspended. The
|
|
exact definition depends on the device's driver; drivers are allowed
|
|
to declare that a device isn't idle even when there's no actual
|
|
communication taking place. (For example, a hub isn't considered idle
|
|
unless all the devices plugged into that hub are already suspended.)
|
|
In addition, a device isn't considered idle so long as a program keeps
|
|
its usbfs file open, whether or not any I/O is going on.
|
|
|
|
If a USB device has no driver, its usbfs file isn't open, and it isn't
|
|
being accessed through sysfs, then it definitely is idle.
|
|
|
|
|
|
Forms of dynamic PM
|
|
-------------------
|
|
|
|
Dynamic suspends occur when the kernel decides to suspend an idle
|
|
device. This is called "autosuspend" for short. In general, a device
|
|
won't be autosuspended unless it has been idle for some minimum period
|
|
of time, the so-called idle-delay time.
|
|
|
|
Of course, nothing the kernel does on its own initiative should
|
|
prevent the computer or its devices from working properly. If a
|
|
device has been autosuspended and a program tries to use it, the
|
|
kernel will automatically resume the device (autoresume). For the
|
|
same reason, an autosuspended device will usually have remote wakeup
|
|
enabled, if the device supports remote wakeup.
|
|
|
|
It is worth mentioning that many USB drivers don't support
|
|
autosuspend. In fact, at the time of this writing (Linux 2.6.23) the
|
|
only drivers which do support it are the hub driver, kaweth, asix,
|
|
usblp, usblcd, and usb-skeleton (which doesn't count). If a
|
|
non-supporting driver is bound to a device, the device won't be
|
|
autosuspended. In effect, the kernel pretends the device is never
|
|
idle.
|
|
|
|
We can categorize power management events in two broad classes:
|
|
external and internal. External events are those triggered by some
|
|
agent outside the USB stack: system suspend/resume (triggered by
|
|
userspace), manual dynamic resume (also triggered by userspace), and
|
|
remote wakeup (triggered by the device). Internal events are those
|
|
triggered within the USB stack: autosuspend and autoresume. Note that
|
|
all dynamic suspend events are internal; external agents are not
|
|
allowed to issue dynamic suspends.
|
|
|
|
|
|
The user interface for dynamic PM
|
|
---------------------------------
|
|
|
|
The user interface for controlling dynamic PM is located in the power/
|
|
subdirectory of each USB device's sysfs directory, that is, in
|
|
/sys/bus/usb/devices/.../power/ where "..." is the device's ID. The
|
|
relevant attribute files are: wakeup, control, and
|
|
autosuspend_delay_ms. (There may also be a file named "level"; this
|
|
file was deprecated as of the 2.6.35 kernel and replaced by the
|
|
"control" file. In 2.6.38 the "autosuspend" file will be deprecated
|
|
and replaced by the "autosuspend_delay_ms" file. The only difference
|
|
is that the newer file expresses the delay in milliseconds whereas the
|
|
older file uses seconds. Confusingly, both files are present in 2.6.37
|
|
but only "autosuspend" works.)
|
|
|
|
power/wakeup
|
|
|
|
This file is empty if the device does not support
|
|
remote wakeup. Otherwise the file contains either the
|
|
word "enabled" or the word "disabled", and you can
|
|
write those words to the file. The setting determines
|
|
whether or not remote wakeup will be enabled when the
|
|
device is next suspended. (If the setting is changed
|
|
while the device is suspended, the change won't take
|
|
effect until the following suspend.)
|
|
|
|
power/control
|
|
|
|
This file contains one of two words: "on" or "auto".
|
|
You can write those words to the file to change the
|
|
device's setting.
|
|
|
|
"on" means that the device should be resumed and
|
|
autosuspend is not allowed. (Of course, system
|
|
suspends are still allowed.)
|
|
|
|
"auto" is the normal state in which the kernel is
|
|
allowed to autosuspend and autoresume the device.
|
|
|
|
(In kernels up to 2.6.32, you could also specify
|
|
"suspend", meaning that the device should remain
|
|
suspended and autoresume was not allowed. This
|
|
setting is no longer supported.)
|
|
|
|
power/autosuspend_delay_ms
|
|
|
|
This file contains an integer value, which is the
|
|
number of milliseconds the device should remain idle
|
|
before the kernel will autosuspend it (the idle-delay
|
|
time). The default is 2000. 0 means to autosuspend
|
|
as soon as the device becomes idle, and negative
|
|
values mean never to autosuspend. You can write a
|
|
number to the file to change the autosuspend
|
|
idle-delay time.
|
|
|
|
Writing "-1" to power/autosuspend_delay_ms and writing "on" to
|
|
power/control do essentially the same thing -- they both prevent the
|
|
device from being autosuspended. Yes, this is a redundancy in the
|
|
API.
|
|
|
|
(In 2.6.21 writing "0" to power/autosuspend would prevent the device
|
|
from being autosuspended; the behavior was changed in 2.6.22. The
|
|
power/autosuspend attribute did not exist prior to 2.6.21, and the
|
|
power/level attribute did not exist prior to 2.6.22. power/control
|
|
was added in 2.6.34, and power/autosuspend_delay_ms was added in
|
|
2.6.37 but did not become functional until 2.6.38.)
|
|
|
|
|
|
Changing the default idle-delay time
|
|
------------------------------------
|
|
|
|
The default autosuspend idle-delay time (in seconds) is controlled by
|
|
a module parameter in usbcore. You can specify the value when usbcore
|
|
is loaded. For example, to set it to 5 seconds instead of 2 you would
|
|
do:
|
|
|
|
modprobe usbcore autosuspend=5
|
|
|
|
Equivalently, you could add to a configuration file in /etc/modprobe.d
|
|
a line saying:
|
|
|
|
options usbcore autosuspend=5
|
|
|
|
Some distributions load the usbcore module very early during the boot
|
|
process, by means of a program or script running from an initramfs
|
|
image. To alter the parameter value you would have to rebuild that
|
|
image.
|
|
|
|
If usbcore is compiled into the kernel rather than built as a loadable
|
|
module, you can add
|
|
|
|
usbcore.autosuspend=5
|
|
|
|
to the kernel's boot command line.
|
|
|
|
Finally, the parameter value can be changed while the system is
|
|
running. If you do:
|
|
|
|
echo 5 >/sys/module/usbcore/parameters/autosuspend
|
|
|
|
then each new USB device will have its autosuspend idle-delay
|
|
initialized to 5. (The idle-delay values for already existing devices
|
|
will not be affected.)
|
|
|
|
Setting the initial default idle-delay to -1 will prevent any
|
|
autosuspend of any USB device. This has the benefit of allowing you
|
|
then to enable autosuspend for selected devices.
|
|
|
|
|
|
Warnings
|
|
--------
|
|
|
|
The USB specification states that all USB devices must support power
|
|
management. Nevertheless, the sad fact is that many devices do not
|
|
support it very well. You can suspend them all right, but when you
|
|
try to resume them they disconnect themselves from the USB bus or
|
|
they stop working entirely. This seems to be especially prevalent
|
|
among printers and scanners, but plenty of other types of device have
|
|
the same deficiency.
|
|
|
|
For this reason, by default the kernel disables autosuspend (the
|
|
power/control attribute is initialized to "on") for all devices other
|
|
than hubs. Hubs, at least, appear to be reasonably well-behaved in
|
|
this regard.
|
|
|
|
(In 2.6.21 and 2.6.22 this wasn't the case. Autosuspend was enabled
|
|
by default for almost all USB devices. A number of people experienced
|
|
problems as a result.)
|
|
|
|
This means that non-hub devices won't be autosuspended unless the user
|
|
or a program explicitly enables it. As of this writing there aren't
|
|
any widespread programs which will do this; we hope that in the near
|
|
future device managers such as HAL will take on this added
|
|
responsibility. In the meantime you can always carry out the
|
|
necessary operations by hand or add them to a udev script. You can
|
|
also change the idle-delay time; 2 seconds is not the best choice for
|
|
every device.
|
|
|
|
If a driver knows that its device has proper suspend/resume support,
|
|
it can enable autosuspend all by itself. For example, the video
|
|
driver for a laptop's webcam might do this (in recent kernels they
|
|
do), since these devices are rarely used and so should normally be
|
|
autosuspended.
|
|
|
|
Sometimes it turns out that even when a device does work okay with
|
|
autosuspend there are still problems. For example, the usbhid driver,
|
|
which manages keyboards and mice, has autosuspend support. Tests with
|
|
a number of keyboards show that typing on a suspended keyboard, while
|
|
causing the keyboard to do a remote wakeup all right, will nonetheless
|
|
frequently result in lost keystrokes. Tests with mice show that some
|
|
of them will issue a remote-wakeup request in response to button
|
|
presses but not to motion, and some in response to neither.
|
|
|
|
The kernel will not prevent you from enabling autosuspend on devices
|
|
that can't handle it. It is even possible in theory to damage a
|
|
device by suspending it at the wrong time. (Highly unlikely, but
|
|
possible.) Take care.
|
|
|
|
|
|
The driver interface for Power Management
|
|
-----------------------------------------
|
|
|
|
The requirements for a USB driver to support external power management
|
|
are pretty modest; the driver need only define
|
|
|
|
.suspend
|
|
.resume
|
|
.reset_resume
|
|
|
|
methods in its usb_driver structure, and the reset_resume method is
|
|
optional. The methods' jobs are quite simple:
|
|
|
|
The suspend method is called to warn the driver that the
|
|
device is going to be suspended. If the driver returns a
|
|
negative error code, the suspend will be aborted. Normally
|
|
the driver will return 0, in which case it must cancel all
|
|
outstanding URBs (usb_kill_urb()) and not submit any more.
|
|
|
|
The resume method is called to tell the driver that the
|
|
device has been resumed and the driver can return to normal
|
|
operation. URBs may once more be submitted.
|
|
|
|
The reset_resume method is called to tell the driver that
|
|
the device has been resumed and it also has been reset.
|
|
The driver should redo any necessary device initialization,
|
|
since the device has probably lost most or all of its state
|
|
(although the interfaces will be in the same altsettings as
|
|
before the suspend).
|
|
|
|
If the device is disconnected or powered down while it is suspended,
|
|
the disconnect method will be called instead of the resume or
|
|
reset_resume method. This is also quite likely to happen when
|
|
waking up from hibernation, as many systems do not maintain suspend
|
|
current to the USB host controllers during hibernation. (It's
|
|
possible to work around the hibernation-forces-disconnect problem by
|
|
using the USB Persist facility.)
|
|
|
|
The reset_resume method is used by the USB Persist facility (see
|
|
Documentation/usb/persist.txt) and it can also be used under certain
|
|
circumstances when CONFIG_USB_PERSIST is not enabled. Currently, if a
|
|
device is reset during a resume and the driver does not have a
|
|
reset_resume method, the driver won't receive any notification about
|
|
the resume. Later kernels will call the driver's disconnect method;
|
|
2.6.23 doesn't do this.
|
|
|
|
USB drivers are bound to interfaces, so their suspend and resume
|
|
methods get called when the interfaces are suspended or resumed. In
|
|
principle one might want to suspend some interfaces on a device (i.e.,
|
|
force the drivers for those interface to stop all activity) without
|
|
suspending the other interfaces. The USB core doesn't allow this; all
|
|
interfaces are suspended when the device itself is suspended and all
|
|
interfaces are resumed when the device is resumed. It isn't possible
|
|
to suspend or resume some but not all of a device's interfaces. The
|
|
closest you can come is to unbind the interfaces' drivers.
|
|
|
|
|
|
The driver interface for autosuspend and autoresume
|
|
---------------------------------------------------
|
|
|
|
To support autosuspend and autoresume, a driver should implement all
|
|
three of the methods listed above. In addition, a driver indicates
|
|
that it supports autosuspend by setting the .supports_autosuspend flag
|
|
in its usb_driver structure. It is then responsible for informing the
|
|
USB core whenever one of its interfaces becomes busy or idle. The
|
|
driver does so by calling these six functions:
|
|
|
|
int usb_autopm_get_interface(struct usb_interface *intf);
|
|
void usb_autopm_put_interface(struct usb_interface *intf);
|
|
int usb_autopm_get_interface_async(struct usb_interface *intf);
|
|
void usb_autopm_put_interface_async(struct usb_interface *intf);
|
|
void usb_autopm_get_interface_no_resume(struct usb_interface *intf);
|
|
void usb_autopm_put_interface_no_suspend(struct usb_interface *intf);
|
|
|
|
The functions work by maintaining a usage counter in the
|
|
usb_interface's embedded device structure. When the counter is > 0
|
|
then the interface is deemed to be busy, and the kernel will not
|
|
autosuspend the interface's device. When the usage counter is = 0
|
|
then the interface is considered to be idle, and the kernel may
|
|
autosuspend the device.
|
|
|
|
Drivers need not be concerned about balancing changes to the usage
|
|
counter; the USB core will undo any remaining "get"s when a driver
|
|
is unbound from its interface. As a corollary, drivers must not call
|
|
any of the usb_autopm_* functions after their disconnect() routine has
|
|
returned.
|
|
|
|
Drivers using the async routines are responsible for their own
|
|
synchronization and mutual exclusion.
|
|
|
|
usb_autopm_get_interface() increments the usage counter and
|
|
does an autoresume if the device is suspended. If the
|
|
autoresume fails, the counter is decremented back.
|
|
|
|
usb_autopm_put_interface() decrements the usage counter and
|
|
attempts an autosuspend if the new value is = 0.
|
|
|
|
usb_autopm_get_interface_async() and
|
|
usb_autopm_put_interface_async() do almost the same things as
|
|
their non-async counterparts. The big difference is that they
|
|
use a workqueue to do the resume or suspend part of their
|
|
jobs. As a result they can be called in an atomic context,
|
|
such as an URB's completion handler, but when they return the
|
|
device will generally not yet be in the desired state.
|
|
|
|
usb_autopm_get_interface_no_resume() and
|
|
usb_autopm_put_interface_no_suspend() merely increment or
|
|
decrement the usage counter; they do not attempt to carry out
|
|
an autoresume or an autosuspend. Hence they can be called in
|
|
an atomic context.
|
|
|
|
The simplest usage pattern is that a driver calls
|
|
usb_autopm_get_interface() in its open routine and
|
|
usb_autopm_put_interface() in its close or release routine. But other
|
|
patterns are possible.
|
|
|
|
The autosuspend attempts mentioned above will often fail for one
|
|
reason or another. For example, the power/control attribute might be
|
|
set to "on", or another interface in the same device might not be
|
|
idle. This is perfectly normal. If the reason for failure was that
|
|
the device hasn't been idle for long enough, a timer is scheduled to
|
|
carry out the operation automatically when the autosuspend idle-delay
|
|
has expired.
|
|
|
|
Autoresume attempts also can fail, although failure would mean that
|
|
the device is no longer present or operating properly. Unlike
|
|
autosuspend, there's no idle-delay for an autoresume.
|
|
|
|
|
|
Other parts of the driver interface
|
|
-----------------------------------
|
|
|
|
Drivers can enable autosuspend for their devices by calling
|
|
|
|
usb_enable_autosuspend(struct usb_device *udev);
|
|
|
|
in their probe() routine, if they know that the device is capable of
|
|
suspending and resuming correctly. This is exactly equivalent to
|
|
writing "auto" to the device's power/control attribute. Likewise,
|
|
drivers can disable autosuspend by calling
|
|
|
|
usb_disable_autosuspend(struct usb_device *udev);
|
|
|
|
This is exactly the same as writing "on" to the power/control attribute.
|
|
|
|
Sometimes a driver needs to make sure that remote wakeup is enabled
|
|
during autosuspend. For example, there's not much point
|
|
autosuspending a keyboard if the user can't cause the keyboard to do a
|
|
remote wakeup by typing on it. If the driver sets
|
|
intf->needs_remote_wakeup to 1, the kernel won't autosuspend the
|
|
device if remote wakeup isn't available. (If the device is already
|
|
autosuspended, though, setting this flag won't cause the kernel to
|
|
autoresume it. Normally a driver would set this flag in its probe
|
|
method, at which time the device is guaranteed not to be
|
|
autosuspended.)
|
|
|
|
If a driver does its I/O asynchronously in interrupt context, it
|
|
should call usb_autopm_get_interface_async() before starting output and
|
|
usb_autopm_put_interface_async() when the output queue drains. When
|
|
it receives an input event, it should call
|
|
|
|
usb_mark_last_busy(struct usb_device *udev);
|
|
|
|
in the event handler. This tells the PM core that the device was just
|
|
busy and therefore the next autosuspend idle-delay expiration should
|
|
be pushed back. Many of the usb_autopm_* routines also make this call,
|
|
so drivers need to worry only when interrupt-driven input arrives.
|
|
|
|
Asynchronous operation is always subject to races. For example, a
|
|
driver may call the usb_autopm_get_interface_async() routine at a time
|
|
when the core has just finished deciding the device has been idle for
|
|
long enough but not yet gotten around to calling the driver's suspend
|
|
method. The suspend method must be responsible for synchronizing with
|
|
the I/O request routine and the URB completion handler; it should
|
|
cause autosuspends to fail with -EBUSY if the driver needs to use the
|
|
device.
|
|
|
|
External suspend calls should never be allowed to fail in this way,
|
|
only autosuspend calls. The driver can tell them apart by applying
|
|
the PMSG_IS_AUTO() macro to the message argument to the suspend
|
|
method; it will return True for internal PM events (autosuspend) and
|
|
False for external PM events.
|
|
|
|
|
|
Mutual exclusion
|
|
----------------
|
|
|
|
For external events -- but not necessarily for autosuspend or
|
|
autoresume -- the device semaphore (udev->dev.sem) will be held when a
|
|
suspend or resume method is called. This implies that external
|
|
suspend/resume events are mutually exclusive with calls to probe,
|
|
disconnect, pre_reset, and post_reset; the USB core guarantees that
|
|
this is true of autosuspend/autoresume events as well.
|
|
|
|
If a driver wants to block all suspend/resume calls during some
|
|
critical section, the best way is to lock the device and call
|
|
usb_autopm_get_interface() (and do the reverse at the end of the
|
|
critical section). Holding the device semaphore will block all
|
|
external PM calls, and the usb_autopm_get_interface() will prevent any
|
|
internal PM calls, even if it fails. (Exercise: Why?)
|
|
|
|
|
|
Interaction between dynamic PM and system PM
|
|
--------------------------------------------
|
|
|
|
Dynamic power management and system power management can interact in
|
|
a couple of ways.
|
|
|
|
Firstly, a device may already be autosuspended when a system suspend
|
|
occurs. Since system suspends are supposed to be as transparent as
|
|
possible, the device should remain suspended following the system
|
|
resume. But this theory may not work out well in practice; over time
|
|
the kernel's behavior in this regard has changed. As of 2.6.37 the
|
|
policy is to resume all devices during a system resume and let them
|
|
handle their own runtime suspends afterward.
|
|
|
|
Secondly, a dynamic power-management event may occur as a system
|
|
suspend is underway. The window for this is short, since system
|
|
suspends don't take long (a few seconds usually), but it can happen.
|
|
For example, a suspended device may send a remote-wakeup signal while
|
|
the system is suspending. The remote wakeup may succeed, which would
|
|
cause the system suspend to abort. If the remote wakeup doesn't
|
|
succeed, it may still remain active and thus cause the system to
|
|
resume as soon as the system suspend is complete. Or the remote
|
|
wakeup may fail and get lost. Which outcome occurs depends on timing
|
|
and on the hardware and firmware design.
|
|
|
|
|
|
xHCI hardware link PM
|
|
---------------------
|
|
|
|
xHCI host controller provides hardware link power management to usb2.0
|
|
(xHCI 1.0 feature) and usb3.0 devices which support link PM. By
|
|
enabling hardware LPM, the host can automatically put the device into
|
|
lower power state(L1 for usb2.0 devices, or U1/U2 for usb3.0 devices),
|
|
which state device can enter and resume very quickly.
|
|
|
|
The user interface for controlling USB2 hardware LPM is located in the
|
|
power/ subdirectory of each USB device's sysfs directory, that is, in
|
|
/sys/bus/usb/devices/.../power/ where "..." is the device's ID. The
|
|
relevant attribute files is usb2_hardware_lpm.
|
|
|
|
power/usb2_hardware_lpm
|
|
|
|
When a USB2 device which support LPM is plugged to a
|
|
xHCI host root hub which support software LPM, the
|
|
host will run a software LPM test for it; if the device
|
|
enters L1 state and resume successfully and the host
|
|
supports USB2 hardware LPM, this file will show up and
|
|
driver will enable hardware LPM for the device. You
|
|
can write y/Y/1 or n/N/0 to the file to enable/disable
|
|
USB2 hardware LPM manually. This is for test purpose mainly.
|