Lines Matching +full:suspend +full:- +full:to +full:- +full:idle
1 .. _usb-power-management:
7 :Date: Last-updated: February 2014
11 ---------
14 * When is a USB device idle?
17 * Changing the default idle-delay time
31 -------------------------
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
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
49 covered to some extent (see ``Documentation/power/*.rst`` for more
67 ----------------------
70 the computer tells it to. Likewise, if the entire computer has been
71 suspended, it generally doesn't resume until the user tells it to, say
75 asking the kernel to resume them, or even telling the entire computer
76 to resume. This capability goes by several names such as "Wake On
77 LAN"; we will refer to it generically as "remote wakeup". When a
79 itself (or send a request to be resumed) in response to some external
84 When is a USB device idle?
85 --------------------------
87 A device is idle whenever the kernel thinks it's not busy doing
90 to declare that a device isn't idle even when there's no actual
91 communication taking place. (For example, a hub isn't considered idle
93 In addition, a device isn't considered idle so long as a program keeps
97 being accessed through sysfs, then it definitely is idle.
101 -------------------
103 Dynamic suspends occur when the kernel decides to suspend an idle
105 won't be autosuspended unless it has been idle for some minimum period
106 of time, the so-called idle-delay time.
110 device has been autosuspended and a program tries to use it, 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
121 idle.
125 agent outside the USB stack: system suspend/resume (triggered by
129 all dynamic suspend events are internal; external agents are not
130 allowed to issue dynamic suspends.
134 ---------------------------------
153 write those words to the file. The setting determines
157 effect until the following suspend.)
162 You can write those words to the file to change the
165 - ``on`` means that the device should be resumed and
169 - ``auto`` is the normal state in which the kernel is
170 allowed to autosuspend and autoresume the device.
172 (In kernels up to 2.6.32, you could also specify
173 ``suspend``, meaning that the device should remain
180 number of milliseconds the device should remain idle
181 before the kernel will autosuspend it (the idle-delay
182 time). The default is 2000. 0 means to autosuspend
183 as soon as the device becomes idle, and negative
184 values mean never to autosuspend. You can write a
185 number to the file to change the autosuspend
186 idle-delay time.
188 Writing ``-1`` to ``power/autosuspend_delay_ms`` and writing ``on`` to
189 ``power/control`` do essentially the same thing -- they both prevent the
193 (In 2.6.21 writing ``0`` to ``power/autosuspend`` would prevent the device
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``
201 Changing the default idle-delay time
202 ------------------------------------
204 The default autosuspend idle-delay time (in seconds) is controlled by
206 is loaded. For example, to set it to 5 seconds instead of 2 you would
211 Equivalently, you could add to a configuration file in /etc/modprobe.d
218 image. To alter the parameter value you would have to rebuild that
226 to the kernel's boot command line.
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
239 then to enable autosuspend for selected devices.
243 --------
247 support it very well. You can suspend them all right, but when you
248 try to resume them they disconnect themselves from the USB bus or
249 they stop working entirely. This seems to be especially prevalent
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
262 This means that non-hub devices won't be autosuspended unless the user
267 necessary operations by hand or add them to a udev script. You can
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,
281 causing the keyboard to do a remote wakeup all right, will nonetheless
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
293 -----------------------------------------
295 The requirements for a USB driver to support external power management
298 .suspend
305 - The ``suspend`` method is called to warn the driver that the
306 device is going to be suspended. If the driver returns a
307 negative error code, the suspend will be aborted. Normally
311 - The ``resume`` method is called to tell the driver that the
312 device has been resumed and the driver can return to normal
315 - The ``reset_resume`` method is called to tell the driver that
320 before the suspend).
324 ``reset_resume`` method. This is also quite likely to happen when
325 waking up from hibernation, as many systems do not maintain suspend
326 current to the USB host controllers during hibernation. (It's
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``
340 principle one might want to suspend some interfaces on a device (i.e.,
341 force the drivers for those interface to stop all activity) without
345 to suspend or resume some but not all of a device's interfaces. The
346 closest you can come is to unbind the interfaces' drivers.
350 ---------------------------------------------------
352 To support autosuspend and autoresume, a driver should implement all
356 USB core whenever one of its interfaces becomes busy or idle. The
368 then the interface is deemed to be busy, and the kernel will not
370 then the interface is considered to be idle, and the kernel may
373 Drivers must be careful to balance their overall changes to the usage
376 runtime suspend should the interface be bound to a driver again. On
377 the other hand, drivers are allowed to achieve this balance by calling
379 has returned -- say from within a work-queue routine -- provided they
380 retain an active reference to the interface (via ``usb_get_intf`` and
395 their non-async counterparts. The big difference is that they
396 use a workqueue to do the resume or suspend part of their
403 decrement the usage counter; they do not attempt to carry out
414 set to ``on``, or another interface in the same device might not be
415 idle. This is perfectly normal. If the reason for failure was that
416 the device hasn't been idle for long enough, a timer is scheduled to
417 carry out the operation automatically when the autosuspend idle-delay
422 autosuspend, there's no idle-delay for an autoresume.
426 -----------------------------------
433 suspending and resuming correctly. This is exactly equivalent to
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.
441 Sometimes a driver needs to make sure that remote wakeup is enabled
443 autosuspending a keyboard if the user can't cause the keyboard to do a
445 ``intf->needs_remote_wakeup`` to 1, the kernel won't autosuspend the
447 autosuspended, though, setting this flag won't cause the kernel to
449 method, at which time the device is guaranteed not to be
460 busy and therefore the next autosuspend idle-delay expiration should
462 so drivers need to worry only when interrupt-driven input arrives.
464 Asynchronous operation is always subject to races. For example, a
466 when the core has just finished deciding the device has been idle for
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
491 critical section, the best way is to lock the device and call
499 --------------------------------------------
504 Firstly, a device may already be autosuspended when a system suspend
505 occurs. Since system suspends are supposed to be as transparent as
509 policy is to resume all devices during a system resume and let them
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
518 succeed, it may still remain active and thus cause the system to
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
540 When a USB2 device which support LPM is plugged to a
546 can write y/Y/1 or n/N/0 to the file to enable/disable
552 When a USB 3.0 lpm-capable device is plugged in to a
563 ----------------------
565 In addition to suspending endpoint devices and enabling hardware
567 capability to disable power to ports under some conditions. Power is
568 controlled through ``Set/ClearPortFeature(PORT_POWER)`` requests to a hub.
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
575 logically off, and may trigger the actual loss of VBUS to the port [#f3]_.
577 a shared power well causing power to remain until all ports in the gang
580 connection with its device, not respond to hotplug events, and not
581 respond to remote wakeup events.
585 turning off a port may result in the inability to hot add a device.
588 As far as the effect on the device itself it is similar to what a device
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
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/
607 wakeup note: if a device is configured to send wakeup events the port
613 -------------------------------------
617 (defaults to 1). If the port is disconnected it will immediately receive a
619 runtime rules and require the attached child device and all descendants to be
625 need to unbind the interface drivers before the :c:type:`usb_device` will
626 suspend. An unbound interface device is suspended by default. When unbinding,
627 be careful to unbind interface drivers, not the driver of the parent usb
629 device (not interface) is unbound the kernel is no longer able to resume the
631 lost and all attached child-devices will disconnect. A good rule of thumb is
632 that if the 'driver/module' link for a device points to
637 these files are relative to a usb hub device (prefix)::
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
668 implementation takes steps to prevent this:
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
672 that the setting ``pm_qos_no_power_off`` to zero on a superspeed port may
673 not cause the port to power-off until its highspeed peer has gone to its
674 runtime suspend state. Userspace must take care to order the suspensions
675 if it wants to guarantee that a superspeed port will power-off.
677 2. Port resume is sequenced to force a superspeed port to power-on prior to its
680 3. Port resume always triggers an attached child device to resume. After a
684 child device can suspend (autosuspend-delay) and resume (reset-resume
689 ``<hubdev-portX>/power/pm_qos_no_power_off``:
690 This writable flag controls the state of an idle port.
692 port may suspend/poweroff provided that
695 the stats of descendants. Defaults to 1.
697 ``<hubdev-portX>/power/runtime_status``:
699 or 'suspended' (logically off). There is no indication to
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
714 ``hardwired`` refers to a port that is not visible but
718 expected to be safe to allow these ports to suspend
721 for the device to be connected prior to the port
722 powering off, or to activate the port prior to enabling
725 ``not used`` refers to an internal port that is expected
726 to never have a device connected to it. These may be
728 exposed on a platform. Considered safe to be
729 powered-off at all times.
732 information for this port. Most commonly refers to
738 - since we are relying on the BIOS to get this ACPI
742 - Take care in clearing ``pm_qos_no_power_off``. Once
744 not respond to new connect events.
747 applied before the port is allowed to poweroff.
756 This defaults to ``1`` for most devices and indicates if
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::
777 -------------------------------------
779 As noted above userspace needs to be careful and deliberate about what
783 ``power/pm_qos_no_power_off`` set to ``1`` causing ports to always remain
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