1 /* 2 * SPDX-FileCopyrightText: 2015,2016 Intel Corporation 3 * SPDX-FileContributor: 2017 PHYTEC Messtechnik GmbH 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 */ 7 8 /** 9 * @file 10 * @brief useful constants and macros for the USB application 11 * 12 * This file contains useful constants and macros for the USB applications. 13 */ 14 15 #pragma once 16 17 #include <stdint.h> 18 #include <sys/cdefs.h> 19 20 #ifdef __cplusplus 21 extern "C" { 22 #endif 23 24 #define BCD(x) ((((x) / 10) << 4) | ((x) / 10)) 25 26 /* Descriptor size in bytes */ 27 #define USB_DEVICE_DESC_SIZE 18 28 #define USB_CONFIGURATION_DESC_SIZE 9 29 #define USB_INTERFACE_DESC_SIZE 9 30 #define USB_ENDPOINT_DESC_SIZE 7 31 #define USB_STRING_DESC_SIZE 4 32 #define USB_HID_DESC_SIZE 9 33 #define USB_DFU_DESC_SIZE 9 34 #define USB_DEVICE_QUAL_DESC_SIZE 10 35 #define USB_INTERFACE_ASSOC_DESC_SIZE 8 36 37 /* Descriptor type */ 38 #define USB_DEVICE_DESC 0x01 39 #define USB_CONFIGURATION_DESC 0x02 40 #define USB_STRING_DESC 0x03 41 #define USB_INTERFACE_DESC 0x04 42 #define USB_ENDPOINT_DESC 0x05 43 #define USB_DEVICE_QUAL_DESC 0x06 44 #define USB_INTERFACE_ASSOC_DESC 0x0B 45 #define USB_DEVICE_CAPABILITY_DESC 0x10 46 #define USB_HID_DESC 0x21 47 #define USB_HID_REPORT_DESC 0x22 48 #define USB_DFU_FUNCTIONAL_DESC 0x21 49 #define USB_ASSOCIATION_DESC 0x0B 50 #define USB_BINARY_OBJECT_STORE_DESC 0x0F 51 52 /* Useful define */ 53 #define USB_1_1 0x0110 54 #define USB_2_0 0x0200 55 /* Set USB version to 2.1 so that the host will request the BOS descriptor */ 56 #define USB_2_1 0x0210 57 58 #define BCDDEVICE_RELNUM (BCD(KERNEL_VERSION_MAJOR) << 8 | \ 59 BCD(KERNEL_VERSION_MINOR)) 60 61 /* 100mA max power, per 2mA units */ 62 /* USB 1.1 spec indicates 100mA(max) per unit load, up to 5 loads */ 63 #define MAX_LOW_POWER 0x32 64 #define MAX_HIGH_POWER 0xFA 65 66 /* bmAttributes: 67 * D7:Reserved, always 1, 68 * D6:Self-Powered -> 1, 69 * D5:Remote Wakeup -> 0, 70 * D4...0:Reserved -> 0 71 */ 72 #define USB_CONFIGURATION_ATTRIBUTES 0xC0 73 74 /* Classes */ 75 #define COMMUNICATION_DEVICE_CLASS 0x02 76 #define COMMUNICATION_DEVICE_CLASS_DATA 0x0A 77 #define HID_CLASS 0x03 78 #define MASS_STORAGE_CLASS 0x08 79 #define WIRELESS_DEVICE_CLASS 0xE0 80 #define MISC_CLASS 0xEF 81 #define CUSTOM_CLASS 0xFF 82 #define DFU_DEVICE_CLASS 0xFE 83 84 /* Sub-classes */ 85 #define CDC_NCM_SUBCLASS 0x0d 86 #define BOOT_INTERFACE_SUBCLASS 0x01 87 #define SCSI_TRANSPARENT_SUBCLASS 0x06 88 #define DFU_INTERFACE_SUBCLASS 0x01 89 #define RF_SUBCLASS 0x01 90 #define CUSTOM_SUBCLASS 0xFF 91 #define COMMON_SUBCLASS 0x02 92 /* Misc subclasses */ 93 #define MISC_RNDIS_SUBCLASS 0x04 94 #define CDC_ABSTRACT_CONTROL_MODEL 0x02 95 96 /* Protocols */ 97 #define V25TER_PROTOCOL 0x01 98 #define MOUSE_PROTOCOL 0x02 99 #define BULK_ONLY_PROTOCOL 0x50 100 #define DFU_RUNTIME_PROTOCOL 0x01 101 #define DFU_MODE_PROTOCOL 0x02 102 #define BLUETOOTH_PROTOCOL 0x01 103 /* CDC ACM protocols */ 104 #define ACM_VENDOR_PROTOCOL 0xFF 105 /* Misc protocols */ 106 #define MISC_ETHERNET_PROTOCOL 0x01 107 #define IAD_PROTOCOL 0x01 108 109 /** Standard Device Descriptor */ 110 struct usb_device_descriptor { 111 uint8_t bLength; 112 uint8_t bDescriptorType; 113 uint16_t bcdUSB; 114 uint8_t bDeviceClass; 115 uint8_t bDeviceSubClass; 116 uint8_t bDeviceProtocol; 117 uint8_t bMaxPacketSize0; 118 uint16_t idVendor; 119 uint16_t idProduct; 120 uint16_t bcdDevice; 121 uint8_t iManufacturer; 122 uint8_t iProduct; 123 uint8_t iSerialNumber; 124 uint8_t bNumConfigurations; 125 } __packed; 126 127 /** Unicode (UTF16LE) String Descriptor */ 128 struct usb_string_descriptor { 129 uint8_t bLength; 130 uint8_t bDescriptorType; 131 uint16_t bString; 132 } __packed; 133 134 /** Association Descriptor */ 135 struct usb_association_descriptor { 136 uint8_t bLength; 137 uint8_t bDescriptorType; 138 uint8_t bFirstInterface; 139 uint8_t bInterfaceCount; 140 uint8_t bFunctionClass; 141 uint8_t bFunctionSubClass; 142 uint8_t bFunctionProtocol; 143 uint8_t iFunction; 144 } __packed; 145 146 /** Standard Configuration Descriptor */ 147 struct usb_cfg_descriptor { 148 uint8_t bLength; 149 uint8_t bDescriptorType; 150 uint16_t wTotalLength; 151 uint8_t bNumInterfaces; 152 uint8_t bConfigurationValue; 153 uint8_t iConfiguration; 154 uint8_t bmAttributes; 155 uint8_t bMaxPower; 156 } __packed; 157 158 /** Standard Interface Descriptor */ 159 struct usb_if_descriptor { 160 uint8_t bLength; 161 uint8_t bDescriptorType; 162 uint8_t bInterfaceNumber; 163 uint8_t bAlternateSetting; 164 uint8_t bNumEndpoints; 165 uint8_t bInterfaceClass; 166 uint8_t bInterfaceSubClass; 167 uint8_t bInterfaceProtocol; 168 uint8_t iInterface; 169 } __packed; 170 171 /** Standard Endpoint Descriptor */ 172 struct usb_ep_descriptor { 173 uint8_t bLength; 174 uint8_t bDescriptorType; 175 uint8_t bEndpointAddress; 176 uint8_t bmAttributes; 177 uint16_t wMaxPacketSize; 178 uint8_t bInterval; 179 } __packed; 180 181 struct string_descriptor_zero { 182 uint8_t bLength; 183 uint8_t bDescriptorType; 184 uint16_t wBcdLang[]; 185 } __packed; 186 187 struct string_descriptor { 188 uint8_t bLength; 189 uint8_t bDescriptorType; 190 uint16_t bString[]; 191 } __packed; 192 193 #define ROM_MAX_CFG_DESC_CNT 1 194 195 struct rom_usb_descriptors { 196 const struct usb_device_descriptor *device_descr; 197 const void *config_descr[ROM_MAX_CFG_DESC_CNT]; 198 int string_count; // including string_descriptor_zero 199 const struct string_descriptor_zero *string0_descr; 200 const struct string_descriptor *string_descrs[]; 201 }; 202 203 /* Descriptors defined in the ROM */ 204 extern struct usb_device_descriptor general_device_descr; 205 extern const void* acm_config_descr; 206 extern const void* dfu_config_descr; 207 extern const struct string_descriptor str_manu_descr; 208 extern const struct string_descriptor str_prod_descr; 209 extern const struct string_descriptor_zero string0_descr; 210 extern const struct rom_usb_descriptors acm_usb_descriptors; 211 extern const struct rom_usb_descriptors dfu_usb_descriptors; 212 extern const struct rom_usb_descriptors *rom_usb_curr_desc; 213 214 /* ROM patch: set the ACM descriptor with the correct serial number. 215 * Only needed on ESP32-S2, on later chips the ROM descriptor is correct. 216 */ 217 void rom_usb_cdc_set_descriptor_patch(void); 218 219 220 #ifdef __cplusplus 221 } 222 #endif 223
