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