4 * This file is part of BeRTOS.
6 * Bertos is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
16 * You should have received a copy of the GNU General Public License
17 * along with this program; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
20 * As a special exception, you may use this file as part of a free software
21 * library without restriction. Specifically, if other files instantiate
22 * templates or use macros or inline functions from this file, or you compile
23 * this file and link it with other files to produce an executable, this
24 * file does not by itself cause the resulting executable to be covered by
25 * the GNU General Public License. This exception does not however
26 * invalidate any other reasons why the executable file might be covered by
27 * the GNU General Public License.
29 * Copyright 2010 Develer S.r.l. (http://www.develer.com/)
33 * \author Andrea Righi <arighi@develer.com>
35 * \brief USB 2.0 standard descriptors
37 * This file holds USB constants and structures that are needed for USB device
38 * APIs, as defined in the USB 2.0 specification.
40 * $WIZ$ module_name = "usb"
41 * $WIZ$ module_configuration = "bertos/cfg/cfg_usb.h"
42 * $WIZ$ module_supports = "stm32"
48 #include <cpu/byteorder.h>
51 * Handle CPU endianess
53 * TODO: consider to move this stuff in compiler.h
55 #define usb_bswap16(x) (((x & 0xff) << 8) | (x >> 8))
56 #define usb_bswap32(x) ((usb_bswap16(x & 0xffff) << 16) | usb_bswap16(x >> 16))
58 #if CPU_BYTE_ORDER == CPU_LITTLE_ENDIAN
59 #define usb_cpu_to_le16(x) (x)
60 #define usb_le16_to_cpu(x) (x)
61 #define usb_cpu_to_le32(x) (x)
62 #define usb_le32_to_cpu(x) (x)
63 #elif CPU_BYTE_ORDER == CPU_BIG_ENDIAN
64 #define usb_cpu_to_le16(x) usb_bswap16(x)
65 #define usb_le16_to_cpu(x) usb_bswap16(x)
66 #define usb_cpu_to_le32(x) usb_bswap32(x)
67 #define usb_le32_to_cpu(x) usb_bswap32(x)
69 #error "unrecognized CPU endianness"
72 /* State of a USB device */
73 enum usb_device_state {
74 USB_STATE_NOTATTACHED = 0,
76 /* chapter 9 device states */
78 USB_STATE_POWERED, /* wired */
79 USB_STATE_DEFAULT, /* limited function */
81 USB_STATE_CONFIGURED, /* most functions */
87 * This bit flag is used in endpoint descriptors' bEndpointAddress field.
88 * It's also one of three fields in control requests bRequestType.
90 #define USB_DIR_OUT 0 /* to device */
91 #define USB_DIR_IN 0x80 /* to host */
94 * USB types, the second of three bRequestType fields
96 #define USB_TYPE_MASK (0x03 << 5)
97 #define USB_TYPE_STANDARD (0x00 << 5)
98 #define USB_TYPE_CLASS (0x01 << 5)
99 #define USB_TYPE_VENDOR (0x02 << 5)
100 #define USB_TYPE_RESERVED (0x03 << 5)
103 * USB recipients, the third of three bRequestType fields
105 #define USB_RECIP_MASK 0x1f
106 #define USB_RECIP_DEVICE 0x00
107 #define USB_RECIP_INTERFACE 0x01
108 #define USB_RECIP_ENDPOINT 0x02
109 #define USB_RECIP_OTHER 0x03
112 * USB standard requests, for the bRequest field of a SETUP packet.
114 #define USB_REQ_GET_STATUS 0x00
115 #define USB_REQ_CLEAR_FEATURE 0x01
116 #define USB_REQ_SET_FEATURE 0x03
117 #define USB_REQ_SET_ADDRESS 0x05
118 #define USB_REQ_GET_DESCRIPTOR 0x06
119 #define USB_REQ_SET_DESCRIPTOR 0x07
120 #define USB_REQ_GET_CONFIGURATION 0x08
121 #define USB_REQ_SET_CONFIGURATION 0x09
122 #define USB_REQ_GET_INTERFACE 0x0A
123 #define USB_REQ_SET_INTERFACE 0x0B
124 #define USB_REQ_SYNCH_FRAME 0x0C
127 * Descriptor types ... USB 2.0 spec table 9.5
129 #define USB_DT_DEVICE 0x01
130 #define USB_DT_CONFIG 0x02
131 #define USB_DT_STRING 0x03
132 #define USB_DT_INTERFACE 0x04
133 #define USB_DT_ENDPOINT 0x05
134 #define USB_DT_DEVICE_QUALIFIER 0x06
135 #define USB_DT_OTHER_SPEED_CONFIG 0x07
136 #define USB_DT_INTERFACE_POWER 0x08
139 * Conventional codes for class-specific descriptors. The convention is
140 * defined in the USB "Common Class" Spec (3.11). Individual class specs
141 * are authoritative for their usage, not the "common class" writeup.
143 #define USB_DT_CS_DEVICE (USB_TYPE_CLASS | USB_DT_DEVICE)
144 #define USB_DT_CS_CONFIG (USB_TYPE_CLASS | USB_DT_CONFIG)
145 #define USB_DT_CS_STRING (USB_TYPE_CLASS | USB_DT_STRING)
146 #define USB_DT_CS_INTERFACE (USB_TYPE_CLASS | USB_DT_INTERFACE)
147 #define USB_DT_CS_ENDPOINT (USB_TYPE_CLASS | USB_DT_ENDPOINT)
150 * This structure is used to send control requests to a USB device.
152 * It matches the different fields of the USB 2.0 spec. section 9.3, table 9-2.
154 typedef struct usb_ctrlrequest
156 uint8_t mRequestType;
161 } PACKED usb_ctrlrequest_t;
163 /* All standard descriptors have these 2 fields at the beginning */
164 typedef struct usb_descriptor_header
167 uint8_t bDescriptorType;
168 } PACKED usb_descriptor_header_t;
170 /* Device descriptor */
171 typedef struct usb_device_descriptor
174 uint8_t bDescriptorType;
176 uint8_t bDeviceClass;
177 uint8_t bDeviceSubClass;
178 uint8_t bDeviceProtocol;
179 uint8_t bMaxPacketSize0;
183 uint8_t iManufacturer;
185 uint8_t iSerialNumber;
186 uint8_t bNumConfigurations;
187 } PACKED usb_device_descriptor_t;
189 /* USB string descriptor */
190 typedef struct usb_string_descriptor
193 uint8_t bDescriptorType;
195 } PACKED usb_string_descriptor_t;
198 * Macros to define USB strings
202 #define USB_STRING_1(__a, ...) __a "\x00"
203 #define USB_STRING_2(__a, ...) __a "\x00" USB_STRING_1(__VA_ARGS__)
204 #define USB_STRING_3(__a, ...) __a "\x00" USB_STRING_2(__VA_ARGS__)
205 #define USB_STRING_4(__a, ...) __a "\x00" USB_STRING_3(__VA_ARGS__)
206 #define USB_STRING_5(__a, ...) __a "\x00" USB_STRING_4(__VA_ARGS__)
207 #define USB_STRING_6(__a, ...) __a "\x00" USB_STRING_5(__VA_ARGS__)
208 #define USB_STRING_7(__a, ...) __a "\x00" USB_STRING_6(__VA_ARGS__)
209 #define USB_STRING_8(__a, ...) __a "\x00" USB_STRING_7(__VA_ARGS__)
210 #define USB_STRING_9(__a, ...) __a "\x00" USB_STRING_8(__VA_ARGS__)
211 #define USB_STRING_10(__a, ...) __a "\x00" USB_STRING_9(__VA_ARGS__)
212 #define USB_STRING_11(__a, ...) __a "\x00" USB_STRING_10(__VA_ARGS__)
213 #define USB_STRING_12(__a, ...) __a "\x00" USB_STRING_11(__VA_ARGS__)
214 #define USB_STRING_13(__a, ...) __a "\x00" USB_STRING_12(__VA_ARGS__)
215 #define USB_STRING_14(__a, ...) __a "\x00" USB_STRING_13(__VA_ARGS__)
216 #define USB_STRING_15(__a, ...) __a "\x00" USB_STRING_14(__VA_ARGS__)
217 #define USB_STRING_16(__a, ...) __a "\x00" USB_STRING_15(__VA_ARGS__)
219 #define USB_STRING(...) PP_CAT(USB_STRING_, PP_COUNT(__VA_ARGS__))(__VA_ARGS__)
221 #define DEFINE_USB_STRING(__name, __text) \
223 usb_descriptor_header_t __header; \
224 uint8_t __body[sizeof(__text)]; \
225 } PACKED __name = { \
227 .bLength = sizeof(__name), \
228 .bDescriptorType = USB_DT_STRING, \
230 .__body = {__text}, \
234 * Device and/or Interface Class codes as found in bDeviceClass or
235 * bInterfaceClass and defined by www.usb.org documents.
237 #define USB_CLASS_PER_INTERFACE 0 /* for DeviceClass */
238 #define USB_CLASS_AUDIO 1
239 #define USB_CLASS_COMM 2
240 #define USB_CLASS_HID 3
241 #define USB_CLASS_PHYSICAL 5
242 #define USB_CLASS_STILL_IMAGE 6
243 #define USB_CLASS_PRINTER 7
244 #define USB_CLASS_MASS_STORAGE 8
245 #define USB_CLASS_HUB 9
246 #define USB_CLASS_CDC_DATA 0x0a
247 #define USB_CLASS_CSCID 0x0b /* chip+ smart card */
248 #define USB_CLASS_CONTENT_SEC 0x0d /* content security */
249 #define USB_CLASS_VIDEO 0x0e
250 #define USB_CLASS_WIRELESS_CONTROLLER 0xe0
251 #define USB_CLASS_MISC 0xef
252 #define USB_CLASS_APP_SPEC 0xfe
253 #define USB_CLASS_VENDOR_SPEC 0xff
255 /* Device configuration descriptor */
256 typedef struct usb_config_descriptor
259 uint8_t bDescriptorType;
260 uint16_t wTotalLength;
261 uint8_t bNumInterfaces;
262 uint8_t bConfigurationValue;
263 uint8_t iConfiguration;
264 uint8_t bmAttributes;
266 } PACKED usb_config_descriptor_t;
268 /* from config descriptor bmAttributes */
269 #define USB_CONFIG_ATT_ONE (1 << 7) /* must be set */
270 #define USB_CONFIG_ATT_SELFPOWER (1 << 6) /* self powered */
271 #define USB_CONFIG_ATT_WAKEUP (1 << 5) /* can wakeup */
272 #define USB_CONFIG_ATT_BATTERY (1 << 4) /* battery powered */
274 /* Device interface descriptor */
275 typedef struct usb_interface_descriptor
278 uint8_t bDescriptorType;
279 uint8_t bInterfaceNumber;
280 uint8_t bAlternateSetting;
281 uint8_t bNumEndpoints;
282 uint8_t bInterfaceClass;
283 uint8_t bInterfaceSubClass;
284 uint8_t bInterfaceProtocol;
286 } PACKED usb_interface_descriptor_t;
288 /* Endpoint descriptor */
289 typedef struct usb_endpoint_descriptor
292 uint8_t bDescriptorType;
293 uint8_t bEndpointAddress;
294 uint8_t bmAttributes;
295 uint16_t wMaxPacketSize;
297 } PACKED usb_endpoint_descriptor_t;
302 #define USB_ENDPOINT_NUMBER_MASK 0x0f /* in bEndpointAddress */
303 #define USB_ENDPOINT_DIR_MASK 0x80
305 #define USB_ENDPOINT_SYNCTYPE 0x0c
306 #define USB_ENDPOINT_SYNC_NONE (0 << 2)
307 #define USB_ENDPOINT_SYNC_ASYNC (1 << 2)
308 #define USB_ENDPOINT_SYNC_ADAPTIVE (2 << 2)
309 #define USB_ENDPOINT_SYNC_SYNC (3 << 2)
311 #define USB_ENDPOINT_XFERTYPE_MASK 0x03 /* in bmAttributes */
312 #define USB_ENDPOINT_XFER_CONTROL 0
313 #define USB_ENDPOINT_XFER_ISOC 1
314 #define USB_ENDPOINT_XFER_BULK 2
315 #define USB_ENDPOINT_XFER_INT 3
316 #define USB_ENDPOINT_MAX_ADJUSTABLE 0x80
318 /* USB: generic device descriptor */
321 usb_device_descriptor_t *device;
322 usb_descriptor_header_t **config;
323 usb_string_descriptor_t **strings;
329 * usb_endpoint_num - get the endpoint's number
331 INLINE int usb_endpoint_num(const usb_endpoint_descriptor_t *epd)
333 return epd->bEndpointAddress & USB_ENDPOINT_NUMBER_MASK;
337 * usb_endpoint_type - get the endpoint's transfer type
339 INLINE int usb_endpoint_type(const struct usb_endpoint_descriptor *epd)
341 return epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK;
345 * usb_endpoint_dir_in - check if the endpoint has IN direction
347 INLINE int usb_endpoint_dir_in(const struct usb_endpoint_descriptor *epd)
349 return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_IN);
353 * usb_endpoint_dir_out - check if the endpoint has OUT direction
355 INLINE int usb_endpoint_dir_out(const struct usb_endpoint_descriptor *epd)
357 return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_OUT);
361 * usb_endpoint_xfer_bulk - check if the endpoint has bulk transfer type
363 INLINE int usb_endpoint_xfer_bulk(const struct usb_endpoint_descriptor *epd)
365 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
366 USB_ENDPOINT_XFER_BULK);
370 * usb_endpoint_xfer_control - check if the endpoint has control transfer type
372 INLINE int usb_endpoint_xfer_control(const struct usb_endpoint_descriptor *epd)
374 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
375 USB_ENDPOINT_XFER_CONTROL);
379 * usb_endpoint_xfer_int - check if the endpoint has interrupt transfer type
381 INLINE int usb_endpoint_xfer_int(const struct usb_endpoint_descriptor *epd)
383 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
384 USB_ENDPOINT_XFER_INT);
388 * usb_endpoint_xfer_isoc - check if the endpoint has isochronous transfer type
390 INLINE int usb_endpoint_xfer_isoc(const struct usb_endpoint_descriptor *epd)
392 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
393 USB_ENDPOINT_XFER_ISOC);
397 * usb_endpoint_is_bulk_in - check if the endpoint is bulk IN
399 INLINE int usb_endpoint_is_bulk_in(const struct usb_endpoint_descriptor *epd)
401 return usb_endpoint_xfer_bulk(epd) && usb_endpoint_dir_in(epd);
405 * usb_endpoint_is_bulk_out - check if the endpoint is bulk OUT
407 INLINE int usb_endpoint_is_bulk_out(const struct usb_endpoint_descriptor *epd)
409 return usb_endpoint_xfer_bulk(epd) && usb_endpoint_dir_out(epd);
413 * usb_endpoint_is_int_in - check if the endpoint is interrupt IN
415 INLINE int usb_endpoint_is_int_in(const struct usb_endpoint_descriptor *epd)
417 return usb_endpoint_xfer_int(epd) && usb_endpoint_dir_in(epd);
421 * usb_endpoint_is_int_out - check if the endpoint is interrupt OUT
423 INLINE int usb_endpoint_is_int_out(const struct usb_endpoint_descriptor *epd)
425 return usb_endpoint_xfer_int(epd) && usb_endpoint_dir_out(epd);
429 * usb_endpoint_is_isoc_in - check if the endpoint is isochronous IN
431 INLINE int usb_endpoint_is_isoc_in(const struct usb_endpoint_descriptor *epd)
433 return usb_endpoint_xfer_isoc(epd) && usb_endpoint_dir_in(epd);
437 * usb_endpoint_is_isoc_out - check if the endpoint is isochronous OUT
439 INLINE int usb_endpoint_is_isoc_out(const struct usb_endpoint_descriptor *epd)
441 return usb_endpoint_xfer_isoc(epd) && usb_endpoint_dir_out(epd);
445 * usb_ep_read - configure endponint and perform the read operation
447 ssize_t usb_ep_read(int ep, void *buffer, ssize_t size);
450 * usb_ep_write - configure endponint and perform the write operation
452 ssize_t usb_ep_write(int ep, const void *buffer, ssize_t size);
455 * usb_device_register - register a generic USB device driver
457 int usb_device_register(struct usb_device *dev);