1 /* 2 * Copyright (c) 2020 PHYTEC Messtechnik GmbH 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 /** 8 * @file 9 * @brief USB Chapter 9 structures and definitions 10 * 11 * This file contains the USB Chapter 9 structures definitions 12 * and follows, with few exceptions, the USB Specification 2.0. 13 */ 14 15 #include <version.h> 16 #include <zephyr/sys/util.h> 17 #include <zephyr/usb/class/usb_hub.h> 18 19 #ifndef ZEPHYR_INCLUDE_USB_CH9_H_ 20 #define ZEPHYR_INCLUDE_USB_CH9_H_ 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 struct usb_req_type_field { 27 #ifdef CONFIG_LITTLE_ENDIAN 28 uint8_t recipient : 5; 29 uint8_t type : 2; 30 uint8_t direction : 1; 31 #else 32 uint8_t direction : 1; 33 uint8_t type : 2; 34 uint8_t recipient : 5; 35 #endif 36 } __packed; 37 38 /** USB Setup Data packet defined in spec. Table 9-2 */ 39 struct usb_setup_packet { 40 union { 41 uint8_t bmRequestType; 42 struct usb_req_type_field RequestType; 43 }; 44 uint8_t bRequest; 45 uint16_t wValue; 46 uint16_t wIndex; 47 uint16_t wLength; 48 }; 49 50 /** USB Setup packet RequestType Direction values (from Table 9-2) */ 51 #define USB_REQTYPE_DIR_TO_DEVICE 0 52 #define USB_REQTYPE_DIR_TO_HOST 1 53 54 /** USB Setup packet RequestType Type values (from Table 9-2) */ 55 #define USB_REQTYPE_TYPE_STANDARD 0 56 #define USB_REQTYPE_TYPE_CLASS 1 57 #define USB_REQTYPE_TYPE_VENDOR 2 58 #define USB_REQTYPE_TYPE_RESERVED 3 59 60 /** USB Setup packet RequestType Recipient values (from Table 9-2) */ 61 #define USB_REQTYPE_RECIPIENT_DEVICE 0 62 #define USB_REQTYPE_RECIPIENT_INTERFACE 1 63 #define USB_REQTYPE_RECIPIENT_ENDPOINT 2 64 #define USB_REQTYPE_RECIPIENT_OTHER 3 65 66 /** Get data transfer direction from bmRequestType */ 67 #define USB_REQTYPE_GET_DIR(bmRequestType) (((bmRequestType) >> 7) & 0x01U) 68 /** Get request type from bmRequestType */ 69 #define USB_REQTYPE_GET_TYPE(bmRequestType) (((bmRequestType) >> 5) & 0x03U) 70 /** Get request recipient from bmRequestType */ 71 #define USB_REQTYPE_GET_RECIPIENT(bmRequestType) ((bmRequestType) & 0x1FU) 72 73 /** 74 * @brief Check if request transfer direction is to host. 75 * 76 * @param setup Pointer to USB Setup packet 77 * @return true If transfer direction is to host 78 */ usb_reqtype_is_to_host(const struct usb_setup_packet * setup)79static inline bool usb_reqtype_is_to_host(const struct usb_setup_packet *setup) 80 { 81 return setup->RequestType.direction == USB_REQTYPE_DIR_TO_HOST; 82 } 83 84 /** 85 * @brief Check if request transfer direction is to device. 86 * 87 * @param setup Pointer to USB Setup packet 88 * @return true If transfer direction is to device 89 */ usb_reqtype_is_to_device(const struct usb_setup_packet * setup)90static inline bool usb_reqtype_is_to_device(const struct usb_setup_packet *setup) 91 { 92 return setup->RequestType.direction == USB_REQTYPE_DIR_TO_DEVICE; 93 } 94 95 /** USB Standard Request Codes defined in spec. Table 9-4 */ 96 #define USB_SREQ_GET_STATUS 0x00 97 #define USB_SREQ_CLEAR_FEATURE 0x01 98 #define USB_SREQ_SET_FEATURE 0x03 99 #define USB_SREQ_SET_ADDRESS 0x05 100 #define USB_SREQ_GET_DESCRIPTOR 0x06 101 #define USB_SREQ_SET_DESCRIPTOR 0x07 102 #define USB_SREQ_GET_CONFIGURATION 0x08 103 #define USB_SREQ_SET_CONFIGURATION 0x09 104 #define USB_SREQ_GET_INTERFACE 0x0A 105 #define USB_SREQ_SET_INTERFACE 0x0B 106 #define USB_SREQ_SYNCH_FRAME 0x0C 107 108 /** Descriptor Types defined in spec. Table 9-5 */ 109 #define USB_DESC_DEVICE 1 110 #define USB_DESC_CONFIGURATION 2 111 #define USB_DESC_STRING 3 112 #define USB_DESC_INTERFACE 4 113 #define USB_DESC_ENDPOINT 5 114 #define USB_DESC_DEVICE_QUALIFIER 6 115 #define USB_DESC_OTHER_SPEED 7 116 #define USB_DESC_INTERFACE_POWER 8 117 /** Additional Descriptor Types defined in USB 3 spec. Table 9-5 */ 118 #define USB_DESC_OTG 9 119 #define USB_DESC_DEBUG 10 120 #define USB_DESC_INTERFACE_ASSOC 11 121 #define USB_DESC_BOS 15 122 #define USB_DESC_DEVICE_CAPABILITY 16 123 124 /** Class-Specific Descriptor Types as defined by 125 * USB Common Class Specification 126 */ 127 #define USB_DESC_CS_DEVICE 0x21 128 #define USB_DESC_CS_CONFIGURATION 0x22 129 #define USB_DESC_CS_STRING 0x23 130 #define USB_DESC_CS_INTERFACE 0x24 131 #define USB_DESC_CS_ENDPOINT 0x25 132 133 /** USB Standard Feature Selectors defined in spec. Table 9-6 */ 134 #define USB_SFS_ENDPOINT_HALT 0x00 135 #define USB_SFS_REMOTE_WAKEUP 0x01 136 #define USB_SFS_TEST_MODE 0x02 137 138 /** Bits used for GetStatus response defined in spec. Figure 9-4 */ 139 #define USB_GET_STATUS_SELF_POWERED BIT(0) 140 #define USB_GET_STATUS_REMOTE_WAKEUP BIT(1) 141 142 /** Header of an USB descriptor */ 143 struct usb_desc_header { 144 uint8_t bLength; 145 uint8_t bDescriptorType; 146 } __packed; 147 148 /** USB Standard Device Descriptor defined in spec. Table 9-8 */ 149 struct usb_device_descriptor { 150 uint8_t bLength; 151 uint8_t bDescriptorType; 152 uint16_t bcdUSB; 153 uint8_t bDeviceClass; 154 uint8_t bDeviceSubClass; 155 uint8_t bDeviceProtocol; 156 uint8_t bMaxPacketSize0; 157 uint16_t idVendor; 158 uint16_t idProduct; 159 uint16_t bcdDevice; 160 uint8_t iManufacturer; 161 uint8_t iProduct; 162 uint8_t iSerialNumber; 163 uint8_t bNumConfigurations; 164 } __packed; 165 166 /** USB Standard Configuration Descriptor defined in spec. Table 9-10 */ 167 struct usb_cfg_descriptor { 168 uint8_t bLength; 169 uint8_t bDescriptorType; 170 uint16_t wTotalLength; 171 uint8_t bNumInterfaces; 172 uint8_t bConfigurationValue; 173 uint8_t iConfiguration; 174 uint8_t bmAttributes; 175 uint8_t bMaxPower; 176 } __packed; 177 178 /** USB Standard Interface Descriptor defined in spec. Table 9-12 */ 179 struct usb_if_descriptor { 180 uint8_t bLength; 181 uint8_t bDescriptorType; 182 uint8_t bInterfaceNumber; 183 uint8_t bAlternateSetting; 184 uint8_t bNumEndpoints; 185 uint8_t bInterfaceClass; 186 uint8_t bInterfaceSubClass; 187 uint8_t bInterfaceProtocol; 188 uint8_t iInterface; 189 } __packed; 190 191 struct usb_ep_desc_bmattr { 192 #ifdef CONFIG_LITTLE_ENDIAN 193 uint8_t transfer : 2; 194 uint8_t synch: 2; 195 uint8_t usage: 2; 196 uint8_t reserved: 2; 197 #else 198 uint8_t reserved: 2; 199 uint8_t usage : 2; 200 uint8_t synch : 2; 201 uint8_t transfer : 2; 202 #endif 203 } __packed; 204 205 /** USB Standard Endpoint Descriptor defined in spec. Table 9-13 */ 206 struct usb_ep_descriptor { 207 uint8_t bLength; 208 uint8_t bDescriptorType; 209 uint8_t bEndpointAddress; 210 union { 211 uint8_t bmAttributes; 212 struct usb_ep_desc_bmattr Attributes; 213 }; 214 uint16_t wMaxPacketSize; 215 uint8_t bInterval; 216 } __packed; 217 218 /** USB Unicode (UTF16LE) String Descriptor defined in spec. Table 9-15 */ 219 struct usb_string_descriptor { 220 uint8_t bLength; 221 uint8_t bDescriptorType; 222 uint16_t bString; 223 } __packed; 224 225 /** USB Association Descriptor defined in USB 3 spec. Table 9-16 */ 226 struct usb_association_descriptor { 227 uint8_t bLength; 228 uint8_t bDescriptorType; 229 uint8_t bFirstInterface; 230 uint8_t bInterfaceCount; 231 uint8_t bFunctionClass; 232 uint8_t bFunctionSubClass; 233 uint8_t bFunctionProtocol; 234 uint8_t iFunction; 235 } __packed; 236 237 /** USB Standard Configuration Descriptor Characteristics from Table 9-10 */ 238 #define USB_SCD_RESERVED BIT(7) 239 #define USB_SCD_SELF_POWERED BIT(6) 240 #define USB_SCD_REMOTE_WAKEUP BIT(5) 241 242 /** USB Defined Base Class Codes from https://www.usb.org/defined-class-codes */ 243 #define USB_BCC_AUDIO 0x01 244 #define USB_BCC_CDC_CONTROL 0x02 245 #define USB_BCC_HID 0x03 246 #define USB_BCC_MASS_STORAGE 0x08 247 #define USB_BCC_CDC_DATA 0x0A 248 #define USB_BCC_VIDEO 0x0E 249 #define USB_BCC_WIRELESS_CONTROLLER 0xE0 250 #define USB_BCC_MISCELLANEOUS 0xEF 251 #define USB_BCC_APPLICATION 0xFE 252 #define USB_BCC_VENDOR 0xFF 253 254 /** USB Specification Release Numbers (bcdUSB Descriptor field) */ 255 #define USB_SRN_1_1 0x0110 256 #define USB_SRN_2_0 0x0200 257 #define USB_SRN_2_1 0x0210 258 259 #define USB_DEC_TO_BCD(dec) ((((dec) / 10) << 4) | ((dec) % 10)) 260 261 /** USB Device release number (bcdDevice Descriptor field) */ 262 #define USB_BCD_DRN (USB_DEC_TO_BCD(KERNEL_VERSION_MAJOR) << 8 | \ 263 USB_DEC_TO_BCD(KERNEL_VERSION_MINOR)) 264 265 /** Macro to obtain descriptor type from USB_SREQ_GET_DESCRIPTOR request */ 266 #define USB_GET_DESCRIPTOR_TYPE(wValue) ((uint8_t)((wValue) >> 8)) 267 268 /** Macro to obtain descriptor index from USB_SREQ_GET_DESCRIPTOR request */ 269 #define USB_GET_DESCRIPTOR_INDEX(wValue) ((uint8_t)(wValue)) 270 271 /** USB Control Endpoints maximum packet size (MPS) */ 272 #define USB_CONTROL_EP_MPS 64U 273 274 /** USB endpoint direction mask */ 275 #define USB_EP_DIR_MASK (uint8_t)BIT(7) 276 277 /** USB IN endpoint direction */ 278 #define USB_EP_DIR_IN (uint8_t)BIT(7) 279 280 /** USB OUT endpoint direction */ 281 #define USB_EP_DIR_OUT 0U 282 283 /* 284 * REVISE: this should actually be (ep) & 0x0F, but is causes 285 * many regressions in the current device support that are difficult 286 * to handle. 287 */ 288 /** Get endpoint index (number) from endpoint address */ 289 #define USB_EP_GET_IDX(ep) ((ep) & ~USB_EP_DIR_MASK) 290 291 /** Get direction based on endpoint address */ 292 #define USB_EP_GET_DIR(ep) ((ep) & USB_EP_DIR_MASK) 293 294 /** Get endpoint address from endpoint index and direction */ 295 #define USB_EP_GET_ADDR(idx, dir) ((idx) | ((dir) & USB_EP_DIR_MASK)) 296 297 /** True if the endpoint is an IN endpoint */ 298 #define USB_EP_DIR_IS_IN(ep) (USB_EP_GET_DIR(ep) == USB_EP_DIR_IN) 299 300 /** True if the endpoint is an OUT endpoint */ 301 #define USB_EP_DIR_IS_OUT(ep) (USB_EP_GET_DIR(ep) == USB_EP_DIR_OUT) 302 303 /** USB Control Endpoints OUT address */ 304 #define USB_CONTROL_EP_OUT (USB_EP_DIR_OUT | 0U) 305 306 /** USB Control Endpoints IN address */ 307 #define USB_CONTROL_EP_IN (USB_EP_DIR_IN | 0U) 308 309 /** USB endpoint transfer type mask */ 310 #define USB_EP_TRANSFER_TYPE_MASK 0x3U 311 312 /** USB endpoint transfer type control */ 313 #define USB_EP_TYPE_CONTROL 0U 314 315 /** USB endpoint transfer type isochronous */ 316 #define USB_EP_TYPE_ISO 1U 317 318 /** USB endpoint transfer type bulk */ 319 #define USB_EP_TYPE_BULK 2U 320 321 /** USB endpoint transfer type interrupt */ 322 #define USB_EP_TYPE_INTERRUPT 3U 323 324 #ifdef __cplusplus 325 } 326 #endif 327 328 #endif /* ZEPHYR_INCLUDE_USB_CH9_H_ */ 329
