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 <sys/util.h> 17 18 #ifndef ZEPHYR_INCLUDE_USB_CH9_H_ 19 #define ZEPHYR_INCLUDE_USB_CH9_H_ 20 21 #ifdef __cplusplus 22 extern "C" { 23 #endif 24 25 struct usb_req_type_field { 26 #if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__ 27 uint8_t recipient : 5; 28 uint8_t type : 2; 29 uint8_t direction : 1; 30 #elif __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__ 31 uint8_t direction : 1; 32 uint8_t type : 2; 33 uint8_t recipient : 5; 34 #endif 35 } __packed; 36 37 /** USB Setup Data packet defined in spec. Table 9-2 */ 38 struct usb_setup_packet { 39 union { 40 uint8_t bmRequestType; 41 struct usb_req_type_field RequestType; 42 }; 43 uint8_t bRequest; 44 uint16_t wValue; 45 uint16_t wIndex; 46 uint16_t wLength; 47 }; 48 49 /** USB Setup packet RequestType Direction values (from Table 9-2) */ 50 #define USB_REQTYPE_DIR_TO_DEVICE 0 51 #define USB_REQTYPE_DIR_TO_HOST 1 52 53 /** USB Setup packet RequestType Type values (from Table 9-2) */ 54 #define USB_REQTYPE_TYPE_STANDARD 0 55 #define USB_REQTYPE_TYPE_CLASS 1 56 #define USB_REQTYPE_TYPE_VENDOR 2 57 #define USB_REQTYPE_TYPE_RESERVED 3 58 59 /** USB Setup packet RequestType Recipient values (from Table 9-2) */ 60 #define USB_REQTYPE_RECIPIENT_DEVICE 0 61 #define USB_REQTYPE_RECIPIENT_INTERFACE 1 62 #define USB_REQTYPE_RECIPIENT_ENDPOINT 2 63 #define USB_REQTYPE_RECIPIENT_OTHER 3 64 65 /** Get data transfer direction from bmRequestType */ 66 #define USB_REQTYPE_GET_DIR(bmRequestType) (((bmRequestType) >> 7) & 0x01U) 67 /** Get request type from bmRequestType */ 68 #define USB_REQTYPE_GET_TYPE(bmRequestType) (((bmRequestType) >> 5) & 0x03U) 69 /** Get request recipient from bmRequestType */ 70 #define USB_REQTYPE_GET_RECIPIENT(bmRequestType) ((bmRequestType) & 0x1FU) 71 72 /** 73 * @brief Check if request transfer direction is to host. 74 * 75 * @param setup Pointer to USB Setup packet 76 * @return true If transfer direction is to host 77 */ usb_reqtype_is_to_host(struct usb_setup_packet * setup)78static inline bool usb_reqtype_is_to_host(struct usb_setup_packet *setup) 79 { 80 return setup->RequestType.direction == USB_REQTYPE_DIR_TO_HOST; 81 } 82 83 /** 84 * @brief Check if request transfer direction is to device. 85 * 86 * @param setup Pointer to USB Setup packet 87 * @return true If transfer direction is to device 88 */ usb_reqtype_is_to_device(struct usb_setup_packet * setup)89static inline bool usb_reqtype_is_to_device(struct usb_setup_packet *setup) 90 { 91 return setup->RequestType.direction == USB_REQTYPE_DIR_TO_DEVICE; 92 } 93 94 /** USB Standard Request Codes defined in spec. Table 9-4 */ 95 #define USB_SREQ_GET_STATUS 0x00 96 #define USB_SREQ_CLEAR_FEATURE 0x01 97 #define USB_SREQ_SET_FEATURE 0x03 98 #define USB_SREQ_SET_ADDRESS 0x05 99 #define USB_SREQ_GET_DESCRIPTOR 0x06 100 #define USB_SREQ_SET_DESCRIPTOR 0x07 101 #define USB_SREQ_GET_CONFIGURATION 0x08 102 #define USB_SREQ_SET_CONFIGURATION 0x09 103 #define USB_SREQ_GET_INTERFACE 0x0A 104 #define USB_SREQ_SET_INTERFACE 0x0B 105 #define USB_SREQ_SYNCH_FRAME 0x0C 106 107 /** Descriptor Types defined in spec. Table 9-5 */ 108 #define USB_DESC_DEVICE 1 109 #define USB_DESC_CONFIGURATION 2 110 #define USB_DESC_STRING 3 111 #define USB_DESC_INTERFACE 4 112 #define USB_DESC_ENDPOINT 5 113 #define USB_DESC_DEVICE_QUALIFIER 6 114 #define USB_DESC_OTHER_SPEED 7 115 #define USB_DESC_INTERFACE_POWER 8 116 /** Additional Descriptor Types defined in USB 3 spec. Table 9-5 */ 117 #define USB_DESC_OTG 9 118 #define USB_DESC_DEBUG 10 119 #define USB_DESC_INTERFACE_ASSOC 11 120 #define USB_DESC_BOS 15 121 #define USB_DESC_DEVICE_CAPABILITY 16 122 123 /** Class-Specific Descriptor Types as defined by 124 * USB Common Class Specification 125 */ 126 #define USB_DESC_CS_DEVICE 0x21 127 #define USB_DESC_CS_CONFIGURATION 0x22 128 #define USB_DESC_CS_STRING 0x23 129 #define USB_DESC_CS_INTERFACE 0x24 130 #define USB_DESC_CS_ENDPOINT 0x25 131 132 /** USB Standard Feature Selectors defined in spec. Table 9-6 */ 133 #define USB_SFS_ENDPOINT_HALT 0x00 134 #define USB_SFS_REMOTE_WAKEUP 0x01 135 #define USB_SFS_TEST_MODE 0x02 136 137 /** Bits used for GetStatus response defined in spec. Figure 9-4 */ 138 #define USB_GET_STATUS_SELF_POWERED BIT(0) 139 #define USB_GET_STATUS_REMOTE_WAKEUP BIT(1) 140 141 /** Header of an USB descriptor */ 142 struct usb_desc_header { 143 uint8_t bLength; 144 uint8_t bDescriptorType; 145 } __packed; 146 147 /** USB Standard Device Descriptor defined in spec. Table 9-8 */ 148 struct usb_device_descriptor { 149 uint8_t bLength; 150 uint8_t bDescriptorType; 151 uint16_t bcdUSB; 152 uint8_t bDeviceClass; 153 uint8_t bDeviceSubClass; 154 uint8_t bDeviceProtocol; 155 uint8_t bMaxPacketSize0; 156 uint16_t idVendor; 157 uint16_t idProduct; 158 uint16_t bcdDevice; 159 uint8_t iManufacturer; 160 uint8_t iProduct; 161 uint8_t iSerialNumber; 162 uint8_t bNumConfigurations; 163 } __packed; 164 165 /** USB Standard Configuration Descriptor defined in spec. Table 9-10 */ 166 struct usb_cfg_descriptor { 167 uint8_t bLength; 168 uint8_t bDescriptorType; 169 uint16_t wTotalLength; 170 uint8_t bNumInterfaces; 171 uint8_t bConfigurationValue; 172 uint8_t iConfiguration; 173 uint8_t bmAttributes; 174 uint8_t bMaxPower; 175 } __packed; 176 177 /** USB Standard Interface Descriptor defined in spec. Table 9-12 */ 178 struct usb_if_descriptor { 179 uint8_t bLength; 180 uint8_t bDescriptorType; 181 uint8_t bInterfaceNumber; 182 uint8_t bAlternateSetting; 183 uint8_t bNumEndpoints; 184 uint8_t bInterfaceClass; 185 uint8_t bInterfaceSubClass; 186 uint8_t bInterfaceProtocol; 187 uint8_t iInterface; 188 } __packed; 189 190 /** USB Standard Endpoint Descriptor defined in spec. Table 9-13 */ 191 struct usb_ep_descriptor { 192 uint8_t bLength; 193 uint8_t bDescriptorType; 194 uint8_t bEndpointAddress; 195 uint8_t bmAttributes; 196 uint16_t wMaxPacketSize; 197 uint8_t bInterval; 198 } __packed; 199 200 /** USB Unicode (UTF16LE) String Descriptor defined in spec. Table 9-15 */ 201 struct usb_string_descriptor { 202 uint8_t bLength; 203 uint8_t bDescriptorType; 204 uint16_t bString; 205 } __packed; 206 207 /** USB Association Descriptor defined in USB 3 spec. Table 9-16 */ 208 struct usb_association_descriptor { 209 uint8_t bLength; 210 uint8_t bDescriptorType; 211 uint8_t bFirstInterface; 212 uint8_t bInterfaceCount; 213 uint8_t bFunctionClass; 214 uint8_t bFunctionSubClass; 215 uint8_t bFunctionProtocol; 216 uint8_t iFunction; 217 } __packed; 218 219 /** USB Standard Configuration Descriptor Characteristics from Table 9-10 */ 220 #define USB_SCD_RESERVED BIT(7) 221 #define USB_SCD_SELF_POWERED BIT(6) 222 #define USB_SCD_REMOTE_WAKEUP BIT(5) 223 #define USB_SCD_ATTRIBUTES (USB_SCD_RESERVED | \ 224 COND_CODE_1(CONFIG_USB_SELF_POWERED, \ 225 (USB_SCD_SELF_POWERED), (0)) | \ 226 COND_CODE_1(CONFIG_USB_DEVICE_REMOTE_WAKEUP, \ 227 (USB_SCD_REMOTE_WAKEUP), (0))) 228 229 /** USB Defined Base Class Codes from https://www.usb.org/defined-class-codes */ 230 #define USB_BCC_AUDIO 0x01 231 #define USB_BCC_CDC_CONTROL 0x02 232 #define USB_BCC_HID 0x03 233 #define USB_BCC_MASS_STORAGE 0x08 234 #define USB_BCC_CDC_DATA 0x0A 235 #define USB_BCC_VIDEO 0x0E 236 #define USB_BCC_WIRELESS_CONTROLLER 0xE0 237 #define USB_BCC_MISCELLANEOUS 0xEF 238 #define USB_BCC_APPLICATION 0xFE 239 #define USB_BCC_VENDOR 0xFF 240 241 /** USB Specification Release Numbers (bcdUSB Descriptor field) */ 242 #define USB_SRN_1_1 0x0110 243 #define USB_SRN_2_0 0x0200 244 #define USB_SRN_2_1 0x0210 245 246 #define USB_DEC_TO_BCD(dec) ((((dec) / 10) << 4) | ((dec) % 10)) 247 248 /** USB Device release number (bcdDevice Descriptor field) */ 249 #define USB_BCD_DRN (USB_DEC_TO_BCD(KERNEL_VERSION_MAJOR) << 8 | \ 250 USB_DEC_TO_BCD(KERNEL_VERSION_MINOR)) 251 252 /** Macro to obtain descriptor type from USB_SREQ_GET_DESCRIPTOR request */ 253 #define USB_GET_DESCRIPTOR_TYPE(wValue) ((uint8_t)((wValue) >> 8)) 254 255 /** Macro to obtain descriptor index from USB_SREQ_GET_DESCRIPTOR request */ 256 #define USB_GET_DESCRIPTOR_INDEX(wValue) ((uint8_t)(wValue)) 257 258 /** USB Control Endpoints OUT and IN Address */ 259 #define USB_CONTROL_EP_OUT 0 260 #define USB_CONTROL_EP_IN 0x80 261 262 /** USB Control Endpoints maximum packet size (MPS) */ 263 #define USB_CONTROL_EP_MPS 64 264 265 #ifdef __cplusplus 266 } 267 #endif 268 269 #endif /* ZEPHYR_INCLUDE_USB_CH9_H_ */ 270
