Documentation/ABI/testing/sysfs-bus-usb

   1 What:           /sys/bus/usb/devices/.../power/autosuspend
   2 Date:           March 2007
   3 KernelVersion:  2.6.21
   4 Contact:        Alan Stern <stern@rowland.harvard.edu>
   5 Description:
   6                 Each USB device directory will contain a file named
   7                 power/autosuspend.  This file holds the time (in seconds)
   8                 the device must be idle before it will be autosuspended.
   9                 0 means the device will be autosuspended as soon as
  10                 possible.  Negative values will prevent the device from
  11                 being autosuspended at all, and writing a negative value
  12                 will resume the device if it is already suspended.
  13
  14                 The autosuspend delay for newly-created devices is set to
  15                 the value of the usbcore.autosuspend module parameter.
  16
  17 What:           /sys/bus/usb/devices/.../power/persist
  18 Date:           May 2007
  19 KernelVersion:  2.6.23
  20 Contact:        Alan Stern <stern@rowland.harvard.edu>
  21 Description:
  22                 If CONFIG_USB_PERSIST is set, then each USB device directory
  23                 will contain a file named power/persist.  The file holds a
  24                 boolean value (0 or 1) indicating whether or not the
  25                 "USB-Persist" facility is enabled for the device.  Since the
  26                 facility is inherently dangerous, it is disabled by default
  27                 for all devices except hubs.  For more information, see
  28                 Documentation/usb/persist.txt.
  29
  30 What:           /sys/bus/usb/device/.../power/connected_duration
  31 Date:           January 2008
  32 KernelVersion:  2.6.25
  33 Contact:        Sarah Sharp <sarah.a.sharp@intel.com>
  34 Description:
  35                 If CONFIG_PM and CONFIG_USB_SUSPEND are enabled, then this file
  36                 is present.  When read, it returns the total time (in msec)
  37                 that the USB device has been connected to the machine.  This
  38                 file is read-only.
  39 Users:
  40                 PowerTOP <power@bughost.org>
  41                 http://www.lesswatts.org/projects/powertop/
  42
  43 What:           /sys/bus/usb/device/.../power/active_duration
  44 Date:           January 2008
  45 KernelVersion:  2.6.25
  46 Contact:        Sarah Sharp <sarah.a.sharp@intel.com>
  47 Description:
  48                 If CONFIG_PM and CONFIG_USB_SUSPEND are enabled, then this file
  49                 is present.  When read, it returns the total time (in msec)
  50                 that the USB device has been active, i.e. not in a suspended
  51                 state.  This file is read-only.
  52
  53                 Tools can use this file and the connected_duration file to
  54                 compute the percentage of time that a device has been active.
  55                 For example,
  56                 echo $((100 * `cat active_duration` / `cat connected_duration`))
  57                 will give an integer percentage.  Note that this does not
  58                 account for counter wrap.
  59 Users:
  60                 PowerTOP <power@bughost.org>
  61                 http://www.lesswatts.org/projects/powertop/
  62
  63 What:           /sys/bus/usb/device/<busnum>-<devnum>...:<config num>-<interface num>/supports_autosuspend
  64 Date:           January 2008
  65 KernelVersion:  2.6.27
  66 Contact:        Sarah Sharp <sarah.a.sharp@intel.com>
  67 Description:
  68                 When read, this file returns 1 if the interface driver
  69                 for this interface supports autosuspend.  It also
  70                 returns 1 if no driver has claimed this interface, as an
  71                 unclaimed interface will not stop the device from being
  72                 autosuspended if all other interface drivers are idle.
  73                 The file returns 0 if autosuspend support has not been
  74                 added to the driver.
  75 Users:
  76                 USB PM tool
  77                 git://git.moblin.org/users/sarah/usb-pm-tool/
  78
  79 What:           /sys/bus/usb/device/.../authorized
  80 Date:           July 2008
  81 KernelVersion:  2.6.26
  82 Contact:        David Vrabel <david.vrabel@csr.com>
  83 Description:
  84                 Authorized devices are available for use by device
  85                 drivers, non-authorized one are not.  By default, wired
  86                 USB devices are authorized.
  87
  88                 Certified Wireless USB devices are not authorized
  89                 initially and should be (by writing 1) after the
  90                 device has been authenticated.
  91
  92 What:           /sys/bus/usb/device/.../wusb_cdid
  93 Date:           July 2008
  94 KernelVersion:  2.6.27
  95 Contact:        David Vrabel <david.vrabel@csr.com>
  96 Description:
  97                 For Certified Wireless USB devices only.
  98
  99                 A devices's CDID, as 16 space-separated hex octets.
 100
 101 What:           /sys/bus/usb/device/.../wusb_ck
 102 Date:           July 2008
 103 KernelVersion:  2.6.27
 104 Contact:        David Vrabel <david.vrabel@csr.com>
 105 Description:
 106                 For Certified Wireless USB devices only.
 107
 108                 Write the device's connection key (CK) to start the
 109                 authentication of the device.  The CK is 16
 110                 space-separated hex octets.
 111
 112 What:           /sys/bus/usb/device/.../wusb_disconnect
 113 Date:           July 2008
 114 KernelVersion:  2.6.27
 115 Contact:        David Vrabel <david.vrabel@csr.com>
 116 Description:
 117                 For Certified Wireless USB devices only.
 118
 119                 Write a 1 to force the device to disconnect
 120                 (equivalent to unplugging a wired USB device).
 121
 122 What:           /sys/bus/usb/drivers/.../new_id
 123 Date:           October 2011
 124 Contact:        linux-usb@vger.kernel.org
 125 Description:
 126                 Writing a device ID to this file will attempt to
 127                 dynamically add a new device ID to a USB device driver.
 128                 This may allow the driver to support more hardware than
 129                 was included in the driver's static device ID support
 130                 table at compile time. The format for the device ID is:
 131                 idVendor idProduct bInterfaceClass.
 132                 The vendor ID and device ID fields are required, the
 133                 interface class is optional.
 134                 Upon successfully adding an ID, the driver will probe
 135                 for the device and attempt to bind to it.  For example:
 136                 # echo "8086 10f5" > /sys/bus/usb/drivers/foo/new_id
 137
 138                 Reading from this file will list all dynamically added
 139                 device IDs in the same format, with one entry per
 140                 line. For example:
 141                 # cat /sys/bus/usb/drivers/foo/new_id
 142                 8086 10f5
 143                 dead beef 06
 144                 f00d cafe
 145
 146                 The list will be truncated at PAGE_SIZE bytes due to
 147                 sysfs restrictions.
 148
 149 What:           /sys/bus/usb-serial/drivers/.../new_id
 150 Date:           October 2011
 151 Contact:        linux-usb@vger.kernel.org
 152 Description:
 153                 For serial USB drivers, this attribute appears under the
 154                 extra bus folder "usb-serial" in sysfs; apart from that
 155                 difference, all descriptions from the entry
 156                 "/sys/bus/usb/drivers/.../new_id" apply.
 157
 158 What:           /sys/bus/usb/drivers/.../remove_id
 159 Date:           November 2009
 160 Contact:        CHENG Renquan <rqcheng@smu.edu.sg>
 161 Description:
 162                 Writing a device ID to this file will remove an ID
 163                 that was dynamically added via the new_id sysfs entry.
 164                 The format for the device ID is:
 165                 idVendor idProduct.     After successfully
 166                 removing an ID, the driver will no longer support the
 167                 device.  This is useful to ensure auto probing won't
 168                 match the driver to the device.  For example:
 169                 # echo "046d c315" > /sys/bus/usb/drivers/foo/remove_id
 170
 171                 Reading from this file will list the dynamically added
 172                 device IDs, exactly like reading from the entry
 173                 "/sys/bus/usb/drivers/.../new_id"
 174
 175 What:           /sys/bus/usb/device/.../avoid_reset_quirk
 176 Date:           December 2009
 177 Contact:        Oliver Neukum <oliver@neukum.org>
 178 Description:
 179                 Writing 1 to this file tells the kernel that this
 180                 device will morph into another mode when it is reset.
 181                 Drivers will not use reset for error handling for
 182                 such devices.
 183 Users:
 184                 usb_modeswitch
 185
 186 What:           /sys/bus/usb/devices/.../power/usb2_hardware_lpm
 187 Date:           September 2011
 188 Contact:        Andiry Xu <andiry.xu@amd.com>
 189 Description:
 190                 If CONFIG_USB_SUSPEND is set and a USB 2.0 lpm-capable device
 191                 is plugged in to a xHCI host which support link PM, it will
 192                 perform a LPM test; if the test is passed and host supports
 193                 USB2 hardware LPM (xHCI 1.0 feature), USB2 hardware LPM will
 194                 be enabled for the device and the USB device directory will
 195                 contain a file named power/usb2_hardware_lpm.  The file holds
 196                 a string value (enable or disable) indicating whether or not
 197                 USB2 hardware LPM is enabled for the device. Developer can
 198                 write y/Y/1 or n/N/0 to the file to enable/disable the
 199                 feature.
 200
 201 What:           /sys/bus/usb/devices/.../removable
 202 Date:           February 2012
 203 Contact:        Matthew Garrett <mjg@redhat.com>
 204 Description:
 205                 Some information about whether a given USB device is
 206                 physically fixed to the platform can be inferred from a
 207                 combination of hub descriptor bits and platform-specific data
 208                 such as ACPI. This file will read either "removable" or
 209                 "fixed" if the information is available, and "unknown"
 210                 otherwise.
 211
 212 What:           /sys/bus/usb/devices/.../ltm_capable
 213 Date:           July 2012
 214 Contact:        Sarah Sharp <sarah.a.sharp@linux.intel.com>
 215 Description:
 216                 USB 3.0 devices may optionally support Latency Tolerance
 217                 Messaging (LTM).  They indicate their support by setting a bit
 218                 in the bmAttributes field of their SuperSpeed BOS descriptors.
 219                 If that bit is set for the device, ltm_capable will read "yes".
 220                 If the device doesn't support LTM, the file will read "no".
 221                 The file will be present for all speeds of USB devices, and will
 222                 always read "no" for USB 1.1 and USB 2.0 devices.
 223
 224 What:           /sys/bus/usb/devices/.../(hub interface)/portX
 225 Date:           August 2012
 226 Contact:        Lan Tianyu <tianyu.lan@intel.com>
 227 Description:
 228                 The /sys/bus/usb/devices/.../(hub interface)/portX
 229                 is usb port device's sysfs directory.
 230
 231 What:           /sys/bus/usb/devices/.../(hub interface)/portX/control
 232 Date:           August 2012
 233 Contact:        Lan Tianyu <tianyu.lan@intel.com>
 234 Description:
 235                 The /sys/bus/usb/devices/.../(hub interface)/portX/control
 236                 attribute allows user space to control the power policy on
 237                 the usb port.
 238
 239                 All ports have one of the following two values for control
 240                 "on" - port power must be on.
 241                 "off" - port power must be off.
 242
 243 What:           /sys/bus/usb/devices/.../(hub interface)/portX/state
 244 Date:           August 2012
 245 Contact:        Lan Tianyu <tianyu.lan@intel.com>
 246 Description:
 247                 The /sys/bus/usb/devices/.../(hub interface)/portX/state
 248                 attribute allows user space to check hub port's power state.
 249
 250                 All ports have three following states
 251                 "on"      -    port power on
 252                 "off"     -    port power off
 253                 "error"   -    can't get the hub port's power state