USB: deprecate the power/level sysfs attribute
[linux-2.6.git] / Documentation / usb / power-management.txt
1                         Power Management for USB
2
3                  Alan Stern <stern@rowland.harvard.edu>
4
5                             December 11, 2009
6
7
8
9         What is Power Management?
10         -------------------------
11
12 Power Management (PM) is the practice of saving energy by suspending
13 parts of a computer system when they aren't being used.  While a
14 component is "suspended" it is in a nonfunctional low-power state; it
15 might even be turned off completely.  A suspended component can be
16 "resumed" (returned to a functional full-power state) when the kernel
17 needs to use it.  (There also are forms of PM in which components are
18 placed in a less functional but still usable state instead of being
19 suspended; an example would be reducing the CPU's clock rate.  This
20 document will not discuss those other forms.)
21
22 When the parts being suspended include the CPU and most of the rest of
23 the system, we speak of it as a "system suspend".  When a particular
24 device is turned off while the system as a whole remains running, we
25 call it a "dynamic suspend" (also known as a "runtime suspend" or
26 "selective suspend").  This document concentrates mostly on how
27 dynamic PM is implemented in the USB subsystem, although system PM is
28 covered to some extent (see Documentation/power/*.txt for more
29 information about system PM).
30
31 Note: Dynamic PM support for USB is present only if the kernel was
32 built with CONFIG_USB_SUSPEND enabled (which depends on
33 CONFIG_PM_RUNTIME).  System PM support is present only if the kernel
34 was built with CONFIG_SUSPEND or CONFIG_HIBERNATION enabled.
35
36
37         What is Remote Wakeup?
38         ----------------------
39
40 When a device has been suspended, it generally doesn't resume until
41 the computer tells it to.  Likewise, if the entire computer has been
42 suspended, it generally doesn't resume until the user tells it to, say
43 by pressing a power button or opening the cover.
44
45 However some devices have the capability of resuming by themselves, or
46 asking the kernel to resume them, or even telling the entire computer
47 to resume.  This capability goes by several names such as "Wake On
48 LAN"; we will refer to it generically as "remote wakeup".  When a
49 device is enabled for remote wakeup and it is suspended, it may resume
50 itself (or send a request to be resumed) in response to some external
51 event.  Examples include a suspended keyboard resuming when a key is
52 pressed, or a suspended USB hub resuming when a device is plugged in.
53
54
55         When is a USB device idle?
56         --------------------------
57
58 A device is idle whenever the kernel thinks it's not busy doing
59 anything important and thus is a candidate for being suspended.  The
60 exact definition depends on the device's driver; drivers are allowed
61 to declare that a device isn't idle even when there's no actual
62 communication taking place.  (For example, a hub isn't considered idle
63 unless all the devices plugged into that hub are already suspended.)
64 In addition, a device isn't considered idle so long as a program keeps
65 its usbfs file open, whether or not any I/O is going on.
66
67 If a USB device has no driver, its usbfs file isn't open, and it isn't
68 being accessed through sysfs, then it definitely is idle.
69
70
71         Forms of dynamic PM
72         -------------------
73
74 Dynamic suspends occur when the kernel decides to suspend an idle
75 device.  This is called "autosuspend" for short.  In general, a device
76 won't be autosuspended unless it has been idle for some minimum period
77 of time, the so-called idle-delay time.
78
79 Of course, nothing the kernel does on its own initiative should
80 prevent the computer or its devices from working properly.  If a
81 device has been autosuspended and a program tries to use it, the
82 kernel will automatically resume the device (autoresume).  For the
83 same reason, an autosuspended device will usually have remote wakeup
84 enabled, if the device supports remote wakeup.
85
86 It is worth mentioning that many USB drivers don't support
87 autosuspend.  In fact, at the time of this writing (Linux 2.6.23) the
88 only drivers which do support it are the hub driver, kaweth, asix,
89 usblp, usblcd, and usb-skeleton (which doesn't count).  If a
90 non-supporting driver is bound to a device, the device won't be
91 autosuspended.  In effect, the kernel pretends the device is never
92 idle.
93
94 We can categorize power management events in two broad classes:
95 external and internal.  External events are those triggered by some
96 agent outside the USB stack: system suspend/resume (triggered by
97 userspace), manual dynamic resume (also triggered by userspace), and
98 remote wakeup (triggered by the device).  Internal events are those
99 triggered within the USB stack: autosuspend and autoresume.  Note that
100 all dynamic suspend events are internal; external agents are not
101 allowed to issue dynamic suspends.
102
103
104         The user interface for dynamic PM
105         ---------------------------------
106
107 The user interface for controlling dynamic PM is located in the power/
108 subdirectory of each USB device's sysfs directory, that is, in
109 /sys/bus/usb/devices/.../power/ where "..." is the device's ID.  The
110 relevant attribute files are: wakeup, control, and autosuspend.
111 (There may also be a file named "level"; this file was deprecated
112 as of the 2.6.35 kernel and replaced by the "control" file.)
113
114         power/wakeup
115
116                 This file is empty if the device does not support
117                 remote wakeup.  Otherwise the file contains either the
118                 word "enabled" or the word "disabled", and you can
119                 write those words to the file.  The setting determines
120                 whether or not remote wakeup will be enabled when the
121                 device is next suspended.  (If the setting is changed
122                 while the device is suspended, the change won't take
123                 effect until the following suspend.)
124
125         power/control
126
127                 This file contains one of two words: "on" or "auto".
128                 You can write those words to the file to change the
129                 device's setting.
130
131                 "on" means that the device should be resumed and
132                 autosuspend is not allowed.  (Of course, system
133                 suspends are still allowed.)
134
135                 "auto" is the normal state in which the kernel is
136                 allowed to autosuspend and autoresume the device.
137
138                 (In kernels up to 2.6.32, you could also specify
139                 "suspend", meaning that the device should remain
140                 suspended and autoresume was not allowed.  This
141                 setting is no longer supported.)
142
143         power/autosuspend
144
145                 This file contains an integer value, which is the
146                 number of seconds the device should remain idle before
147                 the kernel will autosuspend it (the idle-delay time).
148                 The default is 2.  0 means to autosuspend as soon as
149                 the device becomes idle, and negative values mean
150                 never to autosuspend.  You can write a number to the
151                 file to change the autosuspend idle-delay time.
152
153 Writing "-1" to power/autosuspend and writing "on" to power/control do
154 essentially the same thing -- they both prevent the device from being
155 autosuspended.  Yes, this is a redundancy in the API.
156
157 (In 2.6.21 writing "0" to power/autosuspend would prevent the device
158 from being autosuspended; the behavior was changed in 2.6.22.  The
159 power/autosuspend attribute did not exist prior to 2.6.21, and the
160 power/level attribute did not exist prior to 2.6.22.  power/control
161 was added in 2.6.34.)
162
163
164         Changing the default idle-delay time
165         ------------------------------------
166
167 The default autosuspend idle-delay time is controlled by a module
168 parameter in usbcore.  You can specify the value when usbcore is
169 loaded.  For example, to set it to 5 seconds instead of 2 you would
170 do:
171
172         modprobe usbcore autosuspend=5
173
174 Equivalently, you could add to /etc/modprobe.conf a line saying:
175
176         options usbcore autosuspend=5
177
178 Some distributions load the usbcore module very early during the boot
179 process, by means of a program or script running from an initramfs
180 image.  To alter the parameter value you would have to rebuild that
181 image.
182
183 If usbcore is compiled into the kernel rather than built as a loadable
184 module, you can add
185
186         usbcore.autosuspend=5
187
188 to the kernel's boot command line.
189
190 Finally, the parameter value can be changed while the system is
191 running.  If you do:
192
193         echo 5 >/sys/module/usbcore/parameters/autosuspend
194
195 then each new USB device will have its autosuspend idle-delay
196 initialized to 5.  (The idle-delay values for already existing devices
197 will not be affected.)
198
199 Setting the initial default idle-delay to -1 will prevent any
200 autosuspend of any USB device.  This is a simple alternative to
201 disabling CONFIG_USB_SUSPEND and rebuilding the kernel, and it has the
202 added benefit of allowing you to enable autosuspend for selected
203 devices.
204
205
206         Warnings
207         --------
208
209 The USB specification states that all USB devices must support power
210 management.  Nevertheless, the sad fact is that many devices do not
211 support it very well.  You can suspend them all right, but when you
212 try to resume them they disconnect themselves from the USB bus or
213 they stop working entirely.  This seems to be especially prevalent
214 among printers and scanners, but plenty of other types of device have
215 the same deficiency.
216
217 For this reason, by default the kernel disables autosuspend (the
218 power/control attribute is initialized to "on") for all devices other
219 than hubs.  Hubs, at least, appear to be reasonably well-behaved in
220 this regard.
221
222 (In 2.6.21 and 2.6.22 this wasn't the case.  Autosuspend was enabled
223 by default for almost all USB devices.  A number of people experienced
224 problems as a result.)
225
226 This means that non-hub devices won't be autosuspended unless the user
227 or a program explicitly enables it.  As of this writing there aren't
228 any widespread programs which will do this; we hope that in the near
229 future device managers such as HAL will take on this added
230 responsibility.  In the meantime you can always carry out the
231 necessary operations by hand or add them to a udev script.  You can
232 also change the idle-delay time; 2 seconds is not the best choice for
233 every device.
234
235 If a driver knows that its device has proper suspend/resume support,
236 it can enable autosuspend all by itself.  For example, the video
237 driver for a laptop's webcam might do this, since these devices are
238 rarely used and so should normally be autosuspended.
239
240 Sometimes it turns out that even when a device does work okay with
241 autosuspend there are still problems.  For example, there are
242 experimental patches adding autosuspend support to the usbhid driver,
243 which manages keyboards and mice, among other things.  Tests with a
244 number of keyboards showed that typing on a suspended keyboard, while
245 causing the keyboard to do a remote wakeup all right, would
246 nonetheless frequently result in lost keystrokes.  Tests with mice
247 showed that some of them would issue a remote-wakeup request in
248 response to button presses but not to motion, and some in response to
249 neither.
250
251 The kernel will not prevent you from enabling autosuspend on devices
252 that can't handle it.  It is even possible in theory to damage a
253 device by suspending it at the wrong time -- for example, suspending a
254 USB hard disk might cause it to spin down without parking the heads.
255 (Highly unlikely, but possible.)  Take care.
256
257
258         The driver interface for Power Management
259         -----------------------------------------
260
261 The requirements for a USB driver to support external power management
262 are pretty modest; the driver need only define
263
264         .suspend
265         .resume
266         .reset_resume
267
268 methods in its usb_driver structure, and the reset_resume method is
269 optional.  The methods' jobs are quite simple:
270
271         The suspend method is called to warn the driver that the
272         device is going to be suspended.  If the driver returns a
273         negative error code, the suspend will be aborted.  Normally
274         the driver will return 0, in which case it must cancel all
275         outstanding URBs (usb_kill_urb()) and not submit any more.
276
277         The resume method is called to tell the driver that the
278         device has been resumed and the driver can return to normal
279         operation.  URBs may once more be submitted.
280
281         The reset_resume method is called to tell the driver that
282         the device has been resumed and it also has been reset.
283         The driver should redo any necessary device initialization,
284         since the device has probably lost most or all of its state
285         (although the interfaces will be in the same altsettings as
286         before the suspend).
287
288 If the device is disconnected or powered down while it is suspended,
289 the disconnect method will be called instead of the resume or
290 reset_resume method.  This is also quite likely to happen when
291 waking up from hibernation, as many systems do not maintain suspend
292 current to the USB host controllers during hibernation.  (It's
293 possible to work around the hibernation-forces-disconnect problem by
294 using the USB Persist facility.)
295
296 The reset_resume method is used by the USB Persist facility (see
297 Documentation/usb/persist.txt) and it can also be used under certain
298 circumstances when CONFIG_USB_PERSIST is not enabled.  Currently, if a
299 device is reset during a resume and the driver does not have a
300 reset_resume method, the driver won't receive any notification about
301 the resume.  Later kernels will call the driver's disconnect method;
302 2.6.23 doesn't do this.
303
304 USB drivers are bound to interfaces, so their suspend and resume
305 methods get called when the interfaces are suspended or resumed.  In
306 principle one might want to suspend some interfaces on a device (i.e.,
307 force the drivers for those interface to stop all activity) without
308 suspending the other interfaces.  The USB core doesn't allow this; all
309 interfaces are suspended when the device itself is suspended and all
310 interfaces are resumed when the device is resumed.  It isn't possible
311 to suspend or resume some but not all of a device's interfaces.  The
312 closest you can come is to unbind the interfaces' drivers.
313
314
315         The driver interface for autosuspend and autoresume
316         ---------------------------------------------------
317
318 To support autosuspend and autoresume, a driver should implement all
319 three of the methods listed above.  In addition, a driver indicates
320 that it supports autosuspend by setting the .supports_autosuspend flag
321 in its usb_driver structure.  It is then responsible for informing the
322 USB core whenever one of its interfaces becomes busy or idle.  The
323 driver does so by calling these six functions:
324
325         int  usb_autopm_get_interface(struct usb_interface *intf);
326         void usb_autopm_put_interface(struct usb_interface *intf);
327         int  usb_autopm_get_interface_async(struct usb_interface *intf);
328         void usb_autopm_put_interface_async(struct usb_interface *intf);
329         void usb_autopm_get_interface_no_resume(struct usb_interface *intf);
330         void usb_autopm_put_interface_no_suspend(struct usb_interface *intf);
331
332 The functions work by maintaining a usage counter in the
333 usb_interface's embedded device structure.  When the counter is > 0
334 then the interface is deemed to be busy, and the kernel will not
335 autosuspend the interface's device.  When the usage counter is = 0
336 then the interface is considered to be idle, and the kernel may
337 autosuspend the device.
338
339 (There is a similar usage counter field in struct usb_device,
340 associated with the device itself rather than any of its interfaces.
341 This counter is used only by the USB core.)
342
343 Drivers need not be concerned about balancing changes to the usage
344 counter; the USB core will undo any remaining "get"s when a driver
345 is unbound from its interface.  As a corollary, drivers must not call
346 any of the usb_autopm_* functions after their diconnect() routine has
347 returned.
348
349 Drivers using the async routines are responsible for their own
350 synchronization and mutual exclusion.
351
352         usb_autopm_get_interface() increments the usage counter and
353         does an autoresume if the device is suspended.  If the
354         autoresume fails, the counter is decremented back.
355
356         usb_autopm_put_interface() decrements the usage counter and
357         attempts an autosuspend if the new value is = 0.
358
359         usb_autopm_get_interface_async() and
360         usb_autopm_put_interface_async() do almost the same things as
361         their non-async counterparts.  The big difference is that they
362         use a workqueue to do the resume or suspend part of their
363         jobs.  As a result they can be called in an atomic context,
364         such as an URB's completion handler, but when they return the
365         device will generally not yet be in the desired state.
366
367         usb_autopm_get_interface_no_resume() and
368         usb_autopm_put_interface_no_suspend() merely increment or
369         decrement the usage counter; they do not attempt to carry out
370         an autoresume or an autosuspend.  Hence they can be called in
371         an atomic context.
372
373 The simplest usage pattern is that a driver calls
374 usb_autopm_get_interface() in its open routine and
375 usb_autopm_put_interface() in its close or release routine.  But other
376 patterns are possible.
377
378 The autosuspend attempts mentioned above will often fail for one
379 reason or another.  For example, the power/control attribute might be
380 set to "on", or another interface in the same device might not be
381 idle.  This is perfectly normal.  If the reason for failure was that
382 the device hasn't been idle for long enough, a timer is scheduled to
383 carry out the operation automatically when the autosuspend idle-delay
384 has expired.
385
386 Autoresume attempts also can fail, although failure would mean that
387 the device is no longer present or operating properly.  Unlike
388 autosuspend, there's no idle-delay for an autoresume.
389
390
391         Other parts of the driver interface
392         -----------------------------------
393
394 Drivers can enable autosuspend for their devices by calling
395
396         usb_enable_autosuspend(struct usb_device *udev);
397
398 in their probe() routine, if they know that the device is capable of
399 suspending and resuming correctly.  This is exactly equivalent to
400 writing "auto" to the device's power/control attribute.  Likewise,
401 drivers can disable autosuspend by calling
402
403         usb_disable_autosuspend(struct usb_device *udev);
404
405 This is exactly the same as writing "on" to the power/control attribute.
406
407 Sometimes a driver needs to make sure that remote wakeup is enabled
408 during autosuspend.  For example, there's not much point
409 autosuspending a keyboard if the user can't cause the keyboard to do a
410 remote wakeup by typing on it.  If the driver sets
411 intf->needs_remote_wakeup to 1, the kernel won't autosuspend the
412 device if remote wakeup isn't available or has been disabled through
413 the power/wakeup attribute.  (If the device is already autosuspended,
414 though, setting this flag won't cause the kernel to autoresume it.
415 Normally a driver would set this flag in its probe method, at which
416 time the device is guaranteed not to be autosuspended.)
417
418 If a driver does its I/O asynchronously in interrupt context, it
419 should call usb_autopm_get_interface_async() before starting output and
420 usb_autopm_put_interface_async() when the output queue drains.  When
421 it receives an input event, it should call
422
423         usb_mark_last_busy(struct usb_device *udev);
424
425 in the event handler.  This sets udev->last_busy to the current time.
426 udev->last_busy is the field used for idle-delay calculations;
427 updating it will cause any pending autosuspend to be moved back.  Most
428 of the usb_autopm_* routines will also set the last_busy field to the
429 current time.
430
431 Asynchronous operation is always subject to races.  For example, a
432 driver may call one of the usb_autopm_*_interface_async() routines at
433 a time when the core has just finished deciding the device has been
434 idle for long enough but not yet gotten around to calling the driver's
435 suspend method.  The suspend method must be responsible for
436 synchronizing with the output request routine and the URB completion
437 handler; it should cause autosuspends to fail with -EBUSY if the
438 driver needs to use the device.
439
440 External suspend calls should never be allowed to fail in this way,
441 only autosuspend calls.  The driver can tell them apart by checking
442 the PM_EVENT_AUTO bit in the message.event argument to the suspend
443 method; this bit will be set for internal PM events (autosuspend) and
444 clear for external PM events.
445
446
447         Mutual exclusion
448         ----------------
449
450 For external events -- but not necessarily for autosuspend or
451 autoresume -- the device semaphore (udev->dev.sem) will be held when a
452 suspend or resume method is called.  This implies that external
453 suspend/resume events are mutually exclusive with calls to probe,
454 disconnect, pre_reset, and post_reset; the USB core guarantees that
455 this is true of autosuspend/autoresume events as well.
456
457 If a driver wants to block all suspend/resume calls during some
458 critical section, the best way is to lock the device and call
459 usb_autopm_get_interface() (and do the reverse at the end of the
460 critical section).  Holding the device semaphore will block all
461 external PM calls, and the usb_autopm_get_interface() will prevent any
462 internal PM calls, even if it fails.  (Exercise: Why?)
463
464
465         Interaction between dynamic PM and system PM
466         --------------------------------------------
467
468 Dynamic power management and system power management can interact in
469 a couple of ways.
470
471 Firstly, a device may already be autosuspended when a system suspend
472 occurs.  Since system suspends are supposed to be as transparent as
473 possible, the device should remain suspended following the system
474 resume.  But this theory may not work out well in practice; over time
475 the kernel's behavior in this regard has changed.
476
477 Secondly, a dynamic power-management event may occur as a system
478 suspend is underway.  The window for this is short, since system
479 suspends don't take long (a few seconds usually), but it can happen.
480 For example, a suspended device may send a remote-wakeup signal while
481 the system is suspending.  The remote wakeup may succeed, which would
482 cause the system suspend to abort.  If the remote wakeup doesn't
483 succeed, it may still remain active and thus cause the system to
484 resume as soon as the system suspend is complete.  Or the remote
485 wakeup may fail and get lost.  Which outcome occurs depends on timing
486 and on the hardware and firmware design.