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 #define USB_DIR_MASK                    0x80
  93
  94 /*
  95  * USB types, the second of three bRequestType fields
  96  */
  97 #define USB_TYPE_MASK                   (0x03 << 5)
  98 #define USB_TYPE_STANDARD               (0x00 << 5)
  99 #define USB_TYPE_CLASS                  (0x01 << 5)
 100 #define USB_TYPE_VENDOR                 (0x02 << 5)
 101 #define USB_TYPE_RESERVED               (0x03 << 5)
 102
 103 /*
 104  * USB recipients, the third of three bRequestType fields
 105  */
 106 #define USB_RECIP_MASK                  0x1f
 107 #define USB_RECIP_DEVICE                0x00
 108 #define USB_RECIP_INTERFACE             0x01
 109 #define USB_RECIP_ENDPOINT              0x02
 110 #define USB_RECIP_OTHER                 0x03
 111
 112 /*
 113  * USB standard requests, for the bRequest field of a SETUP packet.
 114  */
 115 #define USB_REQ_GET_STATUS              0x00
 116 #define USB_REQ_CLEAR_FEATURE           0x01
 117 #define USB_REQ_SET_FEATURE             0x03
 118 #define USB_REQ_SET_ADDRESS             0x05
 119 #define USB_REQ_GET_DESCRIPTOR          0x06
 120 #define USB_REQ_SET_DESCRIPTOR          0x07
 121 #define USB_REQ_GET_CONFIGURATION       0x08
 122 #define USB_REQ_SET_CONFIGURATION       0x09
 123 #define USB_REQ_GET_INTERFACE           0x0A
 124 #define USB_REQ_SET_INTERFACE           0x0B
 125 #define USB_REQ_SYNCH_FRAME             0x0C
 126
 127 /*
 128  * Descriptor types ... USB 2.0 spec table 9.5
 129  */
 130 #define USB_DT_DEVICE                   0x01
 131 #define USB_DT_CONFIG                   0x02
 132 #define USB_DT_STRING                   0x03
 133 #define USB_DT_INTERFACE                0x04
 134 #define USB_DT_ENDPOINT                 0x05
 135 #define USB_DT_DEVICE_QUALIFIER         0x06
 136 #define USB_DT_OTHER_SPEED_CONFIG       0x07
 137 #define USB_DT_INTERFACE_POWER          0x08
 138
 139 /*
 140  * Conventional codes for class-specific descriptors.  The convention is
 141  * defined in the USB "Common Class" Spec (3.11).  Individual class specs
 142  * are authoritative for their usage, not the "common class" writeup.
 143  */
 144 #define USB_DT_CS_DEVICE                (USB_TYPE_CLASS | USB_DT_DEVICE)
 145 #define USB_DT_CS_CONFIG                (USB_TYPE_CLASS | USB_DT_CONFIG)
 146 #define USB_DT_CS_STRING                (USB_TYPE_CLASS | USB_DT_STRING)
 147 #define USB_DT_CS_INTERFACE             (USB_TYPE_CLASS | USB_DT_INTERFACE)
 148 #define USB_DT_CS_ENDPOINT              (USB_TYPE_CLASS | USB_DT_ENDPOINT)
 149
 150 /*
 151  * This structure is used to send control requests to a USB device.
 152  *
 153  * It matches the different fields of the USB 2.0 spec. section 9.3, table 9-2.
 154  */
 155 typedef struct UsbCtrlRequest
 156 {
 157         uint8_t mRequestType;
 158         uint8_t bRequest;
 159         uint16_t wValue;
 160         uint16_t wIndex;
 161         uint16_t wLength;
 162 } PACKED UsbCtrlRequest;
 163
 164 /* All standard descriptors have these 2 fields at the beginning */
 165 typedef struct UsbDescHeader
 166 {
 167         uint8_t bLength;
 168         uint8_t bDescriptorType;
 169 } PACKED UsbDescHeader;
 170
 171 /* Device descriptor */
 172 typedef struct UsbDeviceDesc
 173 {
 174         uint8_t bLength;
 175         uint8_t bDescriptorType;
 176         uint16_t bcdUSB;
 177         uint8_t bDeviceClass;
 178         uint8_t bDeviceSubClass;
 179         uint8_t bDeviceProtocol;
 180         uint8_t bMaxPacketSize0;
 181         uint16_t idVendor;
 182         uint16_t idProduct;
 183         uint16_t bcdDevice;
 184         uint8_t iManufacturer;
 185         uint8_t iProduct;
 186         uint8_t iSerialNumber;
 187         uint8_t bNumConfigurations;
 188 } PACKED UsbDeviceDesc;
 189
 190 /* USB string descriptor */
 191 typedef struct UsbStringDesc
 192 {
 193         uint8_t bLength;
 194         uint8_t bDescriptorType;
 195         uint8_t data[0];
 196 } PACKED UsbStringDesc;
 197
 198 /*
 199  * Macros to define USB strings
 200  *
 201  * TODO: add comment.
 202  */
 203 #define USB_STRING_1(__a, ...) __a "\x00"
 204 #define USB_STRING_2(__a, ...) __a "\x00" USB_STRING_1(__VA_ARGS__)
 205 #define USB_STRING_3(__a, ...) __a "\x00" USB_STRING_2(__VA_ARGS__)
 206 #define USB_STRING_4(__a, ...) __a "\x00" USB_STRING_3(__VA_ARGS__)
 207 #define USB_STRING_5(__a, ...) __a "\x00" USB_STRING_4(__VA_ARGS__)
 208 #define USB_STRING_6(__a, ...) __a "\x00" USB_STRING_5(__VA_ARGS__)
 209 #define USB_STRING_7(__a, ...) __a "\x00" USB_STRING_6(__VA_ARGS__)
 210 #define USB_STRING_8(__a, ...) __a "\x00" USB_STRING_7(__VA_ARGS__)
 211 #define USB_STRING_9(__a, ...) __a "\x00" USB_STRING_8(__VA_ARGS__)
 212 #define USB_STRING_10(__a, ...) __a "\x00" USB_STRING_9(__VA_ARGS__)
 213 #define USB_STRING_11(__a, ...) __a "\x00" USB_STRING_10(__VA_ARGS__)
 214 #define USB_STRING_12(__a, ...) __a "\x00" USB_STRING_11(__VA_ARGS__)
 215 #define USB_STRING_13(__a, ...) __a "\x00" USB_STRING_12(__VA_ARGS__)
 216 #define USB_STRING_14(__a, ...) __a "\x00" USB_STRING_13(__VA_ARGS__)
 217 #define USB_STRING_15(__a, ...) __a "\x00" USB_STRING_14(__VA_ARGS__)
 218 #define USB_STRING_16(__a, ...) __a "\x00" USB_STRING_15(__VA_ARGS__)
 219
 220 #define USB_STRING(...) PP_CAT(USB_STRING_, PP_COUNT(__VA_ARGS__))(__VA_ARGS__)
 221
 222 #define DEFINE_USB_STRING(__name, __text)                       \
 223         struct {                                                \
 224                 UsbDescHeader __header;         \
 225                 uint8_t __body[sizeof(__text)];                 \
 226         } PACKED __name = {                                     \
 227                 .__header = {                                   \
 228                         .bLength = sizeof(__name),              \
 229                         .bDescriptorType = USB_DT_STRING,       \
 230                 },                                              \
 231                 .__body = {__text},                             \
 232         }
 233
 234 /*
 235  * Device and/or Interface Class codes as found in bDeviceClass or
 236  * bInterfaceClass and defined by www.usb.org documents.
 237  */
 238 #define USB_CLASS_PER_INTERFACE         0       /* for DeviceClass */
 239 #define USB_CLASS_AUDIO                 1
 240 #define USB_CLASS_COMM                  2
 241 #define USB_CLASS_HID                   3
 242 #define USB_CLASS_PHYSICAL              5
 243 #define USB_CLASS_STILL_IMAGE           6
 244 #define USB_CLASS_PRINTER               7
 245 #define USB_CLASS_MASS_STORAGE          8
 246 #define USB_CLASS_HUB                   9
 247 #define USB_CLASS_CDC_DATA              0x0a
 248 #define USB_CLASS_CSCID                 0x0b    /* chip+ smart card */
 249 #define USB_CLASS_CONTENT_SEC           0x0d    /* content security */
 250 #define USB_CLASS_VIDEO                 0x0e
 251 #define USB_CLASS_WIRELESS_CONTROLLER   0xe0
 252 #define USB_CLASS_MISC                  0xef
 253 #define USB_CLASS_APP_SPEC              0xfe
 254 #define USB_CLASS_VENDOR_SPEC           0xff
 255
 256 /* USB Device subclasses */
 257 #define USB_CDC_SUBCLASS_ACM                    0x02
 258 #define USB_CDC_SUBCLASS_ETHERNET               0x06
 259 #define USB_CDC_SUBCLASS_WHCM                   0x08
 260 #define USB_CDC_SUBCLASS_DMM                    0x09
 261 #define USB_CDC_SUBCLASS_MDLM                   0x0a
 262 #define USB_CDC_SUBCLASS_OBEX                   0x0b
 263 #define USB_CDC_SUBCLASS_EEM                    0x0c
 264 #define USB_CDC_SUBCLASS_NCM                    0x0d
 265
 266 /* Device configuration descriptor */
 267 typedef struct UsbConfigDesc
 268 {
 269         uint8_t bLength;
 270         uint8_t bDescriptorType;
 271         uint16_t wTotalLength;
 272         uint8_t bNumInterfaces;
 273         uint8_t bConfigurationValue;
 274         uint8_t iConfiguration;
 275         uint8_t bmAttributes;
 276         uint8_t bMaxPower;
 277 } PACKED UsbConfigDesc;
 278
 279 /* from config descriptor bmAttributes */
 280 #define USB_CONFIG_ATT_ONE              (1 << 7)        /* must be set */
 281 #define USB_CONFIG_ATT_SELFPOWER        (1 << 6)        /* self powered */
 282 #define USB_CONFIG_ATT_WAKEUP           (1 << 5)        /* can wakeup */
 283 #define USB_CONFIG_ATT_BATTERY          (1 << 4)        /* battery powered */
 284
 285 /* Device interface descriptor */
 286 typedef struct UsbInterfaceDesc
 287 {
 288         uint8_t bLength;
 289         uint8_t bDescriptorType;
 290         uint8_t bInterfaceNumber;
 291         uint8_t bAlternateSetting;
 292         uint8_t bNumEndpoints;
 293         uint8_t bInterfaceClass;
 294         uint8_t bInterfaceSubClass;
 295         uint8_t bInterfaceProtocol;
 296         uint8_t iInterface;
 297 } PACKED UsbInterfaceDesc;
 298
 299 /* Endpoint descriptor */
 300 typedef struct UsbEndpointDesc
 301 {
 302         uint8_t bLength;
 303         uint8_t bDescriptorType;
 304         uint8_t bEndpointAddress;
 305         uint8_t bmAttributes;
 306         uint16_t wMaxPacketSize;
 307         uint8_t bInterval;
 308 } PACKED UsbEndpointDesc;
 309
 310 /*
 311  * Endpoints
 312  */
 313 #define USB_ENDPOINT_NUMBER_MASK        0x0f    /* in bEndpointAddress */
 314 #define USB_ENDPOINT_DIR_MASK           USB_DIR_MASK
 315
 316 #define USB_ENDPOINT_SYNCTYPE           0x0c
 317 #define USB_ENDPOINT_SYNC_NONE          (0 << 2)
 318 #define USB_ENDPOINT_SYNC_ASYNC         (1 << 2)
 319 #define USB_ENDPOINT_SYNC_ADAPTIVE      (2 << 2)
 320 #define USB_ENDPOINT_SYNC_SYNC          (3 << 2)
 321
 322 #define USB_ENDPOINT_XFERTYPE_MASK      0x03    /* in bmAttributes */
 323 #define USB_ENDPOINT_XFER_CONTROL       0
 324 #define USB_ENDPOINT_XFER_ISOC          1
 325 #define USB_ENDPOINT_XFER_BULK          2
 326 #define USB_ENDPOINT_XFER_INT           3
 327 #define USB_ENDPOINT_MAX_ADJUSTABLE     0x80
 328
 329 /* USB: generic device descriptor */
 330 typedef struct UsbDevice
 331 {
 332         UsbDeviceDesc *device;
 333         const UsbDescHeader **config;
 334         const UsbStringDesc **strings;
 335
 336         /* Callbacks */
 337         void (*event_cb)(UsbCtrlRequest *);
 338
 339         /* Private data */
 340         bool configured;
 341 } UsbDevice;
 342
 343 /*
 344  * usb_endpointNum - get the endpoint's number
 345  */
 346 INLINE int usb_endpointNum(const UsbEndpointDesc *epd)
 347 {
 348         return epd->bEndpointAddress & USB_ENDPOINT_NUMBER_MASK;
 349 }
 350
 351 /*
 352  * usb_endpointType - get the endpoint's transfer type
 353  */
 354 INLINE int usb_endpointType(const struct UsbEndpointDesc *epd)
 355 {
 356         return epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK;
 357 }
 358
 359 /*
 360  * usb_endpointDirIn - check if the endpoint has IN direction
 361  */
 362 INLINE int usb_endpointDirIn(const struct UsbEndpointDesc *epd)
 363 {
 364         return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_IN);
 365 }
 366
 367 /*
 368  * usb_endpointDirOut - check if the endpoint has OUT direction
 369  */
 370 INLINE int usb_endpointDirOut(const struct UsbEndpointDesc *epd)
 371 {
 372         return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_OUT);
 373 }
 374
 375 /*
 376  * usb_endpointXferBulk - check if the endpoint has bulk transfer type
 377  */
 378 INLINE int usb_endpointXferBulk(const struct UsbEndpointDesc *epd)
 379 {
 380         return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
 381                 USB_ENDPOINT_XFER_BULK);
 382 }
 383
 384 /*
 385  * usb_endpointXferControl - check if the endpoint has control transfer type
 386  */
 387 INLINE int usb_endpointXferControl(const struct UsbEndpointDesc *epd)
 388 {
 389         return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
 390                 USB_ENDPOINT_XFER_CONTROL);
 391 }
 392
 393 /*
 394  * usb_endpointXferInt - check if the endpoint has interrupt transfer type
 395  */
 396 INLINE int usb_endpointXferInt(const struct UsbEndpointDesc *epd)
 397 {
 398         return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
 399                 USB_ENDPOINT_XFER_INT);
 400 }
 401
 402 /*
 403  * usb_endpointXferIsoc - check if the endpoint has isochronous transfer type
 404  */
 405 INLINE int usb_endpointXferIsoc(const struct UsbEndpointDesc *epd)
 406 {
 407         return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
 408                 USB_ENDPOINT_XFER_ISOC);
 409 }
 410
 411 /*
 412  * usb_endpointIsBulkIn - check if the endpoint is bulk IN
 413  */
 414 INLINE int usb_endpointIsBulkIn(const struct UsbEndpointDesc *epd)
 415 {
 416         return usb_endpointXferBulk(epd) && usb_endpointDirIn(epd);
 417 }
 418
 419 /*
 420  * usb_endpointIsBulkOut - check if the endpoint is bulk OUT
 421  */
 422 INLINE int usb_endpointIsBulkOut(const struct UsbEndpointDesc *epd)
 423 {
 424         return usb_endpointXferBulk(epd) && usb_endpointDirOut(epd);
 425 }
 426
 427 /*
 428  * usb_endpointIsIntIn - check if the endpoint is interrupt IN
 429  */
 430 INLINE int usb_endpointIsIntIn(const struct UsbEndpointDesc *epd)
 431 {
 432         return usb_endpointXferInt(epd) && usb_endpointDirIn(epd);
 433 }
 434
 435 /*
 436  * usb_endpointIsIntOut - check if the endpoint is interrupt OUT
 437  */
 438 INLINE int usb_endpointIsIntOut(const struct UsbEndpointDesc *epd)
 439 {
 440         return usb_endpointXferInt(epd) && usb_endpointDirOut(epd);
 441 }
 442
 443 /*
 444  * usb_endpointIsIsocIn - check if the endpoint is isochronous IN
 445  */
 446 INLINE int usb_endpointIsIsocIn(const struct UsbEndpointDesc *epd)
 447 {
 448         return usb_endpointXferIsoc(epd) && usb_endpointDirIn(epd);
 449 }
 450
 451 /*
 452  * usb_endpointIsIsocOut - check if the endpoint is isochronous OUT
 453  */
 454 INLINE int usb_endpointIsIsocOut(const struct UsbEndpointDesc *epd)
 455 {
 456         return usb_endpointXferIsoc(epd) && usb_endpointDirOut(epd);
 457 }
 458
 459 /*
 460  * usb_ep_read - configure endponint and perform the read operation
 461  */
 462 ssize_t usb_ep_read(int ep, void *buffer, ssize_t size);
 463
 464 /*
 465  * usb_ep_write - configure endponint and perform the write operation
 466  */
 467 ssize_t usb_ep_write(int ep, const void *buffer, ssize_t size);
 468
 469 /*
 470  * usb_device_register - register a generic USB device driver
 471  */
 472 int usb_device_register(UsbDevice *dev);
 473
 474 #endif /* USB_H */