Lines Matching +full:keep +full:- +full:power +full:- +full:in +full:- +full:suspend
1 .. _usb-power-management:
3 Power Management for USB
7 :Date: Last-updated: February 2014
11 ---------
12 * What is Power Management?
17 * Changing the default idle-delay time
19 * The driver interface for Power Management
25 * USB Port Power Control
26 * User Interface for Port Power Control
27 * Suggested Userspace Port Power Policy
30 What is Power Management?
31 -------------------------
33 Power Management (PM) is the practice of saving energy by suspending
35 component is ``suspended`` it is in a nonfunctional low-power state; it
37 ``resumed`` (returned to a functional full-power state) when the kernel
38 needs to use it. (There also are forms of PM in which components are
39 placed in a less functional but still usable state instead of being
44 the system, we speak of it as a "system suspend". When a particular
46 call it a "dynamic suspend" (also known as a "runtime suspend" or
47 "selective suspend"). This document concentrates mostly on how
48 dynamic PM is implemented in the USB subsystem, although system PM is
49 covered to some extent (see ``Documentation/power/*.rst`` for more
67 ----------------------
72 by pressing a power button or opening the cover.
79 itself (or send a request to be resumed) in response to some external
81 pressed, or a suspended USB hub resuming when a device is plugged in.
85 --------------------------
93 In addition, a device isn't considered idle so long as a program keeps
101 -------------------
103 Dynamic suspends occur when the kernel decides to suspend an idle
104 device. This is called ``autosuspend`` for short. In general, a device
106 of time, the so-called idle-delay time.
116 autosuspend. In fact, at the time of this writing (Linux 2.6.23) the
118 usblp, usblcd, and usb-skeleton (which doesn't count). If a
119 non-supporting driver is bound to a device, the device won't be
120 autosuspended. In effect, the kernel pretends the device is never
123 We can categorize power management events in two broad classes:
125 agent outside the USB stack: system suspend/resume (triggered by
129 all dynamic suspend events are internal; external agents are not
134 ---------------------------------
136 The user interface for controlling dynamic PM is located in the ``power/``
137 subdirectory of each USB device's sysfs directory, that is, in
138 ``/sys/bus/usb/devices/.../power/`` where "..." is the device's ID. The
142 ``control`` file. In 2.6.38 the ``autosuspend`` file will be deprecated
144 is that the newer file expresses the delay in milliseconds whereas the
145 older file uses seconds. Confusingly, both files are present in 2.6.37
148 ``power/wakeup``
157 effect until the following suspend.)
159 ``power/control``
165 - ``on`` means that the device should be resumed and
169 - ``auto`` is the normal state in which the kernel is
172 (In kernels up to 2.6.32, you could also specify
173 ``suspend``, meaning that the device should remain
177 ``power/autosuspend_delay_ms``
181 before the kernel will autosuspend it (the idle-delay
186 idle-delay time.
188 Writing ``-1`` to ``power/autosuspend_delay_ms`` and writing ``on`` to
189 ``power/control`` do essentially the same thing -- they both prevent the
190 device from being autosuspended. Yes, this is a redundancy in the
193 (In 2.6.21 writing ``0`` to ``power/autosuspend`` would prevent the device
194 from being autosuspended; the behavior was changed in 2.6.22. The
195 ``power/autosuspend`` attribute did not exist prior to 2.6.21, and the
196 ``power/level`` attribute did not exist prior to 2.6.22. ``power/control``
197 was added in 2.6.34, and ``power/autosuspend_delay_ms`` was added in
201 Changing the default idle-delay time
202 ------------------------------------
204 The default autosuspend idle-delay time (in seconds) is controlled by
205 a module parameter in usbcore. You can specify the value when usbcore
211 Equivalently, you could add to a configuration file in /etc/modprobe.d
233 then each new USB device will have its autosuspend idle-delay
234 initialized to 5. (The idle-delay values for already existing devices
237 Setting the initial default idle-delay to -1 will prevent any
243 --------
245 The USB specification states that all USB devices must support power
247 support it very well. You can suspend them all right, but when you
254 ``power/control`` attribute is initialized to ``on``) for all devices other
255 than hubs. Hubs, at least, appear to be reasonably well-behaved in
258 (In 2.6.21 and 2.6.22 this wasn't the case. Autosuspend was enabled
262 This means that non-hub devices won't be autosuspended unless the user
264 any widespread programs which will do this; we hope that in the near
266 responsibility. In the meantime you can always carry out the
268 also change the idle-delay time; 2 seconds is not the best choice for
271 If a driver knows that its device has proper suspend/resume support,
273 driver for a laptop's webcam might do this (in recent kernels they
282 frequently result in lost keystrokes. Tests with mice show that some
283 of them will issue a remote-wakeup request in response to button
284 presses but not to motion, and some in response to neither.
287 that can't handle it. It is even possible in theory to damage a
292 The driver interface for Power Management
293 -----------------------------------------
295 The requirements for a USB driver to support external power management
298 .suspend
302 methods in its :c:type:`usb_driver` structure, and the ``reset_resume`` method
305 - The ``suspend`` method is called to warn the driver that the
307 negative error code, the suspend will be aborted. Normally
308 the driver will return 0, in which case it must cancel all
311 - The ``resume`` method is called to tell the driver that the
315 - The ``reset_resume`` method is called to tell the driver that
319 (although the interfaces will be in the same altsettings as
320 before the suspend).
325 waking up from hibernation, as many systems do not maintain suspend
327 possible to work around the hibernation-forces-disconnect problem by
331 :ref:`usb-persist`) and it can also be used under certain
338 USB drivers are bound to interfaces, so their ``suspend`` and ``resume``
339 methods get called when the interfaces are suspended or resumed. In
340 principle one might want to suspend some interfaces on a device (i.e.,
345 to suspend or resume some but not all of a device's interfaces. The
350 ---------------------------------------------------
353 three of the methods listed above. In addition, a driver indicates
355 in its usb_driver structure. It is then responsible for informing the
366 The functions work by maintaining a usage counter in the
374 counter. Unbalanced "get"s will remain in effect when a driver is
376 runtime suspend should the interface be bound to a driver again. On
379 has returned -- say from within a work-queue routine -- provided they
395 their non-async counterparts. The big difference is that they
396 use a workqueue to do the resume or suspend part of their
397 jobs. As a result they can be called in an atomic context,
399 device will generally not yet be in the desired state.
404 an autoresume or an autosuspend. Hence they can be called in
408 :c:func:`usb_autopm_get_interface` in its open routine and
409 :c:func:`usb_autopm_put_interface` in its close or release routine. But other
413 reason or another. For example, the ``power/control`` attribute might be
414 set to ``on``, or another interface in the same device might not be
417 carry out the operation automatically when the autosuspend idle-delay
422 autosuspend, there's no idle-delay for an autoresume.
426 -----------------------------------
432 in their :c:func:`probe` routine, if they know that the device is capable of
434 writing ``auto`` to the device's ``power/control`` attribute. Likewise,
439 This is exactly the same as writing ``on`` to the ``power/control`` attribute.
445 ``intf->needs_remote_wakeup`` to 1, the kernel won't autosuspend the
448 autoresume it. Normally a driver would set this flag in its ``probe``
452 If a driver does its I/O asynchronously in interrupt context, it
459 in the event handler. This tells the PM core that the device was just
460 busy and therefore the next autosuspend idle-delay expiration should
462 so drivers need to worry only when interrupt-driven input arrives.
467 long enough but not yet gotten around to calling the driver's ``suspend``
468 method. The ``suspend`` method must be responsible for synchronizing with
470 cause autosuspends to fail with -EBUSY if the driver needs to use the
473 External suspend calls should never be allowed to fail in this way,
475 the :c:func:`PMSG_IS_AUTO` macro to the message argument to the ``suspend``
481 ----------------
483 For external events -- but not necessarily for autosuspend or
484 autoresume -- the device semaphore (udev->dev.sem) will be held when a
485 ``suspend`` or ``resume`` method is called. This implies that external
486 suspend/resume events are mutually exclusive with calls to ``probe``,
490 If a driver wants to block all suspend/resume calls during some
499 --------------------------------------------
501 Dynamic power management and system power management can interact in
504 Firstly, a device may already be autosuspended when a system suspend
507 resume. But this theory may not work out well in practice; over time
508 the kernel's behavior in this regard has changed. As of 2.6.37 the
512 Secondly, a dynamic power-management event may occur as a system
513 suspend is underway. The window for this is short, since system
515 For example, a suspended device may send a remote-wakeup signal while
517 cause the system suspend to abort. If the remote wakeup doesn't
519 resume as soon as the system suspend is complete. Or the remote
525 ---------------------
527 xHCI host controller provides hardware link power management to usb2.0
530 lower power state(L1 for usb2.0 devices, or U1/U2 for usb3.0 devices),
533 The user interface for controlling hardware LPM is located in the
534 ``power/`` subdirectory of each USB device's sysfs directory, that is, in
535 ``/sys/bus/usb/devices/.../power/`` where "..." is the device's ID. The
538 ``power/usb2_hardware_lpm``
549 ``power/usb3_hardware_lpm_u1``
550 ``power/usb3_hardware_lpm_u2``
552 When a USB 3.0 lpm-capable device is plugged in to a
554 and U2 exit latencies have been set in the BOS
562 USB Port Power Control
563 ----------------------
565 In addition to suspending endpoint devices and enabling hardware
566 controlled link power management, the USB subsystem also has the
567 capability to disable power to ports under some conditions. Power is
569 In the case of a root or platform-internal hub the host controller
571 method calls to set the port power state. For more background see the
576 VBUS may be maintained in the case where a hub gangs multiple ports into
577 a shared power well causing power to remain until all ports in the gang
579 a charging application. In any event a logically off port will lose
585 turning off a port may result in the inability to hot add a device.
586 Please see "User Interface for Port Power Control" for details.
589 goes through during system suspend, i.e. the power session is lost. Any
590 USB device or driver that misbehaves with system suspend will be
591 similarly affected by a port power cycle event. For this reason the
597 http://dl.dropbox.com/u/96820575/sarah-sharp-lpt-port-power-off2-mini.pdf
601 http://linuxplumbers.ubicast.tv/videos/usb-port-power-off-kerneluserspace-api/
608 power control implementation will block poweroff attempts on that
612 User Interface for Port Power Control
613 -------------------------------------
615 The port power control mechanism uses the PM runtime system. Poweroff is
616 requested by clearing the ``power/pm_qos_no_power_off`` flag of the port device
620 suspended. This mechanism is dependent on the hub advertising port power
621 switching in its hub descriptor (wHubCharacteristics logical power switching
626 suspend. An unbound interface device is suspended by default. When unbinding,
631 lost and all attached child-devices will disconnect. A good rule of thumb is
633 ``/sys/module/usbcore`` then unbinding it will interfere with port power
636 Example of the relevant files for port power control. Note, in this example
639 prefix=/sys/devices/pci0000:00/0000:00:14.0/usb3/3-1
645 $prefix/3-1:1.0/3-1-port1/device
647 $prefix/3-1:1.0/3-1-port1/power/pm_qos_no_power_off
648 $prefix/3-1:1.0/3-1-port1/device/power/control
649 $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intf0>/driver/unbind
650 $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intf1>/driver/unbind
652 $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intfN>/driver/unbind
654 In addition to these files some ports may have a 'peer' link to a port on
656 hi-speed peer::
658 $prefix/3-1:1.0/3-1-port1/peer -> ../../../../usb2/2-1/2-1:1.0/2-1-port1
659 ../../../../usb2/2-1/2-1:1.0/2-1-port1/peer -> ../../../../usb3/3-1/3-1:1.0/3-1-port1
662 peer ports are simply the hi-speed and superspeed interface pins that
667 connection and attempt to connect to the hi-speed pins. The
670 1. Port suspend is sequenced to guarantee that hi-speed ports are powered-off
671 before their superspeed peer is permitted to power-off. The implication is
673 not cause the port to power-off until its highspeed peer has gone to its
674 runtime suspend state. Userspace must take care to order the suspensions
675 if it wants to guarantee that a superspeed port will power-off.
677 2. Port resume is sequenced to force a superspeed port to power-on prior to its
681 power session is lost the device may have been removed, or need reset.
682 Resuming the child device when the parent port regains power resolves those
683 states and clamps the maximum port power cycle frequency at the rate the
684 child device can suspend (autosuspend-delay) and resume (reset-resume
687 Sysfs files relevant for port power control:
689 ``<hubdev-portX>/power/pm_qos_no_power_off``:
692 port may suspend/poweroff provided that
697 ``<hubdev-portX>/power/runtime_status``:
698 This file reflects whether the port is 'active' (power is on)
702 ``<hubdev-portX>/connect_type``:
703 An advisory read-only flag to userspace indicating the
711 to keep such a port powered to handle new device
718 expected to be safe to allow these ports to suspend
729 powered-off at all times.
738 - since we are relying on the BIOS to get this ACPI
742 - Take care in clearing ``pm_qos_no_power_off``. Once
743 power is off this port will
749 ``<child>/power/control``:
751 power down until ``<child>/power/runtime_status``
755 ``<child>/power/persist``:
758 power session loss (suspend / port-power event). When
764 this time the only mechanism to clear the usb-internal
765 wakeup-capability for an interface device is to unbind
768 Summary of poweroff pre-requisite settings relative to a port device::
770 echo 0 > power/pm_qos_no_power_off
771 echo 0 > peer/power/pm_qos_no_power_off # if it exists
772 echo auto > power/control # this is the default value
773 echo auto > <child>/power/control
774 echo 1 > <child>/power/persist # this is the default value
776 Suggested Userspace Port Power Policy
777 -------------------------------------
783 ``power/pm_qos_no_power_off`` set to ``1`` causing ports to always remain
786 Given confidence in the platform firmware's description of the ports
792 A more aggressive userspace policy is to enable USB port power off for
793 all ports (set ``<hubdev-portX>/power/pm_qos_no_power_off`` to ``0``) when
795 system. For example, a distro may want to enable power off all USB
796 ports when the screen blanks, and re-power them when the screen becomes
797 active. Smart phones and tablets may want to power off USB ports when
798 the user pushes the power button.