usb: gadget: add WebUSB support
PATCH 1/1 usb: gadget: add WebUSB 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.
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
--- Documentation/ABI/testing/configfs-usb-gadget | 13 ++ drivers/usb/gadget/composite.c | 102 +++++++++++-- drivers/usb/gadget/configfs.c | 139 ++++++++++++++++++ include/linux/usb/composite.h | 6 + include/uapi/linux/usb/ch9.h | 33 +++++ 5 files changed, 283 insertions(+), 10 deletions(-)
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.2 +Description: + This group contains "WebUSB" extension handling attributes. + + ============= =============================================== + use flag turning "WebUSB" support on/off + bcdVersion bcd WebUSB specification version number + b_vendor_code one-byte value used for custom per-device + landing_page UTF-8 encoded URL of the device's landing page + ============= ===============================================
drivers/usb/gadget/composite.c +92 -10
138 lines not on this page · raw message
drivers/usb/gadget/configfs.c +139 -0
169 lines not on this page · raw message
include/linux/usb/composite.h +6 -0
@@ -474,6 +474,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[255 ]; + unsigned int use_webusb:1; +/* private: */ /* internals */ unsigned int suspended:1;
include/uapi/linux/usb/ch9.h +33 -0
@@ -947,6 +947,39 @@ 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 ]; +} __attribute__((packed)); + +#define USB_DT_USB_PLAT_DEV_CAP_SIZE 20 + +/* +* WebUSB Platform Capability descriptor: A device announces support for the +* WebUSB command set by including the following Platform Descriptor in its +* Binary Object Store +* https://wicg.github.io/webusb/#webusb-platform-capability-descriptor +*/ +struct usb_webusb_cap_descriptor { +__u8 bLength; +__u8 bDescriptorType; +__u8 bDevCapabilityType; +__u8 bReserved; +__u8 UUID[16 ]; +__u16 bcdVersion; +__u8 bVendorCode; +__u8 iLandingPage; +} __attribute__((packed)); +#define USB_DT_WEBUSB_SIZE (USB_DT_USB_PLAT_DEV_CAP_SIZE + 4) +/* * SuperSpeed Plus USB Capability descriptor: Defines the set of * SuperSpeed Plus USB specific device level capabilities
Signature · 1 line
2.37.2
Le 30/12/2022 à 17:58, Jó Ágila Bitsch a écrit :
Quoted 40 lines
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.
Usage is modeled after
os_descdescriptors:
echo 1 > webusb/use
echo "https://www.kernel.org" > webusb/landingPagelsusb 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
Quoted 1 line
Signed-off-by Jó Ágila Bitsch <[email protected]>
Hi,
a few nits below.
CJ
Quoted 207 lines
--- Documentation/ABI/testing/configfs-usb-gadget | 13 ++ drivers/usb/gadget/composite.c | 102 +++++++++++-- drivers/usb/gadget/configfs.c | 139 ++++++++++++++++++ include/linux/usb/composite.h | 6 + include/uapi/linux/usb/ch9.h | 33 +++++ 5 files changed, 283 insertions(+), 10 deletions(-)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.2 +Description: + This group contains "WebUSB" extension handling attributes. + + ============= =============================================== + use flag turning "WebUSB" support on/off + bcdVersion bcd WebUSB specification version number + b_vendor_code one-byte value used for custom per-device + landing_page UTF-8 encoded URL of the device's landing page + ============= ===============================================drivers/usb/gadget/composite.c +92
-10@@ -14,6 +14,7 @@#include <linux/device.h> #include <linux/utsname.h> #include <linux/bitfield.h> +#include <linux/uuid.h> #include <linux/usb/composite.h> #include <linux/usb/otg.h> @@ -713,14 +714,16 @@ static int bos_desc(struct usb_composite_dev *cdev)* A SuperSpeed device shall include the USB2.0 extension descriptor * and shall support LPM when operating in USB2.0 HS mode. */ - usb_ext = cdev->req->buf +le16_to_cpu (bos->wTotalLength); - bos->bNumDeviceCaps++; -le16_add_cpu (&bos->wTotalLength,USB_DT_USB_EXT_CAP_SIZE ); - usb_ext->bLength =USB_DT_USB_EXT_CAP_SIZE ; - usb_ext->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; - usb_ext->bDevCapabilityType =USB_CAP_TYPE_EXT ; - usb_ext->bmAttributes =cpu_to_le32 (USB_LPM_SUPPORT | -USB_BESL_SUPPORT | besl); +if (cdev->gadget->lpm_capable) { + usb_ext = cdev->req->buf +le16_to_cpu (bos->wTotalLength); + bos->bNumDeviceCaps++; +le16_add_cpu (&bos->wTotalLength,USB_DT_USB_EXT_CAP_SIZE ); + usb_ext->bLength =USB_DT_USB_EXT_CAP_SIZE ; + usb_ext->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; + usb_ext->bDevCapabilityType =USB_CAP_TYPE_EXT ; + usb_ext->bmAttributes =cpu_to_le32 (USB_LPM_SUPPORT | +USB_BESL_SUPPORT | besl); + }/* * The Superspeed USB Capability descriptor shall be implemented by all @@ -821,6 +824,41 @@ static int bos_desc(struct usb_composite_dev *cdev) } } +/* +* Following the specifaction at: +* https://wicg.github.io/webusb/#webusb-platform-capability-descriptor +*/ +if (cdev->use_webusb) { +struct usb_webusb_cap_descriptor *webusb_cap; +/* +* little endian PlatformCapablityUUID for WebUSB: +* 3408b638-09a9-47a0-8bfd-a0768815b665 +*/ +#define WEBUSB_UUID UUID_INIT(0x38b60834, 0xa909, 0xa047, \ + 0x8b, 0xfd, 0xa0, 0x76, 0x88, 0x15, 0xb6, 0x65) +uuid_t webusb_uuid =WEBUSB_UUID ; + + webusb_cap = cdev->req->buf +le16_to_cpu (bos->wTotalLength); + bos->bNumDeviceCaps++; + +le16_add_cpu (&bos->wTotalLength,USB_DT_WEBUSB_SIZE ); + webusb_cap->bLength =USB_DT_WEBUSB_SIZE ; + webusb_cap->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; + webusb_cap->bDevCapabilityType =USB_PLAT_DEV_CAP_TYPE ; + webusb_cap->bReserved =0 ; +export_uuid (webusb_cap->UUID, &webusb_uuid); +if (cdev->bcd_webusb_version !=0 ) + webusb_cap->bcdVersion =cpu_to_le16 (cdev->bcd_webusb_version); +else + webusb_cap->bcdVersion =cpu_to_le16 (0x0100 ); + + webusb_cap->bVendorCode = cdev->b_webusb_vendor_code; +if (strnlen (cdev->landing_page,sizeof (cdev->landing_page)) >0 ) + webusb_cap->iLandingPage =1 ; +else + webusb_cap->iLandingPage =0 ; + } +return le16_to_cpu (bos->wTotalLength); }@@ -1744,7 +1782,7 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) cdev->desc.bcdUSB =cpu_to_le16 (0x0210 ); } }else { -if (gadget->lpm_capable) +if (gadget->lpm_capable || cdev->use_webusb) cdev->desc.bcdUSB =cpu_to_le16 (0x0201 );else cdev->desc.bcdUSB =cpu_to_le16 (0x0200 );@@ -1779,7 +1817,7 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl)break ;case USB_DT_BOS :if (gadget_is_superspeed (gadget) || - gadget->lpm_capable) { + gadget->lpm_capable || cdev->use_webusb) { value =bos_desc (cdev); value =min (w_length, (u16 ) value); }@@ -2013,6 +2051,50 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) goto check_value; } +/* +* webusb descriptor handling, following: +* https://wicg.github.io/webusb/#device-requests +*/ +#define WEBUSB_GET_URL 2 +if (cdev->use_webusb && + (ctrl->bRequestType &USB_TYPE_VENDOR ) && + ctrl->wIndex ==WEBUSB_GET_URL && + ctrl->bRequest == cdev->b_webusb_vendor_code) { +/* +* specification of the url descriptor in WebUSB: +* https://wicg.github.io/webusb/#webusb-descriptors +*/ +u8 *buf; +unsigned int schema_http; +unsigned int schema_https; +unsigned int landing_page_length; + + buf = cdev->req->buf; +#define WEBUSB_URL 3 + buf[1 ] =WEBUSB_URL ; + + landing_page_length =strnlen (cdev->landing_page,252 ); + schema_https = (strncmp ("https://" , cdev->landing_page,8 ) ==0 ); + schema_http = (strncmp ("http://" , cdev->landing_page,7 ) ==0 ); +if (schema_https) { + buf[2 ] =0x01 ; +memcpy (buf+3 , cdev->landing_page+8 , landing_page_length-8 ); + buf[0 ] = landing_page_length -8 +3 ; + }else if (schema_http) { + buf[2 ] =0x00 ; +memcpy (buf+3 , cdev->landing_page+7 , landing_page_length-7 ); + buf[0 ] = landing_page_length -7 +3 ; + }else { + buf[2 ] =0xFF ; +memcpy (buf+3 , cdev->landing_page, landing_page_length); + buf[0 ] = landing_page_length +3 ; + } + + value = buf[0 ]; + + goto check_value; + } + VDBG(cdev, "non-core control req%02x.%02x v%04x i%04x l%d\n", ctrl->bRequestType, ctrl->bRequest,drivers/usb/gadget/configfs.c +8
-0@@ -39,6 +39,7 @@ struct gadget_info {struct config_group configs_group;struct config_group strings_group;struct config_group os_desc_group; +struct config_group webusb_group;struct mutex lock;struct usb_gadget_strings *gstrings[MAX_USB_STRING_LANGS +1 ];@@ -50,6 +51,11 @@ struct gadget_info {bool use_os_desc;char b_vendor_code;char qw_sign[OS_STRING_QW_SIGN_LEN ]; +bool use_webusb; +u16 bcd_webusb_version; +u8 b_webusb_vendor_code; +char landing_page[255 ]; +spinlock_t spinlock;bool unbind; };@@ -780,6 +786,125 @@ static void gadget_strings_attr_release(struct config_item *item)USB_CONFIG_STRING_RW_OPS (gadget_strings);USB_CONFIG_STRINGS_LANG (gadget_strings, gadget_info); +static inline struct gadget_info *webusb_item_to_gadget_info ( +struct config_item *item)
drivers/usb/gadget/configfs.c static void gadget_strings_attr_release(struct config_item *item) · line 800
Quoted 10 lines
drivers/usb/gadget/configfs.c +10
-0+{ +return container_of (to_config_group (item), + struct gadget_info, webusb_group); +} + +static ssize_t webusb_use_show (struct config_item *item,char *page) +{ +return sprintf (page,"%d\n" , +webusb_item_to_gadget_info (item)->use_webusb); +}
sysfs_emit()?
Quoted 14 lines
drivers/usb/gadget/configfs.c +14
-0+ +static ssize_t webusb_use_store (struct config_item *item,const char *page, +size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +int ret; +bool use; + +mutex_lock (&gi->lock); + ret =kstrtobool (page, &use); +if (!ret) { + gi->use_webusb = use; + ret = len; + }
drivers/usb/gadget/configfs.c static void gadget_strings_attr_release(struct config_item *item) · line 824
Quoted 10 lines
drivers/usb/gadget/configfs.c +10
-0+mutex_unlock (&gi->lock); + +return ret; +} + +static ssize_t webusb_bcdVersion_show (struct config_item *item,char *page) +{ +return snprintf (page,PAGE_SIZE ,"0x%04x\n" , +webusb_item_to_gadget_info (item)->bcd_webusb_version); +}
sysfs_emit()?
drivers/usb/gadget/configfs.c static void gadget_strings_attr_release(struct config_item *item) · line 830
Quoted 6 lines
drivers/usb/gadget/configfs.c +6
-0+ +static ssize_t webusb_bcdVersion_store (struct config_item *item, +const char *page,size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +u16 bcdVersion;
Why camelCase here?
drivers/usb/gadget/configfs.c static void gadget_strings_attr_release(struct config_item *item) · line 831
Quoted 1 line
drivers/usb/gadget/configfs.c +1
-0+int ret;
no mutex_lock(&gi->lock); here?
Other _store functions have.
Quoted 7 lines
drivers/usb/gadget/configfs.c +7
-0+ + ret =kstrtou16 (page,0 , &bcdVersion); +if (ret) +return ret; + ret =is_valid_bcd (bcdVersion); +if (ret) +return ret;
drivers/usb/gadget/configfs.c static void gadget_strings_attr_release(struct config_item *item) · line 848
Quoted 10 lines
drivers/usb/gadget/configfs.c +10
-0+ + gi->bcd_webusb_version = bcdVersion; +return len; +} + +static ssize_t webusb_bVendorCode_show (struct config_item *item,char *page) +{ +return sprintf (page,"0x%02x\n" , +webusb_item_to_gadget_info (item)->b_webusb_vendor_code); +}
sysfs_emit()?
Quoted 13 lines
drivers/usb/gadget/configfs.c +13
-0+ +static ssize_t webusb_bVendorCode_store (struct config_item *item, +const char *page,size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +int ret; +u8 b_vendor_code; + +mutex_lock (&gi->lock); + ret =kstrtou8 (page,0 , &b_vendor_code); +if (!ret) { + gi->b_webusb_vendor_code = b_vendor_code; + ret = len;
drivers/usb/gadget/configfs.c static void gadget_strings_attr_release(struct config_item *item) · line 871
Quoted 10 lines
drivers/usb/gadget/configfs.c +10
-0+ } +mutex_unlock (&gi->lock); + +return ret; +} + +static ssize_t webusb_landingPage_show (struct config_item *item,char *page) +{ +return snprintf (page,PAGE_SIZE ,"%s\n" ,webusb_item_to_gadget_info (item)->landing_page); +}
sysfs_emit()?
Quoted 128 lines
drivers/usb/gadget/configfs.c +50
-0+ +static ssize_t webusb_landingPage_store (struct config_item *item,const char *page, +size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +int l; + + l =min (len,sizeof (gi->landing_page)); +if (page[l -1 ] =='\n' ) + --l; + +mutex_lock (&gi->lock); +memcpy (gi->landing_page, page, l); +mutex_unlock (&gi->lock); + +return len; +} + +CONFIGFS_ATTR (webusb_, use); +CONFIGFS_ATTR (webusb_, bVendorCode); +CONFIGFS_ATTR (webusb_, bcdVersion); +CONFIGFS_ATTR (webusb_, landingPage); + +static struct configfs_attribute *webusb_attrs[] = { + &webusb_attr_use, + &webusb_attr_bcdVersion, + &webusb_attr_bVendorCode, + &webusb_attr_landingPage, +NULL , +}; + +static struct config_item_type webusb_type = { + .ct_attrs = webusb_attrs, + .ct_owner =THIS_MODULE , +}; +static inline struct gadget_info *os_desc_item_to_gadget_info (struct config_item *item) {@@ -1341,6 +1466,16 @@ static int configfs_composite_bind(struct usb_gadget *gadget, gi->cdev.desc.iSerialNumber = s[USB_GADGET_SERIAL_IDX ].id; } +if (gi->use_webusb) { + cdev->use_webusb = true; + cdev->bcd_webusb_version = gi->bcd_webusb_version; + cdev->b_webusb_vendor_code = gi->b_webusb_vendor_code; +memcpy (cdev->landing_page, gi->landing_page, +strnlen (gi->landing_page, +min (sizeof (cdev->landing_page), +sizeof (gi->landing_page)))); + } +if (gi->use_os_desc) { cdev->use_os_string = true; cdev->b_vendor_code = gi->b_vendor_code;@@ -1605,6 +1740,10 @@ static struct config_group *gadgets_make( &os_desc_type);configfs_add_default_group (&gi->os_desc_group, &gi->group); +config_group_init_type_name (&gi->webusb_group,"webusb" , + &webusb_type); +configfs_add_default_group (&gi->webusb_group, &gi->group); + gi->composite.bind = configfs_do_nothing; gi->composite.unbind = configfs_do_nothing; gi->composite.suspend =NULL ;include/linux/usb/composite.h +6
-0@@ -474,6 +474,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[255 ]; + unsigned int use_webusb:1; +/* private: */ /* internals */ unsigned int suspended:1;include/uapi/linux/usb/ch9.h +33
-0@@ -947,6 +947,39 @@ 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 ]; +} __attribute__((packed)); + +#define USB_DT_USB_PLAT_DEV_CAP_SIZE 20 + +/* +* WebUSB Platform Capability descriptor: A device announces support for the +* WebUSB command set by including the following Platform Descriptor in its +* Binary Object Store +* https://wicg.github.io/webusb/#webusb-platform-capability-descriptor +*/ +struct usb_webusb_cap_descriptor { +__u8 bLength; +__u8 bDescriptorType; +__u8 bDevCapabilityType; +__u8 bReserved; +__u8 UUID[16 ]; +__u16 bcdVersion; +__u8 bVendorCode; +__u8 iLandingPage; +} __attribute__((packed)); +#define USB_DT_WEBUSB_SIZE (USB_DT_USB_PLAT_DEV_CAP_SIZE + 4) +/* * SuperSpeed Plus USB Capability descriptor: Defines the set of * SuperSpeed Plus USB specific device level capabilities
Quoted 42 lines · Christophe JAILLET
Quoted 40 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.
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.
Usage is modeled after
os_descdescriptors:
echo 1 > webusb/use
echo "https://www.kernel.org" > webusb/landingPagelsusb 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
Quoted 7 lines
Quoted 1 line
Signed-off-by Jó Ágila Bitsch <[email protected]>Hi,
a few nits below.
CJ
Thanks for your quick review. I answered inline and will post a new version with the points addressed.
Best,
Jó
Quoted 206 lines
Quoted 206 lines
--- Documentation/ABI/testing/configfs-usb-gadget | 13 ++ drivers/usb/gadget/composite.c | 102 +++++++++++-- drivers/usb/gadget/configfs.c | 139 ++++++++++++++++++ include/linux/usb/composite.h | 6 + include/uapi/linux/usb/ch9.h | 33 +++++ 5 files changed, 283 insertions(+), 10 deletions(-)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.2 +Description: + This group contains "WebUSB" extension handling attributes. + + ============= =============================================== + use flag turning "WebUSB" support on/off + bcdVersion bcd WebUSB specification version number + b_vendor_code one-byte value used for custom per-device + landing_page UTF-8 encoded URL of the device's landing page + ============= ===============================================drivers/usb/gadget/composite.c +92
-10@@ -14,6 +14,7 @@#include <linux/device.h> #include <linux/utsname.h> #include <linux/bitfield.h> +#include <linux/uuid.h> #include <linux/usb/composite.h> #include <linux/usb/otg.h> @@ -713,14 +714,16 @@ static int bos_desc(struct usb_composite_dev *cdev)* A SuperSpeed device shall include the USB2.0 extension descriptor * and shall support LPM when operating in USB2.0 HS mode. */ - usb_ext = cdev->req->buf +le16_to_cpu (bos->wTotalLength); - bos->bNumDeviceCaps++; -le16_add_cpu (&bos->wTotalLength,USB_DT_USB_EXT_CAP_SIZE ); - usb_ext->bLength =USB_DT_USB_EXT_CAP_SIZE ; - usb_ext->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; - usb_ext->bDevCapabilityType =USB_CAP_TYPE_EXT ; - usb_ext->bmAttributes =cpu_to_le32 (USB_LPM_SUPPORT | -USB_BESL_SUPPORT | besl); +if (cdev->gadget->lpm_capable) { + usb_ext = cdev->req->buf +le16_to_cpu (bos->wTotalLength); + bos->bNumDeviceCaps++; +le16_add_cpu (&bos->wTotalLength,USB_DT_USB_EXT_CAP_SIZE ); + usb_ext->bLength =USB_DT_USB_EXT_CAP_SIZE ; + usb_ext->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; + usb_ext->bDevCapabilityType =USB_CAP_TYPE_EXT ; + usb_ext->bmAttributes =cpu_to_le32 (USB_LPM_SUPPORT | +USB_BESL_SUPPORT | besl); + }/* * The Superspeed USB Capability descriptor shall be implemented by all @@ -821,6 +824,41 @@ static int bos_desc(struct usb_composite_dev *cdev) } } +/* +* Following the specifaction at: +* https://wicg.github.io/webusb/#webusb-platform-capability-descriptor +*/ +if (cdev->use_webusb) { +struct usb_webusb_cap_descriptor *webusb_cap; +/* +* little endian PlatformCapablityUUID for WebUSB: +* 3408b638-09a9-47a0-8bfd-a0768815b665 +*/ +#define WEBUSB_UUID UUID_INIT(0x38b60834, 0xa909, 0xa047, \ + 0x8b, 0xfd, 0xa0, 0x76, 0x88, 0x15, 0xb6, 0x65) +uuid_t webusb_uuid =WEBUSB_UUID ; + + webusb_cap = cdev->req->buf +le16_to_cpu (bos->wTotalLength); + bos->bNumDeviceCaps++; + +le16_add_cpu (&bos->wTotalLength,USB_DT_WEBUSB_SIZE ); + webusb_cap->bLength =USB_DT_WEBUSB_SIZE ; + webusb_cap->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; + webusb_cap->bDevCapabilityType =USB_PLAT_DEV_CAP_TYPE ; + webusb_cap->bReserved =0 ; +export_uuid (webusb_cap->UUID, &webusb_uuid); +if (cdev->bcd_webusb_version !=0 ) + webusb_cap->bcdVersion =cpu_to_le16 (cdev->bcd_webusb_version); +else + webusb_cap->bcdVersion =cpu_to_le16 (0x0100 ); + + webusb_cap->bVendorCode = cdev->b_webusb_vendor_code; +if (strnlen (cdev->landing_page,sizeof (cdev->landing_page)) >0 ) + webusb_cap->iLandingPage =1 ; +else + webusb_cap->iLandingPage =0 ; + } +return le16_to_cpu (bos->wTotalLength); }@@ -1744,7 +1782,7 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) cdev->desc.bcdUSB =cpu_to_le16 (0x0210 ); } }else { -if (gadget->lpm_capable) +if (gadget->lpm_capable || cdev->use_webusb) cdev->desc.bcdUSB =cpu_to_le16 (0x0201 );else cdev->desc.bcdUSB =cpu_to_le16 (0x0200 );@@ -1779,7 +1817,7 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl)break ;case USB_DT_BOS :if (gadget_is_superspeed (gadget) || - gadget->lpm_capable) { + gadget->lpm_capable || cdev->use_webusb) { value =bos_desc (cdev); value =min (w_length, (u16 ) value); }@@ -2013,6 +2051,50 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) goto check_value; } +/* +* webusb descriptor handling, following: +* https://wicg.github.io/webusb/#device-requests +*/ +#define WEBUSB_GET_URL 2 +if (cdev->use_webusb && + (ctrl->bRequestType &USB_TYPE_VENDOR ) && + ctrl->wIndex ==WEBUSB_GET_URL && + ctrl->bRequest == cdev->b_webusb_vendor_code) { +/* +* specification of the url descriptor in WebUSB: +* https://wicg.github.io/webusb/#webusb-descriptors +*/ +u8 *buf; +unsigned int schema_http; +unsigned int schema_https; +unsigned int landing_page_length; + + buf = cdev->req->buf; +#define WEBUSB_URL 3 + buf[1 ] =WEBUSB_URL ; + + landing_page_length =strnlen (cdev->landing_page,252 ); + schema_https = (strncmp ("https://" , cdev->landing_page,8 ) ==0 ); + schema_http = (strncmp ("http://" , cdev->landing_page,7 ) ==0 ); +if (schema_https) { + buf[2 ] =0x01 ; +memcpy (buf+3 , cdev->landing_page+8 , landing_page_length-8 ); + buf[0 ] = landing_page_length -8 +3 ; + }else if (schema_http) { + buf[2 ] =0x00 ; +memcpy (buf+3 , cdev->landing_page+7 , landing_page_length-7 ); + buf[0 ] = landing_page_length -7 +3 ; + }else { + buf[2 ] =0xFF ; +memcpy (buf+3 , cdev->landing_page, landing_page_length); + buf[0 ] = landing_page_length +3 ; + } + + value = buf[0 ]; + + goto check_value; + } + VDBG(cdev, "non-core control req%02x.%02x v%04x i%04x l%d\n", ctrl->bRequestType, ctrl->bRequest,drivers/usb/gadget/configfs.c +6
-0@@ -39,6 +39,7 @@ struct gadget_info {struct config_group configs_group;struct config_group strings_group;struct config_group os_desc_group; +struct config_group webusb_group;struct mutex lock;struct usb_gadget_strings *gstrings[MAX_USB_STRING_LANGS +1 ];@@ -50,6 +51,11 @@ struct gadget_info {bool use_os_desc;char b_vendor_code;char qw_sign[OS_STRING_QW_SIGN_LEN ]; +bool use_webusb; +u16 bcd_webusb_version; +u8 b_webusb_vendor_code; +char landing_page[255 ]; +spinlock_t spinlock;bool unbind; };@@ -780,6 +786,125 @@ static void gadget_strings_attr_release(struct config_item *item)USB_CONFIG_STRING_RW_OPS (gadget_strings);USB_CONFIG_STRINGS_LANG (gadget_strings, gadget_info);
Quoted 15 lines
drivers/usb/gadget/configfs.c static void gadget_strings_attr_release(struct config_item *item) · line 800
Quoted 12 lines
drivers/usb/gadget/configfs.c +12
-0+static inline struct gadget_info *webusb_item_to_gadget_info ( +struct config_item *item) +{ +return container_of (to_config_group (item), + struct gadget_info, webusb_group); +} + +static ssize_t webusb_use_show (struct config_item *item,char *page) +{ +return sprintf (page,"%d\n" , +webusb_item_to_gadget_info (item)->use_webusb); +}
sysfs_emit()?
I will replace all sprintf calls with sysfs_emit calls in my next revision. Thanks for the pointer.
Quoted 27 lines
Quoted 14 lines
drivers/usb/gadget/configfs.c +14
-0+ +static ssize_t webusb_use_store (struct config_item *item,const char *page, +size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +int ret; +bool use; + +mutex_lock (&gi->lock); + ret =kstrtobool (page, &use); +if (!ret) { + gi->use_webusb = use; + ret = len; + }drivers/usb/gadget/configfs.c static void gadget_strings_attr_release(struct config_item *item) · line 824
Quoted 10 lines
drivers/usb/gadget/configfs.c +10
-0+mutex_unlock (&gi->lock); + +return ret; +} + +static ssize_t webusb_bcdVersion_show (struct config_item *item,char *page) +{ +return snprintf (page,PAGE_SIZE ,"0x%04x\n" , +webusb_item_to_gadget_info (item)->bcd_webusb_version); +}
sysfs_emit()?
Quoted 8 lines
drivers/usb/gadget/configfs.c static void gadget_strings_attr_release(struct config_item *item) · line 830
Quoted 6 lines
drivers/usb/gadget/configfs.c +6
-0+ +static ssize_t webusb_bcdVersion_store (struct config_item *item, +const char *page,size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +u16 bcdVersion;Why camelCase here?
Actually, I was unsure about that. I modelled my code on the os_desc implementation, which uses kebab_casing. However, all the other usb attributes (e.g. bcdUSB, bDeviceClass) use camelCase. So I thought it would be more consistent for users to have camelCase. That's why I stuck with camelCase for the attribute names (and the function names, so that I can use the default macros).
Quoted 5 lines
drivers/usb/gadget/configfs.c static void gadget_strings_attr_release(struct config_item *item) · line 831
Quoted 2 lines
drivers/usb/gadget/configfs.c +1
-0+int ret;no
mutex_lock(&gi->lock); here?
Other_storefunctions have.
Thanks for pointing that one out. I missed that one.
Quoted 175 lines
Quoted 7 lines
drivers/usb/gadget/configfs.c +7
-0+ + ret =kstrtou16 (page,0 , &bcdVersion); +if (ret) +return ret; + ret =is_valid_bcd (bcdVersion); +if (ret) +return ret;drivers/usb/gadget/configfs.c static void gadget_strings_attr_release(struct config_item *item) · line 848
Quoted 10 lines
drivers/usb/gadget/configfs.c +10
-0+ + gi->bcd_webusb_version = bcdVersion; +return len; +} + +static ssize_t webusb_bVendorCode_show (struct config_item *item,char *page) +{ +return sprintf (page,"0x%02x\n" , +webusb_item_to_gadget_info (item)->b_webusb_vendor_code); +}
sysfs_emit()?Quoted 13 lines
drivers/usb/gadget/configfs.c +13
-0+ +static ssize_t webusb_bVendorCode_store (struct config_item *item, +const char *page,size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +int ret; +u8 b_vendor_code; + +mutex_lock (&gi->lock); + ret =kstrtou8 (page,0 , &b_vendor_code); +if (!ret) { + gi->b_webusb_vendor_code = b_vendor_code; + ret = len;drivers/usb/gadget/configfs.c static void gadget_strings_attr_release(struct config_item *item) · line 871
Quoted 10 lines
drivers/usb/gadget/configfs.c +10
-0+ } +mutex_unlock (&gi->lock); + +return ret; +} + +static ssize_t webusb_landingPage_show (struct config_item *item,char *page) +{ +return snprintf (page,PAGE_SIZE ,"%s\n" ,webusb_item_to_gadget_info (item)->landing_page); +}
sysfs_emit()?Quoted 128 lines
drivers/usb/gadget/configfs.c +50
-0+ +static ssize_t webusb_landingPage_store (struct config_item *item,const char *page, +size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +int l; + + l =min (len,sizeof (gi->landing_page)); +if (page[l -1 ] =='\n' ) + --l; + +mutex_lock (&gi->lock); +memcpy (gi->landing_page, page, l); +mutex_unlock (&gi->lock); + +return len; +} + +CONFIGFS_ATTR (webusb_, use); +CONFIGFS_ATTR (webusb_, bVendorCode); +CONFIGFS_ATTR (webusb_, bcdVersion); +CONFIGFS_ATTR (webusb_, landingPage); + +static struct configfs_attribute *webusb_attrs[] = { + &webusb_attr_use, + &webusb_attr_bcdVersion, + &webusb_attr_bVendorCode, + &webusb_attr_landingPage, +NULL , +}; + +static struct config_item_type webusb_type = { + .ct_attrs = webusb_attrs, + .ct_owner =THIS_MODULE , +}; +static inline struct gadget_info *os_desc_item_to_gadget_info (struct config_item *item) {@@ -1341,6 +1466,16 @@ static int configfs_composite_bind(struct usb_gadget *gadget, gi->cdev.desc.iSerialNumber = s[USB_GADGET_SERIAL_IDX ].id; } +if (gi->use_webusb) { + cdev->use_webusb = true; + cdev->bcd_webusb_version = gi->bcd_webusb_version; + cdev->b_webusb_vendor_code = gi->b_webusb_vendor_code; +memcpy (cdev->landing_page, gi->landing_page, +strnlen (gi->landing_page, +min (sizeof (cdev->landing_page), +sizeof (gi->landing_page)))); + } +if (gi->use_os_desc) { cdev->use_os_string = true; cdev->b_vendor_code = gi->b_vendor_code;@@ -1605,6 +1740,10 @@ static struct config_group *gadgets_make( &os_desc_type);configfs_add_default_group (&gi->os_desc_group, &gi->group); +config_group_init_type_name (&gi->webusb_group,"webusb" , + &webusb_type); +configfs_add_default_group (&gi->webusb_group, &gi->group); + gi->composite.bind = configfs_do_nothing; gi->composite.unbind = configfs_do_nothing; gi->composite.suspend =NULL ;include/linux/usb/composite.h +6
-0@@ -474,6 +474,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[255 ]; + unsigned int use_webusb:1; +/* private: */ /* internals */ unsigned int suspended:1;include/uapi/linux/usb/ch9.h +33
-0@@ -947,6 +947,39 @@ 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 ]; +} __attribute__((packed)); + +#define USB_DT_USB_PLAT_DEV_CAP_SIZE 20 + +/* +* WebUSB Platform Capability descriptor: A device announces support for the +* WebUSB command set by including the following Platform Descriptor in its +* Binary Object Store +* https://wicg.github.io/webusb/#webusb-platform-capability-descriptor +*/ +struct usb_webusb_cap_descriptor { +__u8 bLength; +__u8 bDescriptorType; +__u8 bDevCapabilityType; +__u8 bReserved; +__u8 UUID[16 ]; +__u16 bcdVersion; +__u8 bVendorCode; +__u8 iLandingPage; +} __attribute__((packed)); +#define USB_DT_WEBUSB_SIZE (USB_DT_USB_PLAT_DEV_CAP_SIZE + 4) +/* * SuperSpeed Plus USB Capability descriptor: Defines the set of * SuperSpeed Plus USB specific device level capabilities
PATCH 1/1 usb: gadget: add WebUSB support
In reply to Christophe JAILLETThere 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.
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
--- Documentation/ABI/testing/configfs-usb-gadget | 13 ++ drivers/usb/gadget/composite.c | 102 ++++++++++-- drivers/usb/gadget/configfs.c | 145 ++++++++++++++++++ include/linux/usb/composite.h | 6 + include/uapi/linux/usb/ch9.h | 33 ++++ 5 files changed, 289 insertions(+), 10 deletions(-)
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.2 +Description: + This group contains "WebUSB" extension handling attributes. + + ============= =============================================== + use flag turning "WebUSB" support on/off + bcdVersion bcd WebUSB specification version number + b_vendor_code one-byte value used for custom per-device + landing_page UTF-8 encoded URL of the device's landing page + ============= ===============================================
drivers/usb/gadget/composite.c +92 -10
138 lines not on this page · raw message
drivers/usb/gadget/configfs.c +145 -0
175 lines not on this page · raw message
include/linux/usb/composite.h +6 -0
@@ -474,6 +474,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[255 ]; + unsigned int use_webusb:1; +/* private: */ /* internals */ unsigned int suspended:1;
include/uapi/linux/usb/ch9.h +33 -0
@@ -947,6 +947,39 @@ 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 ]; +} __attribute__((packed)); + +#define USB_DT_USB_PLAT_DEV_CAP_SIZE 20 + +/* +* WebUSB Platform Capability descriptor: A device announces support for the +* WebUSB command set by including the following Platform Descriptor in its +* Binary Object Store +* https://wicg.github.io/webusb/#webusb-platform-capability-descriptor +*/ +struct usb_webusb_cap_descriptor { +__u8 bLength; +__u8 bDescriptorType; +__u8 bDevCapabilityType; +__u8 bReserved; +__u8 UUID[16 ]; +__u16 bcdVersion; +__u8 bVendorCode; +__u8 iLandingPage; +} __attribute__((packed)); +#define USB_DT_WEBUSB_SIZE (USB_DT_USB_PLAT_DEV_CAP_SIZE + 4) +/* * SuperSpeed Plus USB Capability descriptor: Defines the set of * SuperSpeed Plus USB specific device level capabilities
Signature · 1 line
2.37.2
Quoted 14 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.
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.
Quoted 5 lines
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
Where is this 2.01 value specified? I don't remember seeing it in the usual USBIF documents.
Quoted 66 lines
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.
Usage is modeled after
os_descdescriptors:
echo 1 > webusb/use
echo "https://www.kernel.org" > webusb/landingPagelsusb 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.orgSigned-off-by Jó Ágila Bitsch <[email protected]>--- Documentation/ABI/testing/configfs-usb-gadget | 13 ++ drivers/usb/gadget/composite.c | 102 ++++++++++-- drivers/usb/gadget/configfs.c | 145 ++++++++++++++++++ include/linux/usb/composite.h | 6 + include/uapi/linux/usb/ch9.h | 33 ++++ 5 files changed, 289 insertions(+), 10 deletions(-)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.2 +Description: + This group contains "WebUSB" extension handling attributes. + + ============= =============================================== + use flag turning "WebUSB" support on/off + bcdVersion bcd WebUSB specification version number + b_vendor_code one-byte value used for custom per-device + landing_page UTF-8 encoded URL of the device's landing page + ============= ===============================================drivers/usb/gadget/composite.c +1
-0@@ -14,6 +14,7 @@#include <linux/device.h> #include <linux/utsname.h> #include <linux/bitfield.h> +#include <linux/uuid.h> #include <linux/usb/composite.h> #include <linux/usb/otg.h> @@ -713,14 +714,16 @@ static int bos_desc(struct usb_composite_dev *cdev)* A SuperSpeed device shall include the USB2.0 extension descriptor * and shall support LPM when operating in USB2.0 HS mode.
drivers/usb/gadget/composite.c static int bos_desc(struct usb_composite_dev *cdev) · line 717
Quoted 10 lines
drivers/usb/gadget/composite.c +1
-8*/ - usb_ext = cdev->req->buf +le16_to_cpu (bos->wTotalLength); - bos->bNumDeviceCaps++; -le16_add_cpu (&bos->wTotalLength,USB_DT_USB_EXT_CAP_SIZE ); - usb_ext->bLength =USB_DT_USB_EXT_CAP_SIZE ; - usb_ext->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; - usb_ext->bDevCapabilityType =USB_CAP_TYPE_EXT ; - usb_ext->bmAttributes =cpu_to_le32 (USB_LPM_SUPPORT | -USB_BESL_SUPPORT | besl); +if (cdev->gadget->lpm_capable) {
This change doesn't seem to be related to the purpose of this patch.
Quoted 19 lines
drivers/usb/gadget/composite.c +12
-0+ usb_ext = cdev->req->buf +le16_to_cpu (bos->wTotalLength); + bos->bNumDeviceCaps++; +le16_add_cpu (&bos->wTotalLength,USB_DT_USB_EXT_CAP_SIZE ); + usb_ext->bLength =USB_DT_USB_EXT_CAP_SIZE ; + usb_ext->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; + usb_ext->bDevCapabilityType =USB_CAP_TYPE_EXT ; + usb_ext->bmAttributes =cpu_to_le32 (USB_LPM_SUPPORT | +USB_BESL_SUPPORT | besl); + }/* * The Superspeed USB Capability descriptor shall be implemented by all @@ -821,6 +824,41 @@ static int bos_desc(struct usb_composite_dev *cdev) } } +/* +* Following the specifaction at: +* https://wicg.github.io/webusb/#webusb-platform-capability-descriptor
drivers/usb/gadget/composite.c static int bos_desc(struct usb_composite_dev *cdev) · line 839
Quoted 10 lines
drivers/usb/gadget/composite.c +10
-0+*/ +if (cdev->use_webusb) { +struct usb_webusb_cap_descriptor *webusb_cap; +/* +* little endian PlatformCapablityUUID for WebUSB: +* 3408b638-09a9-47a0-8bfd-a0768815b665 +*/ +#define WEBUSB_UUID UUID_INIT(0x38b60834, 0xa909, 0xa047, \ + 0x8b, 0xfd, 0xa0, 0x76, 0x88, 0x15, 0xb6, 0x65) +uuid_t webusb_uuid =WEBUSB_UUID ;
This #define seems to be pointless. It is used nowhere but in the immediately following line. You might as well eliminate it.
Or you might define this UUID at the same place in the header file where you define struct usb_webusb_cap_descriptor.
Quoted 44 lines
drivers/usb/gadget/composite.c +24
-2+ + webusb_cap = cdev->req->buf +le16_to_cpu (bos->wTotalLength); + bos->bNumDeviceCaps++; + +le16_add_cpu (&bos->wTotalLength,USB_DT_WEBUSB_SIZE ); + webusb_cap->bLength =USB_DT_WEBUSB_SIZE ; + webusb_cap->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; + webusb_cap->bDevCapabilityType =USB_PLAT_DEV_CAP_TYPE ; + webusb_cap->bReserved =0 ; +export_uuid (webusb_cap->UUID, &webusb_uuid); +if (cdev->bcd_webusb_version !=0 ) + webusb_cap->bcdVersion =cpu_to_le16 (cdev->bcd_webusb_version); +else + webusb_cap->bcdVersion =cpu_to_le16 (0x0100 ); + + webusb_cap->bVendorCode = cdev->b_webusb_vendor_code; +if (strnlen (cdev->landing_page,sizeof (cdev->landing_page)) >0 ) + webusb_cap->iLandingPage =1 ; +else + webusb_cap->iLandingPage =0 ; + } +return le16_to_cpu (bos->wTotalLength); }@@ -1744,7 +1782,7 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) cdev->desc.bcdUSB =cpu_to_le16 (0x0210 ); } }else { -if (gadget->lpm_capable) +if (gadget->lpm_capable || cdev->use_webusb) cdev->desc.bcdUSB =cpu_to_le16 (0x0201 );else cdev->desc.bcdUSB =cpu_to_le16 (0x0200 );@@ -1779,7 +1817,7 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl)break ;case USB_DT_BOS :if (gadget_is_superspeed (gadget) || - gadget->lpm_capable) { + gadget->lpm_capable || cdev->use_webusb) { value =bos_desc (cdev); value =min (w_length, (u16 ) value); }
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2058
Quoted 8 lines
drivers/usb/gadget/composite.c +5
-0@@ -2013,6 +2051,50 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) goto check_value; } +/* +* webusb descriptor handling, following: +* https://wicg.github.io/webusb/#device-requests +*/ +#define WEBUSB_GET_URL 2
A similar comment applies to this #define. In this case it might make sense to put all the WebUSB-related #defines in an appropriate header file.
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2062
Quoted 4 lines
drivers/usb/gadget/composite.c +4
-0+if (cdev->use_webusb && + (ctrl->bRequestType &USB_TYPE_VENDOR ) && + ctrl->wIndex ==WEBUSB_GET_URL && + ctrl->bRequest == cdev->b_webusb_vendor_code) {
Bad indentation. Visually this makes it look like the last two tests are part of the conditional block, because they share its indentation level.
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2068
Quoted 6 lines
drivers/usb/gadget/composite.c +6
-0+/* +* specification of the url descriptor in WebUSB: +* https://wicg.github.io/webusb/#webusb-descriptors +*/ +u8 *buf; +unsigned int schema_http;
*buf and schema_http should be indented by the same amount.
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2078
Quoted 10 lines
drivers/usb/gadget/composite.c +10
-0+unsigned int schema_https; +unsigned int landing_page_length; + + buf = cdev->req->buf; +#define WEBUSB_URL 3 + buf[1 ] =WEBUSB_URL ; + + landing_page_length =strnlen (cdev->landing_page,252 ); + schema_https = (strncmp ("https://" , cdev->landing_page,8 ) ==0 ); + schema_http = (strncmp ("http://" , cdev->landing_page,7 ) ==0 );
Do you really need these temporary variables? Why not put the tests directly into the "if" conditions?
Also, should the comparisons be case-insensitive?
Quoted 35 lines
drivers/usb/gadget/composite.c +19
-0+if (schema_https) { + buf[2 ] =0x01 ; +memcpy (buf+3 , cdev->landing_page+8 , landing_page_length-8 ); + buf[0 ] = landing_page_length -8 +3 ; + }else if (schema_http) { + buf[2 ] =0x00 ; +memcpy (buf+3 , cdev->landing_page+7 , landing_page_length-7 ); + buf[0 ] = landing_page_length -7 +3 ; + }else { + buf[2 ] =0xFF ; +memcpy (buf+3 , cdev->landing_page, landing_page_length); + buf[0 ] = landing_page_length +3 ; + } + + value = buf[0 ]; + + goto check_value; + } + VDBG(cdev, "non-core control req%02x.%02x v%04x i%04x l%d\n", ctrl->bRequestType, ctrl->bRequest,drivers/usb/gadget/configfs.c +1
-0@@ -39,6 +39,7 @@ struct gadget_info {struct config_group configs_group;struct config_group strings_group;struct config_group os_desc_group; +struct config_group webusb_group;struct mutex lock;struct usb_gadget_strings *gstrings[MAX_USB_STRING_LANGS +1 ];
drivers/usb/gadget/configfs.c struct gadget_info { · line 56
Quoted 6 lines
drivers/usb/gadget/configfs.c +3
-0@@ -50,6 +51,11 @@ struct gadget_info {bool use_os_desc;char b_vendor_code;char qw_sign[OS_STRING_QW_SIGN_LEN ]; +bool use_webusb; +u16 bcd_webusb_version; +u8 b_webusb_vendor_code;
Again, improper indentation.
Quoted 5 lines
drivers/usb/gadget/configfs.c +2
-0+char landing_page[255 ]; +spinlock_t spinlock;bool unbind; };
...
include/linux/usb/composite.h struct usb_composite_dev { · line 480
Quoted 12 lines
include/linux/usb/composite.h +4
-0@@ -474,6 +474,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[255 ];
Improper indentation.
include/linux/usb/composite.h struct usb_composite_dev { · line 485
Quoted 5 lines
include/linux/usb/composite.h +2
-0+ unsigned int use_webusb:1; +/* private: */ /* internals */ unsigned int suspended:1;
Alan Stern
Quoted 16 lines · Alan Stern
Quoted 14 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.
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.
Quoted 8 lines
Quoted 5 lines
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
Where is this 2.01 value specified? I don't remember seeing it in the usual USBIF documents.
This is actually from the backport of BOS descriptors to USB 2
Citing Randy Aull from
https://community.osr.com/discussion/comment/249742/#Comment_249742
Quoted 18 lines
There is no specification called USB 2.1, however there is such a thing as a USB 2.1 device.
The USB 2.0 ECN for LPM introduced a new descriptor request to the enumeration process for USB 2 devices (the BOS descriptor set). The problem is that software can't request a new descriptor type to old devices that don't understand it without introducing compatibility issues with some devices (more than you would probably expect). So, software needed a way to identify whether a device could support the host requesting a BOS descriptor set. The solution in this ECN was to require devices supporting the ECN to set their bcdUSB to0x0201(2.01).Now, when we created the USB 3.0 spec, we again wanted to leverage the BOS descriptor, not only because we wanted to mandate USB 2 LPM in 3.0 devices when operating at high-speed, but also so the device can indicate to a host that it can operate at SuperSpeed (to support everyone's favorite "your device can perform faster" popup). Knowing that when operating at high-speed these devices needed to report the BOS descriptor set, we knew that it couldn't set the bcdUSB to
0x0200. We mistakenly wrote it down as0x0210instead of0x0201in the 3.0 spec (perhaps we just said "two point one" which might have been ambiguous) when we were trying to just be consistent with the requirement from the LPM ECN. So, rather than changing it back to0x0201in the USB 3.0 spec, we just ran with it.
Quoted 4 lines
So, there are USB 2.0 devices, USB 2.01 devices and USB 2.1 devices, even though the latest revision of the USB 2 spec is USB 2.0. I have recommended that the USB-IF actually create a USB 2.1 specification that captures all of the various errata, ECNs, etc from over the years, but it hasn't happened yet.
Btw, configfs already includes these version codes to support Link Power Management (LPM) and
the associated BOS descriptor, so I didn't add that part, I only added webusb as a condition as to
when to send BOS descriptors.
Quoted 71 lines
Quoted 71 lines
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.
Usage is modeled after
os_descdescriptors:
echo 1 > webusb/use
echo "https://www.kernel.org" > webusb/landingPagelsusb 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.orgSigned-off-by Jó Ágila Bitsch <[email protected]>--- Documentation/ABI/testing/configfs-usb-gadget | 13 ++ drivers/usb/gadget/composite.c | 102 ++++++++++-- drivers/usb/gadget/configfs.c | 145 ++++++++++++++++++ include/linux/usb/composite.h | 6 + include/uapi/linux/usb/ch9.h | 33 ++++ 5 files changed, 289 insertions(+), 10 deletions(-)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.2 +Description: + This group contains "WebUSB" extension handling attributes. + + ============= =============================================== + use flag turning "WebUSB" support on/off + bcdVersion bcd WebUSB specification version number + b_vendor_code one-byte value used for custom per-device + landing_page UTF-8 encoded URL of the device's landing page + ============= ===============================================drivers/usb/gadget/composite.c +1
-3@@ -14,6 +14,7 @@#include <linux/device.h> #include <linux/utsname.h> #include <linux/bitfield.h> +#include <linux/uuid.h> #include <linux/usb/composite.h> #include <linux/usb/otg.h> @@ -713,14 +714,16 @@ static int bos_desc(struct usb_composite_dev *cdev)* A SuperSpeed device shall include the USB2.0 extension descriptor * and shall support LPM when operating in USB2.0 HS mode. */ - usb_ext = cdev->req->buf +le16_to_cpu (bos->wTotalLength); - bos->bNumDeviceCaps++; -le16_add_cpu (&bos->wTotalLength,USB_DT_USB_EXT_CAP_SIZE );
Quoted 8 lines
drivers/usb/gadget/composite.c static int bos_desc(struct usb_composite_dev *cdev) · line 717
Quoted 6 lines
drivers/usb/gadget/composite.c +1
-5- usb_ext->bLength =USB_DT_USB_EXT_CAP_SIZE ; - usb_ext->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; - usb_ext->bDevCapabilityType =USB_CAP_TYPE_EXT ; - usb_ext->bmAttributes =cpu_to_le32 (USB_LPM_SUPPORT | -USB_BESL_SUPPORT | besl); +if (cdev->gadget->lpm_capable) {This change doesn't seem to be related to the purpose of this patch.
Actually, it is.
Previously, BOS descriptors would only ever be sent if the device was lpm_capable.
For this reason, this descriptor was previously sent unconditionally.
With my patch in place, it could be that a device is not lpm_capable, but still wants to send BOS descriptors to announce its WebUSB capability, therefore I added
this condition.
Quoted 34 lines
Quoted 20 lines
drivers/usb/gadget/composite.c +12
-0+ usb_ext = cdev->req->buf +le16_to_cpu (bos->wTotalLength); + bos->bNumDeviceCaps++; +le16_add_cpu (&bos->wTotalLength,USB_DT_USB_EXT_CAP_SIZE ); + usb_ext->bLength =USB_DT_USB_EXT_CAP_SIZE ; + usb_ext->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; + usb_ext->bDevCapabilityType =USB_CAP_TYPE_EXT ; + usb_ext->bmAttributes =cpu_to_le32 (USB_LPM_SUPPORT | +USB_BESL_SUPPORT | besl); + }/* * The Superspeed USB Capability descriptor shall be implemented by all @@ -821,6 +824,41 @@ static int bos_desc(struct usb_composite_dev *cdev) } } +/* +* Following the specifaction at: +* https://wicg.github.io/webusb/#webusb-platform-capability-descriptor drivers/usb/gadget/composite.c static int bos_desc(struct usb_composite_dev *cdev) · line 839
Quoted 10 lines
drivers/usb/gadget/composite.c +10
-0+*/ +if (cdev->use_webusb) { +struct usb_webusb_cap_descriptor *webusb_cap; +/* +* little endian PlatformCapablityUUID for WebUSB: +* 3408b638-09a9-47a0-8bfd-a0768815b665 +*/ +#define WEBUSB_UUID UUID_INIT(0x38b60834, 0xa909, 0xa047, \ + 0x8b, 0xfd, 0xa0, 0x76, 0x88, 0x15, 0xb6, 0x65) +uuid_t webusb_uuid =WEBUSB_UUID ;This #define seems to be pointless. It is used nowhere but in the immediately following line. You might as well eliminate it.
Quoted 2 lines
Or you might define this UUID at the same place in the header file where you define struct
usb_webusb_cap_descriptor.
I will update the patch accordingly.
Quoted 26 lines
Quoted 26 lines
drivers/usb/gadget/composite.c +22
-0+ + webusb_cap = cdev->req->buf +le16_to_cpu (bos->wTotalLength); + bos->bNumDeviceCaps++; + +le16_add_cpu (&bos->wTotalLength,USB_DT_WEBUSB_SIZE ); + webusb_cap->bLength =USB_DT_WEBUSB_SIZE ; + webusb_cap->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; + webusb_cap->bDevCapabilityType =USB_PLAT_DEV_CAP_TYPE ; + webusb_cap->bReserved =0 ; +export_uuid (webusb_cap->UUID, &webusb_uuid); +if (cdev->bcd_webusb_version !=0 ) + webusb_cap->bcdVersion =cpu_to_le16 (cdev->bcd_webusb_version); +else + webusb_cap->bcdVersion =cpu_to_le16 (0x0100 ); + + webusb_cap->bVendorCode = cdev->b_webusb_vendor_code; +if (strnlen (cdev->landing_page,sizeof (cdev->landing_page)) >0 ) + webusb_cap->iLandingPage =1 ; +else + webusb_cap->iLandingPage =0 ; + } +return le16_to_cpu (bos->wTotalLength); }
Quoted 6 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 1785
Quoted 6 lines
drivers/usb/gadget/composite.c +1
-1@@ -1744,7 +1782,7 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) cdev->desc.bcdUSB =cpu_to_le16 (0x0210 ); } }else { -if (gadget->lpm_capable) +if (gadget->lpm_capable || cdev->use_webusb)
Btw: this is the location where the USB version 2.01 and 2.1 were already in the code to support LPM.
Quoted 9 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 1820
Quoted 9 lines
drivers/usb/gadget/composite.c +1
-1cdev->desc.bcdUSB =cpu_to_le16 (0x0201 ); else cdev->desc.bcdUSB = cpu_to_le16(0x0200);@@ -1779,7 +1817,7 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl)break ;case USB_DT_BOS :if (gadget_is_superspeed (gadget) || - gadget->lpm_capable) { + gadget->lpm_capable || cdev->use_webusb) {
And this is the location that the BOS descriptors are sent, if the device supports webusb. Previously the
code would only send these descriptors when the device was lpm_capable or superspeed. Thus requiring
the additional condition above in bos_desc.
Quoted 7 lines
Quoted 7 lines
drivers/usb/gadget/composite.c +0
-0value =bos_desc (cdev); value =min (w_length, (u16 ) value); }@@ -2013,6 +2051,50 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) goto check_value; }
Quoted 9 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2058
Quoted 5 lines
drivers/usb/gadget/composite.c +5
-0+/* +* webusb descriptor handling, following: +* https://wicg.github.io/webusb/#device-requests +*/ +#define WEBUSB_GET_URL 2A similar comment applies to this #define. In this case it might make sense to put all the WebUSB-related #defines in an appropriate header file.
Agreed. I'll add a comment instead.
Quoted 9 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2062
Quoted 5 lines
drivers/usb/gadget/composite.c +4
-0+if (cdev->use_webusb && + (ctrl->bRequestType &USB_TYPE_VENDOR ) && + ctrl->wIndex ==WEBUSB_GET_URL && + ctrl->bRequest == cdev->b_webusb_vendor_code) {Bad indentation. Visually this makes it look like the last two tests are part of the conditional block, because they share its indentation level.
I'll fix this.
Quoted 9 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2068
Quoted 7 lines
drivers/usb/gadget/composite.c +6
-0+/* +* specification of the url descriptor in WebUSB: +* https://wicg.github.io/webusb/#webusb-descriptors +*/ +u8 *buf; +unsigned int schema_http;*buf and
schema_httpshould be indented by the same amount.
I'll fix this.
I had accidentally set my tab indentation to 4 spaces.
Quoted 14 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2078
Quoted 11 lines
drivers/usb/gadget/composite.c +10
-0+unsigned int schema_https; +unsigned int landing_page_length; + + buf = cdev->req->buf; +#define WEBUSB_URL 3 + buf[1 ] =WEBUSB_URL ; + + landing_page_length =strnlen (cdev->landing_page,252 ); + schema_https = (strncmp ("https://" , cdev->landing_page,8 ) ==0 ); + schema_http = (strncmp ("http://" , cdev->landing_page,7 ) ==0 );Do you really need these temporary variables? Why not put the tests directly into the "if" conditions?
Good point.
Quoted 1 line
Also, should the comparisons be case-insensitive?
As URI schemes are case-insensitive as per
https://www.rfc-editor.org/rfc/rfc3986#section-3.1
you are right, so I will change this.
Quoted 33 lines
Quoted 33 lines
drivers/usb/gadget/composite.c +19
-0+if (schema_https) { + buf[2 ] =0x01 ; +memcpy (buf+3 , cdev->landing_page+8 , landing_page_length-8 ); + buf[0 ] = landing_page_length -8 +3 ; + }else if (schema_http) { + buf[2 ] =0x00 ; +memcpy (buf+3 , cdev->landing_page+7 , landing_page_length-7 ); + buf[0 ] = landing_page_length -7 +3 ; + }else { + buf[2 ] =0xFF ; +memcpy (buf+3 , cdev->landing_page, landing_page_length); + buf[0 ] = landing_page_length +3 ; + } + + value = buf[0 ]; + + goto check_value; + } + VDBG(cdev, "non-core control req%02x.%02x v%04x i%04x l%d\n", ctrl->bRequestType, ctrl->bRequest,drivers/usb/gadget/configfs.c +1
-0@@ -39,6 +39,7 @@ struct gadget_info {struct config_group configs_group;struct config_group strings_group;struct config_group os_desc_group; +struct config_group webusb_group;
Quoted 11 lines
drivers/usb/gadget/configfs.c struct gadget_info { · line 56
Quoted 9 lines
drivers/usb/gadget/configfs.c +3
-0struct mutex lock;struct usb_gadget_strings *gstrings[MAX_USB_STRING_LANGS +1 ];@@ -50,6 +51,11 @@ struct gadget_info {bool use_os_desc;char b_vendor_code;char qw_sign[OS_STRING_QW_SIGN_LEN ]; +bool use_webusb; +u16 bcd_webusb_version; +u8 b_webusb_vendor_code;Again, improper indentation.
I'll fix this.
Quoted 7 lines
Quoted 5 lines
drivers/usb/gadget/configfs.c +2
-0+char landing_page[255 ]; +spinlock_t spinlock;bool unbind; };...
I'll fix this.
Quoted 9 lines
Quoted 9 lines
include/linux/usb/composite.h +0
-0@@ -474,6 +474,12 @@ struct usb_composite_dev {struct usb_configuration *os_desc_config; unsigned int use_os_string:1;
Quoted 6 lines
include/linux/usb/composite.h struct usb_composite_dev { · line 480
Quoted 4 lines
include/linux/usb/composite.h +4
-0+/* WebUSB */ +u16 bcd_webusb_version; +u8 b_webusb_vendor_code; +char landing_page[255 ];Improper indentation.
I'll fix this.
Quoted 8 lines
include/linux/usb/composite.h struct usb_composite_dev { · line 485
Quoted 6 lines
include/linux/usb/composite.h +2
-0+ unsigned int use_webusb:1; +/* private: */ /* internals */ unsigned int suspended:1;Alan Stern
Thank you for your review! I will post an updated version of the patch soon. Jó
Quoted 7 lines · Jó Ágila Bitsch
Quoted 6 lines · Alan Stern
Quoted 3 lines · Jó Ágila Bitsch
During device enumeration, a host recognizes that the announced USB version is at least 2.01, which means, that there are BOS
Quoted 29 lines
Quoted 2 lines
Where is this 2.01 value specified? I don't remember seeing it in the usual USBIF documents.
This is actually from the backport of BOS descriptors to USB 2
Citing Randy Aull from
https://community.osr.com/discussion/comment/249742/#Comment_249742Quoted 22 lines
There is no specification called USB 2.1, however there is such a thing as a USB 2.1 device.
The USB 2.0 ECN for LPM introduced a new descriptor request to the enumeration process for USB 2 devices (the BOS descriptor set). The problem is that software can't request a new descriptor type to old devices that don't understand it without introducing compatibility issues with some devices (more than you would probably expect). So, software needed a way to identify whether a device could support the host requesting a BOS descriptor set. The solution in this ECN was to require devices supporting the ECN to set their bcdUSB to0x0201(2.01).Now, when we created the USB 3.0 spec, we again wanted to leverage the BOS descriptor, not only because we wanted to mandate USB 2 LPM in 3.0 devices when operating at high-speed, but also so the device can indicate to a host that it can operate at SuperSpeed (to support everyone's favorite "your device can perform faster" popup). Knowing that when operating at high-speed these devices needed to report the BOS descriptor set, we knew that it couldn't set the bcdUSB to
0x0200. We mistakenly wrote it down as0x0210instead of0x0201in the 3.0 spec (perhaps we just said "two point one" which might have been ambiguous) when we were trying to just be consistent with the requirement from the LPM ECN. So, rather than changing it back to0x0201in the USB 3.0 spec, we just ran with it.So, there are USB 2.0 devices, USB 2.01 devices and USB 2.1 devices, even though the latest revision of the USB 2 spec is USB 2.0. I have recommended that the USB-IF actually create a USB 2.1 specification that captures all of the various errata, ECNs, etc from over the years, but it hasn't happened yet.
Interesting history. And now that you point it out, I do see at the end of section 3 of the USB 2.0 Link Power Management ECN:
Devices that support the BOS descriptor must have a bcdUSB value of 0201H or larger.
Quoted 5 lines
Btw, configfs already includes these version codes to support Link Power Management (LPM) and
the associated BOS descriptor, so I didn't add that part, I only added webusb as a condition as to
when to send BOS descriptors.
Right.
Quoted 18 lines
Quoted 7 lines
Quoted 7 lines
drivers/usb/gadget/composite.c +0
-3@@ -713,14 +714,16 @@ static int bos_desc(struct usb_composite_dev *cdev)* A SuperSpeed device shall include the USB2.0 extension descriptor * and shall support LPM when operating in USB2.0 HS mode. */ - usb_ext = cdev->req->buf +le16_to_cpu (bos->wTotalLength); - bos->bNumDeviceCaps++; -le16_add_cpu (&bos->wTotalLength,USB_DT_USB_EXT_CAP_SIZE );Quoted 8 lines
drivers/usb/gadget/composite.c static int bos_desc(struct usb_composite_dev *cdev) · line 717
Quoted 6 lines
drivers/usb/gadget/composite.c +1
-5- usb_ext->bLength =USB_DT_USB_EXT_CAP_SIZE ; - usb_ext->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; - usb_ext->bDevCapabilityType =USB_CAP_TYPE_EXT ; - usb_ext->bmAttributes =cpu_to_le32 (USB_LPM_SUPPORT | -USB_BESL_SUPPORT | besl); +if (cdev->gadget->lpm_capable) {This change doesn't seem to be related to the purpose of this patch.
Actually, it is.
Quoted 8 lines
Previously, BOS descriptors would only ever be sent if the device was
lpm_capable.
For this reason, this descriptor was previously sent unconditionally.With my patch in place, it could be that a device is not
lpm_capable, but still wants to send BOS descriptors to announce its WebUSB capability, therefore I added
this condition.
Okay. It would be good to explain this in the patch description.
Alan Stern
PATCH v3 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
---
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
Documentation/ABI/testing/configfs-usb-gadget | 13 ++ drivers/usb/gadget/composite.c | 95 ++++++++++-- drivers/usb/gadget/configfs.c | 145 ++++++++++++++++++ include/linux/usb/composite.h | 6 + include/uapi/linux/usb/ch9.h | 33 ++++ 5 files changed, 282 insertions(+), 10 deletions(-)
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.2 +Description: + This group contains "WebUSB" extension handling attributes. + + ============= =============================================== + use flag turning "WebUSB" support on/off + bcdVersion bcd WebUSB specification version number + b_vendor_code one-byte value used for custom per-device + landing_page UTF-8 encoded URL of the device's landing page + ============= ===============================================
drivers/usb/gadget/composite.c +85 -10
131 lines not on this page · raw message
drivers/usb/gadget/configfs.c +145 -0
175 lines not on this page · raw message
include/linux/usb/composite.h +6 -0
@@ -474,6 +474,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[255 ]; + unsigned int use_webusb:1; +/* private: */ /* internals */ unsigned int suspended:1;
include/uapi/linux/usb/ch9.h +33 -0
@@ -947,6 +947,39 @@ 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 ]; +} __attribute__((packed)); + +#define USB_DT_USB_PLAT_DEV_CAP_SIZE 20 + +/* +* WebUSB Platform Capability descriptor: A device announces support for the +* WebUSB command set by including the following Platform Descriptor in its +* Binary Object Store +* https://wicg.github.io/webusb/#webusb-platform-capability-descriptor +*/ +struct usb_webusb_cap_descriptor { +__u8 bLength; +__u8 bDescriptorType; +__u8 bDevCapabilityType; +__u8 bReserved; +__u8 UUID[16 ]; +__u16 bcdVersion; +__u8 bVendorCode; +__u8 iLandingPage; +} __attribute__((packed)); +#define USB_DT_WEBUSB_SIZE (USB_DT_USB_PLAT_DEV_CAP_SIZE + 4) +/* * SuperSpeed Plus USB Capability descriptor: Defines the set of * SuperSpeed Plus USB specific device level capabilities
Signature · 1 line
2.37.2
Re: [PATCH v3] usb: gadget: add WebUSB landing page support
Hi Jó Ágila Bitsch,
W dniu 1.01.2023 o 17:59, Jó Ágila Bitsch pisze:
Quoted 9 lines
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.
Quoted 6 lines
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.
I envision an "evil" scenario, where you don't own your USB device any more. Instead you are required to pay a subscription to keep accessing it because its driver is somewhere on the net. I purposedly have put evil in quotes, because such a scenario might be considered preferred by some people. Maybe there are advantages, too, like not having to worry about correct drivers. Anyway, the kernel is about mechanism, not policy, so I'm probably in no position to judge such things.
Please see below.
Quoted 175 lines
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_capablecondition.Usage is modeled after
os_descdescriptors:
echo 1 > webusb/use
echo "https://www.kernel.org" > webusb/landingPagelsusb 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.orgSigned-off-by Jó Ágila Bitsch <[email protected]>---
v2 -> V3: improved commit message to include additional condition indesc_bosas 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: usesysfs_emitinstead of sprintf and use lock inwebusb_bcdVersion_store, addressed review
comments by Christophe JAILLETDocumentation/ABI/testing/configfs-usb-gadget | 13 ++ drivers/usb/gadget/composite.c | 95 ++++++++++-- drivers/usb/gadget/configfs.c | 145 ++++++++++++++++++ include/linux/usb/composite.h | 6 + include/uapi/linux/usb/ch9.h | 33 ++++ 5 files changed, 282 insertions(+), 10 deletions(-)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.2 +Description: + This group contains "WebUSB" extension handling attributes. + + ============= =============================================== + use flag turning "WebUSB" support on/off + bcdVersion bcd WebUSB specification version number + b_vendor_code one-byte value used for custom per-device + landing_page UTF-8 encoded URL of the device's landing page + ============= ===============================================drivers/usb/gadget/composite.c +54
-10@@ -14,6 +14,7 @@#include <linux/device.h> #include <linux/utsname.h> #include <linux/bitfield.h> +#include <linux/uuid.h> #include <linux/usb/composite.h> #include <linux/usb/otg.h> @@ -713,14 +714,16 @@ static int bos_desc(struct usb_composite_dev *cdev)* A SuperSpeed device shall include the USB2.0 extension descriptor * and shall support LPM when operating in USB2.0 HS mode. */ - usb_ext = cdev->req->buf +le16_to_cpu (bos->wTotalLength); - bos->bNumDeviceCaps++; -le16_add_cpu (&bos->wTotalLength,USB_DT_USB_EXT_CAP_SIZE ); - usb_ext->bLength =USB_DT_USB_EXT_CAP_SIZE ; - usb_ext->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; - usb_ext->bDevCapabilityType =USB_CAP_TYPE_EXT ; - usb_ext->bmAttributes =cpu_to_le32 (USB_LPM_SUPPORT | -USB_BESL_SUPPORT | besl); +if (cdev->gadget->lpm_capable) { + usb_ext = cdev->req->buf +le16_to_cpu (bos->wTotalLength); + bos->bNumDeviceCaps++; +le16_add_cpu (&bos->wTotalLength,USB_DT_USB_EXT_CAP_SIZE ); + usb_ext->bLength =USB_DT_USB_EXT_CAP_SIZE ; + usb_ext->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; + usb_ext->bDevCapabilityType =USB_CAP_TYPE_EXT ; + usb_ext->bmAttributes =cpu_to_le32 (USB_LPM_SUPPORT | +USB_BESL_SUPPORT | besl); + }/* * The Superspeed USB Capability descriptor shall be implemented by all @@ -821,6 +824,40 @@ static int bos_desc(struct usb_composite_dev *cdev) } } +/* +* Following the specifaction at: +* https://wicg.github.io/webusb/#webusb-platform-capability-descriptor +*/ +if (cdev->use_webusb) { +struct usb_webusb_cap_descriptor *webusb_cap; +/* +* little endian PlatformCapablityUUID for WebUSB: +* 3408b638-09a9-47a0-8bfd-a0768815b665 +*/ +uuid_t webusb_uuid =UUID_INIT (0x38b60834 ,0xa909 ,0xa047 ,0x8b ,0xfd ,0xa0 ,0x76 , +0x88 ,0x15 ,0xb6 ,0x65 ); + + webusb_cap = cdev->req->buf +le16_to_cpu (bos->wTotalLength); + bos->bNumDeviceCaps++; + +le16_add_cpu (&bos->wTotalLength,USB_DT_WEBUSB_SIZE ); + webusb_cap->bLength =USB_DT_WEBUSB_SIZE ; + webusb_cap->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; + webusb_cap->bDevCapabilityType =USB_PLAT_DEV_CAP_TYPE ; + webusb_cap->bReserved =0 ; +export_uuid (webusb_cap->UUID, &webusb_uuid); +if (cdev->bcd_webusb_version !=0 ) + webusb_cap->bcdVersion =cpu_to_le16 (cdev->bcd_webusb_version); +else + webusb_cap->bcdVersion =cpu_to_le16 (0x0100 ); + + webusb_cap->bVendorCode = cdev->b_webusb_vendor_code; +if (strnlen (cdev->landing_page,sizeof (cdev->landing_page)) >0 ) + webusb_cap->iLandingPage =1 ; +else + webusb_cap->iLandingPage =0 ; + } +return le16_to_cpu (bos->wTotalLength); }@@ -1744,7 +1781,7 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) cdev->desc.bcdUSB =cpu_to_le16 (0x0210 ); } }else { -if (gadget->lpm_capable) +if (gadget->lpm_capable || cdev->use_webusb) cdev->desc.bcdUSB =cpu_to_le16 (0x0201 );else cdev->desc.bcdUSB =cpu_to_le16 (0x0200 );@@ -1779,7 +1816,7 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl)break ;case USB_DT_BOS :if (gadget_is_superspeed (gadget) || - gadget->lpm_capable) { + gadget->lpm_capable || cdev->use_webusb) { value =bos_desc (cdev); value =min (w_length, (u16 ) value); }@@ -2013,6 +2050,44 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) goto check_value; } +/* +* webusb descriptor handling, following: +* https://wicg.github.io/webusb/#device-requests +*/ + if (cdev->use_webusb && + (ctrl->bRequestType & USB_TYPE_VENDOR) && + ctrl->wIndex == /* WEBUSB_GET_URL*/ 2 &&
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2069
Quoted 10 lines
drivers/usb/gadget/composite.c +10
-0+ ctrl->bRequest == cdev->b_webusb_vendor_code) { +/* +* specification of the url descriptor in WebUSB: +* https://wicg.github.io/webusb/#webusb-descriptors +*/ +u8 *buf; +unsigned int landing_page_length; + + buf = cdev->req->buf; + buf[1 ] =/* WEBUSB_URL*/ 3 ;
Why not #define WEBUSB_URL?
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2072
Quoted 3 lines
drivers/usb/gadget/composite.c +3
-0+ + landing_page_length =strnlen (cdev->landing_page,252 ); +if (strncasecmp ("https://" , cdev->landing_page,8 ) ==0 ) {
Maybe it's me, but it would be easier for me to understand why the "8" if the comparison was in reverse order of arguments, like this:
strncasecmp(cdev->landing_page, "https://", 8)
because we want the entirety of "https://" compared, not its substring, so the limit kind of applies to the landing_page in the first place. Maybe the "8" (and "7" below) can be #define'd, too?
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2073
Quoted 1 line
drivers/usb/gadget/composite.c +1
-0+ buf[2 ] =0x01 ;
What is this magic 0x01?
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2074
Quoted 1 line
drivers/usb/gadget/composite.c +1
-0+memcpy (buf+3 , cdev->landing_page+8 , landing_page_length-8 );
spaces around arithmetic operators?
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2077
Quoted 3 lines
drivers/usb/gadget/composite.c +3
-0+ buf[0 ] = landing_page_length -8 +3 ; + }else if (strncasecmp ("http://" , cdev->landing_page,7 ) ==0 ) { + buf[2 ] =0x00 ;
Magic 0x00?
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2081
Quoted 4 lines
drivers/usb/gadget/composite.c +4
-0+memcpy (buf+3 , cdev->landing_page+7 , landing_page_length-7 ); + buf[0 ] = landing_page_length -7 +3 ; + }else { + buf[2 ] =0xFF ;
Magic 0xFF? (plus I'd expect lowercase hex digits).
There's "URL Prefixes" table in 4.3.1 URL Descriptor. Why not define URL_PREFIX_HTTP/HTTPS/NONE?
Quoted 25 lines
drivers/usb/gadget/composite.c +9
-0+memcpy (buf+3 , cdev->landing_page, landing_page_length); + buf[0 ] = landing_page_length +3 ; + } + + value = buf[0 ]; + + goto check_value; + } + VDBG(cdev, "non-core control req%02x.%02x v%04x i%04x l%d\n", ctrl->bRequestType, ctrl->bRequest,drivers/usb/gadget/configfs.c +1
-0@@ -39,6 +39,7 @@ struct gadget_info {struct config_group configs_group;struct config_group strings_group;struct config_group os_desc_group; +struct config_group webusb_group;struct mutex lock;struct usb_gadget_strings *gstrings[MAX_USB_STRING_LANGS +1 ];
drivers/usb/gadget/configfs.c struct gadget_info { · line 57
Quoted 7 lines
drivers/usb/gadget/configfs.c +4
-0@@ -50,6 +51,11 @@ struct gadget_info {bool use_os_desc;char b_vendor_code;char qw_sign[OS_STRING_QW_SIGN_LEN ]; +bool use_webusb; +u16 bcd_webusb_version; +u8 b_webusb_vendor_code; +char landing_page[255 ];
A #define for the size?
Quoted 138 lines
drivers/usb/gadget/configfs.c +126
-0+spinlock_t spinlock;bool unbind; };@@ -780,6 +786,131 @@ static void gadget_strings_attr_release(struct config_item *item)USB_CONFIG_STRING_RW_OPS (gadget_strings);USB_CONFIG_STRINGS_LANG (gadget_strings, gadget_info); +static inline struct gadget_info *webusb_item_to_gadget_info ( +struct config_item *item) +{ +return container_of (to_config_group (item), + struct gadget_info, webusb_group); +} + +static ssize_t webusb_use_show (struct config_item *item,char *page) +{ +return sysfs_emit (page,"%d\n" , +webusb_item_to_gadget_info (item)->use_webusb); +} + +static ssize_t webusb_use_store (struct config_item *item,const char *page, +size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +int ret; +bool use; + +mutex_lock (&gi->lock); + ret =kstrtobool (page, &use); +if (!ret) { + gi->use_webusb = use; + ret = len; + } +mutex_unlock (&gi->lock); + +return ret; +} + +static ssize_t webusb_bcdVersion_show (struct config_item *item,char *page) +{ +return sysfs_emit (page,"0x%04x\n" , +webusb_item_to_gadget_info (item)->bcd_webusb_version); +} + +static ssize_t webusb_bcdVersion_store (struct config_item *item, +const char *page,size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +u16 bcdVersion; +int ret; + +mutex_lock (&gi->lock); + ret =kstrtou16 (page,0 , &bcdVersion); +if (ret) + goto out; + ret =is_valid_bcd (bcdVersion); +if (ret) + goto out; + + gi->bcd_webusb_version = bcdVersion; + ret = len; + +out: +mutex_unlock (&gi->lock); + +return ret; +} + +static ssize_t webusb_bVendorCode_show (struct config_item *item,char *page) +{ +return sysfs_emit (page,"0x%02x\n" , +webusb_item_to_gadget_info (item)->b_webusb_vendor_code); +} + +static ssize_t webusb_bVendorCode_store (struct config_item *item, +const char *page,size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +int ret; +u8 b_vendor_code; + +mutex_lock (&gi->lock); + ret =kstrtou8 (page,0 , &b_vendor_code); +if (!ret) { + gi->b_webusb_vendor_code = b_vendor_code; + ret = len; + } +mutex_unlock (&gi->lock); + +return ret; +} + +static ssize_t webusb_landingPage_show (struct config_item *item,char *page) +{ +return sysfs_emit (page,"%s\n" ,webusb_item_to_gadget_info (item)->landing_page); +} + +static ssize_t webusb_landingPage_store (struct config_item *item,const char *page, +size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +int l; + + l =min (len,sizeof (gi->landing_page)); +if (page[l -1 ] =='\n' ) + --l; + +mutex_lock (&gi->lock); +memcpy (gi->landing_page, page, l); +mutex_unlock (&gi->lock); + +return len; +} + +CONFIGFS_ATTR (webusb_, use); +CONFIGFS_ATTR (webusb_, bVendorCode); +CONFIGFS_ATTR (webusb_, bcdVersion); +CONFIGFS_ATTR (webusb_, landingPage); + +static struct configfs_attribute *webusb_attrs[] = { + &webusb_attr_use, + &webusb_attr_bcdVersion, + &webusb_attr_bVendorCode, + &webusb_attr_landingPage, +NULL , +}; + +static struct config_item_type webusb_type = { + .ct_attrs = webusb_attrs, + .ct_owner =THIS_MODULE , +}; +static inline struct gadget_info *os_desc_item_to_gadget_info (struct config_item *item) {@@ -1341,6 +1472,16 @@ static int configfs_composite_bind(struct usb_gadget *gadget, gi->cdev.desc.iSerialNumber = s[USB_GADGET_SERIAL_IDX ].id;
drivers/usb/gadget/configfs.c static int configfs_composite_bind(struct usb_gadget *gadget, · line 1482
Quoted 10 lines
drivers/usb/gadget/configfs.c +8
-0} +if (gi->use_webusb) { + cdev->use_webusb = true; + cdev->bcd_webusb_version = gi->bcd_webusb_version; + cdev->b_webusb_vendor_code = gi->b_webusb_vendor_code; +memcpy (cdev->landing_page, gi->landing_page, +strnlen (gi->landing_page, +min (sizeof (cdev->landing_page), +sizeof (gi->landing_page))));
checkpatch now allows 100 colums. Plus strnlen() looks indented too far to the right.
The sizeofs are both 255. Are they ever expected to be different? Maybe not? Then a #defined constant ensures they are equal. Then there's no need to find a minimum among equal values.
Regards,
Andrzej
Quoted 77 lines
drivers/usb/gadget/configfs.c +6
-0+ } +if (gi->use_os_desc) { cdev->use_os_string = true; cdev->b_vendor_code = gi->b_vendor_code;@@ -1605,6 +1746,10 @@ static struct config_group *gadgets_make( &os_desc_type);configfs_add_default_group (&gi->os_desc_group, &gi->group); +config_group_init_type_name (&gi->webusb_group,"webusb" , + &webusb_type); +configfs_add_default_group (&gi->webusb_group, &gi->group); + gi->composite.bind = configfs_do_nothing; gi->composite.unbind = configfs_do_nothing; gi->composite.suspend =NULL ;include/linux/usb/composite.h +6
-0@@ -474,6 +474,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[255 ]; + unsigned int use_webusb:1; +/* private: */ /* internals */ unsigned int suspended:1;include/uapi/linux/usb/ch9.h +33
-0@@ -947,6 +947,39 @@ 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 ]; +} __attribute__((packed)); + +#define USB_DT_USB_PLAT_DEV_CAP_SIZE 20 + +/* +* WebUSB Platform Capability descriptor: A device announces support for the +* WebUSB command set by including the following Platform Descriptor in its +* Binary Object Store +* https://wicg.github.io/webusb/#webusb-platform-capability-descriptor +*/ +struct usb_webusb_cap_descriptor { +__u8 bLength; +__u8 bDescriptorType; +__u8 bDevCapabilityType; +__u8 bReserved; +__u8 UUID[16 ]; +__u16 bcdVersion; +__u8 bVendorCode; +__u8 iLandingPage; +} __attribute__((packed)); +#define USB_DT_WEBUSB_SIZE (USB_DT_USB_PLAT_DEV_CAP_SIZE + 4) +/* * SuperSpeed Plus USB Capability descriptor: Defines the set of * SuperSpeed Plus USB specific device level capabilities
Re: [PATCH v3] usb: gadget: add WebUSB landing page support
Hi Andrzej,
Quoted 7 lines
Quoted 6 lines
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.
Quoted 7 lines
I envision an "evil" scenario, where you don't own your USB device any more. Instead you are required to pay a subscription to keep accessing it because its driver is somewhere on the net. I purposedly have put evil in quotes, because such a scenario might be considered preferred by some people. Maybe there are advantages, too, like not having to worry about correct drivers. Anyway, the kernel is about mechanism, not policy, so I'm probably in no position to judge such things.
Unfortunately, the "evil" devices you envision very much already exist.
When I was still working at university in the early 2010s, we were working with a mobile EEG headset (>1000USD) with a USB receiver dongle that would present itself as a USB HID device, but the transferred frames would be AES encrypted, with the key based on a proprietary transformation of the serial number of the device. At first the library that decoded it was available as a binary blob for a one-time payment, where you paid a hefty premium if you wanted access to the raw readings. Later the manufacturer changed their business model to subscription based, where the data had to flow through their cloud service - with a recurring license fee. I don't know what happened afterwards, as I left university.
This all was implemented based on libusb back then before people even thought of WebUSB.
I'm sure there are other examples.
So, "evil" devices are already real and don't depend on WebUSB. The motivating example "Web Drivers" from the specs
(https://wicg.github.io/webusb/#app-drivers) might potentially lead to companies asking for subscription fees for their Web Driver, but as long as there is no strong encryption in place, everyone would be free to write an alternative driver. The mechanisms would not at all preclude you from writing your own kernel or userspace driver using e.g. libusb. A kernel driver would block access from the browser though, as the browser cannot detach the kernel driver. (No such command is currently defined in WebUSB.) The JS implementation might even guide you to understand aspects of the protocol used.
Citing from the motivating example in the design specs
(https://wicg.github.io/webusb/#app-updates-and-diagnostics):
Quoted 1 line
The landing page provides a way for the device manufacturer to direct the user to the right part of their website for help with their device.
The landing page mechanism in WebUSB improves discoverability for devices, as Chrome and also lsusb directly point you to a webpage, where the manufacturer or firmware producer can give more information about the device. This webpage does not necessarily need to use a WebUSB JS driver itself to access the device, but might just as well point you to some git repository, where the hardware design and firmware source are available.
For what it's worth, the pick-up of WebUSB I've seen has been mostly in the maker scene with arduino, micro:bit and similar embedded devices, where devices provide at least two interfaces: One for the OS to claim and one for the Browser to claim.
Anyways, my biased opinion is that I would very much like a device to tell me where I can find support documentation, updates and help also when the device only implements standard interfaces that have kernel drivers. I don't think that this URL will lead to more devices you can only access with a subscription.
Quoted 1 line
Please see below.
Thanks for your excellent feedback. I answered inline.
Quoted 179 lines
Quoted 179 lines
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_capablecondition.Usage is modeled after
os_descdescriptors:
echo 1 > webusb/use
echo "https://www.kernel.org" > webusb/landingPagelsusb 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.orgSigned-off-by Jó Ágila Bitsch <[email protected]>---
v2 -> V3: improved commit message to include additional condition indesc_bosas 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: usesysfs_emitinstead of sprintf and use lock inwebusb_bcdVersion_store, addressed review
comments by Christophe JAILLETDocumentation/ABI/testing/configfs-usb-gadget | 13 ++ drivers/usb/gadget/composite.c | 95 ++++++++++-- drivers/usb/gadget/configfs.c | 145 ++++++++++++++++++ include/linux/usb/composite.h | 6 + include/uapi/linux/usb/ch9.h | 33 ++++ 5 files changed, 282 insertions(+), 10 deletions(-)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.2 +Description: + This group contains "WebUSB" extension handling attributes. + + ============= =============================================== + use flag turning "WebUSB" support on/off + bcdVersion bcd WebUSB specification version number + b_vendor_code one-byte value used for custom per-device + landing_page UTF-8 encoded URL of the device's landing page + ============= ===============================================drivers/usb/gadget/composite.c +58
-10@@ -14,6 +14,7 @@#include <linux/device.h> #include <linux/utsname.h> #include <linux/bitfield.h> +#include <linux/uuid.h> #include <linux/usb/composite.h> #include <linux/usb/otg.h> @@ -713,14 +714,16 @@ static int bos_desc(struct usb_composite_dev *cdev)* A SuperSpeed device shall include the USB2.0 extension descriptor * and shall support LPM when operating in USB2.0 HS mode. */ - usb_ext = cdev->req->buf +le16_to_cpu (bos->wTotalLength); - bos->bNumDeviceCaps++; -le16_add_cpu (&bos->wTotalLength,USB_DT_USB_EXT_CAP_SIZE ); - usb_ext->bLength =USB_DT_USB_EXT_CAP_SIZE ; - usb_ext->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; - usb_ext->bDevCapabilityType =USB_CAP_TYPE_EXT ; - usb_ext->bmAttributes =cpu_to_le32 (USB_LPM_SUPPORT | -USB_BESL_SUPPORT | besl); +if (cdev->gadget->lpm_capable) { + usb_ext = cdev->req->buf +le16_to_cpu (bos->wTotalLength); + bos->bNumDeviceCaps++; +le16_add_cpu (&bos->wTotalLength,USB_DT_USB_EXT_CAP_SIZE ); + usb_ext->bLength =USB_DT_USB_EXT_CAP_SIZE ; + usb_ext->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; + usb_ext->bDevCapabilityType =USB_CAP_TYPE_EXT ; + usb_ext->bmAttributes =cpu_to_le32 (USB_LPM_SUPPORT | +USB_BESL_SUPPORT | besl); + }/* * The Superspeed USB Capability descriptor shall be implemented by all @@ -821,6 +824,40 @@ static int bos_desc(struct usb_composite_dev *cdev) } } +/* +* Following the specifaction at: +* https://wicg.github.io/webusb/#webusb-platform-capability-descriptor +*/ +if (cdev->use_webusb) { +struct usb_webusb_cap_descriptor *webusb_cap; +/* +* little endian PlatformCapablityUUID for WebUSB: +* 3408b638-09a9-47a0-8bfd-a0768815b665 +*/ +uuid_t webusb_uuid =UUID_INIT (0x38b60834 ,0xa909 ,0xa047 ,0x8b ,0xfd ,0xa0 ,0x76 , +0x88 ,0x15 ,0xb6 ,0x65 ); + + webusb_cap = cdev->req->buf +le16_to_cpu (bos->wTotalLength); + bos->bNumDeviceCaps++; + +le16_add_cpu (&bos->wTotalLength,USB_DT_WEBUSB_SIZE ); + webusb_cap->bLength =USB_DT_WEBUSB_SIZE ; + webusb_cap->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; + webusb_cap->bDevCapabilityType =USB_PLAT_DEV_CAP_TYPE ; + webusb_cap->bReserved =0 ; +export_uuid (webusb_cap->UUID, &webusb_uuid); +if (cdev->bcd_webusb_version !=0 ) + webusb_cap->bcdVersion =cpu_to_le16 (cdev->bcd_webusb_version); +else + webusb_cap->bcdVersion =cpu_to_le16 (0x0100 ); + + webusb_cap->bVendorCode = cdev->b_webusb_vendor_code; +if (strnlen (cdev->landing_page,sizeof (cdev->landing_page)) >0 ) + webusb_cap->iLandingPage =1 ; +else + webusb_cap->iLandingPage =0 ; + } +return le16_to_cpu (bos->wTotalLength); }@@ -1744,7 +1781,7 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) cdev->desc.bcdUSB =cpu_to_le16 (0x0210 ); } }else { -if (gadget->lpm_capable) +if (gadget->lpm_capable || cdev->use_webusb) cdev->desc.bcdUSB =cpu_to_le16 (0x0201 );else cdev->desc.bcdUSB =cpu_to_le16 (0x0200 );@@ -1779,7 +1816,7 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl)break ;case USB_DT_BOS :if (gadget_is_superspeed (gadget) || - gadget->lpm_capable) { + gadget->lpm_capable || cdev->use_webusb) { value =bos_desc (cdev); value =min (w_length, (u16 ) value); }@@ -2013,6 +2050,44 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) goto check_value; } +/* +* webusb descriptor handling, following: +* https://wicg.github.io/webusb/#device-requests +*/ +if (cdev->use_webusb && + (ctrl->bRequestType &USB_TYPE_VENDOR ) && + ctrl->wIndex ==/* WEBUSB_GET_URL*/ 2 && + ctrl->bRequest == cdev->b_webusb_vendor_code) { +/* +* specification of the url descriptor in WebUSB: +* https://wicg.github.io/webusb/#webusb-descriptors
Quoted 8 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2069
Quoted 6 lines
drivers/usb/gadget/composite.c +6
-0+*/ +u8 *buf; +unsigned int landing_page_length; + + buf = cdev->req->buf; + buf[1 ] =/* WEBUSB_URL*/ 3 ;Why not #define
WEBUSB_URL?
in a previous iteration, I had that exact #define in place, right above. However, another reviewer found it pointless. Maybe I should instead put the define into include/uapi/linux/usb/ch9.h
Quoted 9 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2072
Quoted 4 lines
drivers/usb/gadget/composite.c +3
-0+ + landing_page_length =strnlen (cdev->landing_page,252 ); +if (strncasecmp ("https://" , cdev->landing_page,8 ) ==0 ) {Maybe it's me, but it would be easier for me to understand why the "8" if the comparison was in reverse order of arguments, like this:
strncasecmp(cdev->landing_page, "https://", 8)
I agree, this makes the 8 clearer.
Quoted 3 lines
because we want the entirety of "https://" compared, not its substring, so the limit kind of applies to the
landing_pagein the first place. Maybe the "8" (and "7" below) can be #define'd, too?
depends on the name, but maybe something like
#define WEBUSB_PREFIX_HTTPS "https://"
#define WEBUSB_PREFIX_HTTPS_LENGTH 8
#define WEBUSB_PREFIX_HTTPS_SCHEME_ID 0x01
would work defined with the struct in include/uapi/linux/usb/ch9.h
Quoted 4 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2073
Quoted 2 lines
drivers/usb/gadget/composite.c +1
-0+ buf[2 ] =0x01 ;What is this magic
0x01?
The field is specified in
https://wicg.github.io/webusb/#url-descriptor and would be the WEBUSB_PREFIX_HTTPS_SCHEME_ID from above.
But yes, I should #define this.
Quoted 4 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2074
Quoted 2 lines
drivers/usb/gadget/composite.c +1
-0+memcpy (buf+3 , cdev->landing_page+8 , landing_page_length-8 );spaces around arithmetic operators?
will do
Quoted 5 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2077
Quoted 3 lines
drivers/usb/gadget/composite.c +3
-0+ buf[0 ] = landing_page_length -8 +3 ; + }else if (strncasecmp ("http://" , cdev->landing_page,7 ) ==0 ) { + buf[2 ] =0x00 ;Magic
0x00?
This would then be WEBUSB_PREFIX_HTTP_SCHEME_ID
Quoted 7 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2081
Quoted 5 lines
drivers/usb/gadget/composite.c +4
-0+memcpy (buf+3 , cdev->landing_page+7 , landing_page_length-7 ); + buf[0 ] = landing_page_length -7 +3 ; + }else { + buf[2 ] =0xFF ;Magic
0xFF? (plus I'd expect lowercase hex digits).
This would then be WEBUSB_PREFIX_NONE_SCHEME_ID
Quoted 2 lines
There's "URL Prefixes" table in 4.3.1 URL Descriptor. Why not define URL_PREFIX_HTTP/HTTPS/NONE?
will do
Quoted 22 lines
Quoted 22 lines
drivers/usb/gadget/composite.c +9
-0+memcpy (buf+3 , cdev->landing_page, landing_page_length); + buf[0 ] = landing_page_length +3 ; + } + + value = buf[0 ]; + + goto check_value; + } + VDBG(cdev, "non-core control req%02x.%02x v%04x i%04x l%d\n", ctrl->bRequestType, ctrl->bRequest,drivers/usb/gadget/configfs.c +1
-0@@ -39,6 +39,7 @@ struct gadget_info {struct config_group configs_group;struct config_group strings_group;struct config_group os_desc_group; +struct config_group webusb_group;
Quoted 12 lines
drivers/usb/gadget/configfs.c struct gadget_info { · line 57
Quoted 10 lines
drivers/usb/gadget/configfs.c +4
-0struct mutex lock;struct usb_gadget_strings *gstrings[MAX_USB_STRING_LANGS +1 ];@@ -50,6 +51,11 @@ struct gadget_info {bool use_os_desc;char b_vendor_code;char qw_sign[OS_STRING_QW_SIGN_LEN ]; +bool use_webusb; +u16 bcd_webusb_version; +u8 b_webusb_vendor_code; +char landing_page[255 ];A #define for the size?
will do
Quoted 141 lines
Quoted 141 lines
drivers/usb/gadget/configfs.c +126
-0+spinlock_t spinlock;bool unbind; };@@ -780,6 +786,131 @@ static void gadget_strings_attr_release(struct config_item *item)USB_CONFIG_STRING_RW_OPS (gadget_strings);USB_CONFIG_STRINGS_LANG (gadget_strings, gadget_info); +static inline struct gadget_info *webusb_item_to_gadget_info ( +struct config_item *item) +{ +return container_of (to_config_group (item), + struct gadget_info, webusb_group); +} + +static ssize_t webusb_use_show (struct config_item *item,char *page) +{ +return sysfs_emit (page,"%d\n" , +webusb_item_to_gadget_info (item)->use_webusb); +} + +static ssize_t webusb_use_store (struct config_item *item,const char *page, +size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +int ret; +bool use; + +mutex_lock (&gi->lock); + ret =kstrtobool (page, &use); +if (!ret) { + gi->use_webusb = use; + ret = len; + } +mutex_unlock (&gi->lock); + +return ret; +} + +static ssize_t webusb_bcdVersion_show (struct config_item *item,char *page) +{ +return sysfs_emit (page,"0x%04x\n" , +webusb_item_to_gadget_info (item)->bcd_webusb_version); +} + +static ssize_t webusb_bcdVersion_store (struct config_item *item, +const char *page,size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +u16 bcdVersion; +int ret; + +mutex_lock (&gi->lock); + ret =kstrtou16 (page,0 , &bcdVersion); +if (ret) + goto out; + ret =is_valid_bcd (bcdVersion); +if (ret) + goto out; + + gi->bcd_webusb_version = bcdVersion; + ret = len; + +out: +mutex_unlock (&gi->lock); + +return ret; +} + +static ssize_t webusb_bVendorCode_show (struct config_item *item,char *page) +{ +return sysfs_emit (page,"0x%02x\n" , +webusb_item_to_gadget_info (item)->b_webusb_vendor_code); +} + +static ssize_t webusb_bVendorCode_store (struct config_item *item, +const char *page,size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +int ret; +u8 b_vendor_code; + +mutex_lock (&gi->lock); + ret =kstrtou8 (page,0 , &b_vendor_code); +if (!ret) { + gi->b_webusb_vendor_code = b_vendor_code; + ret = len; + } +mutex_unlock (&gi->lock); + +return ret; +} + +static ssize_t webusb_landingPage_show (struct config_item *item,char *page) +{ +return sysfs_emit (page,"%s\n" ,webusb_item_to_gadget_info (item)->landing_page); +} + +static ssize_t webusb_landingPage_store (struct config_item *item,const char *page, +size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +int l; + + l =min (len,sizeof (gi->landing_page)); +if (page[l -1 ] =='\n' ) + --l; + +mutex_lock (&gi->lock); +memcpy (gi->landing_page, page, l); +mutex_unlock (&gi->lock); + +return len; +} + +CONFIGFS_ATTR (webusb_, use); +CONFIGFS_ATTR (webusb_, bVendorCode); +CONFIGFS_ATTR (webusb_, bcdVersion); +CONFIGFS_ATTR (webusb_, landingPage); + +static struct configfs_attribute *webusb_attrs[] = { + &webusb_attr_use, + &webusb_attr_bcdVersion, + &webusb_attr_bVendorCode, + &webusb_attr_landingPage, +NULL , +}; + +static struct config_item_type webusb_type = { + .ct_attrs = webusb_attrs, + .ct_owner =THIS_MODULE , +}; +static inline struct gadget_info *os_desc_item_to_gadget_info (struct config_item *item) {@@ -1341,6 +1472,16 @@ static int configfs_composite_bind(struct usb_gadget *gadget, gi->cdev.desc.iSerialNumber = s[USB_GADGET_SERIAL_IDX ].id; }
Quoted 11 lines
drivers/usb/gadget/configfs.c static int configfs_composite_bind(struct usb_gadget *gadget, · line 1482
Quoted 8 lines
drivers/usb/gadget/configfs.c +8
-0+if (gi->use_webusb) { + cdev->use_webusb = true; + cdev->bcd_webusb_version = gi->bcd_webusb_version; + cdev->b_webusb_vendor_code = gi->b_webusb_vendor_code; +memcpy (cdev->landing_page, gi->landing_page, +strnlen (gi->landing_page, +min (sizeof (cdev->landing_page), +sizeof (gi->landing_page))));checkpatch now allows 100 colums. Plus
strnlen()looks indented too far to the right.
I will check this.
Quoted 4 lines
The sizeofs are both 255. Are they ever expected to be different? Maybe not? Then a #defined constant ensures they are equal. Then there's no need to find a minimum among equal values.
Technically, if the url has the empty scheme, it can only be 252 bytes long, since the maximum descriptor length is 255 because bLength is a single byte, but 3 bytes are in the header of this descriptor, leaving 252 for the string.
However, if the landing page scheme is "https://", the maximum length of this string could actually be 255 - 3 /*header*/ + 8 /* the length of the prefix, which is stripped */ => 260 bytes.
I need to rework the validation here a bit. I would like to avoid for userspace to explicitly set the scheme constants directly, as just piping in the string seems so much more ergonomic.
Quoted 4 lines
Regards,
Andrzej
Thanks a lot for your review!
I hope my response to your initial concerns was not too long and windy.
I will post an updated version of my patch within the next few days.
Regards,
Jó
Quoted 79 lines
Quoted 78 lines
drivers/usb/gadget/configfs.c +6
-0+ } +if (gi->use_os_desc) { cdev->use_os_string = true; cdev->b_vendor_code = gi->b_vendor_code;@@ -1605,6 +1746,10 @@ static struct config_group *gadgets_make( &os_desc_type);configfs_add_default_group (&gi->os_desc_group, &gi->group); +config_group_init_type_name (&gi->webusb_group,"webusb" , + &webusb_type); +configfs_add_default_group (&gi->webusb_group, &gi->group); + gi->composite.bind = configfs_do_nothing; gi->composite.unbind = configfs_do_nothing; gi->composite.suspend =NULL ;include/linux/usb/composite.h +6
-0@@ -474,6 +474,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[255 ]; + unsigned int use_webusb:1; +/* private: */ /* internals */ unsigned int suspended:1;include/uapi/linux/usb/ch9.h +33
-0@@ -947,6 +947,39 @@ 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 ]; +} __attribute__((packed)); + +#define USB_DT_USB_PLAT_DEV_CAP_SIZE 20 + +/* +* WebUSB Platform Capability descriptor: A device announces support for the +* WebUSB command set by including the following Platform Descriptor in its +* Binary Object Store +* https://wicg.github.io/webusb/#webusb-platform-capability-descriptor +*/ +struct usb_webusb_cap_descriptor { +__u8 bLength; +__u8 bDescriptorType; +__u8 bDevCapabilityType; +__u8 bReserved; +__u8 UUID[16 ]; +__u16 bcdVersion; +__u8 bVendorCode; +__u8 iLandingPage; +} __attribute__((packed)); +#define USB_DT_WEBUSB_SIZE (USB_DT_USB_PLAT_DEV_CAP_SIZE + 4) +/* * SuperSpeed Plus USB Capability descriptor: Defines the set of * SuperSpeed Plus USB specific device level capabilities
Re: [PATCH v3] usb: gadget: add WebUSB landing page support
Hi Jó,
W dniu 10.01.2023 o 00:19, Jó Ágila Bitsch pisze:
Quoted 19 lines
Hi Andrzej,
Quoted 7 lines
Quoted 6 lines
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.
Quoted 7 lines
I envision an "evil" scenario, where you don't own your USB device any more. Instead you are required to pay a subscription to keep accessing it because its driver is somewhere on the net. I purposedly have put evil in quotes, because such a scenario might be considered preferred by some people. Maybe there are advantages, too, like not having to worry about correct drivers. Anyway, the kernel is about mechanism, not policy, so I'm probably in no position to judge such things.
Unfortunately, the "evil" devices you envision very much already exist.
Quoted 14 lines
When I was still working at university in the early 2010s, we were working with a mobile EEG headset (>1000USD) with a USB receiver dongle that would present itself as a USB HID device, but the transferred frames would be AES encrypted, with the key based on a proprietary transformation of the serial number of the device. At first the library that decoded it was available as a binary blob for a one-time payment, where you paid a hefty premium if you wanted access to the raw readings. Later the manufacturer changed their business model to subscription based, where the data had to flow through their cloud service - with a recurring license fee. I don't know what happened afterwards, as I left university.
This all was implemented based on libusb back then before people even thought of WebUSB.
Thanks for honestly acknowledging their existence. It confirms that what I expressed was not a "conspiracy theory", but a "conspiracy practice" :D
Quoted 19 lines
I'm sure there are other examples.
So, "evil" devices are already real and don't depend on WebUSB. The motivating example "Web Drivers" from the specs
(https://wicg.github.io/webusb/#app-drivers) might potentially lead to companies asking for subscription fees for their Web Driver, but as long as there is no strong encryption in place, everyone would be free to write an alternative driver. The mechanisms would not at all preclude you from writing your own kernel or userspace driver using e.g. libusb. A kernel driver would block access from the browser though, as the browser cannot detach the kernel driver. (No such command is currently defined in WebUSB.) The JS implementation might even guide you to understand aspects of the protocol used.Citing from the motivating example in the design specs
(https://wicg.github.io/webusb/#app-updates-and-diagnostics):Quoted 1 line
The landing page provides a way for the device manufacturer to direct the user to the right part of their website for help with their device.
Quoted 7 lines
The landing page mechanism in WebUSB improves discoverability for devices, as Chrome and also lsusb directly point you to a webpage, where the manufacturer or firmware producer can give more information about the device. This webpage does not necessarily need to use a WebUSB JS driver itself to access the device, but might just as well point you to some git repository, where the hardware design and firmware source are available
I'm wondering why e.g. Firefox does not implement this? Chicken-and-egg dilemma (no OS support at kernel level, so let's refrain from using it, but then there's too few users, so let's not add OS support - this circular depencency can be broken by applying your patch) or something else?
Quoted 204 lines
For what it's worth, the pick-up of WebUSB I've seen has been mostly in the maker scene with arduino, micro:bit and similar embedded devices, where devices provide at least two interfaces: One for the OS to claim and one for the Browser to claim.
Anyways, my biased opinion is that I would very much like a device to tell me where I can find support documentation, updates and help also when the device only implements standard interfaces that have kernel drivers. I don't think that this URL will lead to more devices you can only access with a subscription.
Quoted 1 line
Please see below.
Thanks for your excellent feedback. I answered inline.
Quoted 179 lines
Quoted 179 lines
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_capablecondition.Usage is modeled after
os_descdescriptors:
echo 1 > webusb/use
echo "https://www.kernel.org" > webusb/landingPagelsusb 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.orgSigned-off-by Jó Ágila Bitsch <[email protected]>---
v2 -> V3: improved commit message to include additional condition indesc_bosas 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: usesysfs_emitinstead of sprintf and use lock inwebusb_bcdVersion_store, addressed review
comments by Christophe JAILLETDocumentation/ABI/testing/configfs-usb-gadget | 13 ++ drivers/usb/gadget/composite.c | 95 ++++++++++-- drivers/usb/gadget/configfs.c | 145 ++++++++++++++++++ include/linux/usb/composite.h | 6 + include/uapi/linux/usb/ch9.h | 33 ++++ 5 files changed, 282 insertions(+), 10 deletions(-)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.2 +Description: + This group contains "WebUSB" extension handling attributes. + + ============= =============================================== + use flag turning "WebUSB" support on/off + bcdVersion bcd WebUSB specification version number + b_vendor_code one-byte value used for custom per-device + landing_page UTF-8 encoded URL of the device's landing page + ============= ===============================================drivers/usb/gadget/composite.c +58
-10@@ -14,6 +14,7 @@#include <linux/device.h> #include <linux/utsname.h> #include <linux/bitfield.h> +#include <linux/uuid.h> #include <linux/usb/composite.h> #include <linux/usb/otg.h> @@ -713,14 +714,16 @@ static int bos_desc(struct usb_composite_dev *cdev)* A SuperSpeed device shall include the USB2.0 extension descriptor * and shall support LPM when operating in USB2.0 HS mode. */ - usb_ext = cdev->req->buf +le16_to_cpu (bos->wTotalLength); - bos->bNumDeviceCaps++; -le16_add_cpu (&bos->wTotalLength,USB_DT_USB_EXT_CAP_SIZE ); - usb_ext->bLength =USB_DT_USB_EXT_CAP_SIZE ; - usb_ext->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; - usb_ext->bDevCapabilityType =USB_CAP_TYPE_EXT ; - usb_ext->bmAttributes =cpu_to_le32 (USB_LPM_SUPPORT | -USB_BESL_SUPPORT | besl); +if (cdev->gadget->lpm_capable) { + usb_ext = cdev->req->buf +le16_to_cpu (bos->wTotalLength); + bos->bNumDeviceCaps++; +le16_add_cpu (&bos->wTotalLength,USB_DT_USB_EXT_CAP_SIZE ); + usb_ext->bLength =USB_DT_USB_EXT_CAP_SIZE ; + usb_ext->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; + usb_ext->bDevCapabilityType =USB_CAP_TYPE_EXT ; + usb_ext->bmAttributes =cpu_to_le32 (USB_LPM_SUPPORT | +USB_BESL_SUPPORT | besl); + }/* * The Superspeed USB Capability descriptor shall be implemented by all @@ -821,6 +824,40 @@ static int bos_desc(struct usb_composite_dev *cdev) } } +/* +* Following the specifaction at: +* https://wicg.github.io/webusb/#webusb-platform-capability-descriptor +*/ +if (cdev->use_webusb) { +struct usb_webusb_cap_descriptor *webusb_cap; +/* +* little endian PlatformCapablityUUID for WebUSB: +* 3408b638-09a9-47a0-8bfd-a0768815b665 +*/ +uuid_t webusb_uuid =UUID_INIT (0x38b60834 ,0xa909 ,0xa047 ,0x8b ,0xfd ,0xa0 ,0x76 , +0x88 ,0x15 ,0xb6 ,0x65 ); + + webusb_cap = cdev->req->buf +le16_to_cpu (bos->wTotalLength); + bos->bNumDeviceCaps++; + +le16_add_cpu (&bos->wTotalLength,USB_DT_WEBUSB_SIZE ); + webusb_cap->bLength =USB_DT_WEBUSB_SIZE ; + webusb_cap->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; + webusb_cap->bDevCapabilityType =USB_PLAT_DEV_CAP_TYPE ; + webusb_cap->bReserved =0 ; +export_uuid (webusb_cap->UUID, &webusb_uuid); +if (cdev->bcd_webusb_version !=0 ) + webusb_cap->bcdVersion =cpu_to_le16 (cdev->bcd_webusb_version); +else + webusb_cap->bcdVersion =cpu_to_le16 (0x0100 ); + + webusb_cap->bVendorCode = cdev->b_webusb_vendor_code; +if (strnlen (cdev->landing_page,sizeof (cdev->landing_page)) >0 ) + webusb_cap->iLandingPage =1 ; +else + webusb_cap->iLandingPage =0 ; + } +return le16_to_cpu (bos->wTotalLength); }@@ -1744,7 +1781,7 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) cdev->desc.bcdUSB =cpu_to_le16 (0x0210 ); } }else { -if (gadget->lpm_capable) +if (gadget->lpm_capable || cdev->use_webusb) cdev->desc.bcdUSB =cpu_to_le16 (0x0201 );else cdev->desc.bcdUSB =cpu_to_le16 (0x0200 );@@ -1779,7 +1816,7 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl)break ;case USB_DT_BOS :if (gadget_is_superspeed (gadget) || - gadget->lpm_capable) { + gadget->lpm_capable || cdev->use_webusb) { value =bos_desc (cdev); value =min (w_length, (u16 ) value); }@@ -2013,6 +2050,44 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) goto check_value; } +/* +* webusb descriptor handling, following: +* https://wicg.github.io/webusb/#device-requests +*/ +if (cdev->use_webusb && + (ctrl->bRequestType &USB_TYPE_VENDOR ) && + ctrl->wIndex ==/* WEBUSB_GET_URL*/ 2 && + ctrl->bRequest == cdev->b_webusb_vendor_code) { +/* +* specification of the url descriptor in WebUSB: +* https://wicg.github.io/webusb/#webusb-descriptors Quoted 8 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2069
Quoted 6 lines
drivers/usb/gadget/composite.c +6
-0+*/ +u8 *buf; +unsigned int landing_page_length; + + buf = cdev->req->buf; + buf[1 ] =/* WEBUSB_URL*/ 3 ;Why not #define
WEBUSB_URL?
Quoted 4 lines
in a previous iteration, I had that exact #define in place, right above. However, another reviewer found it pointless. Maybe I should instead put the define into
include/uapi/linux/usb/ch9.h
Hmm. ch9.h had been called ch9.h for a reason. It corresponded to Chapter 9 of the USB spec. Adding to it something that by design is outside the spec might not be what we want. But I don't know.
Quoted 258 lines
Quoted 9 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2072
Quoted 4 lines
drivers/usb/gadget/composite.c +3
-0+ + landing_page_length =strnlen (cdev->landing_page,252 ); +if (strncasecmp ("https://" , cdev->landing_page,8 ) ==0 ) {Maybe it's me, but it would be easier for me to understand why the "8" if the comparison was in reverse order of arguments, like this:
strncasecmp(cdev->landing_page, "https://", 8)I agree, this makes the 8 clearer.
Quoted 3 lines
because we want the entirety of "https://" compared, not its substring, so the limit kind of applies to the
landing_pagein the first place. Maybe the "8" (and "7" below) can be #define'd, too?depends on the name, but maybe something like
#define
WEBUSB_PREFIX_HTTPS"https://"
#defineWEBUSB_PREFIX_HTTPS_LENGTH8
#defineWEBUSB_PREFIX_HTTPS_SCHEME_ID0x01would work defined with the struct in
include/uapi/linux/usb/ch9.hQuoted 4 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2073
Quoted 2 lines
drivers/usb/gadget/composite.c +1
-0+ buf[2 ] =0x01 ;What is this magic
0x01?The field is specified in
https://wicg.github.io/webusb/#url-descriptor and would be theWEBUSB_PREFIX_HTTPS_SCHEME_IDfrom above.
But yes, I should #define this.Quoted 4 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2074
Quoted 2 lines
drivers/usb/gadget/composite.c +1
-0+memcpy (buf+3 , cdev->landing_page+8 , landing_page_length-8 );spaces around arithmetic operators?
will do
Quoted 5 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2077
Quoted 3 lines
drivers/usb/gadget/composite.c +3
-0+ buf[0 ] = landing_page_length -8 +3 ; + }else if (strncasecmp ("http://" , cdev->landing_page,7 ) ==0 ) { + buf[2 ] =0x00 ;Magic
0x00?This would then be
WEBUSB_PREFIX_HTTP_SCHEME_IDQuoted 7 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2081
Quoted 5 lines
drivers/usb/gadget/composite.c +4
-0+memcpy (buf+3 , cdev->landing_page+7 , landing_page_length-7 ); + buf[0 ] = landing_page_length -7 +3 ; + }else { + buf[2 ] =0xFF ;Magic
0xFF? (plus I'd expect lowercase hex digits).This would then be
WEBUSB_PREFIX_NONE_SCHEME_IDQuoted 2 lines
There's "URL Prefixes" table in 4.3.1 URL Descriptor. Why not define URL_PREFIX_HTTP/HTTPS/NONE?
will do
Quoted 22 lines
Quoted 22 lines
drivers/usb/gadget/composite.c +9
-0+memcpy (buf+3 , cdev->landing_page, landing_page_length); + buf[0 ] = landing_page_length +3 ; + } + + value = buf[0 ]; + + goto check_value; + } + VDBG(cdev, "non-core control req%02x.%02x v%04x i%04x l%d\n", ctrl->bRequestType, ctrl->bRequest,drivers/usb/gadget/configfs.c +1
-0@@ -39,6 +39,7 @@ struct gadget_info {struct config_group configs_group;struct config_group strings_group;struct config_group os_desc_group; +struct config_group webusb_group;Quoted 12 lines
drivers/usb/gadget/configfs.c struct gadget_info { · line 57
Quoted 10 lines
drivers/usb/gadget/configfs.c +4
-0struct mutex lock;struct usb_gadget_strings *gstrings[MAX_USB_STRING_LANGS +1 ];@@ -50,6 +51,11 @@ struct gadget_info {bool use_os_desc;char b_vendor_code;char qw_sign[OS_STRING_QW_SIGN_LEN ]; +bool use_webusb; +u16 bcd_webusb_version; +u8 b_webusb_vendor_code; +char landing_page[255 ];A #define for the size?
will do
Quoted 141 lines
Quoted 141 lines
drivers/usb/gadget/configfs.c +126
-0+spinlock_t spinlock;bool unbind; };@@ -780,6 +786,131 @@ static void gadget_strings_attr_release(struct config_item *item)USB_CONFIG_STRING_RW_OPS (gadget_strings);USB_CONFIG_STRINGS_LANG (gadget_strings, gadget_info); +static inline struct gadget_info *webusb_item_to_gadget_info ( +struct config_item *item) +{ +return container_of (to_config_group (item), + struct gadget_info, webusb_group); +} + +static ssize_t webusb_use_show (struct config_item *item,char *page) +{ +return sysfs_emit (page,"%d\n" , +webusb_item_to_gadget_info (item)->use_webusb); +} + +static ssize_t webusb_use_store (struct config_item *item,const char *page, +size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +int ret; +bool use; + +mutex_lock (&gi->lock); + ret =kstrtobool (page, &use); +if (!ret) { + gi->use_webusb = use; + ret = len; + } +mutex_unlock (&gi->lock); + +return ret; +} + +static ssize_t webusb_bcdVersion_show (struct config_item *item,char *page) +{ +return sysfs_emit (page,"0x%04x\n" , +webusb_item_to_gadget_info (item)->bcd_webusb_version); +} + +static ssize_t webusb_bcdVersion_store (struct config_item *item, +const char *page,size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +u16 bcdVersion; +int ret; + +mutex_lock (&gi->lock); + ret =kstrtou16 (page,0 , &bcdVersion); +if (ret) + goto out; + ret =is_valid_bcd (bcdVersion); +if (ret) + goto out; + + gi->bcd_webusb_version = bcdVersion; + ret = len; + +out: +mutex_unlock (&gi->lock); + +return ret; +} + +static ssize_t webusb_bVendorCode_show (struct config_item *item,char *page) +{ +return sysfs_emit (page,"0x%02x\n" , +webusb_item_to_gadget_info (item)->b_webusb_vendor_code); +} + +static ssize_t webusb_bVendorCode_store (struct config_item *item, +const char *page,size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +int ret; +u8 b_vendor_code; + +mutex_lock (&gi->lock); + ret =kstrtou8 (page,0 , &b_vendor_code); +if (!ret) { + gi->b_webusb_vendor_code = b_vendor_code; + ret = len; + } +mutex_unlock (&gi->lock); + +return ret; +} + +static ssize_t webusb_landingPage_show (struct config_item *item,char *page) +{ +return sysfs_emit (page,"%s\n" ,webusb_item_to_gadget_info (item)->landing_page); +} + +static ssize_t webusb_landingPage_store (struct config_item *item,const char *page, +size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +int l; + + l =min (len,sizeof (gi->landing_page)); +if (page[l -1 ] =='\n' ) + --l; + +mutex_lock (&gi->lock); +memcpy (gi->landing_page, page, l); +mutex_unlock (&gi->lock); + +return len; +} + +CONFIGFS_ATTR (webusb_, use); +CONFIGFS_ATTR (webusb_, bVendorCode); +CONFIGFS_ATTR (webusb_, bcdVersion); +CONFIGFS_ATTR (webusb_, landingPage); + +static struct configfs_attribute *webusb_attrs[] = { + &webusb_attr_use, + &webusb_attr_bcdVersion, + &webusb_attr_bVendorCode, + &webusb_attr_landingPage, +NULL , +}; + +static struct config_item_type webusb_type = { + .ct_attrs = webusb_attrs, + .ct_owner =THIS_MODULE , +}; +static inline struct gadget_info *os_desc_item_to_gadget_info (struct config_item *item) {@@ -1341,6 +1472,16 @@ static int configfs_composite_bind(struct usb_gadget *gadget, gi->cdev.desc.iSerialNumber = s[USB_GADGET_SERIAL_IDX ].id; }Quoted 11 lines
drivers/usb/gadget/configfs.c static int configfs_composite_bind(struct usb_gadget *gadget, · line 1482
Quoted 8 lines
drivers/usb/gadget/configfs.c +8
-0+if (gi->use_webusb) { + cdev->use_webusb = true; + cdev->bcd_webusb_version = gi->bcd_webusb_version; + cdev->b_webusb_vendor_code = gi->b_webusb_vendor_code; +memcpy (cdev->landing_page, gi->landing_page, +strnlen (gi->landing_page, +min (sizeof (cdev->landing_page), +sizeof (gi->landing_page))));checkpatch now allows 100 colums. Plus
strnlen()looks indented too far to the right.I will check this.
Quoted 1 line
Quoted 8 lines
Quoted 3 lines
The sizeofs are both 255. Are they ever expected to be different? Maybe not? Then a #defined constant ensures they are equal. Then there's no need to find a minimum among equal values.
Technically, if the url has the empty scheme, it can only be 252 bytes long, since the maximum descriptor length is 255 because bLength is a single byte, but 3 bytes are in the header of this descriptor, leaving 252 for the string.
But you use sizeof() rather than strlen(). And the "landing_page" members are defined as 255-element arrays of chars, so both sizeof() invocations will yield 255, no?
Andrzej
Quoted 103 lines
However, if the landing page scheme is "https://", the maximum length of this string could actually be 255 - 3 /*header*/ + 8 /* the length of the prefix, which is stripped */ => 260 bytes.
I need to rework the validation here a bit. I would like to avoid for userspace to explicitly set the scheme constants directly, as just piping in the string seems so much more ergonomic.
Quoted 4 lines
Regards,
Andrzej
Thanks a lot for your review!
I hope my response to your initial concerns was not too long and windy.
I will post an updated version of my patch within the next few days.
Regards,
JóQuoted 79 lines
Quoted 78 lines
drivers/usb/gadget/configfs.c +6
-0+ } +if (gi->use_os_desc) { cdev->use_os_string = true; cdev->b_vendor_code = gi->b_vendor_code;@@ -1605,6 +1746,10 @@ static struct config_group *gadgets_make( &os_desc_type);configfs_add_default_group (&gi->os_desc_group, &gi->group); +config_group_init_type_name (&gi->webusb_group,"webusb" , + &webusb_type); +configfs_add_default_group (&gi->webusb_group, &gi->group); + gi->composite.bind = configfs_do_nothing; gi->composite.unbind = configfs_do_nothing; gi->composite.suspend =NULL ;include/linux/usb/composite.h +6
-0@@ -474,6 +474,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[255 ]; + unsigned int use_webusb:1; +/* private: */ /* internals */ unsigned int suspended:1;include/uapi/linux/usb/ch9.h +33
-0@@ -947,6 +947,39 @@ 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 ]; +} __attribute__((packed)); + +#define USB_DT_USB_PLAT_DEV_CAP_SIZE 20 + +/* +* WebUSB Platform Capability descriptor: A device announces support for the +* WebUSB command set by including the following Platform Descriptor in its +* Binary Object Store +* https://wicg.github.io/webusb/#webusb-platform-capability-descriptor +*/ +struct usb_webusb_cap_descriptor { +__u8 bLength; +__u8 bDescriptorType; +__u8 bDevCapabilityType; +__u8 bReserved; +__u8 UUID[16 ]; +__u16 bcdVersion; +__u8 bVendorCode; +__u8 iLandingPage; +} __attribute__((packed)); +#define USB_DT_WEBUSB_SIZE (USB_DT_USB_PLAT_DEV_CAP_SIZE + 4) +/* * SuperSpeed Plus USB Capability descriptor: Defines the set of * SuperSpeed Plus USB specific device level capabilities
Re: [PATCH v3] usb: gadget: add WebUSB landing page support
Quoted 8 lines · Andrzej Pietrasiewicz
Hi Jó,
W dniu 10.01.2023 o 00:19, Jó Ágila Bitsch pisze:
Quoted 4 lines
Quoted 3 lines
Quoted 1 line
+ buf[1] = /* WEBUSB_URL*/ 3;
Why not #define
WEBUSB_URL?
Quoted 8 lines
Quoted 4 lines
in a previous iteration, I had that exact #define in place, right above. However, another reviewer found it pointless. Maybe I should instead put the define into
include/uapi/linux/usb/ch9.hHmm.
ch9.hhad been calledch9.hfor a reason. It corresponded to Chapter 9 of the USB spec. Adding to it something that by design is outside the spec might not be what we want. But I don't know.
It wouldn't hurt to create a new file: include/uapi/linux/usb/webusb.h.
Alan Stern
PATCH v4 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
---
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 | 166 ++++++++++++++++++ include/linux/usb/composite.h | 7 + include/linux/usb/webusb.h | 83 +++++++++ include/uapi/linux/usb/ch9.h | 16 ++ 6 files changed, 377 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 +166 -0
202 lines not on this page · raw message
include/linux/usb/composite.h +7 -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>
@@ -474,6 +475,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 +83 -0
83 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
Re: [PATCH v3] usb: gadget: add WebUSB landing page support
In reply to Andrzej PietrasiewiczHi Andrzej,
Quoted 69 lines · Andrzej Pietrasiewicz
Hi Jó,
W dniu 10.01.2023 o 00:19, Jó Ágila Bitsch pisze:
Quoted 19 lines
Hi Andrzej,
Quoted 7 lines
Quoted 6 lines
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.
Quoted 7 lines
I envision an "evil" scenario, where you don't own your USB device any more. Instead you are required to pay a subscription to keep accessing it because its driver is somewhere on the net. I purposedly have put evil in quotes, because such a scenario might be considered preferred by some people. Maybe there are advantages, too, like not having to worry about correct drivers. Anyway, the kernel is about mechanism, not policy, so I'm probably in no position to judge such things.
Unfortunately, the "evil" devices you envision very much already exist.
Quoted 14 lines
When I was still working at university in the early 2010s, we were working with a mobile EEG headset (>1000USD) with a USB receiver dongle that would present itself as a USB HID device, but the transferred frames would be AES encrypted, with the key based on a proprietary transformation of the serial number of the device. At first the library that decoded it was available as a binary blob for a one-time payment, where you paid a hefty premium if you wanted access to the raw readings. Later the manufacturer changed their business model to subscription based, where the data had to flow through their cloud service - with a recurring license fee. I don't know what happened afterwards, as I left university.
This all was implemented based on libusb back then before people even thought of WebUSB.Thanks for honestly acknowledging their existence. It confirms that what I expressed was not a "conspiracy theory", but a "conspiracy practice" :D
Quoted 19 lines
I'm sure there are other examples.
So, "evil" devices are already real and don't depend on WebUSB. The motivating example "Web Drivers" from the specs
(https://wicg.github.io/webusb/#app-drivers) might potentially lead to companies asking for subscription fees for their Web Driver, but as long as there is no strong encryption in place, everyone would be free to write an alternative driver. The mechanisms would not at all preclude you from writing your own kernel or userspace driver using e.g. libusb. A kernel driver would block access from the browser though, as the browser cannot detach the kernel driver. (No such command is currently defined in WebUSB.) The JS implementation might even guide you to understand aspects of the protocol used.Citing from the motivating example in the design specs
(https://wicg.github.io/webusb/#app-updates-and-diagnostics):Quoted 1 line
The landing page provides a way for the device manufacturer to direct the user to the right part of their website for help with their device.
Quoted 7 lines
The landing page mechanism in WebUSB improves discoverability for devices, as Chrome and also lsusb directly point you to a webpage, where the manufacturer or firmware producer can give more information about the device. This webpage does not necessarily need to use a WebUSB JS driver itself to access the device, but might just as well point you to some git repository, where the hardware design and firmware source are available
Quoted 1 line
I'm wondering why e.g. Firefox does not implement this?
There has been an extended discussion within Firefox:
https://github.com/mozilla/standards-positions/issues/100
https://github.com/mozilla/standards-positions/pull/193
The main concerns center around (quoted from the link above):
Quoted 2 lines
* security issues related to attacks on devices that, once compromised, could be used to attack the user's computer more generally
* the permissions model (whether a question can be posed to the user that yields informed consent, whether there should be a CORS-like model for devices to say that they want to interact with particular domains which may improve security but hurts openness)
and tracking users across websites by exposing static identifiers
The webkit position is tracked here:
https://github.com/WebKit/standards-positions/issues/68
They are following Mozilla's position and also raising the issue of device-independence.
However, there has been some recent discussion to reevaluate this position, especially in the context of extensions and users are repeatedly bringing up complaints that they would like to see this implemented.
Quoted 5 lines
Chicken-and-egg
dilemma (no OS support at kernel level, so let's refrain from using it, but then there's too few users, so let's not add OS support - this circular depencency can be broken by applying your patch) or something else?
OS support at the kernel is not actually necessary for the host side of the USB connection at all, as the browser would just access the devices via the exposed character devices in /dev/bus/usb/*/*
My patch would only improve the device side of the USB connection, namely, that the landing page can be announced in gadget mode. So this would enable makers and manufacturers of USB gadgets based on embedded linux devices to point to a landing page for their device.
The other aspects of USB communication are already well supported by the USB gadget subsystem and don't need any changes to work with WebUSB. Actually, they are already working fine with WebUSB. An example with a Linux based gadget side is a WebAdb library
(https://webadb.github.io/), that allows Websites to access Android phones via a website.
I'm imagining the use case of single board computers, such as raspberry pi, orange pi, or other open hardware, such as a linux based USB stick such as https://github.com/usbarmory/usbarmory.
But it might just as well be your home router, that is connected via USB and points you to the configuration page directly. It knows its own IP address on the local network (and/or provide a USB network interface via RNDIS/ECM/NCM) and can dynamically point to the correct one. The last one could probably also work with some network based discovery mechanism but I want to open up the space a bit to things that just need the landing page and not the other parts of webusb.
Actually this would combine well with what you (Andrzej) presented back in 2019 on
https://www.collabora.com/news-and-blog/blog/2019/02/18/modern-usb-gadget-on-linux-and-how-to-integrate-it-with-systemd-part-1/
Quoted 205 lines
Quoted 205 lines
For what it's worth, the pick-up of WebUSB I've seen has been mostly in the maker scene with arduino, micro:bit and similar embedded devices, where devices provide at least two interfaces: One for the OS to claim and one for the Browser to claim.
Anyways, my biased opinion is that I would very much like a device to tell me where I can find support documentation, updates and help also when the device only implements standard interfaces that have kernel drivers. I don't think that this URL will lead to more devices you can only access with a subscription.
Quoted 1 line
Please see below.
Thanks for your excellent feedback. I answered inline.
Quoted 187 lines
Quoted 175 lines
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_capablecondition.Usage is modeled after
os_descdescriptors:
echo 1 > webusb/use
echo "https://www.kernel.org" > webusb/landingPagelsusb 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.orgSigned-off-by Jó Ágila Bitsch <[email protected]>---
v2 -> V3: improved commit message to include additional condition indesc_bosas 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: usesysfs_emitinstead of sprintf and use lock inwebusb_bcdVersion_store, addressed review
comments by Christophe JAILLETDocumentation/ABI/testing/configfs-usb-gadget | 13 ++ drivers/usb/gadget/composite.c | 95 ++++++++++-- drivers/usb/gadget/configfs.c | 145 ++++++++++++++++++ include/linux/usb/composite.h | 6 + include/uapi/linux/usb/ch9.h | 33 ++++ 5 files changed, 282 insertions(+), 10 deletions(-)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.2 +Description: + This group contains "WebUSB" extension handling attributes. + + ============= =============================================== + use flag turning "WebUSB" support on/off + bcdVersion bcd WebUSB specification version number + b_vendor_code one-byte value used for custom per-device + landing_page UTF-8 encoded URL of the device's landing page + ============= ===============================================drivers/usb/gadget/composite.c +54
-10@@ -14,6 +14,7 @@#include <linux/device.h> #include <linux/utsname.h> #include <linux/bitfield.h> +#include <linux/uuid.h> #include <linux/usb/composite.h> #include <linux/usb/otg.h> @@ -713,14 +714,16 @@ static int bos_desc(struct usb_composite_dev *cdev)* A SuperSpeed device shall include the USB2.0 extension descriptor * and shall support LPM when operating in USB2.0 HS mode. */ - usb_ext = cdev->req->buf +le16_to_cpu (bos->wTotalLength); - bos->bNumDeviceCaps++; -le16_add_cpu (&bos->wTotalLength,USB_DT_USB_EXT_CAP_SIZE ); - usb_ext->bLength =USB_DT_USB_EXT_CAP_SIZE ; - usb_ext->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; - usb_ext->bDevCapabilityType =USB_CAP_TYPE_EXT ; - usb_ext->bmAttributes =cpu_to_le32 (USB_LPM_SUPPORT | -USB_BESL_SUPPORT | besl); +if (cdev->gadget->lpm_capable) { + usb_ext = cdev->req->buf +le16_to_cpu (bos->wTotalLength); + bos->bNumDeviceCaps++; +le16_add_cpu (&bos->wTotalLength,USB_DT_USB_EXT_CAP_SIZE ); + usb_ext->bLength =USB_DT_USB_EXT_CAP_SIZE ; + usb_ext->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; + usb_ext->bDevCapabilityType =USB_CAP_TYPE_EXT ; + usb_ext->bmAttributes =cpu_to_le32 (USB_LPM_SUPPORT | +USB_BESL_SUPPORT | besl); + }/* * The Superspeed USB Capability descriptor shall be implemented by all @@ -821,6 +824,40 @@ static int bos_desc(struct usb_composite_dev *cdev) } } +/* +* Following the specifaction at: +* https://wicg.github.io/webusb/#webusb-platform-capability-descriptor +*/ +if (cdev->use_webusb) { +struct usb_webusb_cap_descriptor *webusb_cap; +/* +* little endian PlatformCapablityUUID for WebUSB: +* 3408b638-09a9-47a0-8bfd-a0768815b665 +*/ +uuid_t webusb_uuid =UUID_INIT (0x38b60834 ,0xa909 ,0xa047 ,0x8b ,0xfd ,0xa0 ,0x76 , +0x88 ,0x15 ,0xb6 ,0x65 ); + + webusb_cap = cdev->req->buf +le16_to_cpu (bos->wTotalLength); + bos->bNumDeviceCaps++; + +le16_add_cpu (&bos->wTotalLength,USB_DT_WEBUSB_SIZE ); + webusb_cap->bLength =USB_DT_WEBUSB_SIZE ; + webusb_cap->bDescriptorType =USB_DT_DEVICE_CAPABILITY ; + webusb_cap->bDevCapabilityType =USB_PLAT_DEV_CAP_TYPE ; + webusb_cap->bReserved =0 ; +export_uuid (webusb_cap->UUID, &webusb_uuid); +if (cdev->bcd_webusb_version !=0 ) + webusb_cap->bcdVersion =cpu_to_le16 (cdev->bcd_webusb_version); +else + webusb_cap->bcdVersion =cpu_to_le16 (0x0100 ); + + webusb_cap->bVendorCode = cdev->b_webusb_vendor_code; +if (strnlen (cdev->landing_page,sizeof (cdev->landing_page)) >0 ) + webusb_cap->iLandingPage =1 ; +else + webusb_cap->iLandingPage =0 ; + } +return le16_to_cpu (bos->wTotalLength); }@@ -1744,7 +1781,7 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) cdev->desc.bcdUSB =cpu_to_le16 (0x0210 ); } }else { -if (gadget->lpm_capable) +if (gadget->lpm_capable || cdev->use_webusb) cdev->desc.bcdUSB =cpu_to_le16 (0x0201 );else cdev->desc.bcdUSB =cpu_to_le16 (0x0200 );@@ -1779,7 +1816,7 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl)break ;case USB_DT_BOS :if (gadget_is_superspeed (gadget) || - gadget->lpm_capable) { + gadget->lpm_capable || cdev->use_webusb) { value =bos_desc (cdev); value =min (w_length, (u16 ) value); }@@ -2013,6 +2050,44 @@ composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) goto check_value; } +/* +* webusb descriptor handling, following: +* https://wicg.github.io/webusb/#device-requests +*/ + if (cdev->use_webusb && + (ctrl->bRequestType & USB_TYPE_VENDOR) && + ctrl->wIndex == /* WEBUSB_GET_URL*/ 2 &&drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2069
Quoted 10 lines
drivers/usb/gadget/composite.c +10
-0+ ctrl->bRequest == cdev->b_webusb_vendor_code) { +/* +* specification of the url descriptor in WebUSB: +* https://wicg.github.io/webusb/#webusb-descriptors +*/ +u8 *buf; +unsigned int landing_page_length; + + buf = cdev->req->buf; + buf[1 ] =/* WEBUSB_URL*/ 3 ;Why not #define
WEBUSB_URL?
Quoted 8 lines
Quoted 4 lines
in a previous iteration, I had that exact #define in place, right above. However, another reviewer found it pointless. Maybe I should instead put the define into
include/uapi/linux/usb/ch9.hHmm.
ch9.hhad been calledch9.hfor a reason. It corresponded to Chapter 9 of the USB spec. Adding to it something that by design is outside the spec might not be what we want. But I don't know.
Alan also agrees with you.
I will move it to a new header file: include/uapi/linux/usb/webusb.h.
Quoted 263 lines
Quoted 263 lines
Quoted 10 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2072
Quoted 5 lines
drivers/usb/gadget/composite.c +3
-0+ + landing_page_length =strnlen (cdev->landing_page,252 ); +if (strncasecmp ("https://" , cdev->landing_page,8 ) ==0 ) {Maybe it's me, but it would be easier for me to understand why the "8" if the comparison was in reverse order of arguments, like this:
strncasecmp(cdev->landing_page, "https://", 8)I agree, this makes the 8 clearer.
Quoted 3 lines
because we want the entirety of "https://" compared, not its substring, so the limit kind of applies to the
landing_pagein the first place. Maybe the "8" (and "7" below) can be #define'd, too?depends on the name, but maybe something like
#define
WEBUSB_PREFIX_HTTPS"https://"
#defineWEBUSB_PREFIX_HTTPS_LENGTH8
#defineWEBUSB_PREFIX_HTTPS_SCHEME_ID0x01would work defined with the struct in
include/uapi/linux/usb/ch9.hQuoted 4 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2073
Quoted 2 lines
drivers/usb/gadget/composite.c +1
-0+ buf[2 ] =0x01 ;What is this magic
0x01?The field is specified in
https://wicg.github.io/webusb/#url-descriptor and would be theWEBUSB_PREFIX_HTTPS_SCHEME_IDfrom above.
But yes, I should #define this.Quoted 4 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2074
Quoted 2 lines
drivers/usb/gadget/composite.c +1
-0+memcpy (buf+3 , cdev->landing_page+8 , landing_page_length-8 );spaces around arithmetic operators?
will do
Quoted 5 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2077
Quoted 3 lines
drivers/usb/gadget/composite.c +3
-0+ buf[0 ] = landing_page_length -8 +3 ; + }else if (strncasecmp ("http://" , cdev->landing_page,7 ) ==0 ) { + buf[2 ] =0x00 ;Magic
0x00?This would then be
WEBUSB_PREFIX_HTTP_SCHEME_IDQuoted 7 lines
drivers/usb/gadget/composite.c composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) · line 2081
Quoted 5 lines
drivers/usb/gadget/composite.c +4
-0+memcpy (buf+3 , cdev->landing_page+7 , landing_page_length-7 ); + buf[0 ] = landing_page_length -7 +3 ; + }else { + buf[2 ] =0xFF ;Magic
0xFF? (plus I'd expect lowercase hex digits).This would then be
WEBUSB_PREFIX_NONE_SCHEME_IDQuoted 2 lines
There's "URL Prefixes" table in 4.3.1 URL Descriptor. Why not define URL_PREFIX_HTTP/HTTPS/NONE?
will do
Quoted 22 lines
Quoted 22 lines
drivers/usb/gadget/composite.c +9
-0+memcpy (buf+3 , cdev->landing_page, landing_page_length); + buf[0 ] = landing_page_length +3 ; + } + + value = buf[0 ]; + + goto check_value; + } + VDBG(cdev, "non-core control req%02x.%02x v%04x i%04x l%d\n", ctrl->bRequestType, ctrl->bRequest,drivers/usb/gadget/configfs.c +1
-0@@ -39,6 +39,7 @@ struct gadget_info {struct config_group configs_group;struct config_group strings_group;struct config_group os_desc_group; +struct config_group webusb_group;Quoted 12 lines
drivers/usb/gadget/configfs.c struct gadget_info { · line 57
Quoted 10 lines
drivers/usb/gadget/configfs.c +4
-0struct mutex lock;struct usb_gadget_strings *gstrings[MAX_USB_STRING_LANGS +1 ];@@ -50,6 +51,11 @@ struct gadget_info {bool use_os_desc;char b_vendor_code;char qw_sign[OS_STRING_QW_SIGN_LEN ]; +bool use_webusb; +u16 bcd_webusb_version; +u8 b_webusb_vendor_code; +char landing_page[255 ];A #define for the size?
will do
Quoted 141 lines
Quoted 141 lines
drivers/usb/gadget/configfs.c +126
-0+spinlock_t spinlock;bool unbind; };@@ -780,6 +786,131 @@ static void gadget_strings_attr_release(struct config_item *item)USB_CONFIG_STRING_RW_OPS (gadget_strings);USB_CONFIG_STRINGS_LANG (gadget_strings, gadget_info); +static inline struct gadget_info *webusb_item_to_gadget_info ( +struct config_item *item) +{ +return container_of (to_config_group (item), + struct gadget_info, webusb_group); +} + +static ssize_t webusb_use_show (struct config_item *item,char *page) +{ +return sysfs_emit (page,"%d\n" , +webusb_item_to_gadget_info (item)->use_webusb); +} + +static ssize_t webusb_use_store (struct config_item *item,const char *page, +size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +int ret; +bool use; + +mutex_lock (&gi->lock); + ret =kstrtobool (page, &use); +if (!ret) { + gi->use_webusb = use; + ret = len; + } +mutex_unlock (&gi->lock); + +return ret; +} + +static ssize_t webusb_bcdVersion_show (struct config_item *item,char *page) +{ +return sysfs_emit (page,"0x%04x\n" , +webusb_item_to_gadget_info (item)->bcd_webusb_version); +} + +static ssize_t webusb_bcdVersion_store (struct config_item *item, +const char *page,size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +u16 bcdVersion; +int ret; + +mutex_lock (&gi->lock); + ret =kstrtou16 (page,0 , &bcdVersion); +if (ret) + goto out; + ret =is_valid_bcd (bcdVersion); +if (ret) + goto out; + + gi->bcd_webusb_version = bcdVersion; + ret = len; + +out: +mutex_unlock (&gi->lock); + +return ret; +} + +static ssize_t webusb_bVendorCode_show (struct config_item *item,char *page) +{ +return sysfs_emit (page,"0x%02x\n" , +webusb_item_to_gadget_info (item)->b_webusb_vendor_code); +} + +static ssize_t webusb_bVendorCode_store (struct config_item *item, +const char *page,size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +int ret; +u8 b_vendor_code; + +mutex_lock (&gi->lock); + ret =kstrtou8 (page,0 , &b_vendor_code); +if (!ret) { + gi->b_webusb_vendor_code = b_vendor_code; + ret = len; + } +mutex_unlock (&gi->lock); + +return ret; +} + +static ssize_t webusb_landingPage_show (struct config_item *item,char *page) +{ +return sysfs_emit (page,"%s\n" ,webusb_item_to_gadget_info (item)->landing_page); +} + +static ssize_t webusb_landingPage_store (struct config_item *item,const char *page, +size_t len) +{ +struct gadget_info *gi =webusb_item_to_gadget_info (item); +int l; + + l =min (len,sizeof (gi->landing_page)); +if (page[l -1 ] =='\n' ) + --l; + +mutex_lock (&gi->lock); +memcpy (gi->landing_page, page, l); +mutex_unlock (&gi->lock); + +return len; +} + +CONFIGFS_ATTR (webusb_, use); +CONFIGFS_ATTR (webusb_, bVendorCode); +CONFIGFS_ATTR (webusb_, bcdVersion); +CONFIGFS_ATTR (webusb_, landingPage); + +static struct configfs_attribute *webusb_attrs[] = { + &webusb_attr_use, + &webusb_attr_bcdVersion, + &webusb_attr_bVendorCode, + &webusb_attr_landingPage, +NULL , +}; + +static struct config_item_type webusb_type = { + .ct_attrs = webusb_attrs, + .ct_owner =THIS_MODULE , +}; +static inline struct gadget_info *os_desc_item_to_gadget_info (struct config_item *item) {@@ -1341,6 +1472,16 @@ static int configfs_composite_bind(struct usb_gadget *gadget, gi->cdev.desc.iSerialNumber = s[USB_GADGET_SERIAL_IDX ].id; }Quoted 11 lines
drivers/usb/gadget/configfs.c static int configfs_composite_bind(struct usb_gadget *gadget, · line 1482
Quoted 8 lines
drivers/usb/gadget/configfs.c +8
-0+if (gi->use_webusb) { + cdev->use_webusb = true; + cdev->bcd_webusb_version = gi->bcd_webusb_version; + cdev->b_webusb_vendor_code = gi->b_webusb_vendor_code; +memcpy (cdev->landing_page, gi->landing_page, +strnlen (gi->landing_page, +min (sizeof (cdev->landing_page), +sizeof (gi->landing_page))));checkpatch now allows 100 colums. Plus
strnlen()looks indented too far to the right.I will check this.
Quoted 4 lines
The sizeofs are both 255. Are they ever expected to be different? Maybe not? Then a #defined constant ensures they are equal. Then there's no need to find a minimum among equal values.
Quoted 8 lines
Quoted 4 lines
Technically, if the url has the empty scheme, it can only be 252 bytes long, since the maximum descriptor length is 255 because bLength is a single byte, but 3 bytes are in the header of this descriptor, leaving 252 for the string.
But you use
sizeof()rather thanstrlen(). And the "landing_page" members are defined as 255-element arrays of chars, so bothsizeof()invocations will yield 255, no?
You are correct. I was just thinking of the exact length limitations when you wrote your comment. Before that I hadn't really considered the different lengths based on the scheme, so this version of the patch does not yet make this distinction.
Thanks for your patience with a first-time contributor.
Regards,
Jó
Quoted 107 lines
Andrzej
Quoted 103 lines
However, if the landing page scheme is "https://", the maximum length of this string could actually be 255 - 3 /*header*/ + 8 /* the length of the prefix, which is stripped */ => 260 bytes.
I need to rework the validation here a bit. I would like to avoid for userspace to explicitly set the scheme constants directly, as just piping in the string seems so much more ergonomic.
Quoted 4 lines
Regards,
Andrzej
Thanks a lot for your review!
I hope my response to your initial concerns was not too long and windy.
I will post an updated version of my patch within the next few days.
Regards,
JóQuoted 79 lines
Quoted 78 lines
drivers/usb/gadget/configfs.c +6
-0+ } +if (gi->use_os_desc) { cdev->use_os_string = true; cdev->b_vendor_code = gi->b_vendor_code;@@ -1605,6 +1746,10 @@ static struct config_group *gadgets_make( &os_desc_type);configfs_add_default_group (&gi->os_desc_group, &gi->group); +config_group_init_type_name (&gi->webusb_group,"webusb" , + &webusb_type); +configfs_add_default_group (&gi->webusb_group, &gi->group); + gi->composite.bind = configfs_do_nothing; gi->composite.unbind = configfs_do_nothing; gi->composite.suspend =NULL ;include/linux/usb/composite.h +6
-0@@ -474,6 +474,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[255 ]; + unsigned int use_webusb:1; +/* private: */ /* internals */ unsigned int suspended:1;include/uapi/linux/usb/ch9.h +33
-0@@ -947,6 +947,39 @@ 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 ]; +} __attribute__((packed)); + +#define USB_DT_USB_PLAT_DEV_CAP_SIZE 20 + +/* +* WebUSB Platform Capability descriptor: A device announces support for the +* WebUSB command set by including the following Platform Descriptor in its +* Binary Object Store +* https://wicg.github.io/webusb/#webusb-platform-capability-descriptor +*/ +struct usb_webusb_cap_descriptor { +__u8 bLength; +__u8 bDescriptorType; +__u8 bDevCapabilityType; +__u8 bReserved; +__u8 UUID[16 ]; +__u16 bcdVersion; +__u8 bVendorCode; +__u8 iLandingPage; +} __attribute__((packed)); +#define USB_DT_WEBUSB_SIZE (USB_DT_USB_PLAT_DEV_CAP_SIZE + 4) +/* * SuperSpeed Plus USB Capability descriptor: Defines the set of * SuperSpeed Plus USB specific device level capabilities
PATCH v2 1/1 usb: gadget: add WebUSB support
In reply to Alan SternThere 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.
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
--- Documentation/ABI/testing/configfs-usb-gadget | 13 ++ drivers/usb/gadget/composite.c | 96 ++++++++++-- drivers/usb/gadget/configfs.c | 145 ++++++++++++++++++ include/linux/usb/composite.h | 6 + include/uapi/linux/usb/ch9.h | 33 ++++ 5 files changed, 283 insertions(+), 10 deletions(-)
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.2 +Description: + This group contains "WebUSB" extension handling attributes. + + ============= =============================================== + use flag turning "WebUSB" support on/off + bcdVersion bcd WebUSB specification version number + b_vendor_code one-byte value used for custom per-device + landing_page UTF-8 encoded URL of the device's landing page + ============= ===============================================
drivers/usb/gadget/composite.c +86 -10
132 lines not on this page · raw message
drivers/usb/gadget/configfs.c +145 -0
175 lines not on this page · raw message
include/linux/usb/composite.h +6 -0
@@ -474,6 +474,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[255 ]; + unsigned int use_webusb:1; +/* private: */ /* internals */ unsigned int suspended:1;
include/uapi/linux/usb/ch9.h +33 -0
@@ -947,6 +947,39 @@ 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 ]; +} __attribute__((packed)); + +#define USB_DT_USB_PLAT_DEV_CAP_SIZE 20 + +/* +* WebUSB Platform Capability descriptor: A device announces support for the +* WebUSB command set by including the following Platform Descriptor in its +* Binary Object Store +* https://wicg.github.io/webusb/#webusb-platform-capability-descriptor +*/ +struct usb_webusb_cap_descriptor { +__u8 bLength; +__u8 bDescriptorType; +__u8 bDevCapabilityType; +__u8 bReserved; +__u8 UUID[16 ]; +__u16 bcdVersion; +__u8 bVendorCode; +__u8 iLandingPage; +} __attribute__((packed)); +#define USB_DT_WEBUSB_SIZE (USB_DT_USB_PLAT_DEV_CAP_SIZE + 4) +/* * SuperSpeed Plus USB Capability descriptor: Defines the set of * SuperSpeed Plus USB specific device level capabilities
Signature · 1 line
2.37.2
Greg KH
maintainerQuoted 40 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.
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.
Usage is modeled after
os_descdescriptors:
echo 1 > webusb/use
echo "https://www.kernel.org" > webusb/landingPagelsusb 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
Quoted 9 lines
Signed-off-by Jó Ágila Bitsch <[email protected]>--- Documentation/ABI/testing/configfs-usb-gadget | 13 ++ drivers/usb/gadget/composite.c | 96 ++++++++++-- drivers/usb/gadget/configfs.c | 145 ++++++++++++++++++ include/linux/usb/composite.h | 6 + include/uapi/linux/usb/ch9.h | 33 ++++ 5 files changed, 283 insertions(+), 10 deletions(-)
Hi,
This is the friendly patch-bot of Greg Kroah-Hartman. You have sent him a patch that has triggered this response. He used to manually respond to these common problems, but in order to save his sanity (he kept writing the same thing over and over, yet to different people), I was created. Hopefully you will not take offence and will fix the problem in your patch and resubmit it so that it can be accepted into the Linux kernel tree.
You are receiving this message because of the following common error(s) as indicated below:
- This looks like a new version of a previously submitted patch, but you did not list below the --- line any changes from the previous version. Please read the section entitled "The canonical patch format" in the kernel file, Documentation/process/submitting-patches.rst for what needs to be done here to properly describe this.
If you wish to discuss this problem further, or you have questions about how to resolve this issue, please feel free to respond to this email and Greg will reply once he has dug out from the pending patches received from other developers.
thanks,
greg k-h's patch email bot