About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / usb / power-management.txt




Custom Search

Based on kernel version 3.13. Page generated on 2014-01-20 22:04 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.