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>
50 #define usb_cpu_to_le16(x) cpu_to_le16(x)
51 #define usb_le16_to_cpu(x) le16_to_cpu(x)
52 #define usb_cpu_to_le32(x) cpu_to_le32(x)
53 #define usb_le32_to_cpu(x) le32_to_cpu(x)
55 /* State of a USB device */
56 enum usb_device_state {
57 USB_STATE_NOTATTACHED = 0,
59 /* chapter 9 device states */
61 USB_STATE_POWERED, /* wired */
62 USB_STATE_DEFAULT, /* limited function */
64 USB_STATE_CONFIGURED, /* most functions */
70 * This bit flag is used in endpoint descriptors' bEndpointAddress field.
71 * It's also one of three fields in control requests bRequestType.
73 #define USB_DIR_OUT 0 /* to device */
74 #define USB_DIR_IN 0x80 /* to host */
75 #define USB_DIR_MASK 0x80
78 * USB types, the second of three bRequestType fields
80 #define USB_TYPE_MASK (0x03 << 5)
81 #define USB_TYPE_STANDARD (0x00 << 5)
82 #define USB_TYPE_CLASS (0x01 << 5)
83 #define USB_TYPE_VENDOR (0x02 << 5)
84 #define USB_TYPE_RESERVED (0x03 << 5)
87 * USB recipients, the third of three bRequestType fields
89 #define USB_RECIP_MASK 0x1f
90 #define USB_RECIP_DEVICE 0x00
91 #define USB_RECIP_INTERFACE 0x01
92 #define USB_RECIP_ENDPOINT 0x02
93 #define USB_RECIP_OTHER 0x03
96 * USB standard requests, for the bRequest field of a SETUP packet.
98 #define USB_REQ_GET_STATUS 0x00
99 #define USB_REQ_CLEAR_FEATURE 0x01
100 #define USB_REQ_SET_FEATURE 0x03
101 #define USB_REQ_SET_ADDRESS 0x05
102 #define USB_REQ_GET_DESCRIPTOR 0x06
103 #define USB_REQ_SET_DESCRIPTOR 0x07
104 #define USB_REQ_GET_CONFIGURATION 0x08
105 #define USB_REQ_SET_CONFIGURATION 0x09
106 #define USB_REQ_GET_INTERFACE 0x0A
107 #define USB_REQ_SET_INTERFACE 0x0B
108 #define USB_REQ_SYNCH_FRAME 0x0C
111 * Descriptor types ... USB 2.0 spec table 9.5
113 #define USB_DT_DEVICE 0x01
114 #define USB_DT_CONFIG 0x02
115 #define USB_DT_STRING 0x03
116 #define USB_DT_INTERFACE 0x04
117 #define USB_DT_ENDPOINT 0x05
118 #define USB_DT_DEVICE_QUALIFIER 0x06
119 #define USB_DT_OTHER_SPEED_CONFIG 0x07
120 #define USB_DT_INTERFACE_POWER 0x08
123 * Conventional codes for class-specific descriptors. The convention is
124 * defined in the USB "Common Class" Spec (3.11). Individual class specs
125 * are authoritative for their usage, not the "common class" writeup.
127 #define USB_DT_CS_DEVICE (USB_TYPE_CLASS | USB_DT_DEVICE)
128 #define USB_DT_CS_CONFIG (USB_TYPE_CLASS | USB_DT_CONFIG)
129 #define USB_DT_CS_STRING (USB_TYPE_CLASS | USB_DT_STRING)
130 #define USB_DT_CS_INTERFACE (USB_TYPE_CLASS | USB_DT_INTERFACE)
131 #define USB_DT_CS_ENDPOINT (USB_TYPE_CLASS | USB_DT_ENDPOINT)
134 * This structure is used to send control requests to a USB device.
136 * It matches the different fields of the USB 2.0 spec. section 9.3, table 9-2.
138 typedef struct UsbCtrlRequest
140 uint8_t mRequestType;
145 } PACKED UsbCtrlRequest;
147 /* All standard descriptors have these 2 fields at the beginning */
148 typedef struct UsbDescHeader
151 uint8_t bDescriptorType;
152 } PACKED UsbDescHeader;
154 /* Device descriptor */
155 typedef struct UsbDeviceDesc
158 uint8_t bDescriptorType;
160 uint8_t bDeviceClass;
161 uint8_t bDeviceSubClass;
162 uint8_t bDeviceProtocol;
163 uint8_t bMaxPacketSize0;
167 uint8_t iManufacturer;
169 uint8_t iSerialNumber;
170 uint8_t bNumConfigurations;
171 } PACKED UsbDeviceDesc;
173 /* USB string descriptor */
174 typedef struct UsbStringDesc
177 uint8_t bDescriptorType;
179 } PACKED UsbStringDesc;
182 * Macros to define USB strings
186 #define USB_STRING_1(__a, ...) __a "\x00"
187 #define USB_STRING_2(__a, ...) __a "\x00" USB_STRING_1(__VA_ARGS__)
188 #define USB_STRING_3(__a, ...) __a "\x00" USB_STRING_2(__VA_ARGS__)
189 #define USB_STRING_4(__a, ...) __a "\x00" USB_STRING_3(__VA_ARGS__)
190 #define USB_STRING_5(__a, ...) __a "\x00" USB_STRING_4(__VA_ARGS__)
191 #define USB_STRING_6(__a, ...) __a "\x00" USB_STRING_5(__VA_ARGS__)
192 #define USB_STRING_7(__a, ...) __a "\x00" USB_STRING_6(__VA_ARGS__)
193 #define USB_STRING_8(__a, ...) __a "\x00" USB_STRING_7(__VA_ARGS__)
194 #define USB_STRING_9(__a, ...) __a "\x00" USB_STRING_8(__VA_ARGS__)
195 #define USB_STRING_10(__a, ...) __a "\x00" USB_STRING_9(__VA_ARGS__)
196 #define USB_STRING_11(__a, ...) __a "\x00" USB_STRING_10(__VA_ARGS__)
197 #define USB_STRING_12(__a, ...) __a "\x00" USB_STRING_11(__VA_ARGS__)
198 #define USB_STRING_13(__a, ...) __a "\x00" USB_STRING_12(__VA_ARGS__)
199 #define USB_STRING_14(__a, ...) __a "\x00" USB_STRING_13(__VA_ARGS__)
200 #define USB_STRING_15(__a, ...) __a "\x00" USB_STRING_14(__VA_ARGS__)
201 #define USB_STRING_16(__a, ...) __a "\x00" USB_STRING_15(__VA_ARGS__)
203 #define USB_STRING(...) PP_CAT(USB_STRING_, PP_COUNT(__VA_ARGS__))(__VA_ARGS__)
205 #define DEFINE_USB_STRING(__name, __text) \
207 UsbDescHeader __header; \
208 uint8_t __body[sizeof(__text)]; \
209 } PACKED __name = { \
211 .bLength = sizeof(__name), \
212 .bDescriptorType = USB_DT_STRING, \
214 .__body = {__text}, \
218 * Device and/or Interface Class codes as found in bDeviceClass or
219 * bInterfaceClass and defined by www.usb.org documents.
221 #define USB_CLASS_PER_INTERFACE 0 /* for DeviceClass */
222 #define USB_CLASS_AUDIO 1
223 #define USB_CLASS_COMM 2
224 #define USB_CLASS_HID 3
225 #define USB_CLASS_PHYSICAL 5
226 #define USB_CLASS_STILL_IMAGE 6
227 #define USB_CLASS_PRINTER 7
228 #define USB_CLASS_MASS_STORAGE 8
229 #define USB_CLASS_HUB 9
230 #define USB_CLASS_CDC_DATA 0x0a
231 #define USB_CLASS_CSCID 0x0b /* chip+ smart card */
232 #define USB_CLASS_CONTENT_SEC 0x0d /* content security */
233 #define USB_CLASS_VIDEO 0x0e
234 #define USB_CLASS_WIRELESS_CONTROLLER 0xe0
235 #define USB_CLASS_MISC 0xef
236 #define USB_CLASS_APP_SPEC 0xfe
237 #define USB_CLASS_VENDOR_SPEC 0xff
239 /* USB Device subclasses */
240 #define USB_CDC_SUBCLASS_ACM 0x02
241 #define USB_CDC_SUBCLASS_ETHERNET 0x06
242 #define USB_CDC_SUBCLASS_WHCM 0x08
243 #define USB_CDC_SUBCLASS_DMM 0x09
244 #define USB_CDC_SUBCLASS_MDLM 0x0a
245 #define USB_CDC_SUBCLASS_OBEX 0x0b
246 #define USB_CDC_SUBCLASS_EEM 0x0c
247 #define USB_CDC_SUBCLASS_NCM 0x0d
249 /* Device configuration descriptor */
250 typedef struct UsbConfigDesc
253 uint8_t bDescriptorType;
254 uint16_t wTotalLength;
255 uint8_t bNumInterfaces;
256 uint8_t bConfigurationValue;
257 uint8_t iConfiguration;
258 uint8_t bmAttributes;
260 } PACKED UsbConfigDesc;
262 /* from config descriptor bmAttributes */
263 #define USB_CONFIG_ATT_ONE (1 << 7) /* must be set */
264 #define USB_CONFIG_ATT_SELFPOWER (1 << 6) /* self powered */
265 #define USB_CONFIG_ATT_WAKEUP (1 << 5) /* can wakeup */
266 #define USB_CONFIG_ATT_BATTERY (1 << 4) /* battery powered */
268 /* Device interface descriptor */
269 typedef struct UsbInterfaceDesc
272 uint8_t bDescriptorType;
273 uint8_t bInterfaceNumber;
274 uint8_t bAlternateSetting;
275 uint8_t bNumEndpoints;
276 uint8_t bInterfaceClass;
277 uint8_t bInterfaceSubClass;
278 uint8_t bInterfaceProtocol;
280 } PACKED UsbInterfaceDesc;
282 /* Endpoint descriptor */
283 typedef struct UsbEndpointDesc
286 uint8_t bDescriptorType;
287 uint8_t bEndpointAddress;
288 uint8_t bmAttributes;
289 uint16_t wMaxPacketSize;
291 } PACKED UsbEndpointDesc;
296 #define USB_ENDPOINT_NUMBER_MASK 0x0f /* in bEndpointAddress */
297 #define USB_ENDPOINT_DIR_MASK USB_DIR_MASK
299 #define USB_ENDPOINT_SYNCTYPE 0x0c
300 #define USB_ENDPOINT_SYNC_NONE (0 << 2)
301 #define USB_ENDPOINT_SYNC_ASYNC (1 << 2)
302 #define USB_ENDPOINT_SYNC_ADAPTIVE (2 << 2)
303 #define USB_ENDPOINT_SYNC_SYNC (3 << 2)
305 #define USB_ENDPOINT_XFERTYPE_MASK 0x03 /* in bmAttributes */
306 #define USB_ENDPOINT_XFER_CONTROL 0
307 #define USB_ENDPOINT_XFER_ISOC 1
308 #define USB_ENDPOINT_XFER_BULK 2
309 #define USB_ENDPOINT_XFER_INT 3
310 #define USB_ENDPOINT_MAX_ADJUSTABLE 0x80
312 /* USB: generic device descriptor */
313 typedef struct UsbDevice
315 UsbDeviceDesc *device;
316 const UsbDescHeader **config;
317 const UsbStringDesc **strings;
320 void (*event_cb)(UsbCtrlRequest *);
327 * usb_endpointNum - get the endpoint's number
329 INLINE int usb_endpointNum(const UsbEndpointDesc *epd)
331 return epd->bEndpointAddress & USB_ENDPOINT_NUMBER_MASK;
335 * usb_endpointType - get the endpoint's transfer type
337 INLINE int usb_endpointType(const struct UsbEndpointDesc *epd)
339 return epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK;
343 * usb_endpointDirIn - check if the endpoint has IN direction
345 INLINE int usb_endpointDirIn(const struct UsbEndpointDesc *epd)
347 return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_IN);
351 * usb_endpointDirOut - check if the endpoint has OUT direction
353 INLINE int usb_endpointDirOut(const struct UsbEndpointDesc *epd)
355 return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_OUT);
359 * usb_endpointXferBulk - check if the endpoint has bulk transfer type
361 INLINE int usb_endpointXferBulk(const struct UsbEndpointDesc *epd)
363 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
364 USB_ENDPOINT_XFER_BULK);
368 * usb_endpointXferControl - check if the endpoint has control transfer type
370 INLINE int usb_endpointXferControl(const struct UsbEndpointDesc *epd)
372 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
373 USB_ENDPOINT_XFER_CONTROL);
377 * usb_endpointXferInt - check if the endpoint has interrupt transfer type
379 INLINE int usb_endpointXferInt(const struct UsbEndpointDesc *epd)
381 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
382 USB_ENDPOINT_XFER_INT);
386 * usb_endpointXferIsoc - check if the endpoint has isochronous transfer type
388 INLINE int usb_endpointXferIsoc(const struct UsbEndpointDesc *epd)
390 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
391 USB_ENDPOINT_XFER_ISOC);
395 * usb_endpointIsBulkIn - check if the endpoint is bulk IN
397 INLINE int usb_endpointIsBulkIn(const struct UsbEndpointDesc *epd)
399 return usb_endpointXferBulk(epd) && usb_endpointDirIn(epd);
403 * usb_endpointIsBulkOut - check if the endpoint is bulk OUT
405 INLINE int usb_endpointIsBulkOut(const struct UsbEndpointDesc *epd)
407 return usb_endpointXferBulk(epd) && usb_endpointDirOut(epd);
411 * usb_endpointIsIntIn - check if the endpoint is interrupt IN
413 INLINE int usb_endpointIsIntIn(const struct UsbEndpointDesc *epd)
415 return usb_endpointXferInt(epd) && usb_endpointDirIn(epd);
419 * usb_endpointIsIntOut - check if the endpoint is interrupt OUT
421 INLINE int usb_endpointIsIntOut(const struct UsbEndpointDesc *epd)
423 return usb_endpointXferInt(epd) && usb_endpointDirOut(epd);
427 * usb_endpointIsIsocIn - check if the endpoint is isochronous IN
429 INLINE int usb_endpointIsIsocIn(const struct UsbEndpointDesc *epd)
431 return usb_endpointXferIsoc(epd) && usb_endpointDirIn(epd);
435 * usb_endpointIsIsocOut - check if the endpoint is isochronous OUT
437 INLINE int usb_endpointIsIsocOut(const struct UsbEndpointDesc *epd)
439 return usb_endpointXferIsoc(epd) && usb_endpointDirOut(epd);
443 * usb_endpointRead - configure endponint and perform the read operation
445 ssize_t usb_endpointRead(int ep, void *buffer, ssize_t size);
448 * usb_endpointWrite - configure endponint and perform the write operation
450 ssize_t usb_endpointWrite(int ep, const void *buffer, ssize_t size);
453 * usb_deviceRegister - register a generic USB device driver
455 int usb_deviceRegister(UsbDevice *dev);