1 /* Copyright 2013 The ChromiumOS Authors 2 * Use of this source code is governed by a BSD-style license that can be 3 * found in the LICENSE file. 4 * 5 * USB definitions. 6 */ 7 8 #ifndef __CROS_EC_USB_DESCRIPTOR_H 9 #define __CROS_EC_USB_DESCRIPTOR_H 10 11 #include <stddef.h> /* for wchar_t */ 12 13 #define USB_MAX_PACKET_SIZE 64 14 15 /* USB 2.0 chapter 9 definitions */ 16 17 /* Descriptor types */ 18 #define USB_DT_DEVICE 0x01 19 #define USB_DT_CONFIGURATION 0x02 20 #define USB_DT_STRING 0x03 21 #define USB_DT_INTERFACE 0x04 22 #define USB_DT_ENDPOINT 0x05 23 #define USB_DT_DEVICE_QUALIFIER 0x06 24 #define USB_DT_OTHER_SPEED_CONFIG 0x07 25 #define USB_DT_INTERFACE_POWER 0x08 26 #define USB_DT_DEBUG 0x0a 27 #define USB_DT_BOS 0x0f 28 #define USB_DT_DEVICE_CAPABILITY 0x10 29 30 /* USB Device Descriptor */ 31 struct usb_device_descriptor { 32 uint8_t bLength; 33 uint8_t bDescriptorType; 34 uint16_t bcdUSB; 35 uint8_t bDeviceClass; 36 uint8_t bDeviceSubClass; 37 uint8_t bDeviceProtocol; 38 uint8_t bMaxPacketSize0; 39 uint16_t idVendor; 40 uint16_t idProduct; 41 uint16_t bcdDevice; 42 uint8_t iManufacturer; 43 uint8_t iProduct; 44 uint8_t iSerialNumber; 45 uint8_t bNumConfigurations; 46 } __packed; 47 #define USB_DT_DEVICE_SIZE 18 48 49 /* BOS Descriptor ( USB3.1 rev1 Section 9.6.2 ) */ 50 struct bos_context { 51 void *descp; 52 int size; 53 }; 54 55 struct usb_bos_hdr_descriptor { 56 uint8_t bLength; 57 uint8_t bDescriptorType; /* USB_DT_BOS */ 58 uint16_t wTotalLength; /* Total length of of hdr + all dev caps */ 59 uint8_t bNumDeviceCaps; /* Container ID Descriptor + others */ 60 } __packed; 61 #define USB_DT_BOS_SIZE 5 62 63 /* Container ID Descriptor */ 64 struct usb_contid_caps_descriptor { 65 uint8_t bLength; 66 uint8_t bDescriptorType; /* USB_DT_DEVICE_CAPABILITY */ 67 uint8_t bDevCapabilityType; /* USB_DC_DTYPE_xxx */ 68 uint8_t bReserved; /* SBZ */ 69 uint8_t ContainerID[16]; /* UUID */ 70 } __packed; 71 #define USB_DT_CONTID_SIZE 20 72 73 /* Device Cap Type Codes ( offset 2 of Device Capability Descriptor */ 74 #define USB_DC_DTYPE_WIRELESS 0x01 75 #define USB_DC_DTYPE_USB20EXT 0x02 76 #define USB_DC_DTYPE_USBSS 0x03 77 #define USB_DC_DTYPE_CONTID 0x04 78 #define USB_DC_DTYPE_PLATFORM 0x05 79 #define USB_DC_DTYPE_PD 0x06 80 #define USB_DC_DTYPE_BATTINFO 0x07 81 #define USB_DC_DTYPE_CONSUMER 0x08 82 #define USB_DC_DTYPE_PRODUCER 0x09 83 #define USB_DC_DTYPE_USBSSP 0x0a 84 #define USB_DC_DTYPE_PCSTIME 0x0b 85 #define USB_DC_DTYPE_WUSBEXT 0x0c 86 #define USB_DC_DTYPE_BILLBOARD 0x0d 87 /* RESERVED 0x00, 0xOe - 0xff */ 88 89 /* Platform descriptor */ 90 struct usb_platform_descriptor { 91 uint8_t bLength; 92 uint8_t bDescriptorType; /* USB_DT_DEVICE_CAPABILITY */ 93 uint8_t bDevCapabilityType; /* USB_DC_DTYPE_PLATFORM */ 94 uint8_t bReserved; /* SBZ */ 95 uint8_t PlatformCapUUID[16]; /* USB_PLAT_CAP_xxx */ 96 uint16_t bcdVersion; /* 0x0100 */ 97 uint8_t bVendorCode; 98 uint8_t iLandingPage; 99 } __packed; 100 #define USB_DT_PLATFORM_SIZE 24 101 102 /* Platform Capability UUIDs */ 103 #define USB_PLAT_CAP_WEBUSB /*{3408b638-09a9-47a0-8bfd-a0768815b665}*/ \ 104 {0x38, 0xB6, 0x08, 0x34, 0xA9, 0x09, 0xA0, 0x47, \ 105 0x8B, 0xFD, 0xA0, 0x76, 0x88, 0x15, 0xB6, 0x65} 106 107 /* Qualifier Descriptor */ 108 struct usb_qualifier_descriptor { 109 uint8_t bLength; 110 uint8_t bDescriptorType; 111 uint16_t bcdUSB; 112 uint8_t bDeviceClass; 113 uint8_t bDeviceSubClass; 114 uint8_t bDeviceProtocol; 115 uint8_t bMaxPacketSize0; 116 uint8_t bNumConfigurations; 117 uint8_t bReserved; 118 } __packed; 119 #define USB_DT_QUALIFIER_SIZE 10 120 121 /* Configuration Descriptor */ 122 struct usb_config_descriptor { 123 uint8_t bLength; 124 uint8_t bDescriptorType; 125 uint16_t wTotalLength; 126 uint8_t bNumInterfaces; 127 uint8_t bConfigurationValue; 128 uint8_t iConfiguration; 129 uint8_t bmAttributes; 130 uint8_t bMaxPower; 131 } __packed; 132 #define USB_DT_CONFIG_SIZE 9 133 134 /* String Descriptor */ 135 struct usb_string_descriptor { 136 uint8_t bLength; 137 uint8_t bDescriptorType; 138 uint16_t wData[1]; 139 } __packed; 140 141 /* Interface Descriptor */ 142 struct usb_interface_descriptor { 143 uint8_t bLength; 144 uint8_t bDescriptorType; 145 uint8_t bInterfaceNumber; 146 uint8_t bAlternateSetting; 147 uint8_t bNumEndpoints; 148 uint8_t bInterfaceClass; 149 uint8_t bInterfaceSubClass; 150 uint8_t bInterfaceProtocol; 151 uint8_t iInterface; 152 } __packed; 153 #define USB_DT_INTERFACE_SIZE 9 154 155 /* Endpoint Descriptor */ 156 struct usb_endpoint_descriptor { 157 uint8_t bLength; 158 uint8_t bDescriptorType; 159 uint8_t bEndpointAddress; 160 uint8_t bmAttributes; 161 uint16_t wMaxPacketSize; 162 uint8_t bInterval; 163 } __packed; 164 #define USB_DT_ENDPOINT_SIZE 7 165 166 /* USB Class codes */ 167 #define USB_CLASS_PER_INTERFACE 0x00 168 #define USB_CLASS_AUDIO 0x01 169 #define USB_CLASS_COMM 0x02 170 #define USB_CLASS_HID 0x03 171 #define USB_CLASS_PHYSICAL 0x05 172 #define USB_CLASS_STILL_IMAGE 0x06 173 #define USB_CLASS_PRINTER 0x07 174 #define USB_CLASS_MASS_STORAGE 0x08 175 #define USB_CLASS_HUB 0x09 176 #define USB_CLASS_CDC_DATA 0x0a 177 #define USB_CLASS_CSCID 0x0b 178 #define USB_CLASS_CONTENT_SEC 0x0d 179 #define USB_CLASS_VIDEO 0x0e 180 #define USB_CLASS_BILLBOARD 0x11 181 #define USB_CLASS_WIRELESS_CONTROLLER 0xe0 182 #define USB_CLASS_MISC 0xef 183 #define USB_CLASS_APP_SPEC 0xfe 184 #define USB_CLASS_VENDOR_SPEC 0xff 185 186 /* USB Vendor ID assigned to Google Inc. */ 187 #define USB_VID_GOOGLE 0x18d1 188 189 /* Google specific SubClass/Protocol assignments */ 190 #define USB_SUBCLASS_GOOGLE_SERIAL 0x50 191 #define USB_PROTOCOL_GOOGLE_SERIAL 0x01 192 193 #define USB_SUBCLASS_GOOGLE_SPI 0x51 194 #ifdef CONFIG_USB_SPI_V2 195 #define USB_PROTOCOL_GOOGLE_SPI 0x02 196 #else 197 #define USB_PROTOCOL_GOOGLE_SPI 0x01 198 #endif 199 200 #define USB_SUBCLASS_GOOGLE_I2C 0x52 201 #define USB_PROTOCOL_GOOGLE_I2C 0x01 202 203 #define USB_SUBCLASS_GOOGLE_UPDATE 0x53 204 #define USB_PROTOCOL_GOOGLE_UPDATE 0xff 205 206 /* Double define for cr50 code freeze. 207 * TODO(vbendeb): dedupe this. */ 208 #define USB_SUBCLASS_GOOGLE_CR50 0x53 209 /* We can use any protocol we want */ 210 #define USB_PROTOCOL_GOOGLE_CR50_NON_HC_FW_UPDATE 0xff 211 212 #define USB_SUBCLASS_GOOGLE_POWER 0x54 213 #define USB_PROTOCOL_GOOGLE_POWER 0x01 214 215 #define USB_SUBCLASS_GOOGLE_HEATMAP 0x55 216 #define USB_PROTOCOL_GOOGLE_HEATMAP 0x01 217 218 /* Control requests */ 219 220 /* bRequestType fields */ 221 /* direction field */ 222 #define USB_DIR_OUT 0 /* from host to uC */ 223 #define USB_DIR_IN 0x80 /* from uC to host */ 224 /* type field */ 225 #define USB_TYPE_MASK (0x03 << 5) 226 #define USB_TYPE_STANDARD (0x00 << 5) 227 #define USB_TYPE_CLASS (0x01 << 5) 228 #define USB_TYPE_VENDOR (0x02 << 5) 229 #define USB_TYPE_RESERVED (0x03 << 5) 230 /* recipient field */ 231 #define USB_RECIP_MASK 0x1f 232 #define USB_RECIP_DEVICE 0x00 233 #define USB_RECIP_INTERFACE 0x01 234 #define USB_RECIP_ENDPOINT 0x02 235 #define USB_RECIP_OTHER 0x03 236 237 /* Standard requests for bRequest field in a SETUP packet. */ 238 #define USB_REQ_GET_STATUS 0x00 239 #define USB_REQ_GET_STATUS_SELF_POWERED BIT(0) 240 #define USB_REQ_GET_STATUS_REMOTE_WAKEUP BIT(1) 241 #define USB_REQ_CLEAR_FEATURE 0x01 242 #define USB_REQ_SET_FEATURE 0x03 243 #define USB_REQ_FEATURE_ENDPOINT_HALT 0x0000 244 #define USB_REQ_FEATURE_DEVICE_REMOTE_WAKEUP 0x0001 245 #define USB_REQ_FEATURE_TEST_MODE 0x0002 246 #define USB_REQ_SET_ADDRESS 0x05 247 #define USB_REQ_GET_DESCRIPTOR 0x06 248 #define USB_REQ_SET_DESCRIPTOR 0x07 249 #define USB_REQ_GET_CONFIGURATION 0x08 250 #define USB_REQ_SET_CONFIGURATION 0x09 251 #define USB_REQ_GET_INTERFACE 0x0A 252 #define USB_REQ_SET_INTERFACE 0x0B 253 #define USB_REQ_SYNCH_FRAME 0x0C 254 255 /* WebUSB URL descriptors */ 256 #define WEBUSB_REQ_GET_URL 0x02 257 #define USB_DT_WEBUSB_URL 0x03 258 259 #define USB_URL_SCHEME_HTTP 0x00 260 #define USB_URL_SCHEME_HTTPS 0x01 261 #define USB_URL_SCHEME_NONE 0xff 262 263 /* 264 * URL descriptor helper. 265 * (similar to string descriptor but UTF-8 instead of UTF-16) 266 */ 267 #define USB_URL_DESC(scheme, str) \ 268 (const void *)&(const struct { \ 269 uint8_t _len; \ 270 uint8_t _type; \ 271 uint8_t _scheme; \ 272 char _data[sizeof(str)]; \ 273 }) { \ 274 /* Total size of the descriptor is : \ 275 * size of the UTF-8 text plus the len/type fields \ 276 * minus the string 0-termination \ 277 */ \ 278 sizeof(str) + 3 - 1, \ 279 USB_DT_WEBUSB_URL, \ 280 USB_URL_SCHEME_##scheme, \ 281 str \ 282 } 283 284 /* Setup Packet */ 285 struct usb_setup_packet { 286 uint8_t bmRequestType; 287 uint8_t bRequest; 288 uint16_t wValue; 289 uint16_t wIndex; 290 uint16_t wLength; 291 }; 292 293 /* Helpers for descriptors */ 294 295 #define WIDESTR(quote) WIDESTR2(quote) 296 #define WIDESTR2(quote) L##quote 297 298 #define USB_STRING_DESC(str) \ 299 (const void *)&(const struct { \ 300 uint8_t _len; \ 301 uint8_t _type; \ 302 wchar_t _data[sizeof(str)]; \ 303 }) { \ 304 /* Total size of the descriptor is : \ 305 * size of the UTF-16 text plus the len/type fields \ 306 * minus the string 0-termination \ 307 */ \ 308 sizeof(WIDESTR(str)) + 2 - 2, \ 309 USB_DT_STRING, \ 310 WIDESTR(str) \ 311 } 312 313 #ifdef CONFIG_USB_SERIALNO 314 /* String Descriptor for USB, for editable strings. */ 315 #define USB_STRING_LEN 28 316 struct usb_string_desc { 317 uint8_t _len; 318 uint8_t _type; 319 wchar_t _data[USB_STRING_LEN]; 320 }; 321 #define USB_WR_STRING_DESC(str) \ 322 (&(struct usb_string_desc) { \ 323 /* As above, two bytes metadata, no null terminator. */ \ 324 sizeof(WIDESTR(str)) + 2 - 2, \ 325 USB_DT_STRING, \ 326 WIDESTR(str) \ 327 }) 328 extern struct usb_string_desc *usb_serialno_desc; 329 #endif 330 331 /* Use these macros for declaring descriptors, to order them properly */ 332 #define USB_CONF_DESC_VAR(name, varname) varname \ 333 __keep __attribute__((section(".rodata.usb_desc_" STRINGIFY(name)))) 334 #define USB_CONF_DESC(name) USB_CONF_DESC_VAR(name, CONCAT2(usb_desc_, name)) 335 #define USB_IFACE_DESC(num) USB_CONF_DESC(CONCAT3(iface, num, _0iface)) 336 #define USB_CUSTOM_DESC_VAR(i, name, varname) \ 337 USB_CONF_DESC_VAR(CONCAT4(iface, i, _1, name), varname) 338 #define USB_CUSTOM_DESC(i, name) USB_CONF_DESC(CONCAT4(iface, i, _1, name)) 339 #define USB_EP_DESC(i, num) USB_CONF_DESC(CONCAT4(iface, i, _2ep, num)) 340 341 /* USB Linker data */ 342 extern const uint8_t __usb_desc[]; 343 extern const uint8_t __usb_desc_end[]; 344 #define USB_DESC_SIZE (__usb_desc_end - __usb_desc) 345 346 /* These descriptors defined in board code */ 347 extern const void * const usb_strings[]; 348 extern const uint8_t usb_string_desc[]; 349 /* USB string descriptor with the firmware version */ 350 extern const void * const usb_fw_version; 351 extern const struct bos_context bos_ctx; 352 extern const void *webusb_url; 353 354 #endif /* __CROS_EC_USB_DESCRIPTOR_H */ 355