A couple comments below. On Tue, Jan 07, 2014 at 12:30:21PM -0800, Dan Williams wrote: > From: Lan Tianyu <tianyu.lan@xxxxxxxxx> > > describe the mechanisms for controlling port power policy and > discovering the port power state. > > Cc: Oliver Neukum <oneukum@xxxxxxx> > Signed-off-by: Lan Tianyu <tianyu.lan@xxxxxxxxx> > Signed-off-by: Sarah Sharp <sarah.a.sharp@xxxxxxxxxxxxxxx> I think this version of the patch was changed since the last time I internally signed off on it. I'll have to be more careful about sending draft patches out with my Signed-off-by line. > Signed-off-by: Dan Williams <dan.j.williams@xxxxxxxxx> > --- > Documentation/usb/power-management.txt | 210 ++++++++++++++++++++++++++++++++ > 1 files changed, 210 insertions(+), 0 deletions(-) > > diff --git a/Documentation/usb/power-management.txt b/Documentation/usb/power-management.txt > index 1392b61d6ebe..e5e77a67abb7 100644 > --- a/Documentation/usb/power-management.txt > +++ b/Documentation/usb/power-management.txt > @@ -5,6 +5,25 @@ ... > + 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 requrire the attached child device and all descendants to be > +suspended. > + > +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. > + > +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/<intf>/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 > + > +Physically, a superspeed port is ganged with a hi-speed port to form a > +connector. Distinct from 'companion ports', peer ports share the same > +ancestor XHCI device. Whereas, with a companion port, an EHCI or XHCI > +device optionally drive the same pins. While a superspeed port is I think you mean "with a companion port, an EHCI or OHCI/UHCI device optionally drive the same pins". Or are you talking about the Intel EHCI to xHCI port switchover? We don't call those companion ports in that case. > +powered off a device may downgrade its connection and attempt to connect > +to the hi-speed pins. The implementation takes steps to prevent this > +and sequences port power to guarantee that hi-speed ports are > +powered-off before superspeed are allowed to suspend, and that > +superspeed ports are recovered/repowered before hi-speed. > + > + 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. You probably want to mention the default policy of '1' here. > + > + 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. > + > + 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-capabilty 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' 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. This paragraph is out-of-date. You mention that connect_type is read-only above, and this paragraph assumes it's read-write. It also assumes that the reason why userspace needs to write into connect_type is because we won't power off a port unless it's set to hardwired. I think that assumption is false with the current code base, and we'll power off a port with any connect_type value, as long as userspace says it's OK. Is that correct? Sarah Sharp -- 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
