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.