From: Lan Tianyu <tianyu.lan@xxxxxxxxx> Describe the mechanisms for controlling port power policy and discovering the port power state. Signed-off-by: Lan Tianyu <tianyu.lan@xxxxxxxxx> [sarah: wordsmithing] Signed-off-by: Sarah Sharp <sarah.a.sharp@xxxxxxxxxxxxxxx> [djbw: updates for device model, hotplug, and rework changes] Signed-off-by: Dan Williams <dan.j.williams@xxxxxxxxx> --- Documentation/usb/power-management.txt | 208 ++++++++++++++++++++++++++++++++ 1 files changed, 208 insertions(+), 0 deletions(-) diff --git a/Documentation/usb/power-management.txt b/Documentation/usb/power-management.txt index 1392b61d6ebe..d683b2eebfd1 100644 --- a/Documentation/usb/power-management.txt +++ b/Documentation/usb/power-management.txt @@ -1,3 +1,4 @@ + Power Management for USB Alan Stern <stern@xxxxxxxxxxxxxxxxxxx> @@ -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. -- To unsubscribe from this list: send the line "unsubscribe linux-usb" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
