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