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)
135 * USB Control Request descriptor
137 * This structure is used to send control requests to a USB device.
139 * It matches the different fields of the USB 2.0 specification (section 9.3,
142 typedef struct UsbCtrlRequest
144 uint8_t mRequestType;
149 } PACKED UsbCtrlRequest;
152 * USB common descriptor header.
154 * \note All the USB standard descriptors have these 2 fields at the beginning.
156 typedef struct UsbDescHeader
159 uint8_t bDescriptorType;
160 } PACKED UsbDescHeader;
163 * USB Device descriptor
165 * \note See USB 2.0 specification.
167 typedef struct UsbDeviceDesc
170 uint8_t bDescriptorType;
172 uint8_t bDeviceClass;
173 uint8_t bDeviceSubClass;
174 uint8_t bDeviceProtocol;
175 uint8_t bMaxPacketSize0;
179 uint8_t iManufacturer;
181 uint8_t iSerialNumber;
182 uint8_t bNumConfigurations;
183 } PACKED UsbDeviceDesc;
186 * USB string descriptor.
188 * \note See USB 2.0 specification.
190 typedef struct UsbStringDesc
193 uint8_t bDescriptorType;
195 } PACKED UsbStringDesc;
197 #define USB_STRING_1(__a, ...) __a "\x00"
198 #define USB_STRING_2(__a, ...) __a "\x00" USB_STRING_1(__VA_ARGS__)
199 #define USB_STRING_3(__a, ...) __a "\x00" USB_STRING_2(__VA_ARGS__)
200 #define USB_STRING_4(__a, ...) __a "\x00" USB_STRING_3(__VA_ARGS__)
201 #define USB_STRING_5(__a, ...) __a "\x00" USB_STRING_4(__VA_ARGS__)
202 #define USB_STRING_6(__a, ...) __a "\x00" USB_STRING_5(__VA_ARGS__)
203 #define USB_STRING_7(__a, ...) __a "\x00" USB_STRING_6(__VA_ARGS__)
204 #define USB_STRING_8(__a, ...) __a "\x00" USB_STRING_7(__VA_ARGS__)
205 #define USB_STRING_9(__a, ...) __a "\x00" USB_STRING_8(__VA_ARGS__)
206 #define USB_STRING_10(__a, ...) __a "\x00" USB_STRING_9(__VA_ARGS__)
207 #define USB_STRING_11(__a, ...) __a "\x00" USB_STRING_10(__VA_ARGS__)
208 #define USB_STRING_12(__a, ...) __a "\x00" USB_STRING_11(__VA_ARGS__)
209 #define USB_STRING_13(__a, ...) __a "\x00" USB_STRING_12(__VA_ARGS__)
210 #define USB_STRING_14(__a, ...) __a "\x00" USB_STRING_13(__VA_ARGS__)
211 #define USB_STRING_15(__a, ...) __a "\x00" USB_STRING_14(__VA_ARGS__)
212 #define USB_STRING_16(__a, ...) __a "\x00" USB_STRING_15(__VA_ARGS__)
215 * Pack a list with a variable number of elements into a UTF-16LE USB string.
217 * \note The macro is recursively defined according the number of elements
218 * passed as argument. At the moment we support strings with up to 16
221 #define USB_STRING(...) PP_CAT(USB_STRING_, PP_COUNT(__VA_ARGS__))(__VA_ARGS__)
224 * Define and initialize an USB string descriptor.
226 * This macro is reuquired to properly declare and initialize a constant USB
227 * string in UTF-16LE format.
229 * The structure must contain the standard common USB header (UsbDescHeader)
230 * and the UTF-16LE string all packed in a contiguous memory region.
232 #define DEFINE_USB_STRING(__name, __text) \
234 UsbDescHeader __header; \
235 uint8_t __body[sizeof(__text)]; \
236 } PACKED __name = { \
239 cpu_to_le16((uint16_t)sizeof(__name)), \
240 .bDescriptorType = USB_DT_STRING, \
242 .__body = {__text}, \
246 * Device and/or Interface Class codes as found in bDeviceClass or
247 * bInterfaceClass and defined by www.usb.org documents.
249 #define USB_CLASS_PER_INTERFACE 0 /* for DeviceClass */
250 #define USB_CLASS_AUDIO 1
251 #define USB_CLASS_COMM 2
252 #define USB_CLASS_HID 3
253 #define USB_CLASS_PHYSICAL 5
254 #define USB_CLASS_STILL_IMAGE 6
255 #define USB_CLASS_PRINTER 7
256 #define USB_CLASS_MASS_STORAGE 8
257 #define USB_CLASS_HUB 9
258 #define USB_CLASS_CDC_DATA 0x0a
259 #define USB_CLASS_CSCID 0x0b /* chip+ smart card */
260 #define USB_CLASS_CONTENT_SEC 0x0d /* content security */
261 #define USB_CLASS_VIDEO 0x0e
262 #define USB_CLASS_WIRELESS_CONTROLLER 0xe0
263 #define USB_CLASS_MISC 0xef
264 #define USB_CLASS_APP_SPEC 0xfe
265 #define USB_CLASS_VENDOR_SPEC 0xff
267 /* USB Device subclasses */
268 #define USB_CDC_SUBCLASS_ACM 0x02
269 #define USB_CDC_SUBCLASS_ETHERNET 0x06
270 #define USB_CDC_SUBCLASS_WHCM 0x08
271 #define USB_CDC_SUBCLASS_DMM 0x09
272 #define USB_CDC_SUBCLASS_MDLM 0x0a
273 #define USB_CDC_SUBCLASS_OBEX 0x0b
274 #define USB_CDC_SUBCLASS_EEM 0x0c
275 #define USB_CDC_SUBCLASS_NCM 0x0d
278 * Device configuration descriptor
280 * \note See USB 2.0 specification.
282 typedef struct UsbConfigDesc
285 uint8_t bDescriptorType;
286 uint16_t wTotalLength;
287 uint8_t bNumInterfaces;
288 uint8_t bConfigurationValue;
289 uint8_t iConfiguration;
290 uint8_t bmAttributes;
292 } PACKED UsbConfigDesc;
294 /* from config descriptor bmAttributes */
295 #define USB_CONFIG_ATT_ONE (1 << 7) /* must be set */
296 #define USB_CONFIG_ATT_SELFPOWER (1 << 6) /* self powered */
297 #define USB_CONFIG_ATT_WAKEUP (1 << 5) /* can wakeup */
298 #define USB_CONFIG_ATT_BATTERY (1 << 4) /* battery powered */
301 * Device interface descriptor
303 * \note See USB 2.0 specification.
305 typedef struct UsbInterfaceDesc
308 uint8_t bDescriptorType;
309 uint8_t bInterfaceNumber;
310 uint8_t bAlternateSetting;
311 uint8_t bNumEndpoints;
312 uint8_t bInterfaceClass;
313 uint8_t bInterfaceSubClass;
314 uint8_t bInterfaceProtocol;
316 } PACKED UsbInterfaceDesc;
319 * Endpoint descriptor
321 * \note See USB 2.0 specification.
323 typedef struct UsbEndpointDesc
326 uint8_t bDescriptorType;
327 uint8_t bEndpointAddress;
328 uint8_t bmAttributes;
329 uint16_t wMaxPacketSize;
331 } PACKED UsbEndpointDesc;
336 #define USB_ENDPOINT_NUMBER_MASK 0x0f /* in bEndpointAddress */
337 #define USB_ENDPOINT_DIR_MASK USB_DIR_MASK
339 #define USB_ENDPOINT_SYNCTYPE 0x0c
340 #define USB_ENDPOINT_SYNC_NONE (0 << 2)
341 #define USB_ENDPOINT_SYNC_ASYNC (1 << 2)
342 #define USB_ENDPOINT_SYNC_ADAPTIVE (2 << 2)
343 #define USB_ENDPOINT_SYNC_SYNC (3 << 2)
345 #define USB_ENDPOINT_XFERTYPE_MASK 0x03 /* in bmAttributes */
346 #define USB_ENDPOINT_XFER_CONTROL 0
347 #define USB_ENDPOINT_XFER_ISOC 1
348 #define USB_ENDPOINT_XFER_BULK 2
349 #define USB_ENDPOINT_XFER_INT 3
350 #define USB_ENDPOINT_MAX_ADJUSTABLE 0x80
353 * USB: generic device descriptor
355 typedef struct UsbDevice
357 UsbDeviceDesc *device; ///< USB 2.0 device descriptor
358 const UsbDescHeader **config; ///< USB 2.0 configuration descriptors
359 const UsbStringDesc **strings; ///< USB strings
362 void (*event_cb)(UsbCtrlRequest *); ///< Called to handle control requests.
365 bool configured; ///< True when the device has been correctly initialized.
369 * Get the endpoint's address number of \a epd.
371 INLINE int usb_endpointNum(const UsbEndpointDesc *epd)
373 return epd->bEndpointAddress & USB_ENDPOINT_NUMBER_MASK;
377 * Get the transfer type of the endpoint \a epd.
379 INLINE int usb_endpointType(const struct UsbEndpointDesc *epd)
381 return epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK;
385 * Check if the endpoint \a epd has IN direction.
387 INLINE int usb_endpointDirIn(const struct UsbEndpointDesc *epd)
389 return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_IN);
393 * Check if the endpoint \a epd has OUT direction.
395 INLINE int usb_endpointDirOut(const struct UsbEndpointDesc *epd)
397 return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_OUT);
401 * Check if the endpoint \a epd has bulk transfer type.
403 INLINE int usb_endpointXferBulk(const struct UsbEndpointDesc *epd)
405 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
406 USB_ENDPOINT_XFER_BULK);
410 * Check if the endpoint \a epd has control transfer type.
412 INLINE int usb_endpointXferControl(const struct UsbEndpointDesc *epd)
414 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
415 USB_ENDPOINT_XFER_CONTROL);
419 * Check if the endpoint \a epd has interrupt transfer type.
421 INLINE int usb_endpointXferInt(const struct UsbEndpointDesc *epd)
423 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
424 USB_ENDPOINT_XFER_INT);
428 * Check if the endpoint \a epd has isochronous transfer type.
430 INLINE int usb_endpointXferIsoc(const struct UsbEndpointDesc *epd)
432 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
433 USB_ENDPOINT_XFER_ISOC);
437 * Check if the endpoint \a epd is bulk IN.
439 INLINE int usb_endpointIsBulkIn(const struct UsbEndpointDesc *epd)
441 return usb_endpointXferBulk(epd) && usb_endpointDirIn(epd);
445 * Check if the endpoint \a epd is bulk OUT.
447 INLINE int usb_endpointIsBulkOut(const struct UsbEndpointDesc *epd)
449 return usb_endpointXferBulk(epd) && usb_endpointDirOut(epd);
453 * Check if the endpoint \a epd is interrupt IN.
455 INLINE int usb_endpointIsIntIn(const struct UsbEndpointDesc *epd)
457 return usb_endpointXferInt(epd) && usb_endpointDirIn(epd);
461 * Check if the endpoint \a epd is interrupt OUT.
463 INLINE int usb_endpointIsIntOut(const struct UsbEndpointDesc *epd)
465 return usb_endpointXferInt(epd) && usb_endpointDirOut(epd);
469 * Check if the endpoint \a epd is isochronous IN.
471 INLINE int usb_endpointIsIsocIn(const struct UsbEndpointDesc *epd)
473 return usb_endpointXferIsoc(epd) && usb_endpointDirIn(epd);
477 * Check if the endpoint \a epd is isochronous OUT.
479 INLINE int usb_endpointIsIsocOut(const struct UsbEndpointDesc *epd)
481 return usb_endpointXferIsoc(epd) && usb_endpointDirOut(epd);
485 * Read up to \a size bytes from the USB endpoint identified by the address
486 * \a ep and store them in \a buffer.
488 * \return number of bytes actually read.
490 ssize_t usb_endpointRead(int ep, void *buffer, ssize_t size);
493 * Write up to \a size bytes from the buffer pointed \a buffer to the USB
494 * endpoint identified by the address \a ep.
496 * \return number of bytes actually wrote.
498 ssize_t usb_endpointWrite(int ep, const void *buffer, ssize_t size);
501 * Register a generic USB device driver \a dev in the USB controller.
503 int usb_deviceRegister(UsbDevice *dev);