linux-next: build warning after merge of the usb tree
Subsystems (2)
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
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
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
@@ -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
@@ -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
@@ -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
Greg KH
maintainerRe: [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
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
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ó
PATCH 1/1 usb: gadget: add doc to struct usb_composite_dev
In reply to Greg KHAdded 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
@@ -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
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 htmldocsSigned-off-by Jó Ágila Bitsch <[email protected]>
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
Greg KH
maintainerRe: [PATCH] usb: gadget: add doc to struct usb_composite_dev
In reply to Jó Ágila BitschQuoted 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 htmldocsSigned-off-by Jó Ágila Bitsch <[email protected]>
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
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
---
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
@@ -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
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 htmldocsFixes 93c473948c58 ("usb: gadget: add WebUSB landing page support")Reported-by Stephen Rothwell <[email protected]>Signed-off-by Jó Ágila Bitsch <[email protected]>---
V0 -> V1: added Reported-By and Fixes Tags
V1 -> V2: fixed Reported-by tag (capitalization of "-by" was wrong)
also post to linux-usbinclude/linux/usb/composite.h | 4 ++++ 1 file changed, 4 insertions(+)include/linux/usb/composite.h +0
-0
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