From: Lan Tianyu <tianyu....@intel.com>
describe the mechanisms for controlling port power policy and
discovering the port power state.
Cc: Oliver Neukum <oneu...@suse.de>
[oliver]: fixes, clarification of wakeup vs port-power-control
Signed-off-by: Lan Tianyu <tianyu....@intel.com>
[sarah]: wordsmithing
[djbw]: updates for peer port changes
Signed-off-by: Dan Williams <dan.j.willi...@intel.com>
---
Documentation/usb/power-management.txt | 242 ++++++++++++++++++++++++++++++++
1 files changed, 240 insertions(+), 2 deletions(-)
diff --git a/Documentation/usb/power-management.txt
b/Documentation/usb/power-management.txt
index 1392b61d6ebe..6c3e0f04f6cb 100644
--- a/Documentation/usb/power-management.txt
+++ b/Documentation/usb/power-management.txt
@@ -2,8 +2,27 @@
Alan Stern <st...@rowland.harvard.edu>
- October 28, 2010
-
+ Last-updated: February 2014
+
+
+ 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 +535,222 @@ 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 ports under some conditions. 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].
+VBUS may be maintained in the case where a hub gangs multiple ports into
+a shared power well causing power to remain until all ports in the gang
+are turned off. VBUS may also be maintained by hub ports configured for
+a charging application. 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 hot add a device.
+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
+* wakeup note: if a device is configured to send wakeup events the port
+ power control implementation will block poweroff attempts on that
+ port.
+
+
+ User Interface for Port Power Control
+ -------------------------------------
+
+The port power control mechanism uses the PM runtime system. Poweroff is
+requested by clearing the power/pm_qos_no_power_off flag of the port device
+(defaults to 1). If the port is disconnected it will immediately receive a
+ClearPortFeature(PORT_POWER) request. Otherwise, it will honor the pm runtime
+rules and require the attached child device and all descendants to be
suspended.
+This mechanism is dependent on the hub advertising port power switching in its
+hub descriptor (wHubCharacteristics logical power switching mode field).
+
+Note, some interface devices/drivers do not support autosuspend. Userspace may
+need to unbind the interface drivers before the usb_device will suspend. An
+unbound interface device is suspended by default. When unbinding, be careful
+to unbind interface drivers, not the driver of the parent usb device. Also,
+leave hub interface drivers bound. If the driver for the usb device (not
+interface) is unbound the kernel is no longer able to resume the device. If a
+hub interface driver is unbound, control of its child ports is lost and all
+attached child-devices will disconnect. A good rule of thumb is that if the
+'driver/module' link for a device points to /sys/module/usbcore then unbinding
+it will interfere with port power control.
+
+Example of the relevant files for port power control.
+
+ child device link +
+ port device + |
+ parent hub + | |
+ v v v
+ /sys/bus/devices/usb2/2-0:1.0/port1/device
+
+ /sys/bus/devices/usb2/2-0:1.0/port1/power/pm_qos_no_power_off
+ /sys/bus/devices/usb2/2-0:1.0/port1/device/power/control
+ /sys/bus/devices/usb2/2-0:1.0/port1/device/2-1:<intf0>/driver/unbind
+ /sys/bus/devices/usb2/2-0:1.0/port1/device/2-1:<intf1>/driver/unbind
+ ...
+ /sys/bus/devices/usb2/2-0:1.0/port1/device/2-1:<intfN>/driver/unbind
+
+In addition to these files some ports may have a 'peer' link to a port on
+another hub. The expectation is that all superspeed ports have a
+hi-speed peer.
+
+/sys/bus/usb/devices/usb2/2-0:1.0/port1/peer -> ../../../usb3/3-0:1.0/port1
+/sys/bus/usb/devices/usb3/3-0:1.0/port1/peer -> ../../../usb2/2-0:1.0/port1
+
+Distinct from 'companion ports', or 'ehci/xhci shared switchover ports'
+peer ports are simply the hi-speed and superspeed interface pins that
+are combined into a single usb3 connector. Peer ports share the same
+ancestor XHCI device.
+
+While a superspeed port is powered off a device may downgrade its
+connection and attempt to connect to the hi-speed pins. The
+implementation takes steps to prevent this:
+
+1/ Port suspend is sequenced to guarantee that hi-speed ports are powered-off
+ before their superspeed peer is permitted to power-off. The implication is
+ that the setting pm_qos_no_power_off to zero on a superspeed port may not
cause
+ the port to power-off until its highspeed peer to go to its runtime suspend
+ state. Userspace must take care to order the suspensions if it wants to
+ guarantee that a superspeed port will power-off.
+
+2/ Port resume is sequenced to force a superspeed port to power-on prior to its
+ highspeed peer.
+
+3/ Port resume always triggers an attached child device to resume. After a
+ power session is lost the device may have been removed, or need reset.
+ Resuming the child device when the parent port regains power resolves those
+ states and clamps the maximum port power cycle frequency at the rate the
child
+ device can suspend (autosuspend-delay) and resume (reset-resume latency).
+
+Sysfs files relevant for port power control:
+ <portX>/power/pm_qos_no_power_off:
+ This writable flag controls the state of an idle port.
+ Once all children and descendants have suspended the
+ port may suspend/poweroff provided that
+ pm_qos_no_power_off is '0'. If pm_qos_no_power_off is
+ '1' the port will remain active/powered regardless of
+ the stats of descendants. Defaults to 1.
+
+ <portX>/power/runtime_status:
+ This file reflects whether the port is 'active' (power is on)
+ or 'suspended' (logically off). There is no indication to
+ userspace whether VBUS is still supplied.
+
+ <portX>/connect_type:
+ An advisory read-only flag to userspace indicating the
+ location and connection type of the port. It returns
+ one of four values 'hotplug', 'hardwired', 'not used',
+ and 'unknown'. All values, besides unknown, are set by
+ platform firmware.
+
+ "hotplug" indicates an externally connectable/visible
+ port on the platform. Typically userspace would choose
+ to keep such a port powered to handle new device
+ connection events.
+
+ "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. It is
+ expected to be safe to allow these ports to suspend
+ provided pm_qos_no_power_off is coordinated with any
+ switch that gates connections. Userspace must arrange
+ for the device to be connected prior to the port
+ powering off, or to activate the port prior to enabling
+ connection via a switch.
+
+ "not used" refers to an internal port that is expected
+ to never have a device connected to it. These may be
+ empty internal ports, or ports that are not physically
+ exposed on a platform. Considered safe to be
+ powered-off at all times.
+
+ "unknown" means platform firmware does not provide
+ information for this port. Most commonly refers to
+ external hub ports which should be considered 'hotplug'
+ for policy decisions.
+
+ 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 clearing pm_qos_no_power_off. 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 until <child>/power/runtime_status
+ reflects the 'suspended' state. Default
+ value is controlled by child device driver.
+
+ <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.
+
+ <child>/driver/unbind:
+ Wakeup capable devices will block port poweroff. At
+ this time the only mechanism to clear the usb-internal
+ wakeup-capability for an interface device is to unbind
+ its driver.
+
+Summary of poweroff pre-requisite settings relative to a port device:
+
+ echo 0 > power/pm_qos_no_power_off
+ echo 0 > peer/power/pm_qos_no_power_off # if it exists
+ echo auto > power/control # this is the default value
+ echo auto > <child>/power/control
+ echo 1 > <child>/power/persist # this is the default value
+
+ 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 ports to always remain
+active.
+
+Given confidence in the platform firmware's description of the ports
+(ACPI _PLD record for a port populates 'connect_type') userspace can
+clear pm_qos_no_power_off for all 'not used' ports. The same can be
+done for 'hardwired' ports provided poweroff is coordinated with any
+connection switch for the port.
+
+A more aggressive userspace policy is to enable USB port power off for
+all ports (set portX/power/pm_qos_no_power_off to '0') 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.
--
To unsubscribe from this list: send the line "unsubscribe linux-usb" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
