diff options
Diffstat (limited to 'Documentation/ABI/testing/sysfs-bus-usb')
| -rw-r--r-- | Documentation/ABI/testing/sysfs-bus-usb | 259 |
1 files changed, 177 insertions, 82 deletions
diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb index 11a3c1682ce..614d451cee4 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb +++ b/Documentation/ABI/testing/sysfs-bus-usb @@ -1,87 +1,182 @@ -What: /sys/bus/usb/devices/.../power/autosuspend -Date: March 2007 -KernelVersion: 2.6.21 -Contact: Alan Stern <stern@rowland.harvard.edu> +What: /sys/bus/usb/device/.../authorized +Date: July 2008 +KernelVersion: 2.6.26 +Contact: David Vrabel <david.vrabel@csr.com> Description: - Each USB device directory will contain a file named - power/autosuspend. This file holds the time (in seconds) - the device must be idle before it will be autosuspended. - 0 means the device will be autosuspended as soon as - possible. Negative values will prevent the device from - being autosuspended at all, and writing a negative value - will resume the device if it is already suspended. - - The autosuspend delay for newly-created devices is set to - the value of the usbcore.autosuspend module parameter. - -What: /sys/bus/usb/devices/.../power/level -Date: March 2007 -KernelVersion: 2.6.21 -Contact: Alan Stern <stern@rowland.harvard.edu> + Authorized devices are available for use by device + drivers, non-authorized one are not. By default, wired + USB devices are authorized. + + Certified Wireless USB devices are not authorized + initially and should be (by writing 1) after the + device has been authenticated. + +What: /sys/bus/usb/device/.../wusb_cdid +Date: July 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel <david.vrabel@csr.com> +Description: + For Certified Wireless USB devices only. + + A devices's CDID, as 16 space-separated hex octets. + +What: /sys/bus/usb/device/.../wusb_ck +Date: July 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel <david.vrabel@csr.com> +Description: + For Certified Wireless USB devices only. + + Write the device's connection key (CK) to start the + authentication of the device. The CK is 16 + space-separated hex octets. + +What: /sys/bus/usb/device/.../wusb_disconnect +Date: July 2008 +KernelVersion: 2.6.27 +Contact: David Vrabel <david.vrabel@csr.com> Description: - Each USB device directory will contain a file named - power/level. This file holds a power-level setting for - the device, one of "on", "auto", or "suspend". - - "on" means that the device is not allowed to autosuspend, - although normal suspends for system sleep will still - be honored. "auto" means the device will autosuspend - and autoresume in the usual manner, according to the - capabilities of its driver. "suspend" means the device - is forced into a suspended state and it will not autoresume - in response to I/O requests. However remote-wakeup requests - from the device may still be enabled (the remote-wakeup - setting is controlled separately by the power/wakeup - attribute). - - During normal use, devices should be left in the "auto" - level. The other levels are meant for administrative uses. - If you want to suspend a device immediately but leave it - free to wake up in response to I/O requests, you should - write "0" to power/autosuspend. - -What: /sys/bus/usb/devices/.../power/persist -Date: May 2007 -KernelVersion: 2.6.23 -Contact: Alan Stern <stern@rowland.harvard.edu> + For Certified Wireless USB devices only. + + Write a 1 to force the device to disconnect + (equivalent to unplugging a wired USB device). + +What: /sys/bus/usb/drivers/.../new_id +Date: October 2011 +Contact: linux-usb@vger.kernel.org Description: - If CONFIG_USB_PERSIST is set, then each USB device directory - will contain a file named power/persist. The file holds a - boolean value (0 or 1) indicating whether or not the - "USB-Persist" facility is enabled for the device. Since the - facility is inherently dangerous, it is disabled by default - for all devices except hubs. For more information, see - Documentation/usb/persist.txt. - -What: /sys/bus/usb/device/.../power/connected_duration -Date: January 2008 -KernelVersion: 2.6.25 -Contact: Sarah Sharp <sarah.a.sharp@intel.com> + Writing a device ID to this file will attempt to + dynamically add a new device ID to a USB device driver. + This may allow the driver to support more hardware than + was included in the driver's static device ID support + table at compile time. The format for the device ID is: + idVendor idProduct bInterfaceClass RefIdVendor RefIdProduct + The vendor ID and device ID fields are required, the + rest is optional. The Ref* tuple can be used to tell the + driver to use the same driver_data for the new device as + it is used for the reference device. + Upon successfully adding an ID, the driver will probe + for the device and attempt to bind to it. For example: + # echo "8086 10f5" > /sys/bus/usb/drivers/foo/new_id + + Here add a new device (0458:7045) using driver_data from + an already supported device (0458:704c): + # echo "0458 7045 0 0458 704c" > /sys/bus/usb/drivers/foo/new_id + + Reading from this file will list all dynamically added + device IDs in the same format, with one entry per + line. For example: + # cat /sys/bus/usb/drivers/foo/new_id + 8086 10f5 + dead beef 06 + f00d cafe + + The list will be truncated at PAGE_SIZE bytes due to + sysfs restrictions. + +What: /sys/bus/usb-serial/drivers/.../new_id +Date: October 2011 +Contact: linux-usb@vger.kernel.org Description: - If CONFIG_PM and CONFIG_USB_SUSPEND are enabled, then this file - is present. When read, it returns the total time (in msec) - that the USB device has been connected to the machine. This - file is read-only. -Users: - PowerTOP <power@bughost.org> - http://www.lesswatts.org/projects/powertop/ - -What: /sys/bus/usb/device/.../power/active_duration -Date: January 2008 -KernelVersion: 2.6.25 -Contact: Sarah Sharp <sarah.a.sharp@intel.com> + For serial USB drivers, this attribute appears under the + extra bus folder "usb-serial" in sysfs; apart from that + difference, all descriptions from the entry + "/sys/bus/usb/drivers/.../new_id" apply. + +What: /sys/bus/usb/drivers/.../remove_id +Date: November 2009 +Contact: CHENG Renquan <rqcheng@smu.edu.sg> Description: - If CONFIG_PM and CONFIG_USB_SUSPEND are enabled, then this file - is present. When read, it returns the total time (in msec) - that the USB device has been active, i.e. not in a suspended - state. This file is read-only. - - Tools can use this file and the connected_duration file to - compute the percentage of time that a device has been active. - For example, - echo $((100 * `cat active_duration` / `cat connected_duration`)) - will give an integer percentage. Note that this does not - account for counter wrap. -Users: - PowerTOP <power@bughost.org> - http://www.lesswatts.org/projects/powertop/ + Writing a device ID to this file will remove an ID + that was dynamically added via the new_id sysfs entry. + The format for the device ID is: + idVendor idProduct. After successfully + removing an ID, the driver will no longer support the + device. This is useful to ensure auto probing won't + match the driver to the device. For example: + # echo "046d c315" > /sys/bus/usb/drivers/foo/remove_id + + Reading from this file will list the dynamically added + device IDs, exactly like reading from the entry + "/sys/bus/usb/drivers/.../new_id" + +What: /sys/bus/usb/devices/.../power/usb2_hardware_lpm +Date: September 2011 +Contact: Andiry Xu <andiry.xu@amd.com> +Description: + If CONFIG_PM_RUNTIME is set and a USB 2.0 lpm-capable device + is plugged in to a xHCI host which support link PM, it will + perform a LPM test; if the test is passed and host supports + USB2 hardware LPM (xHCI 1.0 feature), USB2 hardware LPM will + be enabled for the device and the USB device directory will + contain a file named power/usb2_hardware_lpm. The file holds + a string value (enable or disable) indicating whether or not + USB2 hardware LPM is enabled for the device. Developer can + write y/Y/1 or n/N/0 to the file to enable/disable the + feature. + +What: /sys/bus/usb/devices/.../removable +Date: February 2012 +Contact: Matthew Garrett <mjg@redhat.com> +Description: + Some information about whether a given USB device is + physically fixed to the platform can be inferred from a + combination of hub descriptor bits and platform-specific data + such as ACPI. This file will read either "removable" or + "fixed" if the information is available, and "unknown" + otherwise. + +What: /sys/bus/usb/devices/.../ltm_capable +Date: July 2012 +Contact: Sarah Sharp <sarah.a.sharp@linux.intel.com> +Description: + USB 3.0 devices may optionally support Latency Tolerance + Messaging (LTM). They indicate their support by setting a bit + in the bmAttributes field of their SuperSpeed BOS descriptors. + If that bit is set for the device, ltm_capable will read "yes". + If the device doesn't support LTM, the file will read "no". + The file will be present for all speeds of USB devices, and will + always read "no" for USB 1.1 and USB 2.0 devices. + +What: /sys/bus/usb/devices/.../(hub interface)/portX +Date: August 2012 +Contact: Lan Tianyu <tianyu.lan@intel.com> +Description: + The /sys/bus/usb/devices/.../(hub interface)/portX + is usb port device's sysfs directory. + +What: /sys/bus/usb/devices/.../(hub interface)/portX/connect_type +Date: January 2013 +Contact: Lan Tianyu <tianyu.lan@intel.com> +Description: + Some platforms provide usb port connect types through ACPI. + This attribute is to expose these information to user space. + The file will read "hotplug", "wired" and "not used" if the + information is available, and "unknown" otherwise. + +What: /sys/bus/usb/devices/.../power/usb2_lpm_l1_timeout +Date: May 2013 +Contact: Mathias Nyman <mathias.nyman@linux.intel.com> +Description: + USB 2.0 devices may support hardware link power management (LPM) + L1 sleep state. The usb2_lpm_l1_timeout attribute allows + tuning the timeout for L1 inactivity timer (LPM timer), e.g. + needed inactivity time before host requests the device to go to L1 sleep. + Useful for power management tuning. + Supported values are 0 - 65535 microseconds. + +What: /sys/bus/usb/devices/.../power/usb2_lpm_besl +Date: May 2013 +Contact: Mathias Nyman <mathias.nyman@linux.intel.com> +Description: + USB 2.0 devices that support hardware link power management (LPM) + L1 sleep state now use a best effort service latency value (BESL) to + indicate the best effort to resumption of service to the device after the + initiation of the resume event. + If the device does not have a preferred besl value then the host can select + one instead. This usb2_lpm_besl attribute allows to tune the host selected besl + value in order to tune power saving and service latency. + + Supported values are 0 - 15. + More information on how besl values map to microseconds can be found in + USB 2.0 ECN Errata for Link Power Management, section 4.10) |