USB: Documentation for USB port power off mechanismsusb3-port-power-v2

Describe the mechanisms for controlling port power policy and
discovering the port power state.

Signed-off-by: Lan Tianyu <tianyu.lan@intel.com>
[sarah: wordsmithing]
Signed-off-by: Sarah Sharp <sarah.a.sharp@linux.intel.com>
[djbw: updates for device model, hotplug, and rework changes]
Signed-off-by: Dan Williams <dan.j.williams@intel.com>

1 files changed, 208 insertions, 0 deletions

diff --git a/Documentation/usb/power-management.txt b/Documentation/usb/power-management.txt
index 1392b61d6ebe59..d683b2eebfd134 100644
--- a/Documentation/usb/power-management.txt
+++ b/Documentation/usb/power-management.txt
@@ -1,3 +1,4 @@
+
 			Power Management for USB
 
 		 Alan Stern <stern@rowland.harvard.edu>
@@ -5,6 +6,25 @@
 			    October 28, 2010
 
 
+	Contents:
+	---------
+	* What is Power Management?
+	* What is Remote Wakeup?
+	* When is a USB device idle?
+	* Forms of dynamic PM
+	* The user interface for dynamic PM
+	* Changing the default idle-delay time
+	* Warnings
+	* The driver interface for Power Management
+	* The driver interface for autosuspend and autoresume
+	* Other parts of the driver interface
+	* Mutual exclusion
+	* Interaction between dynamic PM and system PM
+	* xHCI hardware link PM
+	* USB Port Power Control
+	* User Interface for Port Power Control
+	* Suggested Userspace Port Power Policy
+
 
 	What is Power Management?
 	-------------------------
@@ -516,3 +536,191 @@ relevant attribute files is usb2_hardware_lpm.
 		driver will enable hardware LPM	for the device. You
 		can write y/Y/1 or n/N/0 to the file to	enable/disable
 		USB2 hardware LPM manually. This is for	test purpose mainly.
+
+
+	USB Port Power Control
+	----------------------
+
+In addition to suspending endpoint devices and enabling hardware
+controlled link power management, the USB subsystem also has the
+capability to disable power to individual ports.  Power is controlled
+through Set/ClearPortFeature(PORT_POWER) requests to a hub.  In the case
+of a root or platform-internal hub the host controller driver translates
+PORT_POWER requests into platform firmware (ACPI) method calls to set
+the port power state. For more background see the Linux Plumbers
+Conference 2012 slides [1] and video [2]:
+
+Upon receiving a ClearPortFeature(PORT_POWER) request a USB port is
+logically off, and may trigger the actual loss of VBUS to the port [3].
+The reason VBUS is not immediately lost is due to the fact that hubs are
+allowed to gang multiple ports into a shared power well causing power to
+remain until all ports in the gang are turned off.  In any event a
+logically off port will lose connection with its device, not respond
+to hotplug events, and not respond to remote wakeup events.
+
+WARNING: turning off a port may result in the inability to wake the
+system or hot add a device.  There are safeguards to prevent this, but
+please see "User Interface for Port Power Control" for details.
+
+As far as the effect on the device itself it is similar to what a device
+goes through during system suspend, i.e. the power session is lost.  Any
+USB device or driver that misbehaves with system suspend will be
+similarly affected by a port power cycle event.  For this reason the
+implementation shares the same device recovery path (and honors the same
+quirks) as the system resume path for the hub.
+
+[1]: http://dl.dropbox.com/u/96820575/sarah-sharp-lpt-port-power-off2-mini.pdf
+[2]: http://linuxplumbers.ubicast.tv/videos/usb-port-power-off-kerneluserspace-api/
+[3]: USB 3.1 Section 10.12
+
+
+	User Interface for Port Power Control
+	-------------------------------------
+
+The port power control mechanism uses the same dynamic PM mechanisms
+used for autosuspending USB devices.  A port device sits between the hub
+and the connected device in the device model.  For example:
+
+                                                   child device +
+                                              port device +     |
+                                       parent hub +       |     |
+                                                  v       v     v
+	/sys/devices/pci0000:00/0000:00:14.0/usb2/2-0:1.0/port1/2-1
+
+Per the dynamic PM rules the port will be held active as long as the
+child device is active, once the child goes idle several other
+constraints must be met before the port will be powered off.  Here are
+the files relative to the port device that affect the power state:
+
+	power/power_state:
+		This read-only file reflects the current
+		reason the port is being powered, or 'off' if port is
+		powered down:
+
+		'active': attached child device is actively using the
+			  port
+		'pm_qos_no_power_off': child inactive, pm qos flag keeps
+				       power enabled
+		'hotplug': child inactive, remaining powered to detect
+			   hotplug events
+		'wakeup enabled': child inactive, port kept powered to
+				  handle remote wakeup events
+		'persist disabled': child inactive, but child device
+				    will not cleanly recover from a
+				    suspend/resume cycle
+		'off': port power is off
+
+	power/runtime_status:
+		This file reflects whether the port is 'active' or
+		'suspended'.  Hubs are allowed to suspend with power
+		still enabled on their ports, so when this file returns
+		'suspended' one must look at power/power_state to see if
+		power is on.
+
+	power/pm_qos_no_power_off:
+		This writable flag is a global enable / disable for port
+		power management.  Once this file is set to '0' poweroff
+		may occur once all other constraints are met.  This
+		defaults to '1'.
+
+	power/control:
+		This file is writable and can be set to
+		'auto' (the default) to let the kernel power down the
+		device when it is idle, or 'on' to disable power
+		management and keep the port powered.
+
+	connect_type:
+		This writable file reflects the capability of the
+		connection to respond to hotplug events.  It returns one
+		of four values 'hotplug', 'hardwired', 'not used', and
+		'unknown'.  The default value is populated by platform
+		firmware, and for all but the 'hardwired' type hotplug
+		support is enabled.  One can write 'hardwired' to turn
+		off hotplug (allow the port to power down), or 'hotplug'
+		to keep the port powered.  The other types can not be
+		written to the file.
+
+		Details on the connection type:
+		"hotplug" refers to a port on the outside of a laptop
+		which is visible and connectable.
+
+		"hardwired" refers to a port that is not visible but
+		connectable. Examples are internal ports for USB
+		bluetooth that can be disconnected via an external
+		switch or a port with a hardwired USB camera.
+
+		"not used" refers to internal port that will never have
+		a device connected to it.  These may be empty internal
+		ports, or ports that are not physically
+		exposed on a platform.
+
+		"unknown" means platform does not provide information
+		for this port.
+
+		NOTE1: since we are relying on the BIOS to get this ACPI
+		information correct, the USB port descriptions may be
+		missing or wrong.
+
+		NOTE2: Take care in writing 'hardwired'.  Once power is
+		off this port will not respond to new connect events.
+
+	Once a child device is attached additional constraints are
+	applied before the port is allowed to poweroff.
+
+	<child>/power/control:
+		Must be 'auto', and the port will not
+		power down <child>/power/runtime_status
+		reflects the 'suspended' state.  Default
+		value is controlled by child device driver.
+
+	<child>/power/wakeup:
+		This controls whether the <child> device
+		is configured as a wakeup source for the
+		system.  When this file returns '1' wakeup is enabled
+		and the port will remain powered to receive remote
+		wakeup events.  Writing '0' to this file enables
+		poweroff.  Default value is controlled by child device
+		driver.
+
+		NOTE: Take care to have an alternate means of waking the
+		system when disabling a wakeup source, or be sure that
+		the system will not transition to a sleep state.
+
+	<child>/power/persist:
+		This defaults to '1' for most devices and indicates if
+		kernel can persist the device's configuration across a
+		power session loss (suspend / port-power event).  When
+		this value is '0' (quirky devices), port poweroff is
+		disabled.
+
+Summary of poweroff pre-requisite settings:
+
+	echo 0 > power/pm_qos_no_power_off
+	echo auto > power/control
+	echo hardwired > connect_type
+	echo auto > <child>/power/control
+	echo 0 > <child>/power/wakeup
+	echo 1 > <child>/power/persist
+
+	Suggested Userspace Port Power Policy
+	-------------------------------------
+
+As noted above userspace needs to be careful and deliberate about what
+ports are enabled for poweroff.
+
+The default configuration is that all ports start with
+power/pm_qos_no_power_off set to '1' causing no port power management to
+occur.
+
+Given good confidence in the platform firmware (ACPI _PLD record for the
+USB ports) userspace can blindly set all occurrences of
+portX/power/pm_qos_no_power_off to '0'.  Then port power management will
+only be enabled for those ports that firmware has marked as 'hardwired'.
+
+A more aggressive userspace policy would be to enable USB port power off
+for all ports (set portX/power/pm_qos_no_power_off to '0' and
+set portX/connect_type to 'hardwired') when some external factor indicates
+the user has stopped interacting with the system.  For example, a distro
+may want to enable power off all USB ports when the screen blanks, and
+re-power them when the screen becomes active.  Smart phones and tablets
+may want to power off USB ports when the user pushes the power button.