About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / usb / power-management.txt


Based on kernel version 4.10.8. Page generated on 2017-04-01 14:44 EST.

1				Power Management for USB
2	
3			 Alan Stern <stern@rowland.harvard.edu>
4	
5			       Last-updated: February 2014
6	
7	
8		Contents:
9		---------
10		* What is Power Management?
11		* What is Remote Wakeup?
12		* When is a USB device idle?
13		* Forms of dynamic PM
14		* The user interface for dynamic PM
15		* Changing the default idle-delay time
16		* Warnings
17		* The driver interface for Power Management
18		* The driver interface for autosuspend and autoresume
19		* Other parts of the driver interface
20		* Mutual exclusion
21		* Interaction between dynamic PM and system PM
22		* xHCI hardware link PM
23		* USB Port Power Control
24		* User Interface for Port Power Control
25		* Suggested Userspace Port Power Policy
26	
27	
28		What is Power Management?
29		-------------------------
30	
31	Power Management (PM) is the practice of saving energy by suspending
32	parts of a computer system when they aren't being used.  While a
33	component is "suspended" it is in a nonfunctional low-power state; it
34	might even be turned off completely.  A suspended component can be
35	"resumed" (returned to a functional full-power state) when the kernel
36	needs to use it.  (There also are forms of PM in which components are
37	placed in a less functional but still usable state instead of being
38	suspended; an example would be reducing the CPU's clock rate.  This
39	document will not discuss those other forms.)
40	
41	When the parts being suspended include the CPU and most of the rest of
42	the system, we speak of it as a "system suspend".  When a particular
43	device is turned off while the system as a whole remains running, we
44	call it a "dynamic suspend" (also known as a "runtime suspend" or
45	"selective suspend").  This document concentrates mostly on how
46	dynamic PM is implemented in the USB subsystem, although system PM is
47	covered to some extent (see Documentation/power/*.txt for more
48	information about system PM).
49	
50	System PM support is present only if the kernel was built with CONFIG_SUSPEND
51	or CONFIG_HIBERNATION enabled.  Dynamic PM support for USB is present whenever
52	the kernel was built with CONFIG_PM enabled.
53	
54	[Historically, dynamic PM support for USB was present only if the
55	kernel had been built with CONFIG_USB_SUSPEND enabled (which depended on
56	CONFIG_PM_RUNTIME).  Starting with the 3.10 kernel release, dynamic PM support
57	for USB was present whenever the kernel was built with CONFIG_PM_RUNTIME
58	enabled.  The CONFIG_USB_SUSPEND option had been eliminated.]
59	
60	
61		What is Remote Wakeup?
62		----------------------
63	
64	When a device has been suspended, it generally doesn't resume until
65	the computer tells it to.  Likewise, if the entire computer has been
66	suspended, it generally doesn't resume until the user tells it to, say
67	by pressing a power button or opening the cover.
68	
69	However some devices have the capability of resuming by themselves, or
70	asking the kernel to resume them, or even telling the entire computer
71	to resume.  This capability goes by several names such as "Wake On
72	LAN"; we will refer to it generically as "remote wakeup".  When a
73	device is enabled for remote wakeup and it is suspended, it may resume
74	itself (or send a request to be resumed) in response to some external
75	event.  Examples include a suspended keyboard resuming when a key is
76	pressed, or a suspended USB hub resuming when a device is plugged in.
77	
78	
79		When is a USB device idle?
80		--------------------------
81	
82	A device is idle whenever the kernel thinks it's not busy doing
83	anything important and thus is a candidate for being suspended.  The
84	exact definition depends on the device's driver; drivers are allowed
85	to declare that a device isn't idle even when there's no actual
86	communication taking place.  (For example, a hub isn't considered idle
87	unless all the devices plugged into that hub are already suspended.)
88	In addition, a device isn't considered idle so long as a program keeps
89	its usbfs file open, whether or not any I/O is going on.
90	
91	If a USB device has no driver, its usbfs file isn't open, and it isn't
92	being accessed through sysfs, then it definitely is idle.
93	
94	
95		Forms of dynamic PM
96		-------------------
97	
98	Dynamic suspends occur when the kernel decides to suspend an idle
99	device.  This is called "autosuspend" for short.  In general, a device
100	won't be autosuspended unless it has been idle for some minimum period
101	of time, the so-called idle-delay time.
102	
103	Of course, nothing the kernel does on its own initiative should
104	prevent the computer or its devices from working properly.  If a
105	device has been autosuspended and a program tries to use it, the
106	kernel will automatically resume the device (autoresume).  For the
107	same reason, an autosuspended device will usually have remote wakeup
108	enabled, if the device supports remote wakeup.
109	
110	It is worth mentioning that many USB drivers don't support
111	autosuspend.  In fact, at the time of this writing (Linux 2.6.23) the
112	only drivers which do support it are the hub driver, kaweth, asix,
113	usblp, usblcd, and usb-skeleton (which doesn't count).  If a
114	non-supporting driver is bound to a device, the device won't be
115	autosuspended.  In effect, the kernel pretends the device is never
116	idle.
117	
118	We can categorize power management events in two broad classes:
119	external and internal.  External events are those triggered by some
120	agent outside the USB stack: system suspend/resume (triggered by
121	userspace), manual dynamic resume (also triggered by userspace), and
122	remote wakeup (triggered by the device).  Internal events are those
123	triggered within the USB stack: autosuspend and autoresume.  Note that
124	all dynamic suspend events are internal; external agents are not
125	allowed to issue dynamic suspends.
126	
127	
128		The user interface for dynamic PM
129		---------------------------------
130	
131	The user interface for controlling dynamic PM is located in the power/
132	subdirectory of each USB device's sysfs directory, that is, in
133	/sys/bus/usb/devices/.../power/ where "..." is the device's ID.  The
134	relevant attribute files are: wakeup, control, and
135	autosuspend_delay_ms.  (There may also be a file named "level"; this
136	file was deprecated as of the 2.6.35 kernel and replaced by the
137	"control" file.  In 2.6.38 the "autosuspend" file will be deprecated
138	and replaced by the "autosuspend_delay_ms" file.  The only difference
139	is that the newer file expresses the delay in milliseconds whereas the
140	older file uses seconds.  Confusingly, both files are present in 2.6.37
141	but only "autosuspend" works.)
142	
143		power/wakeup
144	
145			This file is empty if the device does not support
146			remote wakeup.  Otherwise the file contains either the
147			word "enabled" or the word "disabled", and you can
148			write those words to the file.  The setting determines
149			whether or not remote wakeup will be enabled when the
150			device is next suspended.  (If the setting is changed
151			while the device is suspended, the change won't take
152			effect until the following suspend.)
153	
154		power/control
155	
156			This file contains one of two words: "on" or "auto".
157			You can write those words to the file to change the
158			device's setting.
159	
160			"on" means that the device should be resumed and
161			autosuspend is not allowed.  (Of course, system
162			suspends are still allowed.)
163	
164			"auto" is the normal state in which the kernel is
165			allowed to autosuspend and autoresume the device.
166	
167			(In kernels up to 2.6.32, you could also specify
168			"suspend", meaning that the device should remain
169			suspended and autoresume was not allowed.  This
170			setting is no longer supported.)
171	
172		power/autosuspend_delay_ms
173	
174			This file contains an integer value, which is the
175			number of milliseconds the device should remain idle
176			before the kernel will autosuspend it (the idle-delay
177			time).  The default is 2000.  0 means to autosuspend
178			as soon as the device becomes idle, and negative
179			values mean never to autosuspend.  You can write a
180			number to the file to change the autosuspend
181			idle-delay time.
182	
183	Writing "-1" to power/autosuspend_delay_ms and writing "on" to
184	power/control do essentially the same thing -- they both prevent the
185	device from being autosuspended.  Yes, this is a redundancy in the
186	API.
187	
188	(In 2.6.21 writing "0" to power/autosuspend would prevent the device
189	from being autosuspended; the behavior was changed in 2.6.22.  The
190	power/autosuspend attribute did not exist prior to 2.6.21, and the
191	power/level attribute did not exist prior to 2.6.22.  power/control
192	was added in 2.6.34, and power/autosuspend_delay_ms was added in
193	2.6.37 but did not become functional until 2.6.38.)
194	
195	
196		Changing the default idle-delay time
197		------------------------------------
198	
199	The default autosuspend idle-delay time (in seconds) is controlled by
200	a module parameter in usbcore.  You can specify the value when usbcore
201	is loaded.  For example, to set it to 5 seconds instead of 2 you would
202	do:
203	
204		modprobe usbcore autosuspend=5
205	
206	Equivalently, you could add to a configuration file in /etc/modprobe.d
207	a line saying:
208	
209		options usbcore autosuspend=5
210	
211	Some distributions load the usbcore module very early during the boot
212	process, by means of a program or script running from an initramfs
213	image.  To alter the parameter value you would have to rebuild that
214	image.
215	
216	If usbcore is compiled into the kernel rather than built as a loadable
217	module, you can add
218	
219		usbcore.autosuspend=5
220	
221	to the kernel's boot command line.
222	
223	Finally, the parameter value can be changed while the system is
224	running.  If you do:
225	
226		echo 5 >/sys/module/usbcore/parameters/autosuspend
227	
228	then each new USB device will have its autosuspend idle-delay
229	initialized to 5.  (The idle-delay values for already existing devices
230	will not be affected.)
231	
232	Setting the initial default idle-delay to -1 will prevent any
233	autosuspend of any USB device.  This has the benefit of allowing you
234	then to enable autosuspend for selected devices.
235	
236	
237		Warnings
238		--------
239	
240	The USB specification states that all USB devices must support power
241	management.  Nevertheless, the sad fact is that many devices do not
242	support it very well.  You can suspend them all right, but when you
243	try to resume them they disconnect themselves from the USB bus or
244	they stop working entirely.  This seems to be especially prevalent
245	among printers and scanners, but plenty of other types of device have
246	the same deficiency.
247	
248	For this reason, by default the kernel disables autosuspend (the
249	power/control attribute is initialized to "on") for all devices other
250	than hubs.  Hubs, at least, appear to be reasonably well-behaved in
251	this regard.
252	
253	(In 2.6.21 and 2.6.22 this wasn't the case.  Autosuspend was enabled
254	by default for almost all USB devices.  A number of people experienced
255	problems as a result.)
256	
257	This means that non-hub devices won't be autosuspended unless the user
258	or a program explicitly enables it.  As of this writing there aren't
259	any widespread programs which will do this; we hope that in the near
260	future device managers such as HAL will take on this added
261	responsibility.  In the meantime you can always carry out the
262	necessary operations by hand or add them to a udev script.  You can
263	also change the idle-delay time; 2 seconds is not the best choice for
264	every device.
265	
266	If a driver knows that its device has proper suspend/resume support,
267	it can enable autosuspend all by itself.  For example, the video
268	driver for a laptop's webcam might do this (in recent kernels they
269	do), since these devices are rarely used and so should normally be
270	autosuspended.
271	
272	Sometimes it turns out that even when a device does work okay with
273	autosuspend there are still problems.  For example, the usbhid driver,
274	which manages keyboards and mice, has autosuspend support.  Tests with
275	a number of keyboards show that typing on a suspended keyboard, while
276	causing the keyboard to do a remote wakeup all right, will nonetheless
277	frequently result in lost keystrokes.  Tests with mice show that some
278	of them will issue a remote-wakeup request in response to button
279	presses but not to motion, and some in response to neither.
280	
281	The kernel will not prevent you from enabling autosuspend on devices
282	that can't handle it.  It is even possible in theory to damage a
283	device by suspending it at the wrong time.  (Highly unlikely, but
284	possible.)  Take care.
285	
286	
287		The driver interface for Power Management
288		-----------------------------------------
289	
290	The requirements for a USB driver to support external power management
291	are pretty modest; the driver need only define
292	
293		.suspend
294		.resume
295		.reset_resume
296	
297	methods in its usb_driver structure, and the reset_resume method is
298	optional.  The methods' jobs are quite simple:
299	
300		The suspend method is called to warn the driver that the
301		device is going to be suspended.  If the driver returns a
302		negative error code, the suspend will be aborted.  Normally
303		the driver will return 0, in which case it must cancel all
304		outstanding URBs (usb_kill_urb()) and not submit any more.
305	
306		The resume method is called to tell the driver that the
307		device has been resumed and the driver can return to normal
308		operation.  URBs may once more be submitted.
309	
310		The reset_resume method is called to tell the driver that
311		the device has been resumed and it also has been reset.
312		The driver should redo any necessary device initialization,
313		since the device has probably lost most or all of its state
314		(although the interfaces will be in the same altsettings as
315		before the suspend).
316	
317	If the device is disconnected or powered down while it is suspended,
318	the disconnect method will be called instead of the resume or
319	reset_resume method.  This is also quite likely to happen when
320	waking up from hibernation, as many systems do not maintain suspend
321	current to the USB host controllers during hibernation.  (It's
322	possible to work around the hibernation-forces-disconnect problem by
323	using the USB Persist facility.)
324	
325	The reset_resume method is used by the USB Persist facility (see
326	Documentation/usb/persist.txt) and it can also be used under certain
327	circumstances when CONFIG_USB_PERSIST is not enabled.  Currently, if a
328	device is reset during a resume and the driver does not have a
329	reset_resume method, the driver won't receive any notification about
330	the resume.  Later kernels will call the driver's disconnect method;
331	2.6.23 doesn't do this.
332	
333	USB drivers are bound to interfaces, so their suspend and resume
334	methods get called when the interfaces are suspended or resumed.  In
335	principle one might want to suspend some interfaces on a device (i.e.,
336	force the drivers for those interface to stop all activity) without
337	suspending the other interfaces.  The USB core doesn't allow this; all
338	interfaces are suspended when the device itself is suspended and all
339	interfaces are resumed when the device is resumed.  It isn't possible
340	to suspend or resume some but not all of a device's interfaces.  The
341	closest you can come is to unbind the interfaces' drivers.
342	
343	
344		The driver interface for autosuspend and autoresume
345		---------------------------------------------------
346	
347	To support autosuspend and autoresume, a driver should implement all
348	three of the methods listed above.  In addition, a driver indicates
349	that it supports autosuspend by setting the .supports_autosuspend flag
350	in its usb_driver structure.  It is then responsible for informing the
351	USB core whenever one of its interfaces becomes busy or idle.  The
352	driver does so by calling these six functions:
353	
354		int  usb_autopm_get_interface(struct usb_interface *intf);
355		void usb_autopm_put_interface(struct usb_interface *intf);
356		int  usb_autopm_get_interface_async(struct usb_interface *intf);
357		void usb_autopm_put_interface_async(struct usb_interface *intf);
358		void usb_autopm_get_interface_no_resume(struct usb_interface *intf);
359		void usb_autopm_put_interface_no_suspend(struct usb_interface *intf);
360	
361	The functions work by maintaining a usage counter in the
362	usb_interface's embedded device structure.  When the counter is > 0
363	then the interface is deemed to be busy, and the kernel will not
364	autosuspend the interface's device.  When the usage counter is = 0
365	then the interface is considered to be idle, and the kernel may
366	autosuspend the device.
367	
368	Drivers need not be concerned about balancing changes to the usage
369	counter; the USB core will undo any remaining "get"s when a driver
370	is unbound from its interface.  As a corollary, drivers must not call
371	any of the usb_autopm_* functions after their disconnect() routine has
372	returned.
373	
374	Drivers using the async routines are responsible for their own
375	synchronization and mutual exclusion.
376	
377		usb_autopm_get_interface() increments the usage counter and
378		does an autoresume if the device is suspended.  If the
379		autoresume fails, the counter is decremented back.
380	
381		usb_autopm_put_interface() decrements the usage counter and
382		attempts an autosuspend if the new value is = 0.
383	
384		usb_autopm_get_interface_async() and
385		usb_autopm_put_interface_async() do almost the same things as
386		their non-async counterparts.  The big difference is that they
387		use a workqueue to do the resume or suspend part of their
388		jobs.  As a result they can be called in an atomic context,
389		such as an URB's completion handler, but when they return the
390		device will generally not yet be in the desired state.
391	
392		usb_autopm_get_interface_no_resume() and
393		usb_autopm_put_interface_no_suspend() merely increment or
394		decrement the usage counter; they do not attempt to carry out
395		an autoresume or an autosuspend.  Hence they can be called in
396		an atomic context.
397	
398	The simplest usage pattern is that a driver calls
399	usb_autopm_get_interface() in its open routine and
400	usb_autopm_put_interface() in its close or release routine.  But other
401	patterns are possible.
402	
403	The autosuspend attempts mentioned above will often fail for one
404	reason or another.  For example, the power/control attribute might be
405	set to "on", or another interface in the same device might not be
406	idle.  This is perfectly normal.  If the reason for failure was that
407	the device hasn't been idle for long enough, a timer is scheduled to
408	carry out the operation automatically when the autosuspend idle-delay
409	has expired.
410	
411	Autoresume attempts also can fail, although failure would mean that
412	the device is no longer present or operating properly.  Unlike
413	autosuspend, there's no idle-delay for an autoresume.
414	
415	
416		Other parts of the driver interface
417		-----------------------------------
418	
419	Drivers can enable autosuspend for their devices by calling
420	
421		usb_enable_autosuspend(struct usb_device *udev);
422	
423	in their probe() routine, if they know that the device is capable of
424	suspending and resuming correctly.  This is exactly equivalent to
425	writing "auto" to the device's power/control attribute.  Likewise,
426	drivers can disable autosuspend by calling
427	
428		usb_disable_autosuspend(struct usb_device *udev);
429	
430	This is exactly the same as writing "on" to the power/control attribute.
431	
432	Sometimes a driver needs to make sure that remote wakeup is enabled
433	during autosuspend.  For example, there's not much point
434	autosuspending a keyboard if the user can't cause the keyboard to do a
435	remote wakeup by typing on it.  If the driver sets
436	intf->needs_remote_wakeup to 1, the kernel won't autosuspend the
437	device if remote wakeup isn't available.  (If the device is already
438	autosuspended, though, setting this flag won't cause the kernel to
439	autoresume it.  Normally a driver would set this flag in its probe
440	method, at which time the device is guaranteed not to be
441	autosuspended.)
442	
443	If a driver does its I/O asynchronously in interrupt context, it
444	should call usb_autopm_get_interface_async() before starting output and
445	usb_autopm_put_interface_async() when the output queue drains.  When
446	it receives an input event, it should call
447	
448		usb_mark_last_busy(struct usb_device *udev);
449	
450	in the event handler.  This tells the PM core that the device was just
451	busy and therefore the next autosuspend idle-delay expiration should
452	be pushed back.  Many of the usb_autopm_* routines also make this call,
453	so drivers need to worry only when interrupt-driven input arrives.
454	
455	Asynchronous operation is always subject to races.  For example, a
456	driver may call the usb_autopm_get_interface_async() routine at a time
457	when the core has just finished deciding the device has been idle for
458	long enough but not yet gotten around to calling the driver's suspend
459	method.  The suspend method must be responsible for synchronizing with
460	the I/O request routine and the URB completion handler; it should
461	cause autosuspends to fail with -EBUSY if the driver needs to use the
462	device.
463	
464	External suspend calls should never be allowed to fail in this way,
465	only autosuspend calls.  The driver can tell them apart by applying
466	the PMSG_IS_AUTO() macro to the message argument to the suspend
467	method; it will return True for internal PM events (autosuspend) and
468	False for external PM events.
469	
470	
471		Mutual exclusion
472		----------------
473	
474	For external events -- but not necessarily for autosuspend or
475	autoresume -- the device semaphore (udev->dev.sem) will be held when a
476	suspend or resume method is called.  This implies that external
477	suspend/resume events are mutually exclusive with calls to probe,
478	disconnect, pre_reset, and post_reset; the USB core guarantees that
479	this is true of autosuspend/autoresume events as well.
480	
481	If a driver wants to block all suspend/resume calls during some
482	critical section, the best way is to lock the device and call
483	usb_autopm_get_interface() (and do the reverse at the end of the
484	critical section).  Holding the device semaphore will block all
485	external PM calls, and the usb_autopm_get_interface() will prevent any
486	internal PM calls, even if it fails.  (Exercise: Why?)
487	
488	
489		Interaction between dynamic PM and system PM
490		--------------------------------------------
491	
492	Dynamic power management and system power management can interact in
493	a couple of ways.
494	
495	Firstly, a device may already be autosuspended when a system suspend
496	occurs.  Since system suspends are supposed to be as transparent as
497	possible, the device should remain suspended following the system
498	resume.  But this theory may not work out well in practice; over time
499	the kernel's behavior in this regard has changed.  As of 2.6.37 the
500	policy is to resume all devices during a system resume and let them
501	handle their own runtime suspends afterward.
502	
503	Secondly, a dynamic power-management event may occur as a system
504	suspend is underway.  The window for this is short, since system
505	suspends don't take long (a few seconds usually), but it can happen.
506	For example, a suspended device may send a remote-wakeup signal while
507	the system is suspending.  The remote wakeup may succeed, which would
508	cause the system suspend to abort.  If the remote wakeup doesn't
509	succeed, it may still remain active and thus cause the system to
510	resume as soon as the system suspend is complete.  Or the remote
511	wakeup may fail and get lost.  Which outcome occurs depends on timing
512	and on the hardware and firmware design.
513	
514	
515		xHCI hardware link PM
516		---------------------
517	
518	xHCI host controller provides hardware link power management to usb2.0
519	(xHCI 1.0 feature) and usb3.0 devices which support link PM. By
520	enabling hardware LPM, the host can automatically put the device into
521	lower power state(L1 for usb2.0 devices, or U1/U2 for usb3.0 devices),
522	which state device can enter and resume very quickly.
523	
524	The user interface for controlling hardware LPM is located in the
525	power/ subdirectory of each USB device's sysfs directory, that is, in
526	/sys/bus/usb/devices/.../power/ where "..." is the device's ID. The
527	relevant attribute files are usb2_hardware_lpm and usb3_hardware_lpm.
528	
529		power/usb2_hardware_lpm
530	
531			When a USB2 device which support LPM is plugged to a
532			xHCI host root hub which support software LPM, the
533			host will run a software LPM test for it; if the device
534			enters L1 state and resume successfully and the host
535			supports USB2 hardware LPM, this file will show up and
536			driver will enable hardware LPM	for the device. You
537			can write y/Y/1 or n/N/0 to the file to	enable/disable
538			USB2 hardware LPM manually. This is for	test purpose mainly.
539	
540		power/usb3_hardware_lpm_u1
541		power/usb3_hardware_lpm_u2
542	
543			When a USB 3.0 lpm-capable device is plugged in to a
544			xHCI host which supports link PM, it will check if U1
545			and U2 exit latencies have been set in the BOS
546			descriptor; if the check is is passed and the host
547			supports USB3 hardware LPM, USB3 hardware LPM will be
548			enabled for the device and these files will be created.
549			The files hold a string value (enable or disable)
550			indicating whether or not USB3 hardware LPM U1 or U2
551			is enabled for the device.
552	
553		USB Port Power Control
554		----------------------
555	
556	In addition to suspending endpoint devices and enabling hardware
557	controlled link power management, the USB subsystem also has the
558	capability to disable power to ports under some conditions.  Power is
559	controlled through Set/ClearPortFeature(PORT_POWER) requests to a hub.
560	In the case of a root or platform-internal hub the host controller
561	driver translates PORT_POWER requests into platform firmware (ACPI)
562	method calls to set the port power state. For more background see the
563	Linux Plumbers Conference 2012 slides [1] and video [2]:
564	
565	Upon receiving a ClearPortFeature(PORT_POWER) request a USB port is
566	logically off, and may trigger the actual loss of VBUS to the port [3].
567	VBUS may be maintained in the case where a hub gangs multiple ports into
568	a shared power well causing power to remain until all ports in the gang
569	are turned off.  VBUS may also be maintained by hub ports configured for
570	a charging application.  In any event a logically off port will lose
571	connection with its device, not respond to hotplug events, and not
572	respond to remote wakeup events*.
573	
574	WARNING: turning off a port may result in the inability to hot add a device.
575	Please see "User Interface for Port Power Control" for details.
576	
577	As far as the effect on the device itself it is similar to what a device
578	goes through during system suspend, i.e. the power session is lost.  Any
579	USB device or driver that misbehaves with system suspend will be
580	similarly affected by a port power cycle event.  For this reason the
581	implementation shares the same device recovery path (and honors the same
582	quirks) as the system resume path for the hub.
583	
584	[1]: http://dl.dropbox.com/u/96820575/sarah-sharp-lpt-port-power-off2-mini.pdf
585	[2]: http://linuxplumbers.ubicast.tv/videos/usb-port-power-off-kerneluserspace-api/
586	[3]: USB 3.1 Section 10.12
587	* wakeup note: if a device is configured to send wakeup events the port
588	  power control implementation will block poweroff attempts on that
589	  port.
590	
591	
592		User Interface for Port Power Control
593		-------------------------------------
594	
595	The port power control mechanism uses the PM runtime system.  Poweroff is
596	requested by clearing the power/pm_qos_no_power_off flag of the port device
597	(defaults to 1).  If the port is disconnected it will immediately receive a
598	ClearPortFeature(PORT_POWER) request.  Otherwise, it will honor the pm runtime
599	rules and require the attached child device and all descendants to be suspended.
600	This mechanism is dependent on the hub advertising port power switching in its
601	hub descriptor (wHubCharacteristics logical power switching mode field).
602	
603	Note, some interface devices/drivers do not support autosuspend.  Userspace may
604	need to unbind the interface drivers before the usb_device will suspend.  An
605	unbound interface device is suspended by default.  When unbinding, be careful
606	to unbind interface drivers, not the driver of the parent usb device.  Also,
607	leave hub interface drivers bound.  If the driver for the usb device (not
608	interface) is unbound the kernel is no longer able to resume the device.  If a
609	hub interface driver is unbound, control of its child ports is lost and all
610	attached child-devices will disconnect.  A good rule of thumb is that if the
611	'driver/module' link for a device points to /sys/module/usbcore then unbinding
612	it will interfere with port power control.
613	
614	Example of the relevant files for port power control.  Note, in this example
615	these files are relative to a usb hub device (prefix).
616	
617	     prefix=/sys/devices/pci0000:00/0000:00:14.0/usb3/3-1
618	
619	                      attached child device +
620	                  hub port device +         |
621	     hub interface device +       |         |
622	                          v       v         v
623	                  $prefix/3-1:1.0/3-1-port1/device
624	
625	     $prefix/3-1:1.0/3-1-port1/power/pm_qos_no_power_off
626	     $prefix/3-1:1.0/3-1-port1/device/power/control
627	     $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intf0>/driver/unbind
628	     $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intf1>/driver/unbind
629	     ...
630	     $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intfN>/driver/unbind
631	
632	In addition to these files some ports may have a 'peer' link to a port on
633	another hub.  The expectation is that all superspeed ports have a
634	hi-speed peer.
635	
636	$prefix/3-1:1.0/3-1-port1/peer -> ../../../../usb2/2-1/2-1:1.0/2-1-port1
637	../../../../usb2/2-1/2-1:1.0/2-1-port1/peer -> ../../../../usb3/3-1/3-1:1.0/3-1-port1
638	
639	Distinct from 'companion ports', or 'ehci/xhci shared switchover ports'
640	peer ports are simply the hi-speed and superspeed interface pins that
641	are combined into a single usb3 connector.  Peer ports share the same
642	ancestor XHCI device.
643	
644	While a superspeed port is powered off a device may downgrade its
645	connection and attempt to connect to the hi-speed pins.  The
646	implementation takes steps to prevent this:
647	
648	1/ Port suspend is sequenced to guarantee that hi-speed ports are powered-off
649	   before their superspeed peer is permitted to power-off.  The implication is
650	   that the setting pm_qos_no_power_off to zero on a superspeed port may not cause
651	   the port to power-off until its highspeed peer has gone to its runtime suspend
652	   state.  Userspace must take care to order the suspensions if it wants to
653	   guarantee that a superspeed port will power-off.
654	
655	2/ Port resume is sequenced to force a superspeed port to power-on prior to its
656	   highspeed peer.
657	
658	3/ Port resume always triggers an attached child device to resume.  After a
659	   power session is lost the device may have been removed, or need reset.
660	   Resuming the child device when the parent port regains power resolves those
661	   states and clamps the maximum port power cycle frequency at the rate the child
662	   device can suspend (autosuspend-delay) and resume (reset-resume latency).
663	
664	Sysfs files relevant for port power control:
665		<hubdev-portX>/power/pm_qos_no_power_off:
666			This writable flag controls the state of an idle port.
667			Once all children and descendants have suspended the
668			port may suspend/poweroff provided that
669			pm_qos_no_power_off is '0'.  If pm_qos_no_power_off is
670			'1' the port will remain active/powered regardless of
671			the stats of descendants.  Defaults to 1.
672	
673		<hubdev-portX>/power/runtime_status:
674			This file reflects whether the port is 'active' (power is on)
675			or 'suspended' (logically off).  There is no indication to
676			userspace whether VBUS is still supplied.
677	
678		<hubdev-portX>/connect_type:
679			An advisory read-only flag to userspace indicating the
680			location and connection type of the port.  It returns
681			one of four values 'hotplug', 'hardwired', 'not used',
682			and 'unknown'.  All values, besides unknown, are set by
683			platform firmware.
684	
685			"hotplug" indicates an externally connectable/visible
686			port on the platform.  Typically userspace would choose
687			to keep such a port powered to handle new device
688			connection events.
689	
690			"hardwired" refers to a port that is not visible but
691			connectable. Examples are internal ports for USB
692			bluetooth that can be disconnected via an external
693			switch or a port with a hardwired USB camera.  It is
694			expected to be safe to allow these ports to suspend
695			provided pm_qos_no_power_off is coordinated with any
696			switch that gates connections.  Userspace must arrange
697			for the device to be connected prior to the port
698			powering off, or to activate the port prior to enabling
699			connection via a switch.
700	
701			"not used" refers to an internal port that is expected
702			to never have a device connected to it.  These may be
703			empty internal ports, or ports that are not physically
704			exposed on a platform.  Considered safe to be
705			powered-off at all times.
706	
707			"unknown" means platform firmware does not provide
708			information for this port.  Most commonly refers to
709			external hub ports which should be considered 'hotplug'
710			for policy decisions.
711	
712			NOTE1: since we are relying on the BIOS to get this ACPI
713			information correct, the USB port descriptions may be
714			missing or wrong.
715	
716			NOTE2: Take care in clearing pm_qos_no_power_off.  Once
717			power is off this port will
718			not respond to new connect events.
719	
720		Once a child device is attached additional constraints are
721		applied before the port is allowed to poweroff.
722	
723		<child>/power/control:
724			Must be 'auto', and the port will not
725			power down until <child>/power/runtime_status
726			reflects the 'suspended' state.  Default
727			value is controlled by child device driver.
728	
729		<child>/power/persist:
730			This defaults to '1' for most devices and indicates if
731			kernel can persist the device's configuration across a
732			power session loss (suspend / port-power event).  When
733			this value is '0' (quirky devices), port poweroff is
734			disabled.
735	
736		<child>/driver/unbind:
737			Wakeup capable devices will block port poweroff.  At
738			this time the only mechanism to clear the usb-internal
739			wakeup-capability for an interface device is to unbind
740			its driver.
741	
742	Summary of poweroff pre-requisite settings relative to a port device:
743	
744		echo 0 > power/pm_qos_no_power_off
745		echo 0 > peer/power/pm_qos_no_power_off # if it exists
746		echo auto > power/control # this is the default value
747		echo auto > <child>/power/control
748		echo 1 > <child>/power/persist # this is the default value
749	
750		Suggested Userspace Port Power Policy
751		-------------------------------------
752	
753	As noted above userspace needs to be careful and deliberate about what
754	ports are enabled for poweroff.
755	
756	The default configuration is that all ports start with
757	power/pm_qos_no_power_off set to '1' causing ports to always remain
758	active.
759	
760	Given confidence in the platform firmware's description of the ports
761	(ACPI _PLD record for a port populates 'connect_type') userspace can
762	clear pm_qos_no_power_off for all 'not used' ports.  The same can be
763	done for 'hardwired' ports provided poweroff is coordinated with any
764	connection switch for the port.
765	
766	A more aggressive userspace policy is to enable USB port power off for
767	all ports (set <hubdev-portX>/power/pm_qos_no_power_off to '0') when
768	some external factor indicates the user has stopped interacting with the
769	system.  For example, a distro may want to enable power off all USB
770	ports when the screen blanks, and re-power them when the screen becomes
771	active.  Smart phones and tablets may want to power off USB ports when
772	the user pushes the power button.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog