aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorAlan Stern <stern@rowland.harvard.edu>2010-01-08 12:57:28 -0500
committerGreg Kroah-Hartman <gregkh@suse.de>2010-03-02 17:54:12 -0500
commit9bbdf1e0afe771ca7650f9f476769310bee9d8f3 (patch)
tree22852edde0165523d37f045575512f5759040dba /Documentation
parent0c590e2361511997430130e10e372217c1128da6 (diff)
USB: convert to the runtime PM framework
This patch (as1329) converts the USB stack over to the PM core's runtime PM framework. This involves numerous changes throughout usbcore, especially to hub.c and driver.c. Perhaps the most notable change is that CONFIG_USB_SUSPEND now depends on CONFIG_PM_RUNTIME instead of CONFIG_PM. Several fields in the usb_device and usb_interface structures are no longer needed. Some code which used to depend on CONFIG_USB_PM now depends on CONFIG_USB_SUSPEND (requiring some rearrangement of header files). The only visible change in behavior should be that following a system sleep (resume from RAM or resume from hibernation), autosuspended USB devices will be resumed just like everything else. They won't remain suspended. But if they aren't in use then they will naturally autosuspend again in a few seconds. Signed-off-by: Alan Stern <stern@rowland.harvard.edu> Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/usb/power-management.txt217
1 files changed, 77 insertions, 140 deletions
diff --git a/Documentation/usb/power-management.txt b/Documentation/usb/power-management.txt
index e3fa189c257a..2790ad48cfc2 100644
--- a/Documentation/usb/power-management.txt
+++ b/Documentation/usb/power-management.txt
@@ -2,7 +2,7 @@
2 2
3 Alan Stern <stern@rowland.harvard.edu> 3 Alan Stern <stern@rowland.harvard.edu>
4 4
5 November 10, 2009 5 December 11, 2009
6 6
7 7
8 8
@@ -29,9 +29,9 @@ covered to some extent (see Documentation/power/*.txt for more
29information about system PM). 29information about system PM).
30 30
31Note: Dynamic PM support for USB is present only if the kernel was 31Note: Dynamic PM support for USB is present only if the kernel was
32built with CONFIG_USB_SUSPEND enabled. System PM support is present 32built with CONFIG_USB_SUSPEND enabled (which depends on
33only if the kernel was built with CONFIG_SUSPEND or CONFIG_HIBERNATION 33CONFIG_PM_RUNTIME). System PM support is present only if the kernel
34enabled. 34was built with CONFIG_SUSPEND or CONFIG_HIBERNATION enabled.
35 35
36 36
37 What is Remote Wakeup? 37 What is Remote Wakeup?
@@ -326,64 +326,63 @@ driver does so by calling these six functions:
326 void usb_autopm_get_interface_no_resume(struct usb_interface *intf); 326 void usb_autopm_get_interface_no_resume(struct usb_interface *intf);
327 void usb_autopm_put_interface_no_suspend(struct usb_interface *intf); 327 void usb_autopm_put_interface_no_suspend(struct usb_interface *intf);
328 328
329The functions work by maintaining a counter in the usb_interface 329The functions work by maintaining a usage counter in the
330structure. When intf->pm_usage_count is > 0 then the interface is 330usb_interface's embedded device structure. When the counter is > 0
331deemed to be busy, and the kernel will not autosuspend the interface's 331then the interface is deemed to be busy, and the kernel will not
332device. When intf->pm_usage_count is <= 0 then the interface is 332autosuspend the interface's device. When the usage counter is = 0
333considered to be idle, and the kernel may autosuspend the device. 333then the interface is considered to be idle, and the kernel may
334autosuspend the device.
334 335
335(There is a similar pm_usage_count field in struct usb_device, 336(There is a similar usage counter field in struct usb_device,
336associated with the device itself rather than any of its interfaces. 337associated with the device itself rather than any of its interfaces.
337This field is used only by the USB core.) 338This counter is used only by the USB core.)
338 339
339Drivers must not modify intf->pm_usage_count directly; its value 340Drivers need not be concerned about balancing changes to the usage
340should be changed only be using the functions listed above. Drivers 341counter; the USB core will undo any remaining "get"s when a driver
341are responsible for insuring that the overall change to pm_usage_count 342is unbound from its interface. As a corollary, drivers must not call
342during their lifetime balances out to 0 (it may be necessary for the 343any of the usb_autopm_* functions after their diconnect() routine has
343disconnect method to call usb_autopm_put_interface() one or more times 344returned.
344to fulfill this requirement). The first two routines use the PM mutex 345
345in struct usb_device for mutual exclusion; drivers using the async 346Drivers using the async routines are responsible for their own
346routines are responsible for their own synchronization and mutual 347synchronization and mutual exclusion.
347exclusion. 348
348 349 usb_autopm_get_interface() increments the usage counter and
349 usb_autopm_get_interface() increments pm_usage_count and 350 does an autoresume if the device is suspended. If the
350 attempts an autoresume if the new value is > 0 and the 351 autoresume fails, the counter is decremented back.
351 device is suspended. 352
352 353 usb_autopm_put_interface() decrements the usage counter and
353 usb_autopm_put_interface() decrements pm_usage_count and 354 attempts an autosuspend if the new value is = 0.
354 attempts an autosuspend if the new value is <= 0 and the
355 device isn't suspended.
356 355
357 usb_autopm_get_interface_async() and 356 usb_autopm_get_interface_async() and
358 usb_autopm_put_interface_async() do almost the same things as 357 usb_autopm_put_interface_async() do almost the same things as
359 their non-async counterparts. The differences are: they do 358 their non-async counterparts. The big difference is that they
360 not acquire the PM mutex, and they use a workqueue to do their 359 use a workqueue to do the resume or suspend part of their
361 jobs. As a result they can be called in an atomic context, 360 jobs. As a result they can be called in an atomic context,
362 such as an URB's completion handler, but when they return the 361 such as an URB's completion handler, but when they return the
363 device will not generally not yet be in the desired state. 362 device will generally not yet be in the desired state.
364 363
365 usb_autopm_get_interface_no_resume() and 364 usb_autopm_get_interface_no_resume() and
366 usb_autopm_put_interface_no_suspend() merely increment or 365 usb_autopm_put_interface_no_suspend() merely increment or
367 decrement the pm_usage_count value; they do not attempt to 366 decrement the usage counter; they do not attempt to carry out
368 carry out an autoresume or an autosuspend. Hence they can be 367 an autoresume or an autosuspend. Hence they can be called in
369 called in an atomic context. 368 an atomic context.
370 369
371The conventional usage pattern is that a driver calls 370The simplest usage pattern is that a driver calls
372usb_autopm_get_interface() in its open routine and 371usb_autopm_get_interface() in its open routine and
373usb_autopm_put_interface() in its close or release routine. But 372usb_autopm_put_interface() in its close or release routine. But other
374other patterns are possible. 373patterns are possible.
375 374
376The autosuspend attempts mentioned above will often fail for one 375The autosuspend attempts mentioned above will often fail for one
377reason or another. For example, the power/level attribute might be 376reason or another. For example, the power/level attribute might be
378set to "on", or another interface in the same device might not be 377set to "on", or another interface in the same device might not be
379idle. This is perfectly normal. If the reason for failure was that 378idle. This is perfectly normal. If the reason for failure was that
380the device hasn't been idle for long enough, a delayed workqueue 379the device hasn't been idle for long enough, a timer is scheduled to
381routine is automatically set up to carry out the operation when the 380carry out the operation automatically when the autosuspend idle-delay
382autosuspend idle-delay has expired. 381has expired.
383 382
384Autoresume attempts also can fail, although failure would mean that 383Autoresume attempts also can fail, although failure would mean that
385the device is no longer present or operating properly. Unlike 384the device is no longer present or operating properly. Unlike
386autosuspend, there's no delay for an autoresume. 385autosuspend, there's no idle-delay for an autoresume.
387 386
388 387
389 Other parts of the driver interface 388 Other parts of the driver interface
@@ -413,26 +412,27 @@ though, setting this flag won't cause the kernel to autoresume it.
413Normally a driver would set this flag in its probe method, at which 412Normally a driver would set this flag in its probe method, at which
414time the device is guaranteed not to be autosuspended.) 413time the device is guaranteed not to be autosuspended.)
415 414
416The synchronous usb_autopm_* routines have to run in a sleepable 415If a driver does its I/O asynchronously in interrupt context, it
417process context; they must not be called from an interrupt handler or 416should call usb_autopm_get_interface_async() before starting output and
418while holding a spinlock. In fact, the entire autosuspend mechanism 417usb_autopm_put_interface_async() when the output queue drains. When
419is not well geared toward interrupt-driven operation. However there 418it receives an input event, it should call
420is one thing a driver can do in an interrupt handler:
421 419
422 usb_mark_last_busy(struct usb_device *udev); 420 usb_mark_last_busy(struct usb_device *udev);
423 421
424This sets udev->last_busy to the current time. udev->last_busy is the 422in the event handler. This sets udev->last_busy to the current time.
425field used for idle-delay calculations; updating it will cause any 423udev->last_busy is the field used for idle-delay calculations;
426pending autosuspend to be moved back. The usb_autopm_* routines will 424updating it will cause any pending autosuspend to be moved back. Most
427also set the last_busy field to the current time. 425of the usb_autopm_* routines will also set the last_busy field to the
428 426current time.
429Calling urb_mark_last_busy() from within an URB completion handler is 427
430subject to races: The kernel may have just finished deciding the 428Asynchronous operation is always subject to races. For example, a
431device has been idle for long enough but not yet gotten around to 429driver may call one of the usb_autopm_*_interface_async() routines at
432calling the driver's suspend method. The driver would have to be 430a time when the core has just finished deciding the device has been
433responsible for synchronizing its suspend method with its URB 431idle for long enough but not yet gotten around to calling the driver's
434completion handler and causing the autosuspend to fail with -EBUSY if 432suspend method. The suspend method must be responsible for
435an URB had completed too recently. 433synchronizing with the output request routine and the URB completion
434handler; it should cause autosuspends to fail with -EBUSY if the
435driver needs to use the device.
436 436
437External suspend calls should never be allowed to fail in this way, 437External suspend calls should never be allowed to fail in this way,
438only autosuspend calls. The driver can tell them apart by checking 438only autosuspend calls. The driver can tell them apart by checking
@@ -440,75 +440,23 @@ the PM_EVENT_AUTO bit in the message.event argument to the suspend
440method; this bit will be set for internal PM events (autosuspend) and 440method; this bit will be set for internal PM events (autosuspend) and
441clear for external PM events. 441clear for external PM events.
442 442
443Many of the ingredients in the autosuspend framework are oriented
444towards interfaces: The usb_interface structure contains the
445pm_usage_cnt field, and the usb_autopm_* routines take an interface
446pointer as their argument. But somewhat confusingly, a few of the
447pieces (i.e., usb_mark_last_busy()) use the usb_device structure
448instead. Drivers need to keep this straight; they can call
449interface_to_usbdev() to find the device structure for a given
450interface.
451 443
444 Mutual exclusion
445 ----------------
452 446
453 Locking requirements 447For external events -- but not necessarily for autosuspend or
454 -------------------- 448autoresume -- the device semaphore (udev->dev.sem) will be held when a
455 449suspend or resume method is called. This implies that external
456All three suspend/resume methods are always called while holding the 450suspend/resume events are mutually exclusive with calls to probe,
457usb_device's PM mutex. For external events -- but not necessarily for 451disconnect, pre_reset, and post_reset; the USB core guarantees that
458autosuspend or autoresume -- the device semaphore (udev->dev.sem) will 452this is true of autosuspend/autoresume events as well.
459also be held. This implies that external suspend/resume events are
460mutually exclusive with calls to probe, disconnect, pre_reset, and
461post_reset; the USB core guarantees that this is true of internal
462suspend/resume events as well.
463 453
464If a driver wants to block all suspend/resume calls during some 454If a driver wants to block all suspend/resume calls during some
465critical section, it can simply acquire udev->pm_mutex. Note that 455critical section, the best way is to lock the device and call
466calls to resume may be triggered indirectly. Block IO due to memory 456usb_autopm_get_interface() (and do the reverse at the end of the
467allocations can make the vm subsystem resume a device. Thus while 457critical section). Holding the device semaphore will block all
468holding this lock you must not allocate memory with GFP_KERNEL or 458external PM calls, and the usb_autopm_get_interface() will prevent any
469GFP_NOFS. 459internal PM calls, even if it fails. (Exercise: Why?)
470
471Alternatively, if the critical section might call some of the
472usb_autopm_* routines, the driver can avoid deadlock by doing:
473
474 down(&udev->dev.sem);
475 rc = usb_autopm_get_interface(intf);
476
477and at the end of the critical section:
478
479 if (!rc)
480 usb_autopm_put_interface(intf);
481 up(&udev->dev.sem);
482
483Holding the device semaphore will block all external PM calls, and the
484usb_autopm_get_interface() will prevent any internal PM calls, even if
485it fails. (Exercise: Why?)
486
487The rules for locking order are:
488
489 Never acquire any device semaphore while holding any PM mutex.
490
491 Never acquire udev->pm_mutex while holding the PM mutex for
492 a device that isn't a descendant of udev.
493
494In other words, PM mutexes should only be acquired going up the device
495tree, and they should be acquired only after locking all the device
496semaphores you need to hold. These rules don't matter to drivers very
497much; they usually affect just the USB core.
498
499Still, drivers do need to be careful. For example, many drivers use a
500private mutex to synchronize their normal I/O activities with their
501disconnect method. Now if the driver supports autosuspend then it
502must call usb_autopm_put_interface() from somewhere -- maybe from its
503close method. It should make the call while holding the private mutex,
504since a driver shouldn't call any of the usb_autopm_* functions for an
505interface from which it has been unbound.
506
507But the usb_autpm_* routines always acquire the device's PM mutex, and
508consequently the locking order has to be: private mutex first, PM
509mutex second. Since the suspend method is always called with the PM
510mutex held, it mustn't try to acquire the private mutex. It has to
511synchronize with the driver's I/O activities in some other way.
512 460
513 461
514 Interaction between dynamic PM and system PM 462 Interaction between dynamic PM and system PM
@@ -517,22 +465,11 @@ synchronize with the driver's I/O activities in some other way.
517Dynamic power management and system power management can interact in 465Dynamic power management and system power management can interact in
518a couple of ways. 466a couple of ways.
519 467
520Firstly, a device may already be manually suspended or autosuspended 468Firstly, a device may already be autosuspended when a system suspend
521when a system suspend occurs. Since system suspends are supposed to 469occurs. Since system suspends are supposed to be as transparent as
522be as transparent as possible, the device should remain suspended 470possible, the device should remain suspended following the system
523following the system resume. The 2.6.23 kernel obeys this principle 471resume. But this theory may not work out well in practice; over time
524for manually suspended devices but not for autosuspended devices; they 472the kernel's behavior in this regard has changed.
525do get resumed when the system wakes up. (Presumably they will be
526autosuspended again after their idle-delay time expires.) In later
527kernels this behavior will be fixed.
528
529(There is an exception. If a device would undergo a reset-resume
530instead of a normal resume, and the device is enabled for remote
531wakeup, then the reset-resume takes place even if the device was
532already suspended when the system suspend began. The justification is
533that a reset-resume is a kind of remote-wakeup event. Or to put it
534another way, a device which needs a reset won't be able to generate
535normal remote-wakeup signals, so it ought to be resumed immediately.)
536 473
537Secondly, a dynamic power-management event may occur as a system 474Secondly, a dynamic power-management event may occur as a system
538suspend is underway. The window for this is short, since system 475suspend is underway. The window for this is short, since system