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 /* USB Device subclasses */
256 #define USB_CDC_SUBCLASS_ACM 0x02
257 #define USB_CDC_SUBCLASS_ETHERNET 0x06
258 #define USB_CDC_SUBCLASS_WHCM 0x08
259 #define USB_CDC_SUBCLASS_DMM 0x09
260 #define USB_CDC_SUBCLASS_MDLM 0x0a
261 #define USB_CDC_SUBCLASS_OBEX 0x0b
262 #define USB_CDC_SUBCLASS_EEM 0x0c
263 #define USB_CDC_SUBCLASS_NCM 0x0d
265 /* Device configuration descriptor */
266 typedef struct usb_config_descriptor
269 uint8_t bDescriptorType;
270 uint16_t wTotalLength;
271 uint8_t bNumInterfaces;
272 uint8_t bConfigurationValue;
273 uint8_t iConfiguration;
274 uint8_t bmAttributes;
276 } PACKED usb_config_descriptor_t;
278 /* from config descriptor bmAttributes */
279 #define USB_CONFIG_ATT_ONE (1 << 7) /* must be set */
280 #define USB_CONFIG_ATT_SELFPOWER (1 << 6) /* self powered */
281 #define USB_CONFIG_ATT_WAKEUP (1 << 5) /* can wakeup */
282 #define USB_CONFIG_ATT_BATTERY (1 << 4) /* battery powered */
284 /* Device interface descriptor */
285 typedef struct usb_interface_descriptor
288 uint8_t bDescriptorType;
289 uint8_t bInterfaceNumber;
290 uint8_t bAlternateSetting;
291 uint8_t bNumEndpoints;
292 uint8_t bInterfaceClass;
293 uint8_t bInterfaceSubClass;
294 uint8_t bInterfaceProtocol;
296 } PACKED usb_interface_descriptor_t;
298 /* Endpoint descriptor */
299 typedef struct usb_endpoint_descriptor
302 uint8_t bDescriptorType;
303 uint8_t bEndpointAddress;
304 uint8_t bmAttributes;
305 uint16_t wMaxPacketSize;
307 } PACKED usb_endpoint_descriptor_t;
312 #define USB_ENDPOINT_NUMBER_MASK 0x0f /* in bEndpointAddress */
313 #define USB_ENDPOINT_DIR_MASK 0x80
315 #define USB_ENDPOINT_SYNCTYPE 0x0c
316 #define USB_ENDPOINT_SYNC_NONE (0 << 2)
317 #define USB_ENDPOINT_SYNC_ASYNC (1 << 2)
318 #define USB_ENDPOINT_SYNC_ADAPTIVE (2 << 2)
319 #define USB_ENDPOINT_SYNC_SYNC (3 << 2)
321 #define USB_ENDPOINT_XFERTYPE_MASK 0x03 /* in bmAttributes */
322 #define USB_ENDPOINT_XFER_CONTROL 0
323 #define USB_ENDPOINT_XFER_ISOC 1
324 #define USB_ENDPOINT_XFER_BULK 2
325 #define USB_ENDPOINT_XFER_INT 3
326 #define USB_ENDPOINT_MAX_ADJUSTABLE 0x80
328 /* USB: generic device descriptor */
331 usb_device_descriptor_t *device;
332 usb_descriptor_header_t **config;
333 usb_string_descriptor_t **strings;
336 void (*event_cb)(usb_ctrlrequest_t *);
343 * usb_endpoint_num - get the endpoint's number
345 INLINE int usb_endpoint_num(const usb_endpoint_descriptor_t *epd)
347 return epd->bEndpointAddress & USB_ENDPOINT_NUMBER_MASK;
351 * usb_endpoint_type - get the endpoint's transfer type
353 INLINE int usb_endpoint_type(const struct usb_endpoint_descriptor *epd)
355 return epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK;
359 * usb_endpoint_dir_in - check if the endpoint has IN direction
361 INLINE int usb_endpoint_dir_in(const struct usb_endpoint_descriptor *epd)
363 return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_IN);
367 * usb_endpoint_dir_out - check if the endpoint has OUT direction
369 INLINE int usb_endpoint_dir_out(const struct usb_endpoint_descriptor *epd)
371 return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_OUT);
375 * usb_endpoint_xfer_bulk - check if the endpoint has bulk transfer type
377 INLINE int usb_endpoint_xfer_bulk(const struct usb_endpoint_descriptor *epd)
379 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
380 USB_ENDPOINT_XFER_BULK);
384 * usb_endpoint_xfer_control - check if the endpoint has control transfer type
386 INLINE int usb_endpoint_xfer_control(const struct usb_endpoint_descriptor *epd)
388 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
389 USB_ENDPOINT_XFER_CONTROL);
393 * usb_endpoint_xfer_int - check if the endpoint has interrupt transfer type
395 INLINE int usb_endpoint_xfer_int(const struct usb_endpoint_descriptor *epd)
397 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
398 USB_ENDPOINT_XFER_INT);
402 * usb_endpoint_xfer_isoc - check if the endpoint has isochronous transfer type
404 INLINE int usb_endpoint_xfer_isoc(const struct usb_endpoint_descriptor *epd)
406 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
407 USB_ENDPOINT_XFER_ISOC);
411 * usb_endpoint_is_bulk_in - check if the endpoint is bulk IN
413 INLINE int usb_endpoint_is_bulk_in(const struct usb_endpoint_descriptor *epd)
415 return usb_endpoint_xfer_bulk(epd) && usb_endpoint_dir_in(epd);
419 * usb_endpoint_is_bulk_out - check if the endpoint is bulk OUT
421 INLINE int usb_endpoint_is_bulk_out(const struct usb_endpoint_descriptor *epd)
423 return usb_endpoint_xfer_bulk(epd) && usb_endpoint_dir_out(epd);
427 * usb_endpoint_is_int_in - check if the endpoint is interrupt IN
429 INLINE int usb_endpoint_is_int_in(const struct usb_endpoint_descriptor *epd)
431 return usb_endpoint_xfer_int(epd) && usb_endpoint_dir_in(epd);
435 * usb_endpoint_is_int_out - check if the endpoint is interrupt OUT
437 INLINE int usb_endpoint_is_int_out(const struct usb_endpoint_descriptor *epd)
439 return usb_endpoint_xfer_int(epd) && usb_endpoint_dir_out(epd);
443 * usb_endpoint_is_isoc_in - check if the endpoint is isochronous IN
445 INLINE int usb_endpoint_is_isoc_in(const struct usb_endpoint_descriptor *epd)
447 return usb_endpoint_xfer_isoc(epd) && usb_endpoint_dir_in(epd);
451 * usb_endpoint_is_isoc_out - check if the endpoint is isochronous OUT
453 INLINE int usb_endpoint_is_isoc_out(const struct usb_endpoint_descriptor *epd)
455 return usb_endpoint_xfer_isoc(epd) && usb_endpoint_dir_out(epd);
459 * usb_ep_read - configure endponint and perform the read operation
461 ssize_t usb_ep_read(int ep, void *buffer, ssize_t size);
464 * usb_ep_write - configure endponint and perform the write operation
466 ssize_t usb_ep_write(int ep, const void *buffer, ssize_t size);
469 * usb_device_register - register a generic USB device driver
471 int usb_device_register(struct usb_device *dev);