xref: /linux/Documentation/ABI/testing/sysfs-bus-usb (revision 79790b6818e96c58fe2bffee1b418c16e64e7b80)
1What:		/sys/bus/usb/devices/<INTERFACE>/authorized
2Date:		August 2015
3Description:
4		This allows to authorize (1) or deauthorize (0)
5		individual interfaces instead a whole device
6		in contrast to the device authorization.
7		If a deauthorized interface will be authorized
8		so the driver probing must be triggered manually
9		by writing INTERFACE to /sys/bus/usb/drivers_probe
10		This allows to avoid side-effects with drivers
11		that need multiple interfaces.
12
13		A deauthorized interface cannot be probed or claimed.
14
15What:		/sys/bus/usb/devices/usbX/interface_authorized_default
16Date:		August 2015
17Description:
18		This is used as value that determines if interfaces
19		would be authorized by default.
20		The value can be 1 or 0. It's by default 1.
21
22What:		/sys/bus/usb/device/.../authorized
23Date:		July 2008
24KernelVersion:	2.6.26
25Contact:	David Vrabel <david.vrabel@csr.com>
26Description:
27		Authorized devices are available for use by device
28		drivers, non-authorized one are not.  By default, wired
29		USB devices are authorized.
30
31What:		/sys/bus/usb/drivers/.../new_id
32Date:		October 2011
33Contact:	linux-usb@vger.kernel.org
34Description:
35		Writing a device ID to this file will attempt to
36		dynamically add a new device ID to a USB device driver.
37		This may allow the driver to support more hardware than
38		was included in the driver's static device ID support
39		table at compile time. The format for the device ID is:
40		idVendor idProduct bInterfaceClass RefIdVendor RefIdProduct
41		The vendor ID and device ID fields are required, the
42		rest is optional. The `Ref*` tuple can be used to tell the
43		driver to use the same driver_data for the new device as
44		it is used for the reference device.
45		Upon successfully adding an ID, the driver will probe
46		for the device and attempt to bind to it.  For example::
47
48		  # echo "8086 10f5" > /sys/bus/usb/drivers/foo/new_id
49
50		Here add a new device (0458:7045) using driver_data from
51		an already supported device (0458:704c)::
52
53		  # echo "0458 7045 0 0458 704c" > /sys/bus/usb/drivers/foo/new_id
54
55		Reading from this file will list all dynamically added
56		device IDs in the same format, with one entry per
57		line. For example::
58
59		  # cat /sys/bus/usb/drivers/foo/new_id
60		  8086 10f5
61		  dead beef 06
62		  f00d cafe
63
64		The list will be truncated at PAGE_SIZE bytes due to
65		sysfs restrictions.
66
67What:		/sys/bus/usb-serial/drivers/.../new_id
68Date:		October 2011
69Contact:	linux-usb@vger.kernel.org
70Description:
71		For serial USB drivers, this attribute appears under the
72		extra bus folder "usb-serial" in sysfs; apart from that
73		difference, all descriptions from the entry
74		"/sys/bus/usb/drivers/.../new_id" apply.
75
76What:		/sys/bus/usb/drivers/.../remove_id
77Date:		November 2009
78Contact:	CHENG Renquan <rqcheng@smu.edu.sg>
79Description:
80		Writing a device ID to this file will remove an ID
81		that was dynamically added via the new_id sysfs entry.
82		The format for the device ID is:
83		idVendor idProduct.	After successfully
84		removing an ID, the driver will no longer support the
85		device.  This is useful to ensure auto probing won't
86		match the driver to the device.  For example:
87		# echo "046d c315" > /sys/bus/usb/drivers/foo/remove_id
88
89		Reading from this file will list the dynamically added
90		device IDs, exactly like reading from the entry
91		"/sys/bus/usb/drivers/.../new_id"
92
93What:		/sys/bus/usb/devices/.../power/usb2_hardware_lpm
94Date:		September 2011
95Contact:	Andiry Xu <andiry.xu@amd.com>
96Description:
97		If CONFIG_PM is set and a USB 2.0 lpm-capable device is plugged
98		in to a xHCI host which support link PM, it will perform a LPM
99		test; if the test is passed and host supports USB2 hardware LPM
100		(xHCI 1.0 feature), USB2 hardware LPM will be enabled for the
101		device and the USB device directory will contain a file named
102		power/usb2_hardware_lpm.  The file holds a string value (enable
103		or disable) indicating whether or not USB2 hardware LPM is
104		enabled for the device. Developer can write y/Y/1 or n/N/0 to
105		the file to enable/disable the feature.
106
107What:		/sys/bus/usb/devices/.../power/usb3_hardware_lpm_u1
108		/sys/bus/usb/devices/.../power/usb3_hardware_lpm_u2
109Date:		November 2015
110Contact:	Kevin Strasser <kevin.strasser@linux.intel.com>
111		Lu Baolu <baolu.lu@linux.intel.com>
112Description:
113		If CONFIG_PM is set and a USB 3.0 lpm-capable device is plugged
114		in to a xHCI host which supports link PM, it will check if U1
115		and U2 exit latencies have been set in the BOS descriptor; if
116		the check is passed and the host supports USB3 hardware LPM,
117		USB3 hardware LPM will be enabled for the device and the USB
118		device directory will contain two files named
119		power/usb3_hardware_lpm_u1 and power/usb3_hardware_lpm_u2. These
120		files hold a string value (enable or disable) indicating whether
121		or not USB3 hardware LPM U1 or U2 is enabled for the device.
122
123What:		/sys/bus/usb/devices/.../ltm_capable
124Date:		July 2012
125Contact:	Sarah Sharp <sarah.a.sharp@linux.intel.com>
126Description:
127		USB 3.0 devices may optionally support Latency Tolerance
128		Messaging (LTM).  They indicate their support by setting a bit
129		in the bmAttributes field of their SuperSpeed BOS descriptors.
130		If that bit is set for the device, ltm_capable will read "yes".
131		If the device doesn't support LTM, the file will read "no".
132		The file will be present for all speeds of USB devices, and will
133		always read "no" for USB 1.1 and USB 2.0 devices.
134
135What:		/sys/bus/usb/devices/<INTERFACE>/wireless_status
136Date:		February 2023
137Contact:	Bastien Nocera <hadess@hadess.net>
138Description:
139		Some USB devices use a USB receiver dongle to communicate
140		wirelessly with their device using proprietary protocols. This
141		attribute allows user-space to know whether the device is
142		connected to its receiver dongle, and, for example, consider
143		the device to be absent when choosing whether to show the
144		device's battery, show a headset in a list of outputs, or show
145		an on-screen keyboard if the only wireless keyboard is
146		turned off.
147		This attribute is not to be used to replace protocol specific
148		statuses available in WWAN, WLAN/Wi-Fi, Bluetooth, etc.
149		If the device does not use a receiver dongle with a wireless
150		device, then this attribute will not exist.
151
152What:		/sys/bus/usb/devices/.../<hub_interface>/port<X>
153Date:		August 2012
154Contact:	Lan Tianyu <tianyu.lan@intel.com>
155Description:
156		The /sys/bus/usb/devices/.../<hub_interface>/port<X>
157		is usb port device's sysfs directory.
158
159What:		/sys/bus/usb/devices/.../<hub_interface>/port<X>/connect_type
160Date:		January 2013
161Contact:	Lan Tianyu <tianyu.lan@intel.com>
162Description:
163		Some platforms provide usb port connect types through ACPI.
164		This attribute is to expose these information to user space.
165		The file will read "hotplug", "hardwired" and "not used" if the
166		information is available, and "unknown" otherwise.
167
168What:		/sys/bus/usb/devices/.../<hub_interface>/port<X>/location
169Date:		October 2018
170Contact:	Bjørn Mork <bjorn@mork.no>
171Description:
172		Some platforms provide usb port physical location through
173		firmware. This is used by the kernel to pair up logical ports
174		mapping to the same physical connector. The attribute exposes the
175		raw location value as a hex integer.
176
177
178What:		/sys/bus/usb/devices/.../<hub_interface>/port<X>/quirks
179Date:		May 2018
180Contact:	Nicolas Boichat <drinkcat@chromium.org>
181Description:
182		In some cases, we care about time-to-active for devices
183		connected on a specific port (e.g. non-standard USB port like
184		pogo pins), where the device to be connected is known in
185		advance, and behaves well according to the specification.
186		This attribute is a bit-field that controls the behavior of
187		a specific port:
188
189		 - Bit 0 of this field selects the "old" enumeration scheme,
190		   as it is considerably faster (it only causes one USB reset
191		   instead of 2).
192
193		   The old enumeration scheme can also be selected globally
194		   using /sys/module/usbcore/parameters/old_scheme_first, but
195		   it is often not desirable as the new scheme was introduced to
196		   increase compatibility with more devices.
197		 - Bit 1 reduces TRSTRCY to the 10 ms that are required by the
198		   USB 2.0 specification, instead of the 50 ms that are normally
199		   used to help make enumeration work better on some high speed
200		   devices.
201
202What:		/sys/bus/usb/devices/.../<hub_interface>/port<X>/over_current_count
203Date:		February 2018
204Contact:	Richard Leitner <richard.leitner@skidata.com>
205Description:
206		Most hubs are able to detect over-current situations on their
207		ports and report them to the kernel. This attribute is to expose
208		the number of over-current situation occurred on a specific port
209		to user space. This file will contain an unsigned 32 bit value
210		which wraps to 0 after its maximum is reached. This file supports
211		poll() for monitoring changes to this value in user space.
212
213		Any time this value changes the corresponding hub device will send a
214		udev event with the following attributes::
215
216		  OVER_CURRENT_PORT=/sys/bus/usb/devices/.../<hub_interface>/port<X>
217		  OVER_CURRENT_COUNT=[current value of this sysfs attribute]
218
219What:		/sys/bus/usb/devices/.../<hub_interface>/port<X>/usb3_lpm_permit
220Date:		November 2015
221Contact:	Lu Baolu <baolu.lu@linux.intel.com>
222Description:
223		Some USB3.0 devices are not friendly to USB3 LPM.  usb3_lpm_permit
224		attribute allows enabling/disabling usb3 lpm of a port. It takes
225		effect both before and after a usb device is enumerated. Supported
226		values are "0" if both u1 and u2 are NOT permitted, "u1" if only u1
227		is permitted, "u2" if only u2 is permitted, "u1_u2" if both u1 and
228		u2 are permitted.
229
230What:		/sys/bus/usb/devices/.../<hub_interface>/port<X>/connector
231Date:		December 2021
232Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>
233Description:
234		Link to the USB Type-C connector when available. This link is
235		only created when USB Type-C Connector Class is enabled, and
236		only if the system firmware is capable of describing the
237		connection between a port and its connector.
238
239What:		/sys/bus/usb/devices/.../<hub_interface>/port<X>/disable
240Date:		June 2022
241Contact:	Michael Grzeschik <m.grzeschik@pengutronix.de>
242Description:
243		This file controls the state of a USB port, including
244		Vbus power output (but only on hubs that support
245		power switching -- most hubs don't support it). If
246		a port is disabled, the port is unusable: Devices
247		attached to the port will not be detected, initialized,
248		or enumerated.
249
250What:		/sys/bus/usb/devices/.../<hub_interface>/port<X>/early_stop
251Date:		Sep 2022
252Contact:	Ray Chi <raychi@google.com>
253Description:
254		Some USB hosts have some watchdog mechanisms so that the device
255		may enter ramdump if it takes a long time during port initialization.
256		This attribute allows each port just has two attempts so that the
257		port initialization will be failed quickly. In addition, if a port
258		which is marked with early_stop has failed to initialize, it will ignore
259		all future connections until this attribute is clear.
260
261What:		/sys/bus/usb/devices/.../<hub_interface>/port<X>/state
262Date:		June 2023
263Contact:	Roy Luo <royluo@google.com>
264Description:
265		Indicates current state of the USB device attached to the port.
266		Valid states are: 'not-attached', 'attached', 'powered',
267		'reconnecting', 'unauthenticated', 'default', 'addressed',
268		'configured', and 'suspended'. This file supports poll() to
269		monitor the state change from user space.
270
271What:		/sys/bus/usb/devices/.../power/usb2_lpm_l1_timeout
272Date:		May 2013
273Contact:	Mathias Nyman <mathias.nyman@linux.intel.com>
274Description:
275		USB 2.0 devices may support hardware link power management (LPM)
276		L1 sleep state. The usb2_lpm_l1_timeout attribute allows
277		tuning the timeout for L1 inactivity timer (LPM timer), e.g.
278		needed inactivity time before host requests the device to go to L1 sleep.
279		Useful for power management tuning.
280		Supported values are 0 - 65535 microseconds.
281
282What:		/sys/bus/usb/devices/.../power/usb2_lpm_besl
283Date:		May 2013
284Contact:	Mathias Nyman <mathias.nyman@linux.intel.com>
285Description:
286		USB 2.0 devices that support hardware link power management (LPM)
287		L1 sleep state now use a best effort service latency value (BESL) to
288		indicate the best effort to resumption of service to the device after the
289		initiation of the resume event.
290		If the device does not have a preferred besl value then the host can select
291		one instead. This usb2_lpm_besl attribute allows to tune the host selected besl
292		value in order to tune power saving and service latency.
293
294		Supported values are 0 - 15.
295		More information on how besl values map to microseconds can be found in
296		USB 2.0 ECN Errata for Link Power Management, section 4.10)
297
298What:		/sys/bus/usb/devices/.../rx_lanes
299Date:		March 2018
300Contact:	Mathias Nyman <mathias.nyman@linux.intel.com>
301Description:
302		Number of rx lanes the device is using.
303		USB 3.2 adds Dual-lane support, 2 rx and 2 tx lanes over Type-C.
304		Inter-Chip SSIC devices support asymmetric lanes up to 4 lanes per
305		direction. Devices before USB 3.2 are single lane (rx_lanes = 1)
306
307What:		/sys/bus/usb/devices/.../tx_lanes
308Date:		March 2018
309Contact:	Mathias Nyman <mathias.nyman@linux.intel.com>
310Description:
311		Number of tx lanes the device is using.
312		USB 3.2 adds Dual-lane support, 2 rx and 2 tx -lanes over Type-C.
313		Inter-Chip SSIC devices support asymmetric lanes up to 4 lanes per
314		direction. Devices before USB 3.2 are single lane (tx_lanes = 1)
315
316What:		/sys/bus/usb/devices/.../typec
317Date:		November 2023
318Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>
319Description:
320		Symlink to the USB Type-C partner device. USB Type-C partner
321		represents the component that communicates over the
322		Configuration Channel (CC signal on USB Type-C connectors and
323		cables) with the local port.
324
325What:		/sys/bus/usb/devices/usbX/bAlternateSetting
326Description:
327		The current interface alternate setting number, in decimal.
328
329		See USB specs for its meaning.
330
331What:		/sys/bus/usb/devices/usbX/bcdDevice
332Description:
333		The device's release number, in hexadecimal.
334
335		See USB specs for its meaning.
336
337What:		/sys/bus/usb/devices/usbX/bConfigurationValue
338Description:
339		While a USB device typically have just one configuration
340		setting, some devices support multiple configurations.
341
342		This value shows the current configuration, in decimal.
343
344		Changing its value will change the device's configuration
345		to another setting.
346
347		The number of configurations supported by a device is at:
348
349			/sys/bus/usb/devices/usbX/bNumConfigurations
350
351		See USB specs for its meaning.
352
353What:		/sys/bus/usb/devices/usbX/bDeviceClass
354Description:
355		Class code of the device, in hexadecimal.
356
357		See USB specs for its meaning.
358
359What:		/sys/bus/usb/devices/usbX/bDeviceProtocol
360Description:
361		Protocol code of the device, in hexadecimal.
362
363		See USB specs for its meaning.
364
365What:		/sys/bus/usb/devices/usbX/bDeviceSubClass
366Description:
367		Subclass code of the device, in hexadecimal.
368
369		See USB specs for its meaning.
370
371What:		/sys/bus/usb/devices/usbX/bInterfaceClass
372Description:
373		Class code of the interface, in hexadecimal.
374
375		See USB specs for its meaning.
376
377What:		/sys/bus/usb/devices/usbX/bInterfaceNumber
378Description:
379		Interface number, in hexadecimal.
380
381		See USB specs for its meaning.
382
383What:		/sys/bus/usb/devices/usbX/bInterfaceProtocol
384Description:
385		Protocol code of the interface, in hexadecimal.
386
387		See USB specs for its meaning.
388
389What:		/sys/bus/usb/devices/usbX/bInterfaceSubClass
390Description:
391		Subclass code of the interface, in hexadecimal.
392
393		See USB specs for its meaning.
394
395What:		/sys/bus/usb/devices/usbX/bmAttributes
396Description:
397		Attributes of the current configuration, in hexadecimal.
398
399		See USB specs for its meaning.
400
401What:		/sys/bus/usb/devices/usbX/bMaxPacketSize0
402Description:
403		Maximum endpoint 0 packet size, in decimal.
404
405		See USB specs for its meaning.
406
407What:		/sys/bus/usb/devices/usbX/bMaxPower
408Description:
409		Maximum power consumption of the active configuration of
410		the device, in miliamperes.
411
412What:		/sys/bus/usb/devices/usbX/bNumConfigurations
413Description:
414		Number of the possible configurations of the device, in
415		decimal. The current configuration is controlled via:
416
417			/sys/bus/usb/devices/usbX/bConfigurationValue
418
419		See USB specs for its meaning.
420
421What:		/sys/bus/usb/devices/usbX/bNumEndpoints
422Description:
423		Number of endpoints used on this interface, in hexadecimal.
424
425		See USB specs for its meaning.
426
427What:		/sys/bus/usb/devices/usbX/bNumInterfaces
428Description:
429		Number of interfaces on this device, in decimal.
430
431What:		/sys/bus/usb/devices/usbX/busnum
432Description:
433		Number of the bus.
434
435What:		/sys/bus/usb/devices/usbX/configuration
436Description:
437		Contents of the string descriptor associated with the
438		current configuration. It may include the firmware version
439		of a device and/or its serial number.
440
441What:		/sys/bus/usb/devices/usbX/descriptors
442Description:
443		Contains the interface descriptors, in binary.
444
445What:		/sys/bus/usb/devices/usbX/bos_descriptors
446Date:		March 2024
447Contact:	Elbert Mai <code@elbertmai.com>
448Description:
449		Binary file containing the cached binary device object store (BOS)
450		of the device. This consists of the BOS descriptor followed by the
451		set of device capability descriptors. All descriptors read from
452		this file are in bus-endian format. Note that the kernel will not
453		request the BOS from a device if its bcdUSB is less than 0x0201.
454
455What:		/sys/bus/usb/devices/usbX/idProduct
456Description:
457		Product ID, in hexadecimal.
458
459What:		/sys/bus/usb/devices/usbX/idVendor
460Description:
461		Vendor ID, in hexadecimal.
462
463What:		/sys/bus/usb/devices/usbX/devspec
464Description:
465		Displays the Device Tree Open Firmware node of the interface.
466
467What:		/sys/bus/usb/devices/usbX/avoid_reset_quirk
468Description:
469		Most devices have this set to zero.
470
471		If the value is 1, enable a USB quirk that prevents this
472		device to use reset.
473
474		(read/write)
475
476What:		/sys/bus/usb/devices/usbX/devnum
477Description:
478		USB interface device number, in decimal.
479
480What:		/sys/bus/usb/devices/usbX/devpath
481Description:
482		String containing the USB interface device path.
483
484What:		/sys/bus/usb/devices/usbX/manufacturer
485Description:
486		Vendor specific string containing the name of the
487		manufacturer of the device.
488
489What:		/sys/bus/usb/devices/usbX/maxchild
490Description:
491		Number of ports of an USB hub
492
493What:		/sys/bus/usb/devices/usbX/persist
494Description:
495		Keeps the device even if it gets disconnected.
496
497What:		/sys/bus/usb/devices/usbX/product
498Description:
499		Vendor specific string containing the name of the
500		device's product.
501
502What:		/sys/bus/usb/devices/usbX/speed
503Description:
504		Shows the device's max speed, according to the USB version,
505		in Mbps.
506		Can be:
507
508			=======		====================
509			Unknown		speed unknown
510			1.5		Low speed
511			15		Full speed
512			480		High Speed
513			5000		Super Speed
514			10000		Super Speed+
515			20000		Super Speed+ Gen 2x2
516			=======		====================
517
518What:		/sys/bus/usb/devices/usbX/supports_autosuspend
519Description:
520		Returns 1 if the device doesn't support autosuspend.
521		Otherwise, returns 0.
522
523What:		/sys/bus/usb/devices/usbX/urbnum
524Description:
525		Number of URBs submitted for the whole device.
526
527What:		/sys/bus/usb/devices/usbX/version
528Description:
529		String containing the USB device version, as encoded
530		at the BCD descriptor.
531
532What:		/sys/bus/usb/devices/usbX/power/autosuspend
533Description:
534		Time in milliseconds for the device to autosuspend. If the
535		value is negative, then autosuspend is prevented.
536
537		(read/write)
538
539What:		/sys/bus/usb/devices/usbX/power/active_duration
540Description:
541		The total time the device has not been suspended.
542
543What:		/sys/bus/usb/devices/usbX/power/connected_duration
544Description:
545		The total time (in msec) that the device has been connected.
546
547What:		/sys/bus/usb/devices/usbX/power/level
548Description:
549
550What:		/sys/bus/usb/devices/usbX/ep_<N>/bEndpointAddress
551Description:
552		The address of the endpoint described by this descriptor,
553		in hexadecimal. The endpoint direction on this bitmapped field
554		is also shown at:
555
556			/sys/bus/usb/devices/usbX/ep_<N>/direction
557
558		See USB specs for its meaning.
559
560What:		/sys/bus/usb/devices/usbX/ep_<N>/bInterval
561Description:
562		The interval of the endpoint as described on its descriptor,
563		in hexadecimal. The actual interval depends on the version
564		of the USB. Also shown in time units at
565		/sys/bus/usb/devices/usbX/ep_<N>/interval.
566
567What:		/sys/bus/usb/devices/usbX/ep_<N>/bLength
568Description:
569		Number of bytes of the endpoint descriptor, in hexadecimal.
570
571What:		/sys/bus/usb/devices/usbX/ep_<N>/bmAttributes
572Description:
573		Attributes which apply to the endpoint as described on its
574		descriptor, in hexadecimal. The endpoint type on this
575		bitmapped field is also shown at:
576
577			/sys/bus/usb/devices/usbX/ep_<N>/type
578
579		See USB specs for its meaning.
580
581What:		/sys/bus/usb/devices/usbX/ep_<N>/direction
582Description:
583		Direction of the endpoint. Can be:
584
585		    - both (on control endpoints)
586		    - in
587		    - out
588
589What:		/sys/bus/usb/devices/usbX/ep_<N>/interval
590Description:
591		Interval for polling endpoint for data transfers, in
592		milisseconds or microseconds.
593
594What:		/sys/bus/usb/devices/usbX/ep_<N>/type
595Description:
596		Descriptor type. Can be:
597
598		    - Control
599		    - Isoc
600		    - Bulk
601		    - Interrupt
602		    - unknown
603
604What:		/sys/bus/usb/devices/usbX/ep_<N>/wMaxPacketSize
605Description:
606		Maximum packet size this endpoint is capable of
607		sending or receiving, in hexadecimal.
608