Kévin Redon | 69b92d9 | 2019-01-24 16:39:20 +0100 | [diff] [blame] | 1 | /** |
| 2 | * \file |
| 3 | * |
| 4 | * \brief USB protocol definitions. |
| 5 | * |
| 6 | * This file contains the USB definitions and data structures provided by the |
| 7 | * USB 2.0 specification. |
| 8 | * |
| 9 | * Copyright (c) 2015-2018 Microchip Technology Inc. and its subsidiaries. |
| 10 | * |
| 11 | * \asf_license_start |
| 12 | * |
| 13 | * \page License |
| 14 | * |
| 15 | * Subject to your compliance with these terms, you may use Microchip |
| 16 | * software and any derivatives exclusively with Microchip products. |
| 17 | * It is your responsibility to comply with third party license terms applicable |
| 18 | * to your use of third party software (including open source software) that |
| 19 | * may accompany Microchip software. |
| 20 | * |
| 21 | * THIS SOFTWARE IS SUPPLIED BY MICROCHIP "AS IS". NO WARRANTIES, |
| 22 | * WHETHER EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS SOFTWARE, |
| 23 | * INCLUDING ANY IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, |
| 24 | * AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL MICROCHIP BE |
| 25 | * LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE, INCIDENTAL OR CONSEQUENTIAL |
| 26 | * LOSS, DAMAGE, COST OR EXPENSE OF ANY KIND WHATSOEVER RELATED TO THE |
| 27 | * SOFTWARE, HOWEVER CAUSED, EVEN IF MICROCHIP HAS BEEN ADVISED OF THE |
| 28 | * POSSIBILITY OR THE DAMAGES ARE FORESEEABLE. TO THE FULLEST EXTENT |
| 29 | * ALLOWED BY LAW, MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS IN ANY WAY |
| 30 | * RELATED TO THIS SOFTWARE WILL NOT EXCEED THE AMOUNT OF FEES, IF ANY, |
| 31 | * THAT YOU HAVE PAID DIRECTLY TO MICROCHIP FOR THIS SOFTWARE. |
| 32 | * |
| 33 | * \asf_license_stop |
| 34 | */ |
| 35 | |
| 36 | #ifndef _USB_PROTOCOL_H_ |
| 37 | #define _USB_PROTOCOL_H_ |
| 38 | |
| 39 | #include "usb_includes.h" |
| 40 | |
| 41 | /** |
| 42 | * \ingroup usb_group |
| 43 | * \defgroup usb_protocol_group USB Protocol Definitions |
| 44 | * |
| 45 | * This module defines constants and data structures provided by the USB |
| 46 | * 2.0 specification. |
| 47 | * |
| 48 | * @{ |
| 49 | */ |
| 50 | |
| 51 | #ifdef __cplusplus |
| 52 | extern "C" { |
| 53 | #endif |
| 54 | |
| 55 | #ifdef __CC_ARM |
| 56 | #pragma anon_unions |
| 57 | #endif |
| 58 | |
| 59 | /*! Value for field bcdUSB */ |
| 60 | #define USB_V2_0 (0x0200) /*!< USB Specification version 2.00 */ |
| 61 | #define USB_V2_1 (0x0201) /*!< USB Specification version 2.01 (support BOS) */ |
| 62 | |
| 63 | /*! \name Generic definitions (Class, subclass and protocol) |
| 64 | */ |
| 65 | /*! @{ */ |
| 66 | #define USB_CLASS_NO (0x00) |
| 67 | #define USB_SUBCLASS_NO (0x00) |
| 68 | #define USB_PROTOCOL_NO (0x00) |
| 69 | /*! @} */ |
| 70 | |
| 71 | /*! \name IAD (Interface Association Descriptor) constants */ |
| 72 | /*! @{ */ |
| 73 | #define USB_CLASS_IAD (0xEF) |
| 74 | #define USB_SUBCLASS_IAD (0x02) |
| 75 | #define USB_PROTOCOL_IAD (0x01) |
| 76 | /*! @} */ |
| 77 | |
| 78 | /** |
| 79 | * \brief USB request data transfer direction (bmRequestType) |
| 80 | */ |
| 81 | #define USB_REQT_DIR_OUT (0 << 7) /*!< Host to device */ |
| 82 | #define USB_REQT_DIR_H2D (0 << 7) /*!< Host to device */ |
| 83 | #define USB_REQT_DIR_IN (1 << 7) /*!< Device to host */ |
| 84 | #define USB_REQT_DIR_D2H (1 << 7) /*!< Device to host */ |
| 85 | #define USB_REQT_DIR_MASK (1 << 7) /*!< Mask */ |
| 86 | |
| 87 | /** |
| 88 | * \brief USB request types (bmRequestType) |
| 89 | */ |
| 90 | #define USB_REQT_TYPE_STANDARD (0 << 5) /*!< Standard request */ |
| 91 | #define USB_REQT_TYPE_CLASS (1 << 5) /*!< Class-specific request */ |
| 92 | #define USB_REQT_TYPE_VENDOR (2 << 5) /*!< Vendor-specific request */ |
| 93 | #define USB_REQT_TYPE_MASK (3 << 5) /*!< Mask */ |
| 94 | |
| 95 | /** |
| 96 | * \brief USB recipient codes (bmRequestType) |
| 97 | */ |
| 98 | #define USB_REQT_RECIP_DEVICE (0 << 0) /*!< Recipient device */ |
| 99 | #define USB_REQT_RECIP_INTERFACE (1 << 0) /*!< Recipient interface */ |
| 100 | #define USB_REQT_RECIP_ENDPOINT (2 << 0) /*!< Recipient endpoint */ |
| 101 | #define USB_REQT_RECIP_OTHER (3 << 0) /*!< Recipient other */ |
| 102 | #define USB_REQT_RECIP_MASK (0x1F) /*!< Mask */ |
| 103 | |
| 104 | /** |
| 105 | * \brief Standard USB control transfer stages. |
| 106 | */ |
| 107 | enum usb_ctrl_stage { USB_SETUP_STAGE = 0, USB_DATA_STAGE = 1, USB_STATUS_STAGE = 2 }; |
| 108 | |
| 109 | /** |
| 110 | * \brief Standard USB requests (bRequest) |
| 111 | */ |
| 112 | enum usb_req_code { |
| 113 | USB_REQ_GET_STATUS = 0, |
| 114 | USB_REQ_CLEAR_FTR = 1, |
| 115 | USB_REQ_SET_FTR = 3, |
| 116 | USB_REQ_SET_ADDRESS = 5, |
| 117 | USB_REQ_GET_DESC = 6, |
| 118 | USB_REQ_SET_DESC = 7, |
| 119 | USB_REQ_GET_CONFIG = 8, |
| 120 | USB_REQ_SET_CONFIG = 9, |
| 121 | USB_REQ_GET_INTERFACE = 10, |
| 122 | USB_REQ_SET_INTERFACE = 11, |
| 123 | USB_REQ_SYNCH_FRAME = 12, |
| 124 | USB_REQ_SET_SEL = 48, |
| 125 | USB_REQ_ISOCH_DELAY = 49 |
| 126 | }; |
| 127 | |
| 128 | /** |
| 129 | * \brief Standard USB device status flags |
| 130 | * |
| 131 | */ |
| 132 | enum usb_dev_status { |
| 133 | USB_DEV_STAT_BUS_POWERED = 0, |
| 134 | USB_DEV_STAT_SELF_POWERED = 1, |
| 135 | USB_DEV_STAT_REMOTEWAKEUP = 2, |
| 136 | USB_DEV_STAT_U1_ENABLE = 4, |
| 137 | USB_DEV_STAT_U2_ENABLE = 8, |
| 138 | USB_DEV_STAT_LTM_ENABLE = 16 |
| 139 | }; |
| 140 | |
| 141 | /** |
| 142 | * \brief Standard USB Interface status flags |
| 143 | * |
| 144 | */ |
| 145 | enum usb_interface_status { |
| 146 | USB_IFACE_STAT_RESERVED = 0, |
| 147 | USB_IFACE_STAT_REMOTEWAKE_CAP = 1, |
| 148 | USB_IFACE_STAT_REMOTEWAKE = 2 |
| 149 | }; |
| 150 | |
| 151 | /** |
| 152 | * \brief Standard USB endpoint status flags |
| 153 | * |
| 154 | */ |
| 155 | enum usb_endpoint_status { USB_EP_STAT_HALT = 1 }; |
| 156 | |
| 157 | /** |
| 158 | * \brief Standard USB device feature flags |
| 159 | * |
| 160 | * \note valid for SetFeature request. |
| 161 | */ |
| 162 | enum usb_device_feature { |
| 163 | USB_DEV_FTR_REMOTE_WAKEUP = 1, /*!< Remote wakeup enabled */ |
| 164 | USB_DEV_FTR_TEST_MODE = 2, /*!< USB test mode */ |
| 165 | USB_DEV_FTR_OTG_B_HNP_ENABLE = 3, |
| 166 | USB_DEV_FTR_OTG_A_HNP_SP = 4, |
| 167 | USB_DEV_FTR_OTG_A_ALT_HNP_SP = 5, |
| 168 | USB_DEV_FTR_U1_ENABLE = 48, |
| 169 | USB_DEV_FTR_U2_ENABLE = 49, |
| 170 | USB_DEV_FTR_LTM_ENABLE = 50 |
| 171 | }; |
| 172 | |
| 173 | /** |
| 174 | * \brief Test Mode possible on HS USB device |
| 175 | * |
| 176 | * \note valid for USB_DEV_FTR_TEST_MODE request. |
| 177 | */ |
| 178 | enum usb_device_hs_test_mode { |
| 179 | USB_DEV_TEST_MODE_J = 1, |
| 180 | USB_DEV_TEST_MODE_K = 2, |
| 181 | USB_DEV_TEST_MODE_SE0_NAK = 3, |
| 182 | USB_DEV_TEST_MODE_PACKET = 4, |
| 183 | USB_DEV_TEST_MODE_FORCE_ENABLE = 5 |
| 184 | }; |
| 185 | |
| 186 | /** |
| 187 | * \brief Standard Feature Selectors for Interface |
| 188 | */ |
| 189 | enum usb_iface_feature { USB_IFACE_FTR_FUNC_SUSP = 0 }; |
| 190 | |
| 191 | /** |
| 192 | * \brief Standard USB endpoint feature/status flags |
| 193 | */ |
| 194 | enum usb_endpoint_feature { USB_EP_FTR_HALT = 0 }; |
| 195 | |
| 196 | /** |
| 197 | * \brief Standard USB Test Mode Selectors |
| 198 | */ |
| 199 | enum usb_test_mode_selector { |
| 200 | USB_TEST_J = 0x01, |
| 201 | USB_TEST_K = 0x02, |
| 202 | USB_TEST_SE0_NAK = 0x03, |
| 203 | USB_TEST_PACKET = 0x04, |
| 204 | USB_TEST_FORCE_ENABLE = 0x05 |
| 205 | }; |
| 206 | |
| 207 | /** |
| 208 | * \brief Standard USB descriptor types |
| 209 | */ |
| 210 | enum usb_descriptor_type { |
| 211 | USB_DT_DEVICE = 1, |
| 212 | USB_DT_CONFIG = 2, |
| 213 | USB_DT_STRING = 3, |
| 214 | USB_DT_INTERFACE = 4, |
| 215 | USB_DT_ENDPOINT = 5, |
| 216 | USB_DT_DEVICE_QUALIFIER = 6, |
| 217 | USB_DT_OTHER_SPEED_CONFIG = 7, |
| 218 | USB_DT_INTERFACE_POWER = 8, |
| 219 | USB_DT_OTG = 9, |
| 220 | USB_DT_DEBUG = 10, |
| 221 | USB_DT_IAD = 11, |
| 222 | USB_DT_BOS = 15, |
| 223 | USB_DT_DEV_CAP = 16, |
| 224 | USB_DT_SS_EP_COMPANION = 48 |
| 225 | }; |
| 226 | |
| 227 | /** |
| 228 | * \brief Capability types |
| 229 | */ |
| 230 | enum usb_capability_type { |
| 231 | USB_CAPT_WIRELESS = 1, |
| 232 | USB_CAPT_2_0_EXT = 2, |
| 233 | USB_CAPT_SUPER_SPEED = 3, |
| 234 | USB_CAPT_CONTAINER_ID = 4 |
| 235 | }; |
| 236 | |
| 237 | /** |
| 238 | * \brief USB 2.0 Extension attributes |
| 239 | */ |
| 240 | enum usb_2_0_ext_attr { USB_2_0_EXT_LPM_SP = 1 }; |
| 241 | |
| 242 | /** |
| 243 | * \brief USB SuperSpeed Capability attributes |
| 244 | */ |
| 245 | enum usb_ss_cap_attr { USB_SS_LTM_SP }; |
| 246 | |
| 247 | /** |
| 248 | * \brief USB Speed Supports |
| 249 | */ |
| 250 | enum usb_speed_sp { |
| 251 | USB_SPEED_LOW_SP = 1, |
| 252 | USB_SPEED_LS_SP = 1, |
| 253 | USB_SPEED_FULL_SP = 2, |
| 254 | USB_SPEED_FS_SP = 2, |
| 255 | USB_SPEED_HIGH_SP = 4, |
| 256 | USB_SPEED_HS_SP = 4, |
| 257 | USB_SPEED_SUPER_SP = 8, |
| 258 | USB_SPEED_SS_SP = 8 |
| 259 | }; |
| 260 | |
| 261 | /** |
| 262 | * \brief Standard USB endpoint transfer types |
| 263 | */ |
| 264 | enum usb_ep_type { |
| 265 | USB_EP_TYPE_CONTROL = 0x00, |
| 266 | USB_EP_TYPE_ISOCHRONOUS = 0x01, |
| 267 | USB_EP_TYPE_BULK = 0x02, |
| 268 | USB_EP_TYPE_INTERRUPT = 0x03, |
| 269 | USB_EP_TYPE_MASK = 0x03u |
| 270 | }; |
| 271 | |
| 272 | /** |
| 273 | * \brief USB endpoint interrupt types |
| 274 | */ |
| 275 | enum usb_ep_int_type { USB_EP_INT_T_PERIODIC = 0x00u, USB_EP_INT_T_NOTIFICATION = 0x01u, USB_EP_INT_T_MASK = 0x03u }; |
| 276 | |
| 277 | /** |
| 278 | * \brief Standard USB endpoint synchronization types |
| 279 | */ |
| 280 | enum usb_ep_sync_type { |
| 281 | USB_EP_SYNC_T_NO = 0x00u, |
| 282 | USB_EP_SYNC_T_ASYNC = 0x02u, |
| 283 | USB_EP_SYNC_T_ADAPTIVE = 0x02u, |
| 284 | USB_EP_SYNC_T_SYNC = 0x03u, |
| 285 | USB_EP_SYNC_T_MASK = 0x03u |
| 286 | }; |
| 287 | |
| 288 | /** |
| 289 | * \brief Standard USB endpoint usage types |
| 290 | */ |
| 291 | enum usb_ep_usage_type { |
| 292 | USB_EP_USAGE_T_DATA = 0x00u, |
| 293 | USB_EP_USAGE_T_FEEDBACK = 0x01u, |
| 294 | USB_EP_USAGE_T_FEEDBACK_DATA = 0x02u, |
| 295 | USB_EP_USAGE_T_MASK = 0x03u |
| 296 | }; |
| 297 | |
| 298 | /** |
| 299 | * \brief Standard USB language IDs for string descriptors |
| 300 | */ |
| 301 | enum usb_langid { |
| 302 | USB_LANGID_EN_US = 0x0409 /*!< English (United States) */ |
| 303 | }; |
| 304 | |
| 305 | /** |
| 306 | * \brief Mask selecting the index part of an endpoint address |
| 307 | */ |
| 308 | #define USB_EP_ADDR_MASK 0x0f |
| 309 | /** |
| 310 | * \brief Endpoint transfer direction is IN |
| 311 | */ |
| 312 | #define USB_EP_DIR_IN 0x80 |
| 313 | /** |
| 314 | * \brief Endpoint transfer direction is OUT |
| 315 | */ |
| 316 | #define USB_EP_DIR_OUT 0x00 |
| 317 | |
| 318 | /** |
| 319 | * \brief Maximum length in bytes of a USB descriptor |
| 320 | * |
| 321 | * The maximum length of a USB descriptor is limited by the 8-bit |
| 322 | * bLength field. |
| 323 | */ |
| 324 | #define USB_DESC_LEN_MAX 255 |
| 325 | |
| 326 | /* |
| 327 | * 2-byte alignment requested for all USB structures. |
| 328 | */ |
| 329 | COMPILER_PACK_SET(1) |
| 330 | |
| 331 | /** |
| 332 | * \brief A USB Device SETUP request |
| 333 | * |
| 334 | * The data payload of SETUP packets always follows this structure. |
| 335 | */ |
| 336 | typedef struct usb_req { |
| 337 | uint8_t bmRequestType; |
| 338 | uint8_t bRequest; |
| 339 | union { |
| 340 | le16_t wValue; |
| 341 | struct { |
| 342 | uint8_t l; |
| 343 | uint8_t h; |
| 344 | } wValueBytes; |
| 345 | }; |
| 346 | union { |
| 347 | le16_t wIndex; |
| 348 | struct { |
| 349 | uint8_t l; |
| 350 | uint8_t h; |
| 351 | } wIndexBytes; |
| 352 | }; |
| 353 | union { |
| 354 | le16_t wLength; |
| 355 | struct { |
| 356 | uint8_t l; |
| 357 | uint8_t h; |
| 358 | } wLengthBytes; |
| 359 | }; |
| 360 | } usb_req_t; |
| 361 | |
| 362 | /** |
| 363 | * \brief Standard USB device descriptor structure |
| 364 | */ |
| 365 | typedef struct usb_dev_desc { |
| 366 | uint8_t bLength; |
| 367 | uint8_t bDescriptorType; |
| 368 | le16_t bcdUSB; |
| 369 | uint8_t bDeviceClass; |
| 370 | uint8_t bDeviceSubClass; |
| 371 | uint8_t bDeviceProtocol; |
| 372 | uint8_t bMaxPacketSize0; |
| 373 | le16_t idVendor; |
| 374 | le16_t idProduct; |
| 375 | le16_t bcdDevice; |
| 376 | uint8_t iManufacturer; |
| 377 | uint8_t iProduct; |
| 378 | uint8_t iSerialNumber; |
| 379 | uint8_t bNumConfigurations; |
| 380 | } usb_dev_desc_t; |
| 381 | |
| 382 | /** |
| 383 | * \brief Binary device Object Store (BOS) descriptor structure |
| 384 | */ |
| 385 | typedef struct usb_bos_desc { |
| 386 | uint8_t bLength; |
| 387 | uint8_t bDescriptorType; |
| 388 | le16_t wTotalLength; |
| 389 | uint8_t bNumDeviceCaps; |
| 390 | } usb_bos_desc_t; |
| 391 | |
| 392 | /** |
| 393 | * \brief Device Capability Descriptor structure |
| 394 | */ |
| 395 | typedef struct usb_cap_desc { |
| 396 | uint8_t bLength; |
| 397 | uint8_t bDescriptorType; |
| 398 | uint8_t bDevCapabilityType; |
| 399 | uint8_t Vars[1]; |
| 400 | } usb_cap_desc_t; |
| 401 | |
| 402 | /** |
| 403 | * \brief USB 2.0 Extension Descriptor structure |
| 404 | */ |
| 405 | typedef struct usb_2_0_ext { |
| 406 | uint8_t bLength; |
| 407 | uint8_t bDescriptorType; |
| 408 | uint8_t bDevCapabilityType; |
| 409 | uint32_t bmAttributes; |
| 410 | } usb_2_0_ext_t; |
| 411 | |
| 412 | /** |
| 413 | * \brief LPM Device Capabilities descriptor structure |
| 414 | */ |
| 415 | typedef struct usb_2_0_ext usb_lpm_cap_desc_t; |
| 416 | |
| 417 | /** |
| 418 | * \brief SuperSpeed USB Device Capability structure |
| 419 | */ |
| 420 | typedef struct usb_ss_cap_desc { |
| 421 | uint8_t bLength; |
| 422 | uint8_t bDescriptorType; |
| 423 | uint8_t bDevCapabilityType; |
| 424 | uint8_t bmAttributes; |
| 425 | le16_t wSpeedsSupported; |
| 426 | uint8_t bFunctionalitySupport; |
| 427 | uint8_t bU1DevExitLat; |
| 428 | uint8_t bU2DevExitLat; |
| 429 | } usb_ss_cap_desc_t; |
| 430 | |
| 431 | /** |
| 432 | * \brief USB Container ID Descriptor structure |
| 433 | */ |
| 434 | typedef struct usb_container_id_desc { |
| 435 | uint8_t bLength; |
| 436 | uint8_t bDescriptorType; |
| 437 | uint8_t bDevCapabilityType; |
| 438 | uint8_t bReserved; |
| 439 | uint8_t ContainerID[16]; |
| 440 | } usb_container_id_desc_t; |
| 441 | |
| 442 | /** |
| 443 | * \brief Standard USB device qualifier descriptor structure |
| 444 | * |
| 445 | * This descriptor contains information about the device when running at |
| 446 | * the "other" speed (i.e. if the device is currently operating at high |
| 447 | * speed, this descriptor can be used to determine what would change if |
| 448 | * the device was operating at full speed.) |
| 449 | */ |
| 450 | typedef struct usb_dev_qual_desc { |
| 451 | uint8_t bLength; |
| 452 | uint8_t bDescriptorType; |
| 453 | le16_t bcdUSB; |
| 454 | uint8_t bDeviceClass; |
| 455 | uint8_t bDeviceSubClass; |
| 456 | uint8_t bDeviceProtocol; |
| 457 | uint8_t bMaxPacketSize0; |
| 458 | uint8_t bNumConfigurations; |
| 459 | uint8_t bReserved; |
| 460 | } usb_dev_qual_desc_t; |
| 461 | |
| 462 | /** |
| 463 | * \brief Standard USB configuration descriptor structure |
| 464 | */ |
| 465 | typedef struct usb_config_desc { |
| 466 | uint8_t bLength; |
| 467 | uint8_t bDescriptorType; |
| 468 | le16_t wTotalLength; |
| 469 | uint8_t bNumInterfaces; |
| 470 | uint8_t bConfigurationValue; |
| 471 | uint8_t iConfiguration; |
| 472 | uint8_t bmAttributes; |
| 473 | uint8_t bMaxPower; |
| 474 | } usb_config_desc_t; |
| 475 | |
| 476 | #define USB_CONFIG_ATTR_MUST_SET (1 << 7) /*!< Must always be set */ |
| 477 | #define USB_CONFIG_ATTR_BUS_POWERED (0 << 6) /*!< Bus-powered */ |
| 478 | #define USB_CONFIG_ATTR_SELF_POWERED (1 << 6) /*!< Self-powered */ |
| 479 | #define USB_CONFIG_ATTR_REMOTE_WAKEUP (1 << 5) /*!< remote wakeup supported */ |
| 480 | |
| 481 | #define USB_CONFIG_MAX_POWER(ma) (((ma) + 1) / 2) /*!< Max power in mA */ |
| 482 | |
| 483 | /** |
| 484 | * \brief Standard USB association descriptor structure |
| 485 | */ |
| 486 | typedef struct usb_iad_desc { |
| 487 | uint8_t bLength; /*!< Size of this descriptor in bytes */ |
| 488 | uint8_t bDescriptorType; /*!< Interface descriptor type */ |
| 489 | uint8_t bFirstInterface; /*!< Number of interface */ |
| 490 | uint8_t bInterfaceCount; /*!< value to select alternate setting */ |
| 491 | uint8_t bFunctionClass; /*!< Class code assigned by the USB */ |
| 492 | uint8_t bFunctionSubClass; /*!< Sub-class code assigned by the USB */ |
| 493 | uint8_t bFunctionProtocol; /*!< Protocol code assigned by the USB */ |
| 494 | uint8_t iFunction; /*!< Index of string descriptor */ |
| 495 | } usb_iad_desc_t; |
| 496 | |
| 497 | /** |
| 498 | * \brief Standard USB interface descriptor structure |
| 499 | */ |
| 500 | typedef struct usb_iface_desc { |
| 501 | uint8_t bLength; |
| 502 | uint8_t bDescriptorType; |
| 503 | uint8_t bInterfaceNumber; |
| 504 | uint8_t bAlternateSetting; |
| 505 | uint8_t bNumEndpoints; |
| 506 | uint8_t bInterfaceClass; |
| 507 | uint8_t bInterfaceSubClass; |
| 508 | uint8_t bInterfaceProtocol; |
| 509 | uint8_t iInterface; |
| 510 | } usb_iface_desc_t; |
| 511 | |
| 512 | /** |
| 513 | * \brief Standard USB endpoint descriptor structure |
| 514 | */ |
| 515 | typedef struct usb_ep_desc { |
| 516 | uint8_t bLength; |
| 517 | uint8_t bDescriptorType; |
| 518 | uint8_t bEndpointAddress; |
| 519 | uint8_t bmAttributes; |
| 520 | le16_t wMaxPacketSize; |
| 521 | uint8_t bInterval; |
| 522 | } usb_ep_desc_t; |
| 523 | |
| 524 | /** |
| 525 | * \brief SuperSpeed Endpoint Companion descriptor structure |
| 526 | */ |
| 527 | typedef struct usb_ss_ep_comp_desc { |
| 528 | uint8_t bLength; |
| 529 | uint8_t bDescriptorType; |
| 530 | uint8_t bMaxBurst; |
| 531 | uint8_t bmAttributes; |
| 532 | le16_t wBytesPerInterval; |
| 533 | } usb_ss_ep_comp_desc_t; |
| 534 | |
| 535 | /** |
| 536 | * \brief LPM Token bmAttributes structure |
| 537 | */ |
| 538 | typedef struct usb_lpm_attributes { |
| 539 | uint8_t bLinkState : 4; |
| 540 | uint8_t HIRD : 4; |
| 541 | uint8_t bRemoteWake : 1; |
| 542 | uint8_t Reserved : 2; |
| 543 | } usb_lpm_attributes_t; |
| 544 | |
| 545 | /** |
| 546 | * \brief A standard USB string descriptor structure |
| 547 | */ |
| 548 | typedef struct usb_str_desc { |
| 549 | uint8_t bLength; |
| 550 | uint8_t bDescriptorType; |
| 551 | } usb_str_desc_t; |
| 552 | |
| 553 | typedef struct usb_str_langid_desc { |
| 554 | usb_str_desc_t desc; |
| 555 | le16_t string[1]; |
| 556 | } usb_str_langid_desc_t; |
| 557 | |
| 558 | COMPILER_PACK_RESET() |
| 559 | |
| 560 | /** \name Macros to build USB standard descriptors */ |
| 561 | /*@{*/ |
| 562 | |
| 563 | /** Build bytes for USB device descriptor. */ |
| 564 | #define USB_DEV_DESC_BYTES(bcdUSB, \ |
| 565 | bDeviceClass, \ |
| 566 | bDeviceSubClass, \ |
| 567 | bDeviceProtocol, \ |
| 568 | bMaxPacketSize0, \ |
| 569 | idVendor, \ |
| 570 | idProduct, \ |
| 571 | bcdDevice, \ |
| 572 | iManufacturer, \ |
| 573 | iProduct, \ |
| 574 | iSerialNumber, \ |
| 575 | bNumConfigurations) \ |
| 576 | 18, /* bLength */ \ |
| 577 | 0x01, /* bDescriptorType: DEVICE */ \ |
| 578 | LE_BYTE0(bcdUSB), LE_BYTE1(bcdUSB), bDeviceClass, bDeviceSubClass, bDeviceProtocol, bMaxPacketSize0, \ |
| 579 | LE_BYTE0(idVendor), LE_BYTE1(idVendor), LE_BYTE0(idProduct), LE_BYTE1(idProduct), LE_BYTE0(bcdDevice), \ |
| 580 | LE_BYTE1(bcdDevice), iManufacturer, iProduct, iSerialNumber, bNumConfigurations |
| 581 | |
| 582 | #define USB_DEV_QUAL_DESC_BYTES( \ |
| 583 | bcdUSB, bDeviceClass, bDeviceSubClass, bDeviceProtocol, bMaxPacketSize0, bNumConfigurations) \ |
| 584 | 10, /* bLength */ \ |
| 585 | USB_DT_DEVICE_QUALIFIER, /* bDescriptorType: DEVICE_QUALIFIER */ \ |
| 586 | LE_BYTE0(bcdUSB), LE_BYTE1(bcdUSB), bDeviceClass, bDeviceSubClass, bDeviceProtocol, bMaxPacketSize0, \ |
| 587 | bNumConfigurations, 0 |
| 588 | |
| 589 | #define USB_DEV_DESC_LEN 18 |
| 590 | |
| 591 | /** Build bytes for USB configuration descriptor. */ |
| 592 | #define USB_CONFIG_DESC_BYTES( \ |
| 593 | wTotalLength, bNumInterfaces, bConfigurationValue, iConfiguration, bmAttributes, bMaxPower) \ |
| 594 | 9, /* bLength */ \ |
| 595 | 0x02, /* bDescriptorType: CONFIGURATION */ \ |
| 596 | LE_BYTE0(wTotalLength), LE_BYTE1(wTotalLength), bNumInterfaces, bConfigurationValue, iConfiguration, \ |
| 597 | bmAttributes, bMaxPower |
| 598 | |
| 599 | #define USB_OTH_SPD_CFG_DESC_BYTES( \ |
| 600 | wTotalLength, bNumInterfaces, bConfigurationValue, iConfiguration, bmAttributes, bMaxPower) \ |
| 601 | 9, /* bLength */ \ |
| 602 | USB_DT_OTHER_SPEED_CONFIG, /* bDescriptorType: OTH_SPD_CONFIGURATION */ \ |
| 603 | LE_BYTE0(wTotalLength), LE_BYTE1(wTotalLength), bNumInterfaces, bConfigurationValue, iConfiguration, \ |
| 604 | bmAttributes, bMaxPower |
| 605 | |
| 606 | #define USB_CONFIG_DESC_LEN 9 |
| 607 | |
| 608 | /** Build bytes for USB IAD descriptor. */ |
| 609 | #define USB_IAD_DESC_BYTES( \ |
| 610 | bFirstInterface, bInterfaceCount, bFunctionClass, bFunctionSubClass, bFunctionProtocol, iFunction) \ |
| 611 | 8, /* bLength */ \ |
| 612 | USB_DT_IAD, /* bDescriptorType */ \ |
| 613 | bFirstInterface, bInterfaceCount, bFunctionClass, bFunctionSubClass, bFunctionProtocol, iFunction |
| 614 | |
| 615 | #define USB_IAD_DESC_LEN 8 |
| 616 | |
| 617 | /** Build bytes for USB interface descriptor. */ |
| 618 | #define USB_IFACE_DESC_BYTES(bInterfaceNumber, \ |
| 619 | bAlternateSetting, \ |
| 620 | bNumEndpoints, \ |
| 621 | bInterfaceClass, \ |
| 622 | bInterfaceSubClass, \ |
| 623 | bInterfaceProtocol, \ |
| 624 | iInterface) \ |
| 625 | 9, /* bLength */ \ |
| 626 | 0x04, /* bDescriptorType: INTERFACE */ \ |
| 627 | bInterfaceNumber, bAlternateSetting, bNumEndpoints, bInterfaceClass, bInterfaceSubClass, bInterfaceProtocol, \ |
| 628 | iInterface |
| 629 | |
| 630 | #define USB_IFACE_DESC_LEN 9 |
| 631 | |
| 632 | /** Build bytes for USB endpoint descriptor. */ |
| 633 | #define USB_ENDP_DESC_BYTES(bEndpointAddress, bmAttributes, wMaxPacketSize, bInterval) \ |
| 634 | 7, /* bLength */ \ |
| 635 | 0x05, /* bDescriptorType: ENDPOINT */ \ |
| 636 | bEndpointAddress, bmAttributes, LE_BYTE0(wMaxPacketSize), LE_BYTE1(wMaxPacketSize), bInterval |
| 637 | |
| 638 | #define USB_ENDP_DESC_LEN 7 |
| 639 | |
| 640 | /*@}*/ |
| 641 | |
| 642 | /** \brief Get a word (calculate by little endian 16-bit data) |
| 643 | * \param[in] ptr Byte pointer to the address to get data |
| 644 | * \return a 16-bit word |
| 645 | */ |
| 646 | static inline uint16_t usb_get_u16(const uint8_t *ptr) |
| 647 | { |
| 648 | return (ptr[0] + (ptr[1] << 8)); |
| 649 | } |
| 650 | |
| 651 | /** \brief Get a double word (calculate by little endian 32-bit data) |
| 652 | * \param[in] ptr Byte pointer to the address to get data |
| 653 | * \return a 32-bit word |
| 654 | */ |
| 655 | static inline uint32_t usb_get_u32(const uint8_t *ptr) |
| 656 | { |
| 657 | return (ptr[0] + (ptr[1] << 8) + (ptr[2] << 16) + (ptr[3] << 24)); |
| 658 | } |
| 659 | |
| 660 | /** \brief Get descriptor length |
| 661 | * \param[in] desc Byte pointer to the descriptor start address |
| 662 | * \return descriptor length |
| 663 | */ |
| 664 | static inline uint8_t usb_desc_len(const uint8_t *desc) |
| 665 | { |
| 666 | return desc[0]; |
| 667 | } |
| 668 | |
| 669 | /** \brief Get descriptor type |
| 670 | * \param[in] desc Byte pointer to the descriptor start address |
| 671 | * \return descriptor type |
| 672 | */ |
| 673 | static inline uint8_t usb_desc_type(const uint8_t *desc) |
| 674 | { |
| 675 | return desc[1]; |
| 676 | } |
| 677 | |
| 678 | /** \brief Get next USB descriptor |
| 679 | * \param[in] desc Byte pointer to the descriptor start address |
| 680 | * \return Byte pointer to the next descriptor |
| 681 | */ |
| 682 | static inline uint8_t *usb_desc_next(uint8_t *desc) |
| 683 | { |
| 684 | return (desc + usb_desc_len(desc)); |
| 685 | } |
| 686 | |
| 687 | /** \brief Get idVendor of USB Device Descriptor |
| 688 | * \param[in] dev_desc Byte pointer to the descriptor start address |
| 689 | * \return 16-bit idVendor value |
| 690 | */ |
| 691 | static inline uint16_t usb_dev_desc_vid(const uint8_t *dev_desc) |
| 692 | { |
| 693 | return usb_get_u16(dev_desc + 8); |
| 694 | } |
| 695 | |
| 696 | /** \brief Get idProduct of USB Device Descriptor |
| 697 | * \param[in] dev_desc Byte pointer to the descriptor start address |
| 698 | * \return 16-bit idProduct value |
| 699 | */ |
| 700 | static inline uint16_t usb_dev_desc_pid(const uint8_t *dev_desc) |
| 701 | { |
| 702 | return usb_get_u16(dev_desc + 10); |
| 703 | } |
| 704 | |
| 705 | /** \brief Get wTotalLength of USB Configuration Descriptor |
| 706 | * \param[in] cfg_desc Byte pointer to the descriptor start address |
| 707 | * \return 16-bit total length of configuration list |
| 708 | */ |
| 709 | static inline uint16_t usb_cfg_desc_total_len(const uint8_t *cfg_desc) |
| 710 | { |
| 711 | return usb_get_u16(cfg_desc + 2); |
| 712 | } |
| 713 | |
| 714 | /** \brief Get Next USB Descriptor After the Configuration Descriptors list |
| 715 | * \param[in] cfg_desc Byte pointer to the descriptor start address |
| 716 | * \return Byte pointer to descriptor after configuration end |
| 717 | */ |
| 718 | static inline uint8_t *usb_cfg_desc_next(uint8_t *cfg_desc) |
| 719 | { |
| 720 | return (cfg_desc + usb_cfg_desc_total_len(cfg_desc)); |
| 721 | } |
| 722 | |
| 723 | /** \brief Find specific USB Descriptor by its type |
| 724 | * \param[in] desc Byte pointer to the descriptor start address |
| 725 | * \param[in] eof Byte pointer to the descriptor end address |
| 726 | * \param[in] type The descriptor type expected |
| 727 | * \return Pointer to the descriptor |
| 728 | * \retval NULL if not found |
| 729 | */ |
| 730 | uint8_t *usb_find_desc(uint8_t *desc, uint8_t *eof, uint8_t type); |
| 731 | |
| 732 | /** Get interface descriptor next to the specified one (by interface number) |
| 733 | * \param[in] desc Byte pointer to the descriptor start address |
| 734 | * \param[in] eof Byte pointer to the descriptor end address |
| 735 | * \param[in] iface_n The interface number to check |
| 736 | * \return Pointer to the descriptor |
| 737 | * \retval >= eof if not found |
| 738 | */ |
| 739 | uint8_t *usb_find_iface_after(uint8_t *desc, uint8_t *eof, uint8_t iface_n); |
| 740 | |
| 741 | /** Find endpoint descriptor, breaks if interface descriptor detected |
| 742 | * \param[in] desc Byte pointer to the descriptor start address |
| 743 | * \param[in] eof Byte pointer to the descriptor end address |
| 744 | * \return Pointer to the descriptor |
| 745 | * \retval NULL if not found |
| 746 | */ |
| 747 | uint8_t *usb_find_ep_desc(uint8_t *desc, uint8_t *eof); |
| 748 | |
| 749 | /** Find configuration descriptor by its configuration number |
| 750 | * \param[in] desc Byte pointer to the descriptor start address |
| 751 | * \param[in] eof Byte pointer to the descriptor end address |
| 752 | * \param[in] cfg_value The configure value expected |
| 753 | * \return Pointer to the descriptor |
| 754 | * \retval NULL if not found |
| 755 | */ |
| 756 | uint8_t *usb_find_cfg_desc(uint8_t *desc, uint8_t *eof, uint8_t cfg_value); |
| 757 | |
| 758 | /** Find other speed configuration descriptor by its configuration number |
| 759 | * \param[in] desc Byte pointer to the descriptor start address |
| 760 | * \param[in] eof Byte pointer to the descriptor end address |
| 761 | * \param[in] cfg_value The configure value expected |
| 762 | * \return Pointer to the descriptor |
| 763 | * \retval NULL if not found |
| 764 | */ |
| 765 | uint8_t *usb_find_othspdcfg_desc(uint8_t *desc, uint8_t *eof, uint8_t cfg_value); |
| 766 | |
| 767 | /** Find string descriptor by its index |
| 768 | * \param[in] desc Byte pointer to the descriptor start address |
| 769 | * \param[in] eof Byte pointer to the descriptor end address |
| 770 | * \param[in] str_index The string index expected |
| 771 | * \return Pointer to the descriptor |
| 772 | * \retval NULL if not found |
| 773 | */ |
| 774 | uint8_t *usb_find_str_desc(uint8_t *desc, uint8_t *eof, uint8_t str_index); |
| 775 | |
| 776 | #ifdef __cplusplus |
| 777 | } |
| 778 | #endif |
| 779 | |
| 780 | /*! @} */ |
| 781 | |
| 782 | #endif /* _USB_PROTOCOL_H_ */ |