From ca5e3502eda5af526ab8e0849518fc3ed1867902 Mon Sep 17 00:00:00 2001 From: Johann Fischer Date: Thu, 6 Jul 2023 15:14:36 +0200 Subject: [PATCH 1/2] include: usb: revise BOS support header Hide parts that are not relevant to the application and are only used internally by the stack. Add minimal documentation. Signed-off-by: Johann Fischer --- include/zephyr/usb/bos.h | 79 ++++++++++++++++++++++++++++++---------- 1 file changed, 60 insertions(+), 19 deletions(-) diff --git a/include/zephyr/usb/bos.h b/include/zephyr/usb/bos.h index f61b30a8cc96e2..b7a0ef08339fe3 100644 --- a/include/zephyr/usb/bos.h +++ b/include/zephyr/usb/bos.h @@ -1,5 +1,6 @@ /* * Copyright (c) 2018 Intel Corporation + * Copyright (c) 2023 Nordic Semiconductor ASA * * SPDX-License-Identifier: Apache-2.0 */ @@ -7,40 +8,53 @@ #ifndef ZEPHYR_INCLUDE_USB_BOS_H_ #define ZEPHYR_INCLUDE_USB_BOS_H_ -#if defined(CONFIG_USB_DEVICE_BOS) -#define USB_DEVICE_BOS_DESC_DEFINE_HDR \ - static __in_section(usb, bos_desc_area, 0) __aligned(1) __used +#include + +/** + * @brief USB Binary Device Object Store support + * @defgroup usb_bos USB BOS support + * @ingroup usb + * @{ + */ + +/** + * @brief Helper macro to place the BOS compatibility descriptor + * in the right memory section. + */ #define USB_DEVICE_BOS_DESC_DEFINE_CAP \ static __in_section(usb, bos_desc_area, 1) __aligned(1) __used -#define USB_BOS_CAPABILITY_EXTENSION 0x02 -#define USB_BOS_CAPABILITY_PLATFORM 0x05 +/** Device capability type codes */ +enum usb_bos_capability_types { + USB_BOS_CAPABILITY_EXTENSION = 0x02, + USB_BOS_CAPABILITY_PLATFORM = 0x05, +}; -/* BOS Capability Descriptor */ -struct usb_bos_platform_descriptor { +/** BOS USB 2.0 extension capability descriptor */ +struct usb_bos_capability_lpm { uint8_t bLength; uint8_t bDescriptorType; uint8_t bDevCapabilityType; - uint8_t bReserved; - uint8_t PlatformCapabilityUUID[16]; + uint32_t bmAttributes; } __packed; -/* BOS Descriptor */ -struct usb_bos_descriptor { +/** BOS platform capability descriptor */ +struct usb_bos_platform_descriptor { uint8_t bLength; uint8_t bDescriptorType; - uint16_t wTotalLength; - uint8_t bNumDeviceCaps; + uint8_t bDevCapabilityType; + uint8_t bReserved; + uint8_t PlatformCapabilityUUID[16]; } __packed; -/* BOS Capability webusb */ +/** WebUSB specific part of platform capability descriptor */ struct usb_bos_capability_webusb { uint16_t bcdVersion; uint8_t bVendorCode; uint8_t iLandingPage; } __packed; -/* BOS Capability MS OS Descriptors version 2 */ +/** Microsoft OS 2.0 descriptor specific part of platform capability descriptor */ struct usb_bos_capability_msos { uint32_t dwWindowsVersion; uint16_t wMSOSDescriptorSetTotalLength; @@ -48,20 +62,47 @@ struct usb_bos_capability_msos { uint8_t bAltEnumCode; } __packed; -struct usb_bos_capability_lpm { +/** + * @brief Register BOS capability descriptor + * + * This function should be used by the application to register BOS capability + * descriptors before the USB device stack is enabled. + * + * @param[in] hdr Pointer to BOS capability descriptor + */ +void usb_bos_register_cap(struct usb_bos_platform_descriptor *hdr); + +/** + * @cond INTERNAL_HIDDEN + * Internally used functions + */ + +/* BOS Descriptor (root descriptor) */ +struct usb_bos_descriptor { uint8_t bLength; uint8_t bDescriptorType; - uint8_t bDevCapabilityType; - uint32_t bmAttributes; + uint16_t wTotalLength; + uint8_t bNumDeviceCaps; } __packed; +#define USB_DEVICE_BOS_DESC_DEFINE_HDR \ + static __in_section(usb, bos_desc_area, 0) __aligned(1) __used + size_t usb_bos_get_length(void); + void usb_bos_fix_total_length(void); -void usb_bos_register_cap(struct usb_bos_platform_descriptor *hdr); + const void *usb_bos_get_header(void); + +#if defined(CONFIG_USB_DEVICE_BOS) int usb_handle_bos(struct usb_setup_packet *setup, int32_t *len, uint8_t **data); #else #define usb_handle_bos(x, y, z) -ENOTSUP #endif +/** @endcond */ + +/** + * @} + */ #endif /* ZEPHYR_INCLUDE_USB_BOS_H_ */ From b9ea6caaf5363787a1c72f129e41d7710ef4a6af Mon Sep 17 00:00:00 2001 From: Johann Fischer Date: Thu, 6 Jul 2023 15:18:06 +0200 Subject: [PATCH 2/2] doc: usb: add reference to BOS support API Add a reference to the BOS support API. Signed-off-by: Johann Fischer --- doc/connectivity/usb/device/api/index.rst | 1 + doc/connectivity/usb/device/api/usb_device_bos.rst | 9 +++++++++ 2 files changed, 10 insertions(+) create mode 100644 doc/connectivity/usb/device/api/usb_device_bos.rst diff --git a/doc/connectivity/usb/device/api/index.rst b/doc/connectivity/usb/device/api/index.rst index ddc06aa4768613..02bf793805e342 100644 --- a/doc/connectivity/usb/device/api/index.rst +++ b/doc/connectivity/usb/device/api/index.rst @@ -9,3 +9,4 @@ USB device support APIs usb_dc.rst usb_device.rst usb_device_hid.rst + usb_device_bos.rst diff --git a/doc/connectivity/usb/device/api/usb_device_bos.rst b/doc/connectivity/usb/device/api/usb_device_bos.rst new file mode 100644 index 00000000000000..a4031879646728 --- /dev/null +++ b/doc/connectivity/usb/device/api/usb_device_bos.rst @@ -0,0 +1,9 @@ +.. _usb_bos_api: + +Binary Device Object Store (BOS) support API +############################################ + +API reference +************* + +.. doxygengroup:: usb_bos