bertos/drv/usb.h

   1 /**
   2  * \file
   3  * <!--
   4  * This file is part of BeRTOS.
   5  *
   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.
  10  *
  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.
  15  *
  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
  19  *
  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.
  28  *
  29  * Copyright 2010 Develer S.r.l. (http://www.develer.com/)
  30  *
  31  * -->
  32  *
  33  * \author Andrea Righi <arighi@develer.com>
  34  *
  35  * \brief USB 2.0 standard descriptors
  36  *
  37  * This file holds USB constants and structures that are needed for USB device
  38  * APIs, as defined in the USB 2.0 specification.
  39  *
  40  * $WIZ$ module_name = "usb"
  41  * $WIZ$ module_configuration = "bertos/cfg/cfg_usb.h"
  42  * $WIZ$ module_supports = "stm32"
  43  */
  44
  45 #ifndef USB_H
  46 #define USB_H
  47
  48 #include <cpu/byteorder.h>
  49
  50 /*
  51  * Handle CPU endianess
  52  *
  53  * TODO: consider to move this stuff in compiler.h
  54  */
  55 #define usb_bswap16(x) (((x & 0xff) << 8) | (x >> 8))
  56 #define usb_bswap32(x) ((usb_bswap16(x & 0xffff) << 16) | usb_bswap16(x >> 16))
  57
  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)
  68 #else
  69 #error "unrecognized CPU endianness"
  70 #endif
  71
  72 /* State of a USB device */
  73 enum usb_device_state {
  74         USB_STATE_NOTATTACHED = 0,
  75
  76         /* chapter 9 device states */
  77         USB_STATE_ATTACHED,
  78         USB_STATE_POWERED,                      /* wired */
  79         USB_STATE_DEFAULT,                      /* limited function */
  80         USB_STATE_ADDRESS,
  81         USB_STATE_CONFIGURED,                   /* most functions */
  82 };
  83
  84 /*
  85  * USB directions
  86  *
  87  * This bit flag is used in endpoint descriptors' bEndpointAddress field.
  88  * It's also one of three fields in control requests bRequestType.
  89  */
  90 #define USB_DIR_OUT                     0               /* to device */
  91 #define USB_DIR_IN                      0x80            /* to host */
  92
  93 /*
  94  * USB types, the second of three bRequestType fields
  95  */
  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)
 101
 102 /*
 103  * USB recipients, the third of three bRequestType fields
 104  */
 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
 110
 111 /*
 112  * USB standard requests, for the bRequest field of a SETUP packet.
 113  */
 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
 125
 126 /*
 127  * Descriptor types ... USB 2.0 spec table 9.5
 128  */
 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
 137
 138 /*
 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.
 142  */
 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)
 148
 149 /*
 150  * This structure is used to send control requests to a USB device.
 151  *
 152  * It matches the different fields of the USB 2.0 spec. section 9.3, table 9-2.
 153  */
 154 typedef struct usb_ctrlrequest
 155 {
 156         uint8_t mRequestType;
 157         uint8_t bRequest;
 158         uint16_t wValue;
 159         uint16_t wIndex;
 160         uint16_t wLength;
 161 } PACKED usb_ctrlrequest_t;
 162
 163 /* All standard descriptors have these 2 fields at the beginning */
 164 typedef struct usb_descriptor_header
 165 {
 166         uint8_t bLength;
 167         uint8_t bDescriptorType;
 168 } PACKED usb_descriptor_header_t;
 169
 170 /* Device descriptor */
 171 typedef struct usb_device_descriptor
 172 {
 173         uint8_t bLength;
 174         uint8_t bDescriptorType;
 175         uint16_t bcdUSB;
 176         uint8_t bDeviceClass;
 177         uint8_t bDeviceSubClass;
 178         uint8_t bDeviceProtocol;
 179         uint8_t bMaxPacketSize0;
 180         uint16_t idVendor;
 181         uint16_t idProduct;
 182         uint16_t bcdDevice;
 183         uint8_t iManufacturer;
 184         uint8_t iProduct;
 185         uint8_t iSerialNumber;
 186         uint8_t bNumConfigurations;
 187 } PACKED usb_device_descriptor_t;
 188
 189 /* USB string descriptor */
 190 typedef struct usb_string_descriptor
 191 {
 192         uint8_t bLength;
 193         uint8_t bDescriptorType;
 194         uint8_t data[0];
 195 } PACKED usb_string_descriptor_t;
 196
 197 /*
 198  * Macros to define USB strings
 199  *
 200  * TODO: add comment.
 201  */
 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__)
 218
 219 #define USB_STRING(...) PP_CAT(USB_STRING_, PP_COUNT(__VA_ARGS__))(__VA_ARGS__)
 220
 221 #define DEFINE_USB_STRING(__name, __text)                       \
 222         struct {                                                \
 223                 usb_descriptor_header_t __header;               \
 224                 uint8_t __body[sizeof(__text)];                 \
 225         } PACKED __name = {                                     \
 226                 .__header = {                                   \
 227                         .bLength = sizeof(__name),              \
 228                         .bDescriptorType = USB_DT_STRING,       \
 229                 },                                              \
 230                 .__body = {__text},                             \
 231         }
 232
 233 /*
 234  * Device and/or Interface Class codes as found in bDeviceClass or
 235  * bInterfaceClass and defined by www.usb.org documents.
 236  */
 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
 254
 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
 264
 265 /* Device configuration descriptor */
 266 typedef struct usb_config_descriptor
 267 {
 268         uint8_t bLength;
 269         uint8_t bDescriptorType;
 270         uint16_t wTotalLength;
 271         uint8_t bNumInterfaces;
 272         uint8_t bConfigurationValue;
 273         uint8_t iConfiguration;
 274         uint8_t bmAttributes;
 275         uint8_t bMaxPower;
 276 } PACKED usb_config_descriptor_t;
 277
 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 */
 283
 284 /* Device interface descriptor */
 285 typedef struct usb_interface_descriptor
 286 {
 287         uint8_t bLength;
 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;
 295         uint8_t iInterface;
 296 } PACKED usb_interface_descriptor_t;
 297
 298 /* Endpoint descriptor */
 299 typedef struct usb_endpoint_descriptor
 300 {
 301         uint8_t bLength;
 302         uint8_t bDescriptorType;
 303         uint8_t bEndpointAddress;
 304         uint8_t bmAttributes;
 305         uint16_t wMaxPacketSize;
 306         uint8_t bInterval;
 307 } PACKED usb_endpoint_descriptor_t;
 308
 309 /*
 310  * Endpoints
 311  */
 312 #define USB_ENDPOINT_NUMBER_MASK        0x0f    /* in bEndpointAddress */
 313 #define USB_ENDPOINT_DIR_MASK           0x80
 314
 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)
 320
 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
 327
 328 /* USB: generic device descriptor */
 329 struct usb_device
 330 {
 331         usb_device_descriptor_t *device;
 332         usb_descriptor_header_t **config;
 333         usb_string_descriptor_t **strings;
 334
 335         /* Callbacks */
 336         void (*event_cb)(usb_ctrlrequest_t *);
 337
 338         /* Private data */
 339         bool configured;
 340 };
 341
 342 /*
 343  * usb_endpoint_num - get the endpoint's number
 344  */
 345 INLINE int usb_endpoint_num(const usb_endpoint_descriptor_t *epd)
 346 {
 347         return epd->bEndpointAddress & USB_ENDPOINT_NUMBER_MASK;
 348 }
 349
 350 /*
 351  * usb_endpoint_type - get the endpoint's transfer type
 352  */
 353 INLINE int usb_endpoint_type(const struct usb_endpoint_descriptor *epd)
 354 {
 355         return epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK;
 356 }
 357
 358 /*
 359  * usb_endpoint_dir_in - check if the endpoint has IN direction
 360  */
 361 INLINE int usb_endpoint_dir_in(const struct usb_endpoint_descriptor *epd)
 362 {
 363         return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_IN);
 364 }
 365
 366 /*
 367  * usb_endpoint_dir_out - check if the endpoint has OUT direction
 368  */
 369 INLINE int usb_endpoint_dir_out(const struct usb_endpoint_descriptor *epd)
 370 {
 371         return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_OUT);
 372 }
 373
 374 /*
 375  * usb_endpoint_xfer_bulk - check if the endpoint has bulk transfer type
 376  */
 377 INLINE int usb_endpoint_xfer_bulk(const struct usb_endpoint_descriptor *epd)
 378 {
 379         return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
 380                 USB_ENDPOINT_XFER_BULK);
 381 }
 382
 383 /*
 384  * usb_endpoint_xfer_control - check if the endpoint has control transfer type
 385  */
 386 INLINE int usb_endpoint_xfer_control(const struct usb_endpoint_descriptor *epd)
 387 {
 388         return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
 389                 USB_ENDPOINT_XFER_CONTROL);
 390 }
 391
 392 /*
 393  * usb_endpoint_xfer_int - check if the endpoint has interrupt transfer type
 394  */
 395 INLINE int usb_endpoint_xfer_int(const struct usb_endpoint_descriptor *epd)
 396 {
 397         return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
 398                 USB_ENDPOINT_XFER_INT);
 399 }
 400
 401 /*
 402  * usb_endpoint_xfer_isoc - check if the endpoint has isochronous transfer type
 403  */
 404 INLINE int usb_endpoint_xfer_isoc(const struct usb_endpoint_descriptor *epd)
 405 {
 406         return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
 407                 USB_ENDPOINT_XFER_ISOC);
 408 }
 409
 410 /*
 411  * usb_endpoint_is_bulk_in - check if the endpoint is bulk IN
 412  */
 413 INLINE int usb_endpoint_is_bulk_in(const struct usb_endpoint_descriptor *epd)
 414 {
 415         return usb_endpoint_xfer_bulk(epd) && usb_endpoint_dir_in(epd);
 416 }
 417
 418 /*
 419  * usb_endpoint_is_bulk_out - check if the endpoint is bulk OUT
 420  */
 421 INLINE int usb_endpoint_is_bulk_out(const struct usb_endpoint_descriptor *epd)
 422 {
 423         return usb_endpoint_xfer_bulk(epd) && usb_endpoint_dir_out(epd);
 424 }
 425
 426 /*
 427  * usb_endpoint_is_int_in - check if the endpoint is interrupt IN
 428  */
 429 INLINE int usb_endpoint_is_int_in(const struct usb_endpoint_descriptor *epd)
 430 {
 431         return usb_endpoint_xfer_int(epd) && usb_endpoint_dir_in(epd);
 432 }
 433
 434 /*
 435  * usb_endpoint_is_int_out - check if the endpoint is interrupt OUT
 436  */
 437 INLINE int usb_endpoint_is_int_out(const struct usb_endpoint_descriptor *epd)
 438 {
 439         return usb_endpoint_xfer_int(epd) && usb_endpoint_dir_out(epd);
 440 }
 441
 442 /*
 443  * usb_endpoint_is_isoc_in - check if the endpoint is isochronous IN
 444  */
 445 INLINE int usb_endpoint_is_isoc_in(const struct usb_endpoint_descriptor *epd)
 446 {
 447         return usb_endpoint_xfer_isoc(epd) && usb_endpoint_dir_in(epd);
 448 }
 449
 450 /*
 451  * usb_endpoint_is_isoc_out - check if the endpoint is isochronous OUT
 452  */
 453 INLINE int usb_endpoint_is_isoc_out(const struct usb_endpoint_descriptor *epd)
 454 {
 455         return usb_endpoint_xfer_isoc(epd) && usb_endpoint_dir_out(epd);
 456 }
 457
 458 /*
 459  * usb_ep_read - configure endponint and perform the read operation
 460  */
 461 ssize_t usb_ep_read(int ep, void *buffer, ssize_t size);
 462
 463 /*
 464  * usb_ep_write - configure endponint and perform the write operation
 465  */
 466 ssize_t usb_ep_write(int ep, const void *buffer, ssize_t size);
 467
 468 /*
 469  * usb_device_register - register a generic USB device driver
 470  */
 471 int usb_device_register(struct usb_device *dev);
 472
 473 #endif /* USB_H */