USB: document ehci-hcd's "companion" sysfs attribute

This patch (as1484) adds documentation for ehci-hcd's "companion"
sysfs attribute, which was added to the kernel over four years ago but
never documented.

Signed-off-by: Alan Stern <stern@rowland.harvard.edu>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>

1 files changed, 46 insertions, 0 deletions

diff --git a/Documentation/ABI/testing/sysfs-bus-pci-drivers-ehci_hcd b/Documentation/ABI/testing/sysfs-bus-pci-drivers-ehci_hcd
new file mode 100644
index 000000000000..60c60fa624b2
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-bus-pci-drivers-ehci_hcd
@@ -0,0 +1,46 @@
+What:           /sys/bus/pci/drivers/ehci_hcd/.../companion
+                /sys/bus/usb/devices/usbN/../companion
+Date:           January 2007
+KernelVersion:  2.6.21
+Contact:        Alan Stern <stern@rowland.harvard.edu>
+Description:
+                PCI-based EHCI USB controllers (i.e., high-speed USB-2.0
+                controllers) are often implemented along with a set of
+                "companion" full/low-speed USB-1.1 controllers.  When a
+                high-speed device is plugged in, the connection is routed
+                to the EHCI controller; when a full- or low-speed device
+                is plugged in, the connection is routed to the companion
+                controller.
+
+                Sometimes you want to force a high-speed device to connect
+                at full speed, which can be accomplished by forcing the
+                connection to be routed to the companion controller.
+                That's what this file does.  Writing a port number to the
+                file causes connections on that port to be routed to the
+                companion controller, and writing the negative of a port
+                number returns the port to normal operation.
+
+                For example: To force the high-speed device attached to
+                port 4 on bus 2 to run at full speed:
+
+                        echo 4 >/sys/bus/usb/devices/usb2/../companion
+
+                To return the port to high-speed operation:
+
+                        echo -4 >/sys/bus/usb/devices/usb2/../companion
+
+                Reading the file gives the list of ports currently forced
+                to the companion controller.
+
+                Note: Some EHCI controllers do not have companions; they
+                may contain an internal "transaction translator" or they
+                may be attached directly to a "rate-matching hub".  This
+                mechanism will not work with such controllers.  Also, it
+                cannot be used to force a port on a high-speed hub to
+                connect at full speed.
+
+                Note: When this file was first added, it appeared in a
+                different sysfs directory.  The location given above is
+                correct for 2.6.35 (and probably several earlier kernel
+                versions as well).
+