Line data    Source code

       1            1 : /*
       2              :  * Copyright (c) 2018 Intel Corporation
       3              :  * Copyright (c) 2023 Nordic Semiconductor ASA
       4              :  *
       5              :  * SPDX-License-Identifier: Apache-2.0
       6              :  */
       7              : 
       8              : /**
       9              :  * @file
      10              :  * @brief USB Binary Device Object Store support
      11              :  * @ingroup usb_bos
      12              :  */
      13              : 
      14              : #ifndef ZEPHYR_INCLUDE_USB_BOS_H_
      15              : #define ZEPHYR_INCLUDE_USB_BOS_H_
      16              : 
      17              : #include <stdint.h>
      18              : 
      19              : /**
      20              :  * @brief USB Binary Device Object Store support
      21              :  * @defgroup usb_bos USB BOS support
      22              :  * @ingroup usb
      23              :  * @since 1.13
      24              :  * @version 1.0.0
      25              :  * @{
      26              :  */
      27              : 
      28              : /** Root BOS Descriptor */
      29            1 : struct usb_bos_descriptor {
      30              :         /** Size of this descriptor in bytes (5). */
      31            1 :         uint8_t bLength;
      32              :         /** Descriptor type. Must be set to @ref USB_DESC_BOS. */
      33            1 :         uint8_t bDescriptorType;
      34              :         /**
      35              :          * Total length of this descriptor and all associated device
      36              :          * capability descriptors.
      37              :          */
      38            1 :         uint16_t wTotalLength;
      39              :         /** Number of device capability descriptors that follow. */
      40            1 :         uint8_t bNumDeviceCaps;
      41              : } __packed;
      42              : 
      43              : /** Device capability type codes */
      44            1 : enum usb_bos_capability_types {
      45              :         /** USB 2.0 Extension capability. */
      46              :         USB_BOS_CAPABILITY_EXTENSION = 0x02,
      47              :         /** Platform-specific capability (e.g., WebUSB, MS OS). */
      48              :         USB_BOS_CAPABILITY_PLATFORM = 0x05,
      49              : };
      50              : 
      51              : /**
      52              :  * BOS USB 2.0 extension capability descriptor
      53              :  *
      54              :  * Used to indicate support for USB 2.0 Link Power Management (LPM) and associated best effort
      55              :  * service latency (BESL) parameters.
      56              :  */
      57            1 : struct usb_bos_capability_lpm {
      58              :         /** Size of this descriptor in bytes. */
      59            1 :         uint8_t bLength;
      60              : 
      61              :         /** Descriptor type. Must be set to @ref USB_DESC_DEVICE_CAPABILITY. */
      62            1 :         uint8_t bDescriptorType;
      63              : 
      64              :         /** Device capability type. Must be @ref USB_BOS_CAPABILITY_EXTENSION. */
      65            1 :         uint8_t bDevCapabilityType;
      66              : 
      67              :         /**
      68              :          * Bitmap of supported attributes.
      69              :          */
      70            1 :         uint32_t bmAttributes;
      71              : } __packed;
      72              : 
      73              : /**
      74              :  * BOS platform capability descriptor
      75              :  *
      76              :  * Used to describe platform-specific capabilities, identified by a UUID.
      77              :  */
      78            1 : struct usb_bos_platform_descriptor {
      79              :         /** Size of this descriptor in bytes (20). */
      80            1 :         uint8_t bLength;
      81              :         /** Descriptor type. Must be set to @c USB_DESC_DEVICE_CAPABILITY. */
      82            1 :         uint8_t bDescriptorType;
      83              :         /** Device capability type. Must be @c USB_BOS_CAPABILITY_PLATFORM. */
      84            1 :         uint8_t bDevCapabilityType;
      85              :         /** Reserved (must be zero). */
      86            1 :         uint8_t bReserved;
      87              :         /** Platform capability UUID (16 bytes, little-endian). */
      88            1 :         uint8_t PlatformCapabilityUUID[16];
      89              : } __packed;
      90              : 
      91              : /**
      92              :  * WebUSB specific part of platform capability descriptor
      93              :  *
      94              :  * Defines the WebUSB-specific fields that extend the generic platform capability descriptor.
      95              :  */
      96            1 : struct usb_bos_capability_webusb {
      97              :         /** WebUSB specification version in BCD format (e.g., 0x0100). */
      98            1 :         uint16_t bcdVersion;
      99              :         /**
     100              :          * Vendor-specific request code used by the host to retrieve WebUSB descriptors.
     101              :          */
     102            1 :         uint8_t bVendorCode;
     103              : 
     104              :         /**
     105              :          * Index of the landing page string descriptor.
     106              :          * Zero means no landing page is defined.
     107              :          */
     108            1 :         uint8_t iLandingPage;
     109              : } __packed;
     110              : 
     111              : /**
     112              :  * Microsoft OS 2.0 descriptor specific part of platform capability descriptor
     113              :  *
     114              :  * Defines the Microsoft OS 2.0 descriptor set, used to describe device capabilities to Windows
     115              :  * hosts.
     116              :  */
     117            1 : struct usb_bos_capability_msos {
     118              :         /** Windows version supported (e.g., 0x0A000000UL for Windows 10). */
     119            1 :         uint32_t dwWindowsVersion;
     120              :         /** Total length of the MS OS 2.0 descriptor set. */
     121            1 :         uint16_t wMSOSDescriptorSetTotalLength;
     122              :         /**
     123              :          * Vendor-specific request code used to retrieve the MS OS 2.0 descriptor set.
     124              :          */
     125            1 :         uint8_t bMS_VendorCode;
     126              :         /** Alternate enumeration code (or 0 if not used). */
     127            1 :         uint8_t bAltEnumCode;
     128              : } __packed;
     129              : 
     130              : /**
     131              :  * @}
     132              :  */
     133              : 
     134              : #endif  /* ZEPHYR_INCLUDE_USB_BOS_H_ */