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