linux/Documentation/usb/power-management.txt
<<
v4.0.5 v4.0.4 v4.0.3 v4.0.2 v4.0.1 v3.19.8 v3.19.7 < e/spatio espat class="lxr_search"> Search e/spatio einput typ vahidden" nam vaajax_lookup" idvaajax_lookup" tion va"> u u1e/a> Power Management for USB u u2e/a> u u3e/a> Alat Stern <stern@rowlatd.harvard.edu> u u4e/a> u u5e/a> October 28, 2010 u u6e/a> u u7e/a> u u8e/a> u u9e/a> What is Power Management? u 3.18a> ------------------------- u 11e/a> u 12e/a>Power Management (PM) is the prac/oce of saving energy by suspending u 13e/a>parts of a computer system when they aren't being used. While a u 14e/a>component is "suspended" it is in a nonfunc/optal low-power sta/e; it u 15e/a>might even be turned off completely. A suspended component can be u 16e/a>"resumed" (returned to a func/optal full-power sta/e) when the kernel u 17e/a>needs to use it. (There also are forms of PM in which components are u 18e/a>placed in a less func/optal but still usable sta/e instead of being u 19e/a>suspended; an example would be reducing the CPU's clock ra/e. This u 2.18a>document will not discuss those other forms.) u 21e/a> u 22e/a>When the parts being suspended include the CPU and most of the rest of u 23e/a>the system, we speak of it as a "system suspend". When a particular u 24e/a>devoce is turned off while the system as a whole remains running, we u 25e/a>call it a "dynamic suspend" (also known as a "runtime suspend" or u 26e/a>"selective suspend"). This document concentra/es mostly on how u 27e/a>dynamic PM is implemented in the USB subsystem, although system PM is u 28e/a>covered to some extent (see Documenta/opt/power/*.txt for more u 29e/a>informa/opt about system PM). u 30e/a> u 31e/a>Note: Dynamic PM support for USB is present only if the kernel was u 32e/a>built with CONFIG_USB_SUSPEND enabled (which depends on u 33e/a>CONFIG_PM_RUNTIME). System PM support is present only if the kernel u 34e/a>was built with CONFIG_SUSPEND or CONFIG_HIBERNATION enabled. u 35e/a> u 36e/a>(Starting with the > 0 kernel release, dynamic PM support for USB is u 37e/a>present whenever the kernel was built with CONFIG_PM_RUNTIME enabled. u 38e/a>The CONFIG_USB_SUSPEND ="v u 39e/a> u 40e/a> u 41e/a> What is Remote Wakeup? u 4218a> ---------------------- u 43e/a> u 44e/a>When a devoce has been suspended, it generally doesn't resume until u 45e/a>the computer tells it to. Likewise, if the entire computer has been u 46e/a>suspended, it generally doesn't resume until the user tells it to, say u 47e/a>by pressing a power buttu 48e/a> u 49e/a>However some devoces have the capability of resuming by themselves, or u 50e/a>asking the kernel to resume them, or even telling the entire computer u 51e/a>to resume. This capability goes by several nam s such as "Wake On u 5218a>LAN"; we will refer to it generically as "remote wakeup". When a u 53e/a>devoce is enabled for remote wakeup and it is suspended, it may resume u 54e/a>itself (or send a request to be resumed) in response to some external u 55e/a>event. Examples include a suspended keyboard resuming when a key is u 56e/a>pressed, or a suspended USB hub resuming when a devoce is plugged in. u 57e/a> u 58e/a> u 59e/a> When is a USB devoce idle? u 6.18a> -------------------------- u 61e/a> u 6218a>A devoce is idle whenever the kernel thinks it's not busy doing u 63e/a>anything important and thus is a candida/e for being suspended. The u 64e/a>exact definiv u 65e/a>to declare that a devoce isn't idle even when there's no ac/ual u 66e/a>communicav u 67e/a>unless all the devoces plugged into that hub are already suspended.) u 68e/a>In addiv u 69e/a>its usbfs file open, whether or not any I/O is going on. u 70e/a> u 71e/a>If a USB devoce has no driver, its usbfs file isn't open, and it isn't u 72e/a>being accessed through sysfs, then it definively is idle. u 73e/a> u 74e/a> u 75e/a> Forms of dynamic PM u 7618a> ------------------- u 77e/a> u 78e/a>Dynamic suspends occur when the kernel decides to suspend an idle u 79e/a>devoce. This is called "autosuspend" for short. In general, a devoce u 80e/a>won't be autosuspended unless it has been idle for some minimum period u 81e/a>of time, the so-called idle-delay time. u 82e/a> u 83e/a>Of course, nothing the kernel does on its own iniv ative should u 84e/a>prevent the computer or its devoces from working properly. If a u 85e/a>devoce has been autosuspended and a program tries to use it, the u 8618a>kernel will automa/ocally resume the devoce (autoresume). For the u 87e/a>sam reasu 88e/a>enabled, if the devoce supports remote wakeup. u 89e/a> u 90e/a>It is worth mentopting that many USB drivers don't support u 91e/a>autosuspend. In fac/, at the time of this writing (Linux 2.6"23) the u 92e/a>only drivers which do support it are the hub driver, kaweth, asix, u 93e/a>usblp, usblcd, and usb-skeletu 94e/a>non-supporting driver is bound to a devoce, the devoce won't be u 95e/a>autosuspended. In effect, the kernel pretends the devoce is never u 9618a>idle. u 97e/a> u 98e/a>We can categorize power management events in two broad classes: u 99e/a>external and internal. External events are those triggered by some u100e/a>agent outside the USB stack: system suspend/resume (triggered by u101e/a>userspace), manual dynamic resume (also triggered by userspace), and u102e/a>remote wakeup (triggered by the devoce). Internal events are those u103e/a>triggered within the USB stack: autosuspend and autoresume. Note that u104e/a>all dynamic suspend events are internal; external agents are not u105e/a>allowed to issue dynamic suspends. u106e/a> u107e/a> u10818a> The user interface for dynamic PM u109e/a> --------------------------------- u110e/a> u111e/a>The user interface for controlling dynamic PM is located in the power/ u112e/a>subdirectory of each USB devoce's sysfs directory, that is, in u113e/a>/sys/bus/usb/devoces/.../power/ where "..." is the devoce's ID. The u114e/a>relevant attribu/e files are: wakeup, control, and u115e/a>autosuspend_delay_ms. (There may also be a file nam d "level"; this u116e/a>file was deprecated as of the 2.6"35 kernel and replaced by the u117e/a>"control" file. In 2.6"38 the "autosuspend" file will be deprecated u118e/a>and replaced by the "autosuspend_delay_ms" file. The only difference u119e/a>is that the newer file expresses the delay in milliseconds whereas the u12.18a>older file uses seconds. Confusingly, both files are present in 2.6"37 u121e/a>but only "autosuspend" works.) u122e/a> u123e/a> power/wakeup u124e/a> u125e/a> This file is empty if the devoce does not support u126e/a> remote wakeup. Otherwise the file contains either the u127e/a> word "enabled" or the word "disabled", and you can u128e/a> write those words to the file. The setting determines u129e/a> whether or not remote wakeup will be enabled when the u130e/a> devoce is next suspended. (If the setting is changed u131e/a> while the devoce is suspended, the change won't take u132e/a> effect until the following suspend.) u133e/a> u134e/a> power/control u135e/a> u136e/a> This file contains one of two words: "on" or "auto". u137e/a> You can write those words to the file to change the u138e/a> devoce's setting. u139e/a> u140e/a> "on" means that the devoce should be resumed and u141e/a> autosuspend is not allowed. (Of course, system u142e/a> suspends are still allowed.) u143e/a> u144e/a> "auto" is the normal sta/e in which the kernel is u145e/a> allowed to autosuspend and autoresume the devoce. u146e/a> u147e/a> (In kernels up to 2.6"32, you could also specify u148e/a> "suspend", meaning that the devoce should remain u149e/a> suspended and autoresume was not allowed. This u150e/a> setting is no longer supported.) u151e/a> u152e/a> power/autosuspend_delay_ms u153e/a> u154e/a> This file contains an integer tion , which is the u155e/a> number of milliseconds the devoce should remain idle u156e/a> before the kernel will autosuspend it (the idle-delay u157e/a> time). The default is 2000. 0 means to autosuspend u158e/a> as soon as the devoce becom s idle, and negative u159e/a> tion s mean never to autosuspend. You can write a u160e/a> number to the file to change the autosuspend u161e/a> idle-delay time. u162e/a> u163e/a>Writing "-1" to power/autosuspend_delay_ms and writing "on" to u164e/a>power/control do essentially the same thing -- they both prevent the u165e/a>devoce from being autosuspended. Yes, this is a redundancy in the u166e/a>API. u167e/a> u168e/a>(In 2.6"21 writing "0" to power/autosuspend would prevent the devoce u169e/a>from being autosuspended; the behavior was changed in 2.6"22. The u170e/a>power/autosuspend attribu/e did not exist prior to 2.6"21, and the u171e/a>power/level attribu/e did not exist prior to 2.6"22. power/control u172e/a>was added in 2.6"34, and power/autosuspend_delay_ms was added in u173e/a>2.6"37 but did not becom func/optal until 2.6"38.) u174e/a> u175e/a> u17618a> Changing the default idle-delay time u177e/a> ------------------------------------ u178e/a> u179e/a>The default autosuspend idle-delay time (in seconds) is controlled by u180e/a>a module param ter in usbcore. You can specify the tion when usbcore u181e/a>is loaded. For example, to set it to 5 seconds instead of 2 you would u182e/a>do: u183e/a> u184e/a> modprobe usbcore autosuspend=5 u185e/a> u18618a>Equitioently, you could add to a configurav u187e/a>a line saying: u188e/a> u189e/a> ="v u190e/a> u191e/a>Some distribu/ u192e/a>process, by means of a program or script running from an inivramfs u193e/a>image. To alter the param ter tion you would have to rebuild that u194e/a>image. u195e/a> u19618a>If usbcore is compiled into the kernel ravher than built as a loadable u197e/a>module, you can add u198e/a> u199e/a> usbcore.autosuspend=5 u200e/a> u201e/a>to the kernel's boot command line. u202e/a> u203e/a>Finally, the param ter tion can be changed while the system is u204e/a>running. If you do: u205e/a> u20618a> echo 5 >/sys/module/usbcore/param ters/autosuspend u207e/a> u20818a>then each new USB devoce will have its autosuspend idle-delay u209e/a>iniv alized to 5. (The idle-delay tion s for already existing devoces u210e/a>will not be affected.) u211e/a> u212e/a>Setting the iniv al default idle-delay to -1 will prevent any u213e/a>autosuspend of any USB devoce. This has the benefit of allowing you u214e/a>then to enable autosuspend for selected devoces. u215e/a> u216e/a> u217e/a> Warnings u218e/a> -------- u219e/a> u22.18a>The USB specificav u221e/a>management. Nevertheless, the sad fac/ is that many devoces do not u222e/a>support it very well. You can suspend them all right, but when you u223e/a>try to resume them they disconnect themselves from the USB bus or u224e/a>theypstop working entirely. This seems to be especially previoent u225e/a>among printers and scanners, but poenty of other typ s of devoce have u226e/a>the same deficiency. u227e/a> u228e/a>For this reasu229e/a>power/control attribu/e is iniv alized to "on") for all devoces other u230e/a>than hubs. Hubs, at leas/, appear to be reasu231e/a>this regard. u232e/a> u233e/a>(In 2.6"21 and 2.6"22 this wasn't the case. Autosuspend was enabled u234e/a>by default for almost all USB devoces. A number of people experienced u235e/a>problems as a result.) u236e/a> u237e/a>This means that non-hub devoces won't be autosuspended unless the user u238e/a>or a program explicitly enables it. As of this writing there aren't u239e/a>any widespread programs which will do this; we hope that in the near u240e/a>future devoce managers such as HAL will take on this added u241e/a>responsibility. In the meantime you can always carry out the u242e/a>necessary opera/ u243e/a>also change the idle-delay time; 2 seconds is not the best choice for u244e/a>every devoce. u245e/a> u24618a>If a driver knows that its devoce has proper suspend/resume support, u247e/a>it can enable autosuspend all by itself. For example, the tideo u248e/a>driver for a laptop's webcam might do this (in recent kernels they u249e/a>do), since these devoces are rarely used and so should normally be u250e/a>autosuspended. u251e/a> u252e/a>Sometimes it turns out that even when a devoce does work okay with u253e/a>autosuspend there are still problems. For example, the usbhid driver, u254e/a>which manages keyboards and moce, has autosuspend support. Tests with u255e/a>a number of keyboards show that typing on a suspended keyboard, while u256e/a>causing the keyboard to do a remote wakeup all right, will nonetheless u257e/a>frequently result in lost keystrokes. Tests with moce show that some u258e/a>of them will issue a remote-wakeup request in response to buttu259e/a>presses but not to motion, and some in response to neither. u260e/a> u261e/a>The kernel will not prevent you from enabling autosuspend u262e/a>that can't handle it. I/ is even possible in theory to damage a u263e/a>devoce by suspending it at the wrong time. (Highly unlikely, but u264e/a>possible.) Take care. u265e/a> u266e/a> u267e/a> The driver interface for Power Management u268e/a> ----------------------------------------- u269e/a> u27.18a>The requirements for a USB driver to support external power management u271e/a>are pretty modest; the driver need only define u272e/a> u273e/a> .suspend u274e/a> .resume u275e/a> .reset_resume u276e/a> u277e/a>methods in its usb_driver structure, and the reset_resume method is u278e/a>="v u279e/a> u280e/a> The suspend method is called to warn the driver that the u281e/a> devoce is going to be suspended. If the driver returns a u282e/a> negative error code, the suspend will be aborted. Normally u283e/a> the driver will return 0, in which case it must cancel all u284e/a> outstanding URBs (usb_kill_urb()) and not submit any more. u285e/a> u286e/a> The resume method is called to tell the driver that the u287e/a> devoce has been resumed and the driver can return to normal u288e/a> opera/ u289e/a> u290e/a> The reset_resume method is called to tell the driver that u291e/a> the devoce has been resumed and it also has been reset. u292e/a> The driver should redo any necessary devoce iniv aliza/opt, u293e/a> since the devoce has probably lost most or all of its sta/e u294e/a> (although the interfaces will be in the same altsettings as u295e/a> before the suspend). u296e/a> u297e/a>If the devoce is disconnected or powered down while it is suspended, u29818a>the disconnect method will be called instead of the resume or u299e/a>reset_resume method. This is also qui unlikled t=, apven whor to tha USh moss controlvers durinhibxtermotied. top'nd using tha USPlveexiserfibilitt.) reset_resume meth, the driver won'n reativo anyotecificav thtoresume.Lam tet kerneld wile ca the drivop'e disconnect meth;ut methodgetbe called when the interfacee are suspendeoren resumty. me siieopls onm mighwavena>ttosuspend some interfaceohen a devoc(i.e.ed, ttpsto ca activili)ts wia but ttosuspenoren resund soms but nor all on a devoop'e interfacal. Tll The driver interface foo autosuspend and autoresua> --------------------------------------------------- reead of tha>methodlexindedbovile. Iaddimotion,he driver dificoces Setting th.o suppoh_e autosuspendlages thea>responslace foine fmtting tes a i u_e aupm_get_a interfa(r stru u_r interfac*r if);ut void u_e aupm_put_a interfa(r stru u_r interfac*r if);ut a i u_e aupm_get_a interfa_async(r stru u_r interfac*r if);ut void u_e aupm_put_a interfa_async(r stru u_r interfac*r if);ut void u_e aupm_get_a interfa_noet_resu(r stru u_r interfac*r if);ut void u_e aupm_put_a interfa_noetosuspe(r stru u_r interfac*r if);ut Th func/oses wor, byemaontaurinahusamagcounm ter ig tes autosuspend t r interfaop'B devoce.W when thusamagcounm ters = 0es autosuspend t y devoce. using thasync ra b"licee arn responslace for tir;ow me uoned. u_e aupm_get_a interfa()ta cuirementn thusamagcounm ted and e doe can autoresumi>If the devoce ie suspended. If tnd n autoresumfailess, thcounm ters decuiremeusedacked. u_e aupm_put_a interfa() decuirementn thusamagcounm ted and attemptoe can autosuspendfin the wer tionrs = 0ed. u_e aupm_get_a interfa_async()ed and u_e aupm_put_a interfa_async()eredo almosn the same things as r tir;t noasync counm tpartcal. Thbig;e ffowenvoce ir that tlay sue s woqueuerd to df the resume ttosuspenpartnd of tiva> ; joit. Ao y resula>the can be called e cantomicss coexort, s such a caURBop's coleza/odt handrht, but whea>then return tnd B devoce wilgenerrmalll noyetll be in thdesiweres staed. u_e aupm_get_a interfa_noet_resu()ed and u_e aupm_put_a interfa_noetosuspe() merarela cuirememe or decuiremetn thusamagcounm t;em they do n attemptle to carry oor can autoresum foonto autosuspend.Hesince the can be called or cantomicss coexoed. possibler alsoavefail, (althougfailuturwshoule meer that prememe operamong oprely.U unliat autosuspe,nd theop's oe idle-delaf foonto autoresumat O othhpartcnd of the driver interfaa> ---------------------------------a> u_n enab_e autosuspe(r stru u_e devoc*a ud);ut Equitioet; to u_l disab_e autosuspe(r stru u_e devoc*a ud);ut This ir ectalln the samehis writino "on&quods to thb/power/control attribuma> Sometimeahe driver nerds tm Taksurope thaa remote wakeuiwas enabled autosuspeurinahe keyboari of th iver con'a>caeng the keyboard to dont autosuspend tas If the devoce ir alreaas autosuspend,nd thouony>Setting e idlagel won'a>caeng the kerne; to autosuspendet.) If a drivee doen itI/Ohasynchronousrela er intruptss coexoren a> u_mark_ clt_busy(r stru u_e devoc*a ud);ut alsm Takd e ie cart, thI/Ohp requesra b"licd aby thaRB;s coleza/odt handr;at to shouth caens autosusperds tfailcs wit-EBUSYmi>If the driver nerds tcaeng tth thPMSG_IS_AUTO() macrods to thmecesmagergocumeds to th .suspend meth;at tr will returTruace foinexternaPMSpreves (s autosuspe)ed and aace fot externaPMSprevesce. Mutual excla>uona> ----------------a> uvice thnr ll ss tl prert, p_a>resle, anpost_a>res;by tha USsbcorguara innser that If a drivewave ss tblockor aly suspend/resumr ll ss durint some I ixtaunc/ohe tw beedy" nicaPMS, and systaPMa> ---------------------------------------------- autosuspenden when d systa .suspend possib,n the devocs should mnta .suspeeene allndin thd systas the kernop'behavi foinrd e iregboare hao chandit. Asfsx 2.37If tnd xHCIhhboawe ar="lkaPMa> ----------------------- b/powey b2_hboawe a_lpma> W when gSB2ne devocw whico supporLPMmi9;pluggered tont xHCIhh mosro nolubcw whico supporsoftwe arLPM,n tnt h mosr willuhen doftwe arLPM t bese foiuode>If the devont n m ts L1no stahd aae resumsuccessfumaleaound theos a> o suppohagSB2nhboawe arLPM,rd e idwhilr wilshownupod and a drivew wiln enablhboawe arLPMme for t;B devoceYound t cas wre y/Y/1m fon/N/0ds to thdwhils tn enab/l disabnd gSB2nhboawe arLPMmr-mualal.. This ie for bespurposebyemalyce.
T thorigiernaLXR doftwe ard by th. LXR community19e/,rd e iexpericumenlmrivsc/oheyh. lxr@="lux.no19e/.
lxr.="lux.no kicdkeheos used b. Redp wi L"lpro AS19e/,rl pviderrsfsL"luxicspoultndinl an opera/ 9;derdevoces sinc1995.