usb: Export BOS descriptor to sysfs

PATCH In review Elbert Mai 2 participants 2 messages Mar 5, 2024 USB

lore

Share & tools

lore

Elbert Mai

author

2024-03-05 00:23 UTC #0 lore raw

PATCH v2 1/1 usb: Export BOS descriptor to sysfs

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 <[email protected]>

---
Changes in v2:
- Rename to bos_descriptors (plural) since the attribute contains the entire BOS, not just the first descriptor in it.
- Use binary attribute groups to let driver core handle attribute creation for both descriptors and bos_descriptors.
- The attribute is visible in sysfs only if the BOS is present in the USB device.

 Documentation/ABI/testing/sysfs-bus-usb | 10 ++++
 drivers/usb/core/sysfs.c                | 78 +++++++++++++++++++------
 2 files changed, 71 insertions(+), 17 deletions(-)

Documentation/ABI/testing/sysfs-bus-usb +10 -0

index 614d216dff1d..102ee4215e48 100644
@@ -293,3 +293,13 @@ Description:
 		USB 3.2 adds Dual-lane support, 2 rx and 2 tx -lanes over Type-C.
 		Inter-Chip SSIC devices support asymmetric lanes up to 4 lanes per
 		direction. Devices before USB 3.2 are single lane (tx_lanes = 1)
+
+What:		/sys/bus/usb/devices/.../bos_descriptors
+Date:		March 2024
+Contact:	Elbert Mai <[email protected]>
+Description:
+		Binary file containing the cached binary device object store (BOS)
+		of the device. This consists of the BOS descriptor followed by the
+		set of device capability descriptors. All descriptors read from
+		this file are in bus-endian format. Note that the kernel will not
+		request the BOS from a device if its bcdUSB is less than 0x0201.

drivers/usb/core/sysfs.c +61 ~~-17~~

112 lines not on this page · raw message

Signature · 1 line

2.34.1

Greg KH

maintainer

2024-03-05 07:52 UTC #1 lore raw

Quoted 26 lines · Elbert Mai

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 <[email protected]>

Quoted 8 lines

---
Changes in v2:
- Rename to bos_descriptors (plural) since the attribute contains the entire BOS, not just the first descriptor in it.
- Use binary attribute groups to let driver core handle attribute creation for both descriptors and bos_descriptors.
- The attribute is visible in sysfs only if the BOS is present in the USB device.

Very nice, thanks for this!

One very minor comment, you can send a follow-on patch for this if you like:

drivers/usb/core/sysfs.c read_descriptors(struct file *filp, struct kobject *kobj, · line 955

Quoted 9 lines

drivers/usb/core/sysfs.c +9 -0

+static umode_t dev_bin_attrs_are_visible(struct kobject *kobj,
+		struct bin_attribute *a, int n)
+{
+	struct device *dev = kobj_to_dev(kobj);
+	struct usb_device *udev = to_usb_device(dev);
+
+	/* All USB devices have a device descriptor, so the descriptors
+	 * attribute always exists. No need to check for its visibility.
+	 */

This comment is in the "wrong" style, I think checkpatch will complain about that, right?

But it's a bit confusing, you say "no need to check", and then you:

drivers/usb/core/sysfs.c read_descriptors(struct file *filp, struct kobject *kobj, · line 959

Quoted 4 lines

drivers/usb/core/sysfs.c +4 -0

+	if (a == &bin_attr_bos_descriptors) {
+		if (udev->bos == NULL)
+			return 0;
+	}

check something :)

How about this as a comment instead:

	/*
	 * If this is the BOS descriptor, check to verify if the device
	 * has that descriptor at all or not.
	 */

That's all you need here, right?

Anyway, again, very nice, I'll go queue this up and run it through the 0-day tests.

thanks!

greg k -h