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