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 */
92 #define USB_DIR_MASK 0x80
95 * USB types, the second of three bRequestType fields
97 #define USB_TYPE_MASK (0x03 << 5)
98 #define USB_TYPE_STANDARD (0x00 << 5)
99 #define USB_TYPE_CLASS (0x01 << 5)
100 #define USB_TYPE_VENDOR (0x02 << 5)
101 #define USB_TYPE_RESERVED (0x03 << 5)
104 * USB recipients, the third of three bRequestType fields
106 #define USB_RECIP_MASK 0x1f
107 #define USB_RECIP_DEVICE 0x00
108 #define USB_RECIP_INTERFACE 0x01
109 #define USB_RECIP_ENDPOINT 0x02
110 #define USB_RECIP_OTHER 0x03
113 * USB standard requests, for the bRequest field of a SETUP packet.
115 #define USB_REQ_GET_STATUS 0x00
116 #define USB_REQ_CLEAR_FEATURE 0x01
117 #define USB_REQ_SET_FEATURE 0x03
118 #define USB_REQ_SET_ADDRESS 0x05
119 #define USB_REQ_GET_DESCRIPTOR 0x06
120 #define USB_REQ_SET_DESCRIPTOR 0x07
121 #define USB_REQ_GET_CONFIGURATION 0x08
122 #define USB_REQ_SET_CONFIGURATION 0x09
123 #define USB_REQ_GET_INTERFACE 0x0A
124 #define USB_REQ_SET_INTERFACE 0x0B
125 #define USB_REQ_SYNCH_FRAME 0x0C
128 * Descriptor types ... USB 2.0 spec table 9.5
130 #define USB_DT_DEVICE 0x01
131 #define USB_DT_CONFIG 0x02
132 #define USB_DT_STRING 0x03
133 #define USB_DT_INTERFACE 0x04
134 #define USB_DT_ENDPOINT 0x05
135 #define USB_DT_DEVICE_QUALIFIER 0x06
136 #define USB_DT_OTHER_SPEED_CONFIG 0x07
137 #define USB_DT_INTERFACE_POWER 0x08
140 * Conventional codes for class-specific descriptors. The convention is
141 * defined in the USB "Common Class" Spec (3.11). Individual class specs
142 * are authoritative for their usage, not the "common class" writeup.
144 #define USB_DT_CS_DEVICE (USB_TYPE_CLASS | USB_DT_DEVICE)
145 #define USB_DT_CS_CONFIG (USB_TYPE_CLASS | USB_DT_CONFIG)
146 #define USB_DT_CS_STRING (USB_TYPE_CLASS | USB_DT_STRING)
147 #define USB_DT_CS_INTERFACE (USB_TYPE_CLASS | USB_DT_INTERFACE)
148 #define USB_DT_CS_ENDPOINT (USB_TYPE_CLASS | USB_DT_ENDPOINT)
151 * This structure is used to send control requests to a USB device.
153 * It matches the different fields of the USB 2.0 spec. section 9.3, table 9-2.
155 typedef struct usb_ctrlrequest
157 uint8_t mRequestType;
162 } PACKED usb_ctrlrequest_t;
164 /* All standard descriptors have these 2 fields at the beginning */
165 typedef struct usb_descriptor_header
168 uint8_t bDescriptorType;
169 } PACKED usb_descriptor_header_t;
171 /* Device descriptor */
172 typedef struct usb_device_descriptor
175 uint8_t bDescriptorType;
177 uint8_t bDeviceClass;
178 uint8_t bDeviceSubClass;
179 uint8_t bDeviceProtocol;
180 uint8_t bMaxPacketSize0;
184 uint8_t iManufacturer;
186 uint8_t iSerialNumber;
187 uint8_t bNumConfigurations;
188 } PACKED usb_device_descriptor_t;
190 /* USB string descriptor */
191 typedef struct usb_string_descriptor
194 uint8_t bDescriptorType;
196 } PACKED usb_string_descriptor_t;
199 * Macros to define USB strings
203 #define USB_STRING_1(__a, ...) __a "\x00"
204 #define USB_STRING_2(__a, ...) __a "\x00" USB_STRING_1(__VA_ARGS__)
205 #define USB_STRING_3(__a, ...) __a "\x00" USB_STRING_2(__VA_ARGS__)
206 #define USB_STRING_4(__a, ...) __a "\x00" USB_STRING_3(__VA_ARGS__)
207 #define USB_STRING_5(__a, ...) __a "\x00" USB_STRING_4(__VA_ARGS__)
208 #define USB_STRING_6(__a, ...) __a "\x00" USB_STRING_5(__VA_ARGS__)
209 #define USB_STRING_7(__a, ...) __a "\x00" USB_STRING_6(__VA_ARGS__)
210 #define USB_STRING_8(__a, ...) __a "\x00" USB_STRING_7(__VA_ARGS__)
211 #define USB_STRING_9(__a, ...) __a "\x00" USB_STRING_8(__VA_ARGS__)
212 #define USB_STRING_10(__a, ...) __a "\x00" USB_STRING_9(__VA_ARGS__)
213 #define USB_STRING_11(__a, ...) __a "\x00" USB_STRING_10(__VA_ARGS__)
214 #define USB_STRING_12(__a, ...) __a "\x00" USB_STRING_11(__VA_ARGS__)
215 #define USB_STRING_13(__a, ...) __a "\x00" USB_STRING_12(__VA_ARGS__)
216 #define USB_STRING_14(__a, ...) __a "\x00" USB_STRING_13(__VA_ARGS__)
217 #define USB_STRING_15(__a, ...) __a "\x00" USB_STRING_14(__VA_ARGS__)
218 #define USB_STRING_16(__a, ...) __a "\x00" USB_STRING_15(__VA_ARGS__)
220 #define USB_STRING(...) PP_CAT(USB_STRING_, PP_COUNT(__VA_ARGS__))(__VA_ARGS__)
222 #define DEFINE_USB_STRING(__name, __text) \
224 usb_descriptor_header_t __header; \
225 uint8_t __body[sizeof(__text)]; \
226 } PACKED __name = { \
228 .bLength = sizeof(__name), \
229 .bDescriptorType = USB_DT_STRING, \
231 .__body = {__text}, \
235 * Device and/or Interface Class codes as found in bDeviceClass or
236 * bInterfaceClass and defined by www.usb.org documents.
238 #define USB_CLASS_PER_INTERFACE 0 /* for DeviceClass */
239 #define USB_CLASS_AUDIO 1
240 #define USB_CLASS_COMM 2
241 #define USB_CLASS_HID 3
242 #define USB_CLASS_PHYSICAL 5
243 #define USB_CLASS_STILL_IMAGE 6
244 #define USB_CLASS_PRINTER 7
245 #define USB_CLASS_MASS_STORAGE 8
246 #define USB_CLASS_HUB 9
247 #define USB_CLASS_CDC_DATA 0x0a
248 #define USB_CLASS_CSCID 0x0b /* chip+ smart card */
249 #define USB_CLASS_CONTENT_SEC 0x0d /* content security */
250 #define USB_CLASS_VIDEO 0x0e
251 #define USB_CLASS_WIRELESS_CONTROLLER 0xe0
252 #define USB_CLASS_MISC 0xef
253 #define USB_CLASS_APP_SPEC 0xfe
254 #define USB_CLASS_VENDOR_SPEC 0xff
256 /* USB Device subclasses */
257 #define USB_CDC_SUBCLASS_ACM 0x02
258 #define USB_CDC_SUBCLASS_ETHERNET 0x06
259 #define USB_CDC_SUBCLASS_WHCM 0x08
260 #define USB_CDC_SUBCLASS_DMM 0x09
261 #define USB_CDC_SUBCLASS_MDLM 0x0a
262 #define USB_CDC_SUBCLASS_OBEX 0x0b
263 #define USB_CDC_SUBCLASS_EEM 0x0c
264 #define USB_CDC_SUBCLASS_NCM 0x0d
266 /* Device configuration descriptor */
267 typedef struct usb_config_descriptor
270 uint8_t bDescriptorType;
271 uint16_t wTotalLength;
272 uint8_t bNumInterfaces;
273 uint8_t bConfigurationValue;
274 uint8_t iConfiguration;
275 uint8_t bmAttributes;
277 } PACKED usb_config_descriptor_t;
279 /* from config descriptor bmAttributes */
280 #define USB_CONFIG_ATT_ONE (1 << 7) /* must be set */
281 #define USB_CONFIG_ATT_SELFPOWER (1 << 6) /* self powered */
282 #define USB_CONFIG_ATT_WAKEUP (1 << 5) /* can wakeup */
283 #define USB_CONFIG_ATT_BATTERY (1 << 4) /* battery powered */
285 /* Device interface descriptor */
286 typedef struct usb_interface_descriptor
289 uint8_t bDescriptorType;
290 uint8_t bInterfaceNumber;
291 uint8_t bAlternateSetting;
292 uint8_t bNumEndpoints;
293 uint8_t bInterfaceClass;
294 uint8_t bInterfaceSubClass;
295 uint8_t bInterfaceProtocol;
297 } PACKED usb_interface_descriptor_t;
299 /* Endpoint descriptor */
300 typedef struct usb_endpoint_descriptor
303 uint8_t bDescriptorType;
304 uint8_t bEndpointAddress;
305 uint8_t bmAttributes;
306 uint16_t wMaxPacketSize;
308 } PACKED usb_endpoint_descriptor_t;
313 #define USB_ENDPOINT_NUMBER_MASK 0x0f /* in bEndpointAddress */
314 #define USB_ENDPOINT_DIR_MASK USB_DIR_MASK
316 #define USB_ENDPOINT_SYNCTYPE 0x0c
317 #define USB_ENDPOINT_SYNC_NONE (0 << 2)
318 #define USB_ENDPOINT_SYNC_ASYNC (1 << 2)
319 #define USB_ENDPOINT_SYNC_ADAPTIVE (2 << 2)
320 #define USB_ENDPOINT_SYNC_SYNC (3 << 2)
322 #define USB_ENDPOINT_XFERTYPE_MASK 0x03 /* in bmAttributes */
323 #define USB_ENDPOINT_XFER_CONTROL 0
324 #define USB_ENDPOINT_XFER_ISOC 1
325 #define USB_ENDPOINT_XFER_BULK 2
326 #define USB_ENDPOINT_XFER_INT 3
327 #define USB_ENDPOINT_MAX_ADJUSTABLE 0x80
329 /* USB: generic device descriptor */
332 usb_device_descriptor_t *device;
333 const usb_descriptor_header_t **config;
334 const usb_string_descriptor_t **strings;
337 void (*event_cb)(usb_ctrlrequest_t *);
344 * usb_endpoint_num - get the endpoint's number
346 INLINE int usb_endpoint_num(const usb_endpoint_descriptor_t *epd)
348 return epd->bEndpointAddress & USB_ENDPOINT_NUMBER_MASK;
352 * usb_endpoint_type - get the endpoint's transfer type
354 INLINE int usb_endpoint_type(const struct usb_endpoint_descriptor *epd)
356 return epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK;
360 * usb_endpoint_dir_in - check if the endpoint has IN direction
362 INLINE int usb_endpoint_dir_in(const struct usb_endpoint_descriptor *epd)
364 return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_IN);
368 * usb_endpoint_dir_out - check if the endpoint has OUT direction
370 INLINE int usb_endpoint_dir_out(const struct usb_endpoint_descriptor *epd)
372 return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_OUT);
376 * usb_endpoint_xfer_bulk - check if the endpoint has bulk transfer type
378 INLINE int usb_endpoint_xfer_bulk(const struct usb_endpoint_descriptor *epd)
380 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
381 USB_ENDPOINT_XFER_BULK);
385 * usb_endpoint_xfer_control - check if the endpoint has control transfer type
387 INLINE int usb_endpoint_xfer_control(const struct usb_endpoint_descriptor *epd)
389 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
390 USB_ENDPOINT_XFER_CONTROL);
394 * usb_endpoint_xfer_int - check if the endpoint has interrupt transfer type
396 INLINE int usb_endpoint_xfer_int(const struct usb_endpoint_descriptor *epd)
398 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
399 USB_ENDPOINT_XFER_INT);
403 * usb_endpoint_xfer_isoc - check if the endpoint has isochronous transfer type
405 INLINE int usb_endpoint_xfer_isoc(const struct usb_endpoint_descriptor *epd)
407 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
408 USB_ENDPOINT_XFER_ISOC);
412 * usb_endpoint_is_bulk_in - check if the endpoint is bulk IN
414 INLINE int usb_endpoint_is_bulk_in(const struct usb_endpoint_descriptor *epd)
416 return usb_endpoint_xfer_bulk(epd) && usb_endpoint_dir_in(epd);
420 * usb_endpoint_is_bulk_out - check if the endpoint is bulk OUT
422 INLINE int usb_endpoint_is_bulk_out(const struct usb_endpoint_descriptor *epd)
424 return usb_endpoint_xfer_bulk(epd) && usb_endpoint_dir_out(epd);
428 * usb_endpoint_is_int_in - check if the endpoint is interrupt IN
430 INLINE int usb_endpoint_is_int_in(const struct usb_endpoint_descriptor *epd)
432 return usb_endpoint_xfer_int(epd) && usb_endpoint_dir_in(epd);
436 * usb_endpoint_is_int_out - check if the endpoint is interrupt OUT
438 INLINE int usb_endpoint_is_int_out(const struct usb_endpoint_descriptor *epd)
440 return usb_endpoint_xfer_int(epd) && usb_endpoint_dir_out(epd);
444 * usb_endpoint_is_isoc_in - check if the endpoint is isochronous IN
446 INLINE int usb_endpoint_is_isoc_in(const struct usb_endpoint_descriptor *epd)
448 return usb_endpoint_xfer_isoc(epd) && usb_endpoint_dir_in(epd);
452 * usb_endpoint_is_isoc_out - check if the endpoint is isochronous OUT
454 INLINE int usb_endpoint_is_isoc_out(const struct usb_endpoint_descriptor *epd)
456 return usb_endpoint_xfer_isoc(epd) && usb_endpoint_dir_out(epd);
460 * usb_ep_read - configure endponint and perform the read operation
462 ssize_t usb_ep_read(int ep, void *buffer, ssize_t size);
465 * usb_ep_write - configure endponint and perform the write operation
467 ssize_t usb_ep_write(int ep, const void *buffer, ssize_t size);
470 * usb_device_register - register a generic USB device driver
472 int usb_device_register(struct usb_device *dev);