linux-toradex.git/Documentation/ABI/testing/sysfs-bus-usb, branch v6.15 Linux kernel for Apalis and Colibri modules usb: Export BOS descriptor to sysfs 2024-03-05T07:57:23+00:00 Elbert Mai code@elbertmai.com 2024-03-05T00:23:01+00:00 12fc84e8c4288cc8ed5f14a35e077130c2cfece2 Motivation ---------- The binary device object store (BOS) of a USB device consists of the BOS descriptor followed by a set of device capability descriptors. One that is of interest to users is the platform descriptor. This contains a 128-bit UUID and arbitrary data, and it allows parties outside of USB-IF to add additional metadata about a USB device in a standards-compliant manner. Notable examples include the WebUSB and Microsoft OS 2.0 descriptors. The kernel already retrieves and caches the BOS from USB devices if its bcdUSB is >= 0x0201. Because the BOS is flexible and extensible, we export the entire BOS to sysfs so users can retrieve whatever device capabilities they desire, without requiring USB I/O or elevated permissions. Implementation -------------- Add bos_descriptors attribute to sysfs. This is a binary file and it works the same way as the existing descriptors attribute. The file exists only if the BOS is present in the USB device. Also create a binary attribute group, so the driver core can handle the creation of both the descriptors and bos_descriptors attributes in sysfs. Signed-off-by: Elbert Mai <code@elbertmai.com> Link: https://lore.kernel.org/r/20240305002301.95323-1-code@elbertmai.com Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> 
Motivation
----------

The binary device object store (BOS) of a USB device consists of the BOS
descriptor followed by a set of device capability descriptors. One that is
of interest to users is the platform descriptor. This contains a 128-bit
UUID and arbitrary data, and it allows parties outside of USB-IF to add
additional metadata about a USB device in a standards-compliant manner.
Notable examples include the WebUSB and Microsoft OS 2.0 descriptors.

The kernel already retrieves and caches the BOS from USB devices if its
bcdUSB is >= 0x0201. Because the BOS is flexible and extensible, we export
the entire BOS to sysfs so users can retrieve whatever device capabilities
they desire, without requiring USB I/O or elevated permissions.

Implementation
--------------

Add bos_descriptors attribute to sysfs. This is a binary file and it works
the same way as the existing descriptors attribute. The file exists only if
the BOS is present in the USB device.

Also create a binary attribute group, so the driver core can handle the
creation of both the descriptors and bos_descriptors attributes in sysfs.

Signed-off-by: Elbert Mai <code@elbertmai.com>
Link: https://lore.kernel.org/r/20240305002301.95323-1-code@elbertmai.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
usb: typec: Link enumerated USB devices with Type-C partner 2023-10-16T18:02:36+00:00 Heikki Krogerus heikki.krogerus@linux.intel.com 2023-10-11T10:58:24+00:00 59de2a56d127890cc610f3896d5fc31887c54ac2 Adding functions that USB hub code can use to inform the Type-C class about connected USB devices. Once taken into use, it will allow the Type-C port drivers to power off components that are not needed, for example if USB2 device is enumerated, everything that is only relevant for USB3 (retimers, etc.), can be powered off. This will also create a symlink "typec" for the USB devices pointing to the USB Type-C partner device. Suggested-by: Benson Leung <bleung@chromium.org> Tested-by: Benson Leung <bleung@chromium.org> Signed-off-by: Heikki Krogerus <heikki.krogerus@linux.intel.com> Link: https://lore.kernel.org/r/20231011105825.320062-2-heikki.krogerus@linux.intel.com Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> 
Adding functions that USB hub code can use to inform the
Type-C class about connected USB devices.

Once taken into use, it will allow the Type-C port drivers
to power off components that are not needed, for example if
USB2 device is enumerated, everything that is only relevant
for USB3 (retimers, etc.), can be powered off.

This will also create a symlink "typec" for the USB devices
pointing to the USB Type-C partner device.

Suggested-by: Benson Leung <bleung@chromium.org>
Tested-by: Benson Leung <bleung@chromium.org>
Signed-off-by: Heikki Krogerus <heikki.krogerus@linux.intel.com>
Link: https://lore.kernel.org/r/20231011105825.320062-2-heikki.krogerus@linux.intel.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
USB: Remove Wireless USB and UWB documentation 2023-08-09T12:17:32+00:00 Alan Stern stern@rowland.harvard.edu 2023-08-09T00:44:35+00:00 f176638af476c6d46257cc3303f5c7cf47d5967d Support for Wireless USB and Ultra WideBand was removed in 2020 by commit caa6772db4c1 ("Staging: remove wusbcore and UWB from the kernel tree."). But the documentation files were left behind. Let's get rid of that out-of-date documentation. Signed-off-by: Alan Stern <stern@rowland.harvard.edu> Link: https://lore.kernel.org/r/015d4310-bcd3-4ba4-9a0e-3664f281a9be@rowland.harvard.edu Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> 
Support for Wireless USB and Ultra WideBand was removed in 2020 by
commit caa6772db4c1 ("Staging: remove wusbcore and UWB from the kernel
tree.").  But the documentation files were left behind.

Let's get rid of that out-of-date documentation.

Signed-off-by: Alan Stern <stern@rowland.harvard.edu>
Link: https://lore.kernel.org/r/015d4310-bcd3-4ba4-9a0e-3664f281a9be@rowland.harvard.edu
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
usb: core: add sysfs entry for usb device state 2023-06-13T09:58:26+00:00 Roy Luo royluo@google.com 2023-06-08T01:59:12+00:00 83cb2604f641cecadc275ca18adbba4bf262320f Expose usb device state to userland as the information is useful in detecting non-compliant setups and diagnosing enumeration failures. For example: - End-to-end signal integrity issues: the device would fail port reset repeatedly and thus be stuck in POWERED state. - Charge-only cables (missing D+/D- lines): the device would never enter POWERED state as the HC would not see any pullup. What's the status quo? We do have error logs such as "Cannot enable. Maybe the USB cable is bad?" to flag potential setup issues, but there's no good way to expose them to userspace. Why add a sysfs entry in struct usb_port instead of struct usb_device? The struct usb_device is not device_add() to the system until it's in ADDRESS state hence we would miss the first two states. The struct usb_port is a better place to keep the information because its life cycle is longer than the struct usb_device that is attached to the port. Reported-by: kernel test robot <oliver.sang@intel.com> Closes: https://lore.kernel.org/oe-lkp/202306042228.e532af6e-oliver.sang@intel.com Reviewed-by: Alan Stern <stern@rowland.harvard.edu> Signed-off-by: Roy Luo <royluo@google.com> Message-ID: <20230608015913.1679984-1-royluo@google.com> Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> 
Expose usb device state to userland as the information is useful in
detecting non-compliant setups and diagnosing enumeration failures.
For example:
- End-to-end signal integrity issues: the device would fail port reset
  repeatedly and thus be stuck in POWERED state.
- Charge-only cables (missing D+/D- lines): the device would never enter
  POWERED state as the HC would not see any pullup.

What's the status quo?
We do have error logs such as "Cannot enable. Maybe the USB cable is bad?"
to flag potential setup issues, but there's no good way to expose them to
userspace.

Why add a sysfs entry in struct usb_port instead of struct usb_device?
The struct usb_device is not device_add() to the system until it's in
ADDRESS state hence we would miss the first two states. The struct
usb_port is a better place to keep the information because its life
cycle is longer than the struct usb_device that is attached to the port.

Reported-by: kernel test robot <oliver.sang@intel.com>
Closes: https://lore.kernel.org/oe-lkp/202306042228.e532af6e-oliver.sang@intel.com
Reviewed-by: Alan Stern <stern@rowland.harvard.edu>
Signed-off-by: Roy Luo <royluo@google.com>
Message-ID: <20230608015913.1679984-1-royluo@google.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
USB: core: Add wireless_status sysfs attribute 2023-04-03T11:30:08+00:00 Bastien Nocera hadess@hadess.net 2023-03-02T10:55:53+00:00 f98e0640c5c6b8bb00336dae8d06ede862754c28 Add a wireless_status sysfs attribute to USB devices to keep track of whether a USB device that's comprised of a receiver dongle and an emitter device over a, most of the time proprietary, wireless link has its emitter connected or disconnected. This will be used by user-space OS components to determine whether the battery-powered part of the device is wirelessly connected or not, allowing, for example: - upower to hide the battery for devices where the device is turned off but the receiver plugged in, rather than showing 0%, or other values that could be confusing to users - Pipewire to hide a headset from the list of possible inputs or outputs or route audio appropriately if the headset is suddenly turned off, or turned on - libinput to determine whether a keyboard or mouse is present when its receiver is plugged in. This is done at the USB interface level as: - the interface on which the wireless status is detected is sometimes not the same as where it could be consumed (eg. the audio interface on a headset dongle will still appear even if the headset is turned off), and we cannot have synchronisation of status across subsystems. - this behaviour is not specific to HID devices, even if the protocols used to determine whether or not the remote device is connected can be HID. This is not an attribute that is meant to replace protocol specific APIs, such as the ones available for WWAN, WLAN/Wi-Fi, or Bluetooth or any other sort of networking, but solely for wireless devices with an ad-hoc “lose it and your device is e-waste” receiver dongle. The USB interface will only be exporting the wireless_status sysfs attribute if it gets set through the API exported in the next commit. Signed-off-by: Bastien Nocera <hadess@hadess.net> Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Acked-by: Alan Stern <stern@rowland.harvard.edu> Link: https://lore.kernel.org/r/20230302105555.51417-4-hadess@hadess.net Signed-off-by: Benjamin Tissoires <benjamin.tissoires@redhat.com> 
Add a wireless_status sysfs attribute to USB devices to keep track of
whether a USB device that's comprised of a receiver dongle and an emitter
device over a, most of the time proprietary, wireless link has its emitter
connected or disconnected.

This will be used by user-space OS components to determine whether the
battery-powered part of the device is wirelessly connected or not,
allowing, for example:
- upower to hide the battery for devices where the device is turned off
  but the receiver plugged in, rather than showing 0%, or other values
  that could be confusing to users
- Pipewire to hide a headset from the list of possible inputs or outputs
  or route audio appropriately if the headset is suddenly turned off, or
  turned on
- libinput to determine whether a keyboard or mouse is present when its
  receiver is plugged in.

This is done at the USB interface level as:
- the interface on which the wireless status is detected is sometimes
  not the same as where it could be consumed (eg. the audio interface
  on a headset dongle will still appear even if the headset is turned
  off), and we cannot have synchronisation of status across subsystems.
- this behaviour is not specific to HID devices, even if the protocols
  used to determine whether or not the remote device is connected can
  be HID.

This is not an attribute that is meant to replace protocol specific
APIs, such as the ones available for WWAN, WLAN/Wi-Fi, or Bluetooth
or any other sort of networking, but solely for wireless devices with
an ad-hoc “lose it and your device is e-waste” receiver dongle.

The USB interface will only be exporting the wireless_status sysfs
attribute if it gets set through the API exported in the next commit.

Signed-off-by: Bastien Nocera <hadess@hadess.net>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Acked-by: Alan Stern <stern@rowland.harvard.edu>
Link: https://lore.kernel.org/r/20230302105555.51417-4-hadess@hadess.net
Signed-off-by: Benjamin Tissoires <benjamin.tissoires@redhat.com>
usb: core: stop USB enumeration if too many retries 2022-11-08T15:50:21+00:00 Ray Chi raychi@google.com 2022-11-07T07:27:54+00:00 430d57f53eb1cdbf9ba9bbd397317912b3cd2de5 When a broken USB accessory connects to a USB host, usbcore might keep doing enumeration retries. If the host has a watchdog mechanism, the kernel panic will happen on the host. This patch provides an attribute early_stop to limit the numbers of retries for each port of a hub. If a port was marked with early_stop attribute, unsuccessful connection attempts will fail quickly. In addition, if an early_stop port has failed to initialize, it will ignore all future connection events until early_stop attribute is clear. Signed-off-by: Ray Chi <raychi@google.com> Reviewed-by: Alan Stern <stern@rowland.harvard.edu> Link: https://lore.kernel.org/r/20221107072754.3336357-1-raychi@google.com Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> 
When a broken USB accessory connects to a USB host, usbcore might
keep doing enumeration retries. If the host has a watchdog mechanism,
the kernel panic will happen on the host.

This patch provides an attribute early_stop to limit the numbers of retries
for each port of a hub. If a port was marked with early_stop attribute,
unsuccessful connection attempts will fail quickly. In addition, if an
early_stop port has failed to initialize, it will ignore all future
connection events until early_stop attribute is clear.

Signed-off-by: Ray Chi <raychi@google.com>
Reviewed-by: Alan Stern <stern@rowland.harvard.edu>
Link: https://lore.kernel.org/r/20221107072754.3336357-1-raychi@google.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
usb: hub: port: add sysfs entry to switch port power 2022-06-12T04:49:46+00:00 Michael Grzeschik m.grzeschik@pengutronix.de 2022-06-07T11:45:22+00:00 f061f43d7418cb62b8d073e221ec75d3f5b89e17 In some cases the port of an hub needs to be disabled or switched off and on again. E.g. when the connected device needs to be re-enumerated. Or it needs to be explicitly disabled while the rest of the usb tree stays working. For this purpose this patch adds an sysfs switch to enable/disable the port on any hub. In the case the hub is supporting power switching, the power line will be disabled to the connected device. When the port gets disabled, the associated device gets disconnected and removed from the logical usb tree. No further device will be enumerated on that port until the port gets enabled again. Reviewed-by: Alan Stern <stern@rowland.harvard.edu> Signed-off-by: Michael Grzeschik <m.grzeschik@pengutronix.de> Link: https://lore.kernel.org/r/20220607114522.3359148-1-m.grzeschik@pengutronix.de Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> 
In some cases the port of an hub needs to be disabled or switched off
and on again. E.g. when the connected device needs to be re-enumerated.
Or it needs to be explicitly disabled while the rest of the usb tree
stays working.

For this purpose this patch adds an sysfs switch to enable/disable the
port on any hub. In the case the hub is supporting power switching, the
power line will be disabled to the connected device.

When the port gets disabled, the associated device gets disconnected and
removed from the logical usb tree. No further device will be enumerated
on that port until the port gets enabled again.

Reviewed-by: Alan Stern <stern@rowland.harvard.edu>
Signed-off-by: Michael Grzeschik <m.grzeschik@pengutronix.de>
Link: https://lore.kernel.org/r/20220607114522.3359148-1-m.grzeschik@pengutronix.de
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
usb: Link the ports to the connectors they are attached to 2021-12-30T11:13:04+00:00 Heikki Krogerus heikki.krogerus@linux.intel.com 2021-12-23T08:23:49+00:00 8c67d06f3fd9639c44d8147483fb1c132d71388f Creating link to the USB Type-C connector for every new port that is added when possible. Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com> Acked-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com> Signed-off-by: Heikki Krogerus <heikki.krogerus@linux.intel.com> Link: https://lore.kernel.org/r/20211223082349.45616-1-heikki.krogerus@linux.intel.com Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> 
Creating link to the USB Type-C connector for every new port
that is added when possible.

Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Acked-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Signed-off-by: Heikki Krogerus <heikki.krogerus@linux.intel.com>
Link: https://lore.kernel.org/r/20211223082349.45616-1-heikki.krogerus@linux.intel.com
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
ABI: sysfs-bus-usb: add missing sysfs fields 2021-09-28T10:48:15+00:00 Mauro Carvalho Chehab mchehab+huawei@kernel.org 2021-09-27T13:59:47+00:00 989eff9cdb799d1366c8cdd3456cec4083a9a6d6 There are lots of interface, power and endpoint properties that are currently missing any documentation. Add a description for them. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/7f6f7b955032836546f78a9041b22c10b6f4bc5b.1632750608.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> 
There are lots of interface, power and endpoint properties that are currently
missing any documentation.

Add a description for them.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/7f6f7b955032836546f78a9041b22c10b6f4bc5b.1632750608.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
ABI: sysfs-bus-usb: use a wildcard for interface name on What 2021-09-28T10:48:15+00:00 Mauro Carvalho Chehab mchehab+huawei@kernel.org 2021-09-27T13:59:46+00:00 e06ab8d57433086f8fafa71516564d15d6e3c430 Use <INTERFACE> instead of INTERFACE, in order for the get_abi.pl script to be able to identify this as a wildcard. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Link: https://lore.kernel.org/r/cec7048385b6a4779894e19af681226e60f4d8b9.1632750608.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> 
Use <INTERFACE> instead of INTERFACE, in order for the get_abi.pl
script to be able to identify this as a wildcard.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/cec7048385b6a4779894e19af681226e60f4d8b9.1632750608.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>