Skip to contentSkip to conversation

linux-next: build warning after merge of the usb tree

PATCH In review Stephen Rothwell 5 participants 11 messages Jan 23, 2023 – Apr 12, 2023

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

Hi all,

After merging the usb tree, today's linux-next build (htmldocs) produced this warning:

include/linux/usb/composite.h:510: warning: Function parameter or member 'bcd_webusb_version' not described in 'usb_composite_dev' include/linux/usb/composite.h:510: warning: Function parameter or member 'b_webusb_vendor_code' not described in 'usb_composite_dev' include/linux/usb/composite.h:510: warning: Function parameter or member 'landing_page' not described in 'usb_composite_dev' include/linux/usb/composite.h:510: warning: Function parameter or member 'use_webusb' not described in 'usb_composite_dev'

Introduced by commit

93c473948c58 ("usb: gadget: add WebUSB landing page support")

Signature · 2 lines
Cheers,
Stephen Rothwell
#1 lore raw
Quoted 5 lines · Stephen Rothwell

Hi all,

After merging the usb tree, today's linux-next build (htmldocs) produced this warning:

Quoted 8 lines

include/linux/usb/composite.h:510: warning: Function parameter or member 'bcd_webusb_version' not described in 'usb_composite_dev' include/linux/usb/composite.h:510: warning: Function parameter or member 'b_webusb_vendor_code' not described in 'usb_composite_dev' include/linux/usb/composite.h:510: warning: Function parameter or member 'landing_page' not described in 'usb_composite_dev' include/linux/usb/composite.h:510: warning: Function parameter or member 'use_webusb' not described in 'usb_composite_dev'

Introduced by commit

93c473948c58 ("usb: gadget: add WebUSB landing page support")

Jó, can you send a follow-on patch to fix this issue please?

thanks,

greg k-h

#2 lore raw

PATCH v5 1/1 usb: gadget: add WebUSB landing page support

There is a custom (non-USB IF) extension to the USB standard:

https://wicg.github.io/webusb/

This specification is published under the W3C Community Contributor Agreement, which in particular allows to implement the specification without any royalties.

The specification allows USB gadgets to announce an URL to landing page and describes a Javascript interface for websites to interact with the USB gadget, if the user allows it. It is currently supported by Chromium-based browsers, such as Chrome, Edge and Opera on all major operating systems including Linux.

This patch adds optional support for Linux-based USB gadgets wishing to expose such a landing page.

During device enumeration, a host recognizes that the announced USB version is at least 2.01, which means, that there are BOS descriptors available. The device than announces WebUSB support using a platform device capability. This includes a vendor code under which the landing page URL can be retrieved using a vendor-specific request.

Previously, the BOS descriptors would unconditionally include an LPM related descriptor, as BOS descriptors were only ever sent when the device was LPM capable. As this is no longer the case, this patch puts this descriptor behind a lpm_capable condition.

Usage is modeled after os_desc descriptors:
echo 1 > webusb/use
echo "https://www.kernel.org" > webusb/landingPage

lsusb will report the device with the following lines:
Platform Device Capability:
bLength 24
bDescriptorType 16
bDevCapabilityType 5
bReserved 0
PlatformCapabilityUUID {3408b638-09a9-47a0-8bfd-a0768815b665}
WebUSB:
bcdVersion 1.00
bVendorCode 0
iLandingPage 1 https://www.kernel.org

---
V4 -> V5: * Addressed the htmldocs warnings reported by Stephen Rothwell
* Fixed GUID/UID usage as pointed out by Andy Shevchenko
* Changed locking in configfs as pointed out by Andy Shevchenko
V3 -> V4: Addressed comments by Andrzej Pietrasiewicz and Alan Stern
* Moved WebUSB specific structs and constants to its own header file
* added structs for all descriptors sent
* added the magic numbers to the new header file with links to the specification
* added length validation to landingPage sysfs interface
V2 -> V3: improved commit message to include additional condition in desc_bos as per comment
by Alan Stern
V1 -> V2: cleaned up coding style, made URL scheme comparison case insensitive, addressed review
comments by Alan Stern
V0 -> V1: use sysfs_emit instead of sprintf and use lock in webusb_bcdVersion_store, addressed review
comments by Christophe JAILLET

Checkpatch currently gives a warning if MAINTAINERS should be updated. I didn't because I feel this patch is too small for adding me here. Nevertheless, if you think I should, let me know.

 Documentation/ABI/testing/configfs-usb-gadget |  13 ++
 drivers/usb/gadget/composite.c                | 102 +++++++++--
 drivers/usb/gadget/configfs.c                 | 168 ++++++++++++++++++
 include/linux/usb/composite.h                 |  11 ++
 include/linux/usb/webusb.h                    |  80 +++++++++
 include/uapi/linux/usb/ch9.h                  |  16 ++
 6 files changed, 380 insertions(+), 10 deletions(-)
 create mode 100644 include/linux/usb/webusb.h
Documentation/ABI/testing/configfs-usb-gadget +13 -0
index b7943aa7e997..a8bb896def54 100644
@@ -143,3 +143,16 @@ Description:
 		qw_sign		an identifier to be reported as "OS String"
 				proper
 		=============	===============================================
+
+What:		/config/usb-gadget/gadget/webusb
+Date:		Dec 2022
+KernelVersion:	6.3
+Description:
+		This group contains "WebUSB" extension handling attributes.
+
+		=============	===============================================
+		use		flag turning "WebUSB" support on/off
+		bcdVersion	bcd WebUSB specification version number
+		bVendorCode	one-byte value used for custom per-device
+		landingPage	UTF-8 encoded URL of the device's landing page
+		=============	===============================================
drivers/usb/gadget/composite.c +92 -10

141 lines not on this page · raw message

drivers/usb/gadget/configfs.c +168 -0

204 lines not on this page · raw message

include/linux/usb/composite.h +11 -0
index 43ac3fa760db..7ef8cea67f50 100644
@@ -25,6 +25,7 @@
 #include <linux/version.h>
 #include <linux/usb/ch9.h>
 #include <linux/usb/gadget.h>
+#include <linux/usb/webusb.h>
 #include <linux/log2.h>
 #include <linux/configfs.h>
 
@@ -431,6 +432,10 @@ static inline struct usb_composite_driver *to_cdriver(
  * @qw_sign: qwSignature part of the OS string
  * @b_vendor_code: bMS_VendorCode part of the OS string
  * @use_os_string: false by default, interested gadgets set it
+ * @bcd_webusb_version: 0x0100 by default, WebUSB specification version
+ * @b_webusb_vendor_code: 0x0 by default, vendor code for WebUSB
+ * @landing_page: empty by default, landing page to announce in WebUSB
+ * @use_webusb:: false by default, interested gadgets set it
  * @os_desc_config: the configuration to be used with OS descriptors
  * @setup_pending: true when setup request is queued but not completed
  * @os_desc_pending: true when os_desc request is queued but not completed
@@ -474,6 +479,12 @@ struct usb_composite_dev {
 	struct usb_configuration	*os_desc_config;
 	unsigned int			use_os_string:1;
 
+	/* WebUSB */
+	u16				bcd_webusb_version;
+	u8				b_webusb_vendor_code;
+	char				landing_page[WEBUSB_URL_RAW_MAX_LENGTH];
+	unsigned int			use_webusb:1;
+
 	/* private: */
 	/* internals */
 	unsigned int			suspended:1;
include/linux/usb/webusb.h new file +80 -0

80 lines not on this page · raw message

include/uapi/linux/usb/ch9.h +16 -0
index 31fcfa084e63..b17e3a21b15f 100644
@@ -947,6 +947,22 @@ struct usb_ss_container_id_descriptor {
 
 #define USB_DT_USB_SS_CONTN_ID_SIZE	20
 
+/*
+ * Platform Device Capability descriptor: Defines platform specific device
+ * capabilities
+ */
+#define	USB_PLAT_DEV_CAP_TYPE	5
+struct usb_plat_dev_cap_descriptor {
+	__u8  bLength;
+	__u8  bDescriptorType;
+	__u8  bDevCapabilityType;
+	__u8  bReserved;
+	__u8  UUID[16];
+	__u8  CapabilityData[];
+} __attribute__((packed));
+
+#define USB_DT_USB_PLAT_DEV_CAP_SIZE(capability_data_size)	(20 + capability_data_size)
+
 /*
  * SuperSpeed Plus USB Capability descriptor: Defines the set of
  * SuperSpeed Plus USB specific device level capabilities
Signature · 1 line
2.37.2
maintainer
#3 lore raw

Re: [PATCH v5] usb: gadget: add WebUSB landing page support

Quoted 7 lines · Jó Ágila Bitsch

There is a custom (non-USB IF) extension to the USB standard:

https://wicg.github.io/webusb/

This specification is published under the W3C Community Contributor Agreement, which in particular allows to implement the specification without any royalties.

<snip>

No, I can't revert the existing patch and then add this one, just send a set of follow-on patches that fix up the needed things and I can apply that as I can not rebase my public tree.

thanks,

greg k-h

#4 lore raw

Re: [PATCH v5] usb: gadget: add WebUSB landing page support

Thanks for letting me know. I'm not that sure on the exact process yet, so thanks a lot for bearing with me.

I'll send a new patch in a few moments.

Thanks,
Jó

Quoted 19 lines · Greg KH
Quoted 7 lines · Jó Ágila Bitsch

There is a custom (non-USB IF) extension to the USB standard:

https://wicg.github.io/webusb/

This specification is published under the W3C Community Contributor Agreement, which in particular allows to implement the specification without any royalties.

<snip>

No, I can't revert the existing patch and then add this one, just send a set of follow-on patches that fix up the needed things and I can apply that as I can not rebase my public tree.

thanks,

greg k-h

#5 lore raw
In reply to Greg KH
Quoted 14 lines · Greg KH
Quoted 12 lines · Stephen Rothwell

Hi all,

After merging the usb tree, today's linux-next build (htmldocs) produced this warning:

include/linux/usb/composite.h:510: warning: Function parameter or member 'bcd_webusb_version' not described in 'usb_composite_dev' include/linux/usb/composite.h:510: warning: Function parameter or member 'b_webusb_vendor_code' not described in 'usb_composite_dev' include/linux/usb/composite.h:510: warning: Function parameter or member 'landing_page' not described in 'usb_composite_dev' include/linux/usb/composite.h:510: warning: Function parameter or member 'use_webusb' not described in 'usb_composite_dev'

Introduced by commit

Quoted 7 lines
Quoted 1 line

93c473948c58 ("usb: gadget: add WebUSB landing page support")

Jó, can you send a follow-on patch to fix this issue please?

thanks,

greg k-h

I just posted a new version where I also merged in Andy Shevchenko's patches against by patch.

Best regards,
Jó

#6 lore raw

PATCH 1/1 usb: gadget: add doc to struct usb_composite_dev

In reply to Greg KH

Added documentation to the new struct members:
* bcd_webusb_version
* b_webusb_vendor_code
* landing_page
* use_webusb
to avoid warnings in the build of htmldocs

---
 include/linux/usb/composite.h | 4 ++++
 1 file changed, 4 insertions(+)
include/linux/usb/composite.h +4 -0
index 91d22c3ed458..7ef8cea67f50 100644
@@ -432,6 +432,10 @@ static inline struct usb_composite_driver *to_cdriver(
  * @qw_sign: qwSignature part of the OS string
  * @b_vendor_code: bMS_VendorCode part of the OS string
  * @use_os_string: false by default, interested gadgets set it
+ * @bcd_webusb_version: 0x0100 by default, WebUSB specification version
+ * @b_webusb_vendor_code: 0x0 by default, vendor code for WebUSB
+ * @landing_page: empty by default, landing page to announce in WebUSB
+ * @use_webusb:: false by default, interested gadgets set it
  * @os_desc_config: the configuration to be used with OS descriptors
  * @setup_pending: true when setup request is queued but not completed
  * @os_desc_pending: true when os_desc request is queued but not completed
Signature · 1 line
2.37.2
#7 lore raw

Re: [PATCH] usb: gadget: add doc to struct usb_composite_dev

Quoted 8 lines · Jó Ágila Bitsch

Added documentation to the new struct members:
* bcd_webusb_version
* b_webusb_vendor_code
* landing_page
* use_webusb
to avoid warnings in the build of htmldocs

What commit id does this fix?

And it was reported by Stephen, so can you provide a reported-by tag too?

thanks,
greg k-h

maintainer
#8 lore raw

Re: [PATCH] usb: gadget: add doc to struct usb_composite_dev

In reply to Jó Ágila Bitsch
Quoted 8 lines · Jó Ágila Bitsch

Added documentation to the new struct members:
* bcd_webusb_version
* b_webusb_vendor_code
* landing_page
* use_webusb
to avoid warnings in the build of htmldocs

You forgot a Reported-by: tag?

Also didn't cc: the linux-usb mailing list?

please fix up and send v2.

thanks,

greg k-h

#9 lore raw

PATCH v2 1/1 usb: gadget: add doc to struct usb_composite_dev

Added documentation to new struct members for WebUSB:
* bcd_webusb_version
* b_webusb_vendor_code
* landing_page
* use_webusb
to avoid warnings in the build of htmldocs

Fixes 93c473948c58 ("usb: gadget: add WebUSB landing page support")

---
V0 -> V1: added Reported-By and Fixes Tags
V1 -> V2: fixed Reported-by tag (capitalization of "-by" was wrong)
also post to linux-usb

 include/linux/usb/composite.h | 4 ++++
 1 file changed, 4 insertions(+)
include/linux/usb/composite.h +4 -0
index 91d22c3ed458..7ef8cea67f50 100644
@@ -432,6 +432,10 @@ static inline struct usb_composite_driver *to_cdriver(
  * @qw_sign: qwSignature part of the OS string
  * @b_vendor_code: bMS_VendorCode part of the OS string
  * @use_os_string: false by default, interested gadgets set it
+ * @bcd_webusb_version: 0x0100 by default, WebUSB specification version
+ * @b_webusb_vendor_code: 0x0 by default, vendor code for WebUSB
+ * @landing_page: empty by default, landing page to announce in WebUSB
+ * @use_webusb:: false by default, interested gadgets set it
  * @os_desc_config: the configuration to be used with OS descriptors
  * @setup_pending: true when setup request is queued but not completed
  * @os_desc_pending: true when os_desc request is queued but not completed
Signature · 1 line
2.37.2
#10 lore raw

Re: [PATCH v2] usb: gadget: add doc to struct usb_composite_dev

Hi,

Quoted 23 lines · Jó Ágila Bitsch

Added documentation to new struct members for WebUSB:
* bcd_webusb_version
* b_webusb_vendor_code
* landing_page
* use_webusb
to avoid warnings in the build of htmldocs

Fixes 93c473948c58 ("usb: gadget: add WebUSB landing page support")

---
V0 -> V1: added Reported-By and Fixes Tags
V1 -> V2: fixed Reported-by tag (capitalization of "-by" was wrong)
also post to linux-usb

 include/linux/usb/composite.h | 4 ++++
 1 file changed, 4 insertions(+)
include/linux/usb/composite.h +0 -0
index 91d22c3ed458..7ef8cea67f50 100644

include/linux/usb/composite.h static inline struct usb_composite_driver *to_cdriver( · line 438

Quoted 7 lines
include/linux/usb/composite.h +4 -0
@@ -432,6 +432,10 @@ static inline struct usb_composite_driver *to_cdriver(
  * @qw_sign: qwSignature part of the OS string
  * @b_vendor_code: bMS_VendorCode part of the OS string
  * @use_os_string: false by default, interested gadgets set it
+ * @bcd_webusb_version: 0x0100 by default, WebUSB specification version
+ * @b_webusb_vendor_code: 0x0 by default, vendor code for WebUSB
+ * @landing_page: empty by default, landing page to announce in WebUSB
+ * @use_webusb:: false by default, interested gadgets set it

Please drop one ':' above so that kernel-doc does not complain:

include/linux/usb/composite.h:523: warning: Function parameter or member 'use_webusb' not described in 'usb_composite_dev'

include/linux/usb/composite.h static inline struct usb_composite_driver *to_cdriver( · line 441

Quoted 3 lines
include/linux/usb/composite.h +0 -0
  * @os_desc_config: the configuration to be used with OS descriptors
  * @setup_pending: true when setup request is queued but not completed
  * @os_desc_pending: true when os_desc request is queued but not completed

Thanks.

Signature · 1 line
~Randy