1/** 2 * \brief this file contains definitions for the standard USB descriptors 3 */ 4 5/* 6 * Copyright (c) 2007-2013 ETH Zurich. 7 * All rights reserved. 8 * 9 * This file is distributed under the terms in the attached LICENSE file. 10 * If you do not find this file, copies can be found by writing to: 11 * ETH Zurich D-INFK, Haldeneggsteig 4, CH-8092 Zurich. Attn: Systems Group. 12 */ 13 14#ifndef _USB_DESCRIPTOR_H_ 15#define _USB_DESCRIPTOR_H_ 16 17#include <stdint.h> 18 19//USB descriptor codes (USB Specification, Rev 2.0, Table 9.5) 20#define USB_DESCRIPTOR_TYPE_DEVICE 1 21#define USB_DESCRIPTOR_TYPE_CONFIG 2 22#define USB_DESCRIPTOR_TYPE_STRING 3 23#define USB_DESCRIPTOR_TYPE_INTERFACE 4 24#define USB_DESCRIPTOR_TYPE_ENDPOINT 5 25#define USB_DESCRIPTOR_TYPE_DEVICE_QUALIFIER 6 26#define USB_DESCRIPTOR_TYPE_OTHER_SPEED_CONFIG 7 27#define USB_DESCRIPTOR_TYPE_INTERFACE_POWER 8 28#define USB_DESCRIPTOR_TYPE_OTG 9 29 30// USB Specification Release Numbers 31#define USB_RELEASE_NUMBER_10 0x0100 32#define USB_RELEASE_NUMBER_11 0x0110 33#define USB_RELEASE_NUMBER_20 0x0200 34#define USB_RELEASE_NUMBER_25 0x0250 35#define USB_RELEASE_NUMBER_30 0x0300 36 37// USB release number masks 38#define USB_RELEASE_NUMBER_MAJOR 0xFF00 39#define USB_RELEASE_NUMBER_MINOR 0x00F0 40#define USB_RELEASE_NUMBER_SUB 0x000F 41 42/** 43 * ------------------------------------------------------------------------ 44 * USB Generic Descriptor 45 * ------------------------------------------------------------------------ 46 */ 47struct usb_descriptor { 48 uint8_t bLength; ///< the length of this descriptor 49 uint8_t bDescriptorType; ///< the type of this descriptor 50 uint8_t bDescriptorSubType; ///< the subtype of this descritpor 51}__attribute__((packed)); 52 53/// type definition for the generic descriptor 54typedef struct usb_descriptor usb_descriptor_t; 55 56/** 57 * ------------------------------------------------------------------------ 58 * USB Device Descriptor (USB Specification, Rev 2.0, Section 9.6.1) 59 * ------------------------------------------------------------------------ 60 * General and global information about an USB device. Each USB device 61 * has exactly one usb_device_descriptor. 62 */ 63struct usb_device_descriptor { 64 uint8_t bLength; ///< the length of the descriptor (18 bytes) 65 uint8_t bDescriptorType; ///< always USB_DESCRIPTOR_TYPE_DEVICE 66 uint16_t bcdUSB; ///< the USB revision number 67 uint8_t bDeviceClass; ///< device class code (defined by USB-IF) 68 uint8_t bDeviceSubClass; ///< device sub class code (defined by USB-IF) 69 uint8_t bDeviceProtocol; ///< specific protocol used by this device 70 uint8_t bMaxPacketSize0; ///< the max packet size of endpoint 0 71 uint16_t idVendor; ///< the vendor ID 72 uint16_t idProduct; ///< the product ID 73 uint16_t bcdDevice; ///< the revision of the device 74 uint8_t iManufacturer; ///< string index of the manufacturer 75 uint8_t iProduct; ///< string index of the product 76 uint8_t iSerialNumber; ///< string index of the serial number 77 uint8_t bNumConfigurations; ///< the number of configurations 78}; 79 80/// type definition of the device descriptor 81typedef struct usb_device_descriptor usb_device_descriptor_t; 82 83/// size information of the device descriptor 84#define USB_DEVICE_DESCRIPTOR_SIZE 18 85 86/** 87 * ------------------------------------------------------------------------ 88 * USB Device Qualifier Descriptor (USB Specification, Rev 2.0, Section 9.6.2) 89 * ------------------------------------------------------------------------ 90 * This descriptor contains information about a high-speed capable device 91 * that would change, if the device is operating at other speed: 92 * - device runs at full speed -> descriptor returns values for high speed. 93 */ 94struct usb_device_qualifier_descriptor { 95 uint8_t bLength; ///< should be 10 bytes 96 uint8_t bDescriptorType; ///< always USB_DESCRIPTOR_TYPE_DEVICE_QUALIFIER 97 uint16_t bcdUSB; ///< the USB revision 98 uint8_t bDeviceClass; ///< USB device class code (defined by USB-IF) 99 uint8_t bDeviceSubClass; ///< SB Device subclass code (defined by USB-IF) 100 uint8_t bDeviceProtocol; ///< the device protocol to be used 101 uint8_t bMaxPacketSize0; ///< maximum packet size of endpoint 0 102 uint8_t bNumConfigurations; ///< the number of configurations 103 uint8_t bReserved; ///< always zero 104}__attribute__((packed)); 105 106/// type definition of the qualifier descriptor 107typedef struct usb_device_qualifier_descriptor usb_device_qualifier_descriptor_t; 108 109// size information of the device qualifier descriptor 110#define USB_DEVICE_QUALIFIER_DESCRIPTOR_SIZE 10 111 112/** 113 * ------------------------------------------------------------------------ 114 * USB Configuration Descriptor (USB Specification, Rev 2.0, Section 9.6.3) 115 * ------------------------------------------------------------------------ 116 * This descriptor contains information about a specific device 117 * configuration. The bConfigurationValue is used as a parameter to 118 * SetConfiguration(). 119 * 120 * wTotalLength: the size of the entire configuration: 121 * config descriptor + interfaces + endpoints 122 * Each USB device has one or more configuration descriptors 123 */ 124struct usb_config_descriptor { 125 uint8_t bLength; ///< length of the descriptor in bytes 126 uint8_t bDescriptorType; ///< always USB_DESCRIPTOR_TYPE_CONFIG 127 uint16_t wTotalLength; ///< total length of this descritpor 128 uint8_t bNumInterfaces; ///< the number of interfaces in this config 129 uint8_t bConfigurationValue; ///< parameter for SetConfiguration() 130 uint8_t iConfiguration; ///< string index of this configuration 131 uint8_t bmAttributes; ///< configuration characteristics 132 uint8_t bMaxPower; ///< the maximum power consumption (2mA steps) 133}__attribute__((packed)); 134 135typedef struct usb_config_descriptor usb_config_descriptor_t; 136 137// size information of the configuration descriptor 138#define USB_CONFIG_DESCRIPTOR_SIZE 9 139 140// values for the bit map 141#define USB_CONFIG_SELF_POWERED 0x40 142#define USB_CONFIG_REMOTE_WAKEUP 0x20 143#define USB_CONFIG_BUS_POWERED 0x80 144 145/** 146 * ------------------------------------------------------------------------ 147 * USB Interface Descriptor (USB Specification, Rev 2.0, Section 9.6.5) 148 * ------------------------------------------------------------------------ 149 * This descriptor contains information about a specific interface within 150 * an USB configuration. The interface descriptor defines an unique set 151 * of endpoints within the configuration. 152 * 153 * Interface descriptors cannot directly be accesses by Get/SetDescriptor(), 154 * they are returned as a part of the configuration descriptor. 155 */ 156struct usb_interface_descriptor { 157 uint8_t bLength; ///< should be 9 bytes 158 uint8_t bDescriptorType; ///< always USB_DESCRIPTOR_TYPE_INTERFACE 159 uint8_t bInterfaceNumber; ///< number of this interface within the config 160 uint8_t bAlternateSetting; ///< the alternate setting 161 uint8_t bNumEndpoints; ///< number of used endpoints in this interface 162 uint8_t bInterfaceClass; ///< interface class code (assigned by USB-IF) 163 uint8_t bInterfaceSubClass; ///< interface subclass code (assigned by USB-IF) 164 uint8_t bInterfaceProtocol; ///< protocol code (qualified by class/subclass) 165 uint8_t iInterface; ///< string index describing this interface 166}__attribute__((packed)); 167 168/// type definition for the interface descriptor 169typedef struct usb_interface_descriptor usb_interface_descriptor_t; 170 171// size information about the interface descriptor 172#define USB_INTERFACE_DESCRIPTOR_SIZE 9 173 174 175struct usb_endpoint_address { 176 uint8_t ep_number :4; ///< the endpoint number 177 uint8_t _reserved :3; ///< should be zero 178 uint8_t direction :1; ///< direction, either IN or OUT 179}; 180typedef struct usb_endpoint_address usb_endpoint_address_t; 181 182struct usb_endpoint_attributes { 183 uint8_t xfer_type :2; ///< the type of this endpoint 184 uint8_t sync_type :2; ///< for isochronus only 185 uint8_t usage_type :2; ///< for isochronous only 186 uint8_t _unused :2; ///< should be zero 187}; 188typedef struct usb_endpoint_attributes usb_endpoint_attributes_t; 189 190/** 191 * ------------------------------------------------------------------------ 192 * USB Endpoint Descriptor (USB Specification, Rev 2.0, Section 9.6.6) 193 * ------------------------------------------------------------------------ 194 * This descriptor contains information about one endpoint for an interface. 195 * Endpoint descriptors are always returned as part of the configuration 196 * Information by GetConfiguration(). 197 * 198 * Each endpoint has its own endpoint descriptor. 199 */ 200struct usb_endpoint_descriptor { 201 uint8_t bLength; ///< should be 9 bytes 202 uint8_t bDescriptorType; ///< always USB_DESCRIPTOR_TYPE_ENDPOINT 203 usb_endpoint_address_t bEndpointAddress; 204 usb_endpoint_attributes_t bmAttributes; 205 uint16_t wMaxPacketSize; ///< maximum packet size for this endpoint 206 uint8_t bInterval; ///< interval for polling in (micro)frames 207}__attribute__((packed)); 208 209typedef struct usb_endpoint_descriptor usb_endpoint_descriptor_t; 210 211// size information of endpoint descriptor 212#define USB_ENDPOINT_DESCRIPTOR_SIZE 9 213 214/// used for endpoint lookup 215#define USB_ENDPOINT_ADDRESS_ANY 0xFF 216 217// endpoint directions 218#define USB_ENDPOINT_DIRECTION_OUT 0x00 219#define USB_ENDPOINT_DIRECTION_IN 0x01 220#define USB_ENDPOINT_DIRECTION_ANY 0xFF 221 222// endpoint types 223#define USB_ENDPOINT_TYPE_CONTROL 0x00 224#define USB_ENDPOINT_TYPE_ISOCHR 0x01 225#define USB_ENDPOINT_TYPE_BULK 0x02 226#define USB_ENDPOINT_TYPE_INTR 0x03 227#define USB_ENDPOINT_TYPE_ANY 0xFF 228 229// endpoint synchronization for isochronus transfers 230#define USB_ENDPOINT_SYNC_NON_ISO 0x00 231#define USB_ENDPOINT_SYNC_NONE 0x00 232#define USB_ENDPOINT_SYNC_ASYNC 0x04 233#define USB_ENDPOINT_SYNC_ADAPT 0x08 234#define USB_ENDPOINT_SYNC_SYNC 0x0A 235 236// endpoint usages for isochronus transfers 237#define USB_ENDPOINT_USAGE_NON_ISO 0x00 238#define USB_ENDPOINT_USAGE_DATA 0x00 239#define USB_ENDPOINT_USAGE_FEEDBACK 0x10 240#define USB_ENDPOINT_USAGE_IMPLICIT 0x20 241#define USB_ENDPOINT_USAGE_RESERVED 0x30 242 243/** 244 * ------------------------------------------------------------------------ 245 * USB String Descriptor (USB Specification, Rev 2.0, Section 9.6.7) 246 * ------------------------------------------------------------------------ 247 * String descriptors contains string describing certain elements of other 248 * USB descriptors. String descriptors are optional. All references to 249 * string descriptors are set to zero if they are not implemented by 250 * the device 251 * 252 * The strings are encoded using UNICODE and are NOT null terminated. 253 */ 254struct usb_string_descriptor_languages { 255 uint8_t bLength; ///< length of the descriptor in bytes 256 uint8_t bDescriptorType; ///< always USB_DESCRIPTOR_TYPE_STRING 257 uint16_t wLangID[128]; ///< language ID code 258}__attribute__((packed)); 259 260typedef struct usb_string_descriptor_languages usb_string_descriptor_languages_t; 261 262struct usb_string_descriptor { 263 uint8_t bLength; ///< length of the descriptor in bytes 264 uint8_t bDescriptorType; ///< always USB_DESCRIPTOR_TYPE_STRING 265 char bString[256]; ///< char array containing the string (not null term.) 266}__attribute__((packed)); 267 268typedef struct usb_string_descriptor usb_string_descriptor_t; 269 270#define USB_STRING_GET_ELEMENT_COUNT(sd) ((sd->bLength -2 )/2) 271#define USB_STRING_GET_STRLEN(sd) ((sd->bLength -2 )) 272 273/** 274 * ------------------------------------------------------------------------ 275 * USB Generic Descriptor 276 * ------------------------------------------------------------------------ 277 * This descriptor is used to supply the device driver with all the necessary 278 * information upon initialization and connection to the usb manager. 279 * 280 * A request for a configuration descriptor returns the configuration 281 * descriptor, all interface descriptors, and endpoint descriptors for all of 282 * the interfaces in a single request. The first interface descriptor follows 283 * the configuration descriptor. The endpoint descriptors for the first 284 * interface follow the first interface descriptor. If there are additional 285 * interfaces, their interface descriptor and endpoint descriptors follow the 286 * first interface���s endpoint descriptors. 287 */ 288struct usb_generic_descriptor { 289 struct usb_device_descriptor device; 290 struct usb_config_descriptor config; 291 struct usb_interface_descriptor iface[1]; 292 struct usb_endpoint_descriptor endpoint[1]; 293}; 294 295typedef struct usb_generic_descriptor usb_generic_descriptor_t; 296 297#endif 298