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 * \attention The API is work in progress and may change in future versions.
42 * $WIZ$ module_name = "usb"
43 * $WIZ$ module_configuration = "bertos/cfg/cfg_usb.h"
44 * $WIZ$ module_supports = "stm32"
50 #include <cpu/byteorder.h>
52 #define usb_cpu_to_le16(x) cpu_to_le16(x)
53 #define usb_le16_to_cpu(x) le16_to_cpu(x)
54 #define usb_cpu_to_le32(x) cpu_to_le32(x)
55 #define usb_le32_to_cpu(x) le32_to_cpu(x)
57 /* State of a USB device */
58 enum usb_device_state {
59 USB_STATE_NOTATTACHED = 0,
61 /* chapter 9 device states */
63 USB_STATE_POWERED, /* wired */
64 USB_STATE_DEFAULT, /* limited function */
66 USB_STATE_CONFIGURED, /* most functions */
72 * This bit flag is used in endpoint descriptors' bEndpointAddress field.
73 * It's also one of three fields in control requests bRequestType.
75 #define USB_DIR_OUT 0 /* to device */
76 #define USB_DIR_IN 0x80 /* to host */
77 #define USB_DIR_MASK 0x80
80 * USB types, the second of three bRequestType fields
82 #define USB_TYPE_MASK (0x03 << 5)
83 #define USB_TYPE_STANDARD (0x00 << 5)
84 #define USB_TYPE_CLASS (0x01 << 5)
85 #define USB_TYPE_VENDOR (0x02 << 5)
86 #define USB_TYPE_RESERVED (0x03 << 5)
89 * USB recipients, the third of three bRequestType fields
91 #define USB_RECIP_MASK 0x1f
92 #define USB_RECIP_DEVICE 0x00
93 #define USB_RECIP_INTERFACE 0x01
94 #define USB_RECIP_ENDPOINT 0x02
95 #define USB_RECIP_OTHER 0x03
98 * USB standard requests, for the bRequest field of a SETUP packet.
100 #define USB_REQ_GET_STATUS 0x00
101 #define USB_REQ_CLEAR_FEATURE 0x01
102 #define USB_REQ_SET_FEATURE 0x03
103 #define USB_REQ_SET_ADDRESS 0x05
104 #define USB_REQ_GET_DESCRIPTOR 0x06
105 #define USB_REQ_SET_DESCRIPTOR 0x07
106 #define USB_REQ_GET_CONFIGURATION 0x08
107 #define USB_REQ_SET_CONFIGURATION 0x09
108 #define USB_REQ_GET_INTERFACE 0x0A
109 #define USB_REQ_SET_INTERFACE 0x0B
110 #define USB_REQ_SYNCH_FRAME 0x0C
113 * Descriptor types ... USB 2.0 spec table 9.5
115 #define USB_DT_DEVICE 0x01
116 #define USB_DT_CONFIG 0x02
117 #define USB_DT_STRING 0x03
118 #define USB_DT_INTERFACE 0x04
119 #define USB_DT_ENDPOINT 0x05
120 #define USB_DT_DEVICE_QUALIFIER 0x06
121 #define USB_DT_OTHER_SPEED_CONFIG 0x07
122 #define USB_DT_INTERFACE_POWER 0x08
125 * Conventional codes for class-specific descriptors. The convention is
126 * defined in the USB "Common Class" Spec (3.11). Individual class specs
127 * are authoritative for their usage, not the "common class" writeup.
129 #define USB_DT_CS_DEVICE (USB_TYPE_CLASS | USB_DT_DEVICE)
130 #define USB_DT_CS_CONFIG (USB_TYPE_CLASS | USB_DT_CONFIG)
131 #define USB_DT_CS_STRING (USB_TYPE_CLASS | USB_DT_STRING)
132 #define USB_DT_CS_INTERFACE (USB_TYPE_CLASS | USB_DT_INTERFACE)
133 #define USB_DT_CS_ENDPOINT (USB_TYPE_CLASS | USB_DT_ENDPOINT)
137 * USB Control Request descriptor
139 * This structure is used to send control requests to a USB device.
141 * It matches the different fields of the USB 2.0 specification (section 9.3,
144 typedef struct UsbCtrlRequest
146 uint8_t mRequestType;
151 } PACKED UsbCtrlRequest;
154 * USB common descriptor header.
156 * \note All the USB standard descriptors have these 2 fields at the beginning.
158 typedef struct UsbDescHeader
161 uint8_t bDescriptorType;
162 } PACKED UsbDescHeader;
165 * USB Device descriptor
167 * \note See USB 2.0 specification.
169 typedef struct UsbDeviceDesc
172 uint8_t bDescriptorType;
174 uint8_t bDeviceClass;
175 uint8_t bDeviceSubClass;
176 uint8_t bDeviceProtocol;
177 uint8_t bMaxPacketSize0;
181 uint8_t iManufacturer;
183 uint8_t iSerialNumber;
184 uint8_t bNumConfigurations;
185 } PACKED UsbDeviceDesc;
188 * USB string descriptor.
190 * \note See USB 2.0 specification.
192 typedef struct UsbStringDesc
195 uint8_t bDescriptorType;
197 } PACKED UsbStringDesc;
199 #define USB_STRING_1(__a, ...) __a "\x00"
200 #define USB_STRING_2(__a, ...) __a "\x00" USB_STRING_1(__VA_ARGS__)
201 #define USB_STRING_3(__a, ...) __a "\x00" USB_STRING_2(__VA_ARGS__)
202 #define USB_STRING_4(__a, ...) __a "\x00" USB_STRING_3(__VA_ARGS__)
203 #define USB_STRING_5(__a, ...) __a "\x00" USB_STRING_4(__VA_ARGS__)
204 #define USB_STRING_6(__a, ...) __a "\x00" USB_STRING_5(__VA_ARGS__)
205 #define USB_STRING_7(__a, ...) __a "\x00" USB_STRING_6(__VA_ARGS__)
206 #define USB_STRING_8(__a, ...) __a "\x00" USB_STRING_7(__VA_ARGS__)
207 #define USB_STRING_9(__a, ...) __a "\x00" USB_STRING_8(__VA_ARGS__)
208 #define USB_STRING_10(__a, ...) __a "\x00" USB_STRING_9(__VA_ARGS__)
209 #define USB_STRING_11(__a, ...) __a "\x00" USB_STRING_10(__VA_ARGS__)
210 #define USB_STRING_12(__a, ...) __a "\x00" USB_STRING_11(__VA_ARGS__)
211 #define USB_STRING_13(__a, ...) __a "\x00" USB_STRING_12(__VA_ARGS__)
212 #define USB_STRING_14(__a, ...) __a "\x00" USB_STRING_13(__VA_ARGS__)
213 #define USB_STRING_15(__a, ...) __a "\x00" USB_STRING_14(__VA_ARGS__)
214 #define USB_STRING_16(__a, ...) __a "\x00" USB_STRING_15(__VA_ARGS__)
217 * Pack a list with a variable number of elements into a UTF-16LE USB string.
219 * \note The macro is recursively defined according the number of elements
220 * passed as argument. At the moment we support strings with up to 16
223 #define USB_STRING(...) PP_CAT(USB_STRING_, PP_COUNT(__VA_ARGS__))(__VA_ARGS__)
226 * Define and initialize an USB string descriptor.
228 * This macro is reuquired to properly declare and initialize a constant USB
229 * string in UTF-16LE format.
231 * The structure must contain the standard common USB header (UsbDescHeader)
232 * and the UTF-16LE string all packed in a contiguous memory region.
234 #define DEFINE_USB_STRING(__name, __text) \
236 UsbDescHeader __header; \
237 uint8_t __body[sizeof(__text)]; \
238 } PACKED __name = { \
241 cpu_to_le16((uint16_t)sizeof(__name)), \
242 .bDescriptorType = USB_DT_STRING, \
244 .__body = {__text}, \
248 * Device and/or Interface Class codes as found in bDeviceClass or
249 * bInterfaceClass and defined by www.usb.org documents.
251 #define USB_CLASS_PER_INTERFACE 0 /* for DeviceClass */
252 #define USB_CLASS_AUDIO 1
253 #define USB_CLASS_COMM 2
254 #define USB_CLASS_HID 3
255 #define USB_CLASS_PHYSICAL 5
256 #define USB_CLASS_STILL_IMAGE 6
257 #define USB_CLASS_PRINTER 7
258 #define USB_CLASS_MASS_STORAGE 8
259 #define USB_CLASS_HUB 9
260 #define USB_CLASS_CDC_DATA 0x0a
261 #define USB_CLASS_CSCID 0x0b /* chip+ smart card */
262 #define USB_CLASS_CONTENT_SEC 0x0d /* content security */
263 #define USB_CLASS_VIDEO 0x0e
264 #define USB_CLASS_WIRELESS_CONTROLLER 0xe0
265 #define USB_CLASS_MISC 0xef
266 #define USB_CLASS_APP_SPEC 0xfe
267 #define USB_CLASS_VENDOR_SPEC 0xff
269 /* USB Device subclasses */
270 #define USB_CDC_SUBCLASS_ACM 0x02
271 #define USB_CDC_SUBCLASS_ETHERNET 0x06
272 #define USB_CDC_SUBCLASS_WHCM 0x08
273 #define USB_CDC_SUBCLASS_DMM 0x09
274 #define USB_CDC_SUBCLASS_MDLM 0x0a
275 #define USB_CDC_SUBCLASS_OBEX 0x0b
276 #define USB_CDC_SUBCLASS_EEM 0x0c
277 #define USB_CDC_SUBCLASS_NCM 0x0d
280 * Device configuration descriptor
282 * \note See USB 2.0 specification.
284 typedef struct UsbConfigDesc
287 uint8_t bDescriptorType;
288 uint16_t wTotalLength;
289 uint8_t bNumInterfaces;
290 uint8_t bConfigurationValue;
291 uint8_t iConfiguration;
292 uint8_t bmAttributes;
294 } PACKED UsbConfigDesc;
296 /* from config descriptor bmAttributes */
297 #define USB_CONFIG_ATT_ONE (1 << 7) /* must be set */
298 #define USB_CONFIG_ATT_SELFPOWER (1 << 6) /* self powered */
299 #define USB_CONFIG_ATT_WAKEUP (1 << 5) /* can wakeup */
300 #define USB_CONFIG_ATT_BATTERY (1 << 4) /* battery powered */
303 * Device interface descriptor
305 * \note See USB 2.0 specification.
307 typedef struct UsbInterfaceDesc
310 uint8_t bDescriptorType;
311 uint8_t bInterfaceNumber;
312 uint8_t bAlternateSetting;
313 uint8_t bNumEndpoints;
314 uint8_t bInterfaceClass;
315 uint8_t bInterfaceSubClass;
316 uint8_t bInterfaceProtocol;
318 } PACKED UsbInterfaceDesc;
321 * Endpoint descriptor
323 * \note See USB 2.0 specification.
325 typedef struct UsbEndpointDesc
328 uint8_t bDescriptorType;
329 uint8_t bEndpointAddress;
330 uint8_t bmAttributes;
331 uint16_t wMaxPacketSize;
333 } PACKED UsbEndpointDesc;
338 #define USB_ENDPOINT_NUMBER_MASK 0x0f /* in bEndpointAddress */
339 #define USB_ENDPOINT_DIR_MASK USB_DIR_MASK
341 #define USB_ENDPOINT_SYNCTYPE 0x0c
342 #define USB_ENDPOINT_SYNC_NONE (0 << 2)
343 #define USB_ENDPOINT_SYNC_ASYNC (1 << 2)
344 #define USB_ENDPOINT_SYNC_ADAPTIVE (2 << 2)
345 #define USB_ENDPOINT_SYNC_SYNC (3 << 2)
347 #define USB_ENDPOINT_XFERTYPE_MASK 0x03 /* in bmAttributes */
348 #define USB_ENDPOINT_XFER_CONTROL 0
349 #define USB_ENDPOINT_XFER_ISOC 1
350 #define USB_ENDPOINT_XFER_BULK 2
351 #define USB_ENDPOINT_XFER_INT 3
352 #define USB_ENDPOINT_MAX_ADJUSTABLE 0x80
355 * USB: generic device descriptor
357 typedef struct UsbDevice
359 UsbDeviceDesc *device; ///< USB 2.0 device descriptor
360 const UsbDescHeader **config; ///< USB 2.0 configuration descriptors
361 const UsbStringDesc **strings; ///< USB strings
364 void (*event_cb)(UsbCtrlRequest *); ///< Called to handle control requests.
367 bool configured; ///< True when the device has been correctly initialized.
371 * Get the endpoint's address number of \a epd.
373 INLINE int usb_endpointNum(const UsbEndpointDesc *epd)
375 return epd->bEndpointAddress & USB_ENDPOINT_NUMBER_MASK;
379 * Get the transfer type of the endpoint \a epd.
381 INLINE int usb_endpointType(const struct UsbEndpointDesc *epd)
383 return epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK;
387 * Check if the endpoint \a epd has IN direction.
389 INLINE int usb_endpointDirIn(const struct UsbEndpointDesc *epd)
391 return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_IN);
395 * Check if the endpoint \a epd has OUT direction.
397 INLINE int usb_endpointDirOut(const struct UsbEndpointDesc *epd)
399 return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_OUT);
403 * Check if the endpoint \a epd has bulk transfer type.
405 INLINE int usb_endpointXferBulk(const struct UsbEndpointDesc *epd)
407 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
408 USB_ENDPOINT_XFER_BULK);
412 * Check if the endpoint \a epd has control transfer type.
414 INLINE int usb_endpointXferControl(const struct UsbEndpointDesc *epd)
416 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
417 USB_ENDPOINT_XFER_CONTROL);
421 * Check if the endpoint \a epd has interrupt transfer type.
423 INLINE int usb_endpointXferInt(const struct UsbEndpointDesc *epd)
425 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
426 USB_ENDPOINT_XFER_INT);
430 * Check if the endpoint \a epd has isochronous transfer type.
432 INLINE int usb_endpointXferIsoc(const struct UsbEndpointDesc *epd)
434 return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
435 USB_ENDPOINT_XFER_ISOC);
439 * Check if the endpoint \a epd is bulk IN.
441 INLINE int usb_endpointIsBulkIn(const struct UsbEndpointDesc *epd)
443 return usb_endpointXferBulk(epd) && usb_endpointDirIn(epd);
447 * Check if the endpoint \a epd is bulk OUT.
449 INLINE int usb_endpointIsBulkOut(const struct UsbEndpointDesc *epd)
451 return usb_endpointXferBulk(epd) && usb_endpointDirOut(epd);
455 * Check if the endpoint \a epd is interrupt IN.
457 INLINE int usb_endpointIsIntIn(const struct UsbEndpointDesc *epd)
459 return usb_endpointXferInt(epd) && usb_endpointDirIn(epd);
463 * Check if the endpoint \a epd is interrupt OUT.
465 INLINE int usb_endpointIsIntOut(const struct UsbEndpointDesc *epd)
467 return usb_endpointXferInt(epd) && usb_endpointDirOut(epd);
471 * Check if the endpoint \a epd is isochronous IN.
473 INLINE int usb_endpointIsIsocIn(const struct UsbEndpointDesc *epd)
475 return usb_endpointXferIsoc(epd) && usb_endpointDirIn(epd);
479 * Check if the endpoint \a epd is isochronous OUT.
481 INLINE int usb_endpointIsIsocOut(const struct UsbEndpointDesc *epd)
483 return usb_endpointXferIsoc(epd) && usb_endpointDirOut(epd);
487 * Read up to \a size bytes from the USB endpoint identified by the address
488 * \a ep and store them in \a buffer.
490 * \return number of bytes actually read.
492 ssize_t usb_endpointRead(int ep, void *buffer, ssize_t size);
495 * Write up to \a size bytes from the buffer pointed \a buffer to the USB
496 * endpoint identified by the address \a ep.
498 * \return number of bytes actually wrote.
500 ssize_t usb_endpointWrite(int ep, const void *buffer, ssize_t size);
503 * Register a generic USB device driver \a dev in the USB controller.
505 int usb_deviceRegister(UsbDevice *dev);