About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / usb / power-management.txt

Custom Search

Based on kernel version 4.3. Page generated on 2015-11-02 12:51 EST.

1				Power Management for USB
3			 Alan Stern <stern@rowland.harvard.edu>
5			       Last-updated: February 2014
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
28		What is Power Management?
29		-------------------------
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.)
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).
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.
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.]
61		What is Remote Wakeup?
62		----------------------
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.
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.
79		When is a USB device idle?
80		--------------------------
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.
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.
95		Forms of dynamic PM
96		-------------------
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.
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.
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.
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.
128		The user interface for dynamic PM
129		---------------------------------
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.)
143		power/wakeup
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.)
154		power/control
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.
160			"on" means that the device should be resumed and
161			autosuspend is not allowed.  (Of course, system
162			suspends are still allowed.)
164			"auto" is the normal state in which the kernel is
165			allowed to autosuspend and autoresume the device.
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.)
172		power/autosuspend_delay_ms
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.
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.
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.)
196		Changing the default idle-delay time
197		------------------------------------
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:
204		modprobe usbcore autosuspend=5
206	Equivalently, you could add to a configuration file in /etc/modprobe.d
207	a line saying:
209		options usbcore autosuspend=5
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.
216	If usbcore is compiled into the kernel rather than built as a loadable
217	module, you can add
219		usbcore.autosuspend=5
221	to the kernel's boot command line.
223	Finally, the parameter value can be changed while the system is
224	running.  If you do:
226		echo 5 >/sys/module/usbcore/parameters/autosuspend
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.)
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.
237		Warnings
238		--------
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.
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.
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.)
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.
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.
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.
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.
287		The driver interface for Power Management
288		-----------------------------------------
290	The requirements for a USB driver to support external power management
291	are pretty modest; the driver need only define
293		.suspend
294		.resume
295		.reset_resume
297	methods in its usb_driver structure, and the reset_resume method is
298	optional.  The methods' jobs are quite simple:
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.
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.
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).
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.)
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.
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.
344		The driver interface for autosuspend and autoresume
345		---------------------------------------------------
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:
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);
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.
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.
374	Drivers using the async routines are responsible for their own
375	synchronization and mutual exclusion.
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.
381		usb_autopm_put_interface() decrements the usage counter and
382		attempts an autosuspend if the new value is = 0.
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.
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.
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.
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.
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.
416		Other parts of the driver interface
417		-----------------------------------
419	Drivers can enable autosuspend for their devices by calling
421		usb_enable_autosuspend(struct usb_device *udev);
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
428		usb_disable_autosuspend(struct usb_device *udev);
430	This is exactly the same as writing "on" to the power/control attribute.
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.)
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
448		usb_mark_last_busy(struct usb_device *udev);
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.
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.
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.
471		Mutual exclusion
472		----------------
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.
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?)
489		Interaction between dynamic PM and system PM
490		--------------------------------------------
492	Dynamic power management and system power management can interact in
493	a couple of ways.
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.
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.
515		xHCI hardware link PM
516		---------------------
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.
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.
529		power/usb2_hardware_lpm
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.
540		power/usb3_hardware_lpm
542			When a USB 3.0 lpm-capable device is plugged in to a
543			xHCI host which supports link PM, it will check if U1
544			and U2 exit latencies have been set in the BOS
545			descriptor; if the check is is passed and the host
546			supports USB3 hardware LPM, USB3 hardware LPM will be
547			enabled for the device and this file will be created.
548			The file holds a string value (enable or disable)
549			indicating whether or not USB3 hardware LPM is
550			enabled for the device.
552		USB Port Power Control
553		----------------------
555	In addition to suspending endpoint devices and enabling hardware
556	controlled link power management, the USB subsystem also has the
557	capability to disable power to ports under some conditions.  Power is
558	controlled through Set/ClearPortFeature(PORT_POWER) requests to a hub.
559	In the case of a root or platform-internal hub the host controller
560	driver translates PORT_POWER requests into platform firmware (ACPI)
561	method calls to set the port power state. For more background see the
562	Linux Plumbers Conference 2012 slides [1] and video [2]:
564	Upon receiving a ClearPortFeature(PORT_POWER) request a USB port is
565	logically off, and may trigger the actual loss of VBUS to the port [3].
566	VBUS may be maintained in the case where a hub gangs multiple ports into
567	a shared power well causing power to remain until all ports in the gang
568	are turned off.  VBUS may also be maintained by hub ports configured for
569	a charging application.  In any event a logically off port will lose
570	connection with its device, not respond to hotplug events, and not
571	respond to remote wakeup events*.
573	WARNING: turning off a port may result in the inability to hot add a device.
574	Please see "User Interface for Port Power Control" for details.
576	As far as the effect on the device itself it is similar to what a device
577	goes through during system suspend, i.e. the power session is lost.  Any
578	USB device or driver that misbehaves with system suspend will be
579	similarly affected by a port power cycle event.  For this reason the
580	implementation shares the same device recovery path (and honors the same
581	quirks) as the system resume path for the hub.
583	[1]: http://dl.dropbox.com/u/96820575/sarah-sharp-lpt-port-power-off2-mini.pdf
584	[2]: http://linuxplumbers.ubicast.tv/videos/usb-port-power-off-kerneluserspace-api/
585	[3]: USB 3.1 Section 10.12
586	* wakeup note: if a device is configured to send wakeup events the port
587	  power control implementation will block poweroff attempts on that
588	  port.
591		User Interface for Port Power Control
592		-------------------------------------
594	The port power control mechanism uses the PM runtime system.  Poweroff is
595	requested by clearing the power/pm_qos_no_power_off flag of the port device
596	(defaults to 1).  If the port is disconnected it will immediately receive a
597	ClearPortFeature(PORT_POWER) request.  Otherwise, it will honor the pm runtime
598	rules and require the attached child device and all descendants to be suspended.
599	This mechanism is dependent on the hub advertising port power switching in its
600	hub descriptor (wHubCharacteristics logical power switching mode field).
602	Note, some interface devices/drivers do not support autosuspend.  Userspace may
603	need to unbind the interface drivers before the usb_device will suspend.  An
604	unbound interface device is suspended by default.  When unbinding, be careful
605	to unbind interface drivers, not the driver of the parent usb device.  Also,
606	leave hub interface drivers bound.  If the driver for the usb device (not
607	interface) is unbound the kernel is no longer able to resume the device.  If a
608	hub interface driver is unbound, control of its child ports is lost and all
609	attached child-devices will disconnect.  A good rule of thumb is that if the
610	'driver/module' link for a device points to /sys/module/usbcore then unbinding
611	it will interfere with port power control.
613	Example of the relevant files for port power control.  Note, in this example
614	these files are relative to a usb hub device (prefix).
616	     prefix=/sys/devices/pci0000:00/0000:00:14.0/usb3/3-1
618	                      attached child device +
619	                  hub port device +         |
620	     hub interface device +       |         |
621	                          v       v         v
622	                  $prefix/3-1:1.0/3-1-port1/device
624	     $prefix/3-1:1.0/3-1-port1/power/pm_qos_no_power_off
625	     $prefix/3-1:1.0/3-1-port1/device/power/control
626	     $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intf0>/driver/unbind
627	     $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intf1>/driver/unbind
628	     ...
629	     $prefix/3-1:1.0/3-1-port1/device/3-1.1:<intfN>/driver/unbind
631	In addition to these files some ports may have a 'peer' link to a port on
632	another hub.  The expectation is that all superspeed ports have a
633	hi-speed peer.
635	$prefix/3-1:1.0/3-1-port1/peer -> ../../../../usb2/2-1/2-1:1.0/2-1-port1
636	../../../../usb2/2-1/2-1:1.0/2-1-port1/peer -> ../../../../usb3/3-1/3-1:1.0/3-1-port1
638	Distinct from 'companion ports', or 'ehci/xhci shared switchover ports'
639	peer ports are simply the hi-speed and superspeed interface pins that
640	are combined into a single usb3 connector.  Peer ports share the same
641	ancestor XHCI device.
643	While a superspeed port is powered off a device may downgrade its
644	connection and attempt to connect to the hi-speed pins.  The
645	implementation takes steps to prevent this:
647	1/ Port suspend is sequenced to guarantee that hi-speed ports are powered-off
648	   before their superspeed peer is permitted to power-off.  The implication is
649	   that the setting pm_qos_no_power_off to zero on a superspeed port may not cause
650	   the port to power-off until its highspeed peer has gone to its runtime suspend
651	   state.  Userspace must take care to order the suspensions if it wants to
652	   guarantee that a superspeed port will power-off.
654	2/ Port resume is sequenced to force a superspeed port to power-on prior to its
655	   highspeed peer.
657	3/ Port resume always triggers an attached child device to resume.  After a
658	   power session is lost the device may have been removed, or need reset.
659	   Resuming the child device when the parent port regains power resolves those
660	   states and clamps the maximum port power cycle frequency at the rate the child
661	   device can suspend (autosuspend-delay) and resume (reset-resume latency).
663	Sysfs files relevant for port power control:
664		<hubdev-portX>/power/pm_qos_no_power_off:
665			This writable flag controls the state of an idle port.
666			Once all children and descendants have suspended the
667			port may suspend/poweroff provided that
668			pm_qos_no_power_off is '0'.  If pm_qos_no_power_off is
669			'1' the port will remain active/powered regardless of
670			the stats of descendants.  Defaults to 1.
672		<hubdev-portX>/power/runtime_status:
673			This file reflects whether the port is 'active' (power is on)
674			or 'suspended' (logically off).  There is no indication to
675			userspace whether VBUS is still supplied.
677		<hubdev-portX>/connect_type:
678			An advisory read-only flag to userspace indicating the
679			location and connection type of the port.  It returns
680			one of four values 'hotplug', 'hardwired', 'not used',
681			and 'unknown'.  All values, besides unknown, are set by
682			platform firmware.
684			"hotplug" indicates an externally connectable/visible
685			port on the platform.  Typically userspace would choose
686			to keep such a port powered to handle new device
687			connection events.
689			"hardwired" refers to a port that is not visible but
690			connectable. Examples are internal ports for USB
691			bluetooth that can be disconnected via an external
692			switch or a port with a hardwired USB camera.  It is
693			expected to be safe to allow these ports to suspend
694			provided pm_qos_no_power_off is coordinated with any
695			switch that gates connections.  Userspace must arrange
696			for the device to be connected prior to the port
697			powering off, or to activate the port prior to enabling
698			connection via a switch.
700			"not used" refers to an internal port that is expected
701			to never have a device connected to it.  These may be
702			empty internal ports, or ports that are not physically
703			exposed on a platform.  Considered safe to be
704			powered-off at all times.
706			"unknown" means platform firmware does not provide
707			information for this port.  Most commonly refers to
708			external hub ports which should be considered 'hotplug'
709			for policy decisions.
711			NOTE1: since we are relying on the BIOS to get this ACPI
712			information correct, the USB port descriptions may be
713			missing or wrong.
715			NOTE2: Take care in clearing pm_qos_no_power_off.  Once
716			power is off this port will
717			not respond to new connect events.
719		Once a child device is attached additional constraints are
720		applied before the port is allowed to poweroff.
722		<child>/power/control:
723			Must be 'auto', and the port will not
724			power down until <child>/power/runtime_status
725			reflects the 'suspended' state.  Default
726			value is controlled by child device driver.
728		<child>/power/persist:
729			This defaults to '1' for most devices and indicates if
730			kernel can persist the device's configuration across a
731			power session loss (suspend / port-power event).  When
732			this value is '0' (quirky devices), port poweroff is
733			disabled.
735		<child>/driver/unbind:
736			Wakeup capable devices will block port poweroff.  At
737			this time the only mechanism to clear the usb-internal
738			wakeup-capability for an interface device is to unbind
739			its driver.
741	Summary of poweroff pre-requisite settings relative to a port device:
743		echo 0 > power/pm_qos_no_power_off
744		echo 0 > peer/power/pm_qos_no_power_off # if it exists
745		echo auto > power/control # this is the default value
746		echo auto > <child>/power/control
747		echo 1 > <child>/power/persist # this is the default value
749		Suggested Userspace Port Power Policy
750		-------------------------------------
752	As noted above userspace needs to be careful and deliberate about what
753	ports are enabled for poweroff.
755	The default configuration is that all ports start with
756	power/pm_qos_no_power_off set to '1' causing ports to always remain
757	active.
759	Given confidence in the platform firmware's description of the ports
760	(ACPI _PLD record for a port populates 'connect_type') userspace can
761	clear pm_qos_no_power_off for all 'not used' ports.  The same can be
762	done for 'hardwired' ports provided poweroff is coordinated with any
763	connection switch for the port.
765	A more aggressive userspace policy is to enable USB port power off for
766	all ports (set <hubdev-portX>/power/pm_qos_no_power_off to '0') when
767	some external factor indicates the user has stopped interacting with the
768	system.  For example, a distro may want to enable power off all USB
769	ports when the screen blanks, and re-power them when the screen becomes
770	active.  Smart phones and tablets may want to power off USB ports when
771	the user pushes the power button.
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.