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 #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)
  54
  55 /* State of a USB device */
  56 enum usb_device_state {
  57         USB_STATE_NOTATTACHED = 0,
  58
  59         /* chapter 9 device states */
  60         USB_STATE_ATTACHED,
  61         USB_STATE_POWERED,                      /* wired */
  62         USB_STATE_DEFAULT,                      /* limited function */
  63         USB_STATE_ADDRESS,
  64         USB_STATE_CONFIGURED,                   /* most functions */
  65 };
  66
  67 /*
  68  * USB directions
  69  *
  70  * This bit flag is used in endpoint descriptors' bEndpointAddress field.
  71  * It's also one of three fields in control requests bRequestType.
  72  */
  73 #define USB_DIR_OUT                     0               /* to device */
  74 #define USB_DIR_IN                      0x80            /* to host */
  75 #define USB_DIR_MASK                    0x80
  76
  77 /*
  78  * USB types, the second of three bRequestType fields
  79  */
  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)
  85
  86 /*
  87  * USB recipients, the third of three bRequestType fields
  88  */
  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
  94
  95 /*
  96  * USB standard requests, for the bRequest field of a SETUP packet.
  97  */
  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
 109
 110 /*
 111  * Descriptor types ... USB 2.0 spec table 9.5
 112  */
 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
 121
 122 /*
 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.
 126  */
 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)
 132
 133 /**
 134  *
 135  * USB Control Request descriptor
 136  *
 137  * This structure is used to send control requests to a USB device.
 138  *
 139  * It matches the different fields of the USB 2.0 specification (section 9.3,
 140  * table 9-2).
 141  */
 142 typedef struct UsbCtrlRequest
 143 {
 144         uint8_t mRequestType;
 145         uint8_t bRequest;
 146         uint16_t wValue;
 147         uint16_t wIndex;
 148         uint16_t wLength;
 149 } PACKED UsbCtrlRequest;
 150
 151 /**
 152  * USB common descriptor header.
 153  *
 154  * \note All the USB standard descriptors have these 2 fields at the beginning.
 155  */
 156 typedef struct UsbDescHeader
 157 {
 158         uint8_t bLength;
 159         uint8_t bDescriptorType;
 160 } PACKED UsbDescHeader;
 161
 162 /**
 163  * USB Device descriptor
 164  *
 165  * \note See USB 2.0 specification.
 166  */
 167 typedef struct UsbDeviceDesc
 168 {
 169         uint8_t bLength;
 170         uint8_t bDescriptorType;
 171         uint16_t bcdUSB;
 172         uint8_t bDeviceClass;
 173         uint8_t bDeviceSubClass;
 174         uint8_t bDeviceProtocol;
 175         uint8_t bMaxPacketSize0;
 176         uint16_t idVendor;
 177         uint16_t idProduct;
 178         uint16_t bcdDevice;
 179         uint8_t iManufacturer;
 180         uint8_t iProduct;
 181         uint8_t iSerialNumber;
 182         uint8_t bNumConfigurations;
 183 } PACKED UsbDeviceDesc;
 184
 185 /**
 186  * USB string descriptor.
 187  *
 188  * \note See USB 2.0 specification.
 189  */
 190 typedef struct UsbStringDesc
 191 {
 192         uint8_t bLength;
 193         uint8_t bDescriptorType;
 194         uint8_t data[0];
 195 } PACKED UsbStringDesc;
 196
 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__)
 213
 214 /**
 215  * Pack a list with a variable number of elements into a UTF-16LE USB string.
 216  *
 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
 219  * characters.
 220  */
 221 #define USB_STRING(...) PP_CAT(USB_STRING_, PP_COUNT(__VA_ARGS__))(__VA_ARGS__)
 222
 223 /**
 224  * Define and initialize an USB string descriptor.
 225  *
 226  * This macro is reuquired to properly declare and initialize a constant USB
 227  * string in UTF-16LE format.
 228  *
 229  * The structure must contain the standard common USB header (UsbDescHeader)
 230  * and the UTF-16LE string all packed in a contiguous memory region.
 231  */
 232 #define DEFINE_USB_STRING(__name, __text)                               \
 233         struct {                                                        \
 234                 UsbDescHeader __header;                                 \
 235                 uint8_t __body[sizeof(__text)];                         \
 236         } PACKED __name = {                                             \
 237                 .__header = {                                           \
 238                         .bLength =                                      \
 239                                 cpu_to_le16((uint16_t)sizeof(__name)),  \
 240                         .bDescriptorType = USB_DT_STRING,               \
 241                 },                                                      \
 242                 .__body = {__text},                                     \
 243         }
 244
 245 /*
 246  * Device and/or Interface Class codes as found in bDeviceClass or
 247  * bInterfaceClass and defined by www.usb.org documents.
 248  */
 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
 266
 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
 276
 277 /**
 278  * Device configuration descriptor
 279  *
 280  * \note See USB 2.0 specification.
 281  */
 282 typedef struct UsbConfigDesc
 283 {
 284         uint8_t bLength;
 285         uint8_t bDescriptorType;
 286         uint16_t wTotalLength;
 287         uint8_t bNumInterfaces;
 288         uint8_t bConfigurationValue;
 289         uint8_t iConfiguration;
 290         uint8_t bmAttributes;
 291         uint8_t bMaxPower;
 292 } PACKED UsbConfigDesc;
 293
 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 */
 299
 300 /**
 301  * Device interface descriptor
 302  *
 303  * \note See USB 2.0 specification.
 304  */
 305 typedef struct UsbInterfaceDesc
 306 {
 307         uint8_t bLength;
 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;
 315         uint8_t iInterface;
 316 } PACKED UsbInterfaceDesc;
 317
 318 /**
 319  * Endpoint descriptor
 320  *
 321  * \note See USB 2.0 specification.
 322  */
 323 typedef struct UsbEndpointDesc
 324 {
 325         uint8_t bLength;
 326         uint8_t bDescriptorType;
 327         uint8_t bEndpointAddress;
 328         uint8_t bmAttributes;
 329         uint16_t wMaxPacketSize;
 330         uint8_t bInterval;
 331 } PACKED UsbEndpointDesc;
 332
 333 /*
 334  * Endpoints
 335  */
 336 #define USB_ENDPOINT_NUMBER_MASK        0x0f    /* in bEndpointAddress */
 337 #define USB_ENDPOINT_DIR_MASK           USB_DIR_MASK
 338
 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)
 344
 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
 351
 352 /**
 353  * USB: generic device descriptor
 354  */
 355 typedef struct UsbDevice
 356 {
 357         UsbDeviceDesc *device;              ///< USB 2.0 device descriptor
 358         const UsbDescHeader **config;       ///< USB 2.0 configuration descriptors
 359         const UsbStringDesc **strings;      ///< USB strings
 360
 361         /* Callbacks */
 362         void (*event_cb)(UsbCtrlRequest *); ///< Called to handle control requests.
 363
 364         /* Private data */
 365         bool configured;                    ///< True when the device has been correctly initialized.
 366 } UsbDevice;
 367
 368 /**
 369  * Get the endpoint's address number of \a epd.
 370  */
 371 INLINE int usb_endpointNum(const UsbEndpointDesc *epd)
 372 {
 373         return epd->bEndpointAddress & USB_ENDPOINT_NUMBER_MASK;
 374 }
 375
 376 /**
 377  * Get the transfer type of the endpoint \a epd.
 378  */
 379 INLINE int usb_endpointType(const struct UsbEndpointDesc *epd)
 380 {
 381         return epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK;
 382 }
 383
 384 /**
 385  * Check if the endpoint \a epd has IN direction.
 386  */
 387 INLINE int usb_endpointDirIn(const struct UsbEndpointDesc *epd)
 388 {
 389         return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_IN);
 390 }
 391
 392 /**
 393  * Check if the endpoint \a epd has OUT direction.
 394  */
 395 INLINE int usb_endpointDirOut(const struct UsbEndpointDesc *epd)
 396 {
 397         return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_OUT);
 398 }
 399
 400 /**
 401  * Check if the endpoint \a epd has bulk transfer type.
 402  */
 403 INLINE int usb_endpointXferBulk(const struct UsbEndpointDesc *epd)
 404 {
 405         return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
 406                 USB_ENDPOINT_XFER_BULK);
 407 }
 408
 409 /**
 410  * Check if the endpoint \a epd has control transfer type.
 411  */
 412 INLINE int usb_endpointXferControl(const struct UsbEndpointDesc *epd)
 413 {
 414         return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
 415                 USB_ENDPOINT_XFER_CONTROL);
 416 }
 417
 418 /**
 419  * Check if the endpoint \a epd has interrupt transfer type.
 420  */
 421 INLINE int usb_endpointXferInt(const struct UsbEndpointDesc *epd)
 422 {
 423         return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
 424                 USB_ENDPOINT_XFER_INT);
 425 }
 426
 427 /**
 428  * Check if the endpoint \a epd has isochronous transfer type.
 429  */
 430 INLINE int usb_endpointXferIsoc(const struct UsbEndpointDesc *epd)
 431 {
 432         return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
 433                 USB_ENDPOINT_XFER_ISOC);
 434 }
 435
 436 /**
 437  * Check if the endpoint \a epd is bulk IN.
 438  */
 439 INLINE int usb_endpointIsBulkIn(const struct UsbEndpointDesc *epd)
 440 {
 441         return usb_endpointXferBulk(epd) && usb_endpointDirIn(epd);
 442 }
 443
 444 /**
 445  * Check if the endpoint \a epd is bulk OUT.
 446  */
 447 INLINE int usb_endpointIsBulkOut(const struct UsbEndpointDesc *epd)
 448 {
 449         return usb_endpointXferBulk(epd) && usb_endpointDirOut(epd);
 450 }
 451
 452 /**
 453  * Check if the endpoint \a epd is interrupt IN.
 454  */
 455 INLINE int usb_endpointIsIntIn(const struct UsbEndpointDesc *epd)
 456 {
 457         return usb_endpointXferInt(epd) && usb_endpointDirIn(epd);
 458 }
 459
 460 /**
 461  * Check if the endpoint \a epd is interrupt OUT.
 462  */
 463 INLINE int usb_endpointIsIntOut(const struct UsbEndpointDesc *epd)
 464 {
 465         return usb_endpointXferInt(epd) && usb_endpointDirOut(epd);
 466 }
 467
 468 /**
 469  * Check if the endpoint \a epd is isochronous IN.
 470  */
 471 INLINE int usb_endpointIsIsocIn(const struct UsbEndpointDesc *epd)
 472 {
 473         return usb_endpointXferIsoc(epd) && usb_endpointDirIn(epd);
 474 }
 475
 476 /**
 477  * Check if the endpoint \a epd is isochronous OUT.
 478  */
 479 INLINE int usb_endpointIsIsocOut(const struct UsbEndpointDesc *epd)
 480 {
 481         return usb_endpointXferIsoc(epd) && usb_endpointDirOut(epd);
 482 }
 483
 484 /**
 485  * Read up to \a size bytes from the USB endpoint identified by the address
 486  * \a ep and store them in \a buffer.
 487  *
 488  * \return number of bytes actually read.
 489  */
 490 ssize_t usb_endpointRead(int ep, void *buffer, ssize_t size);
 491
 492 /**
 493  * Write up to \a size bytes from the buffer pointed \a buffer to the USB
 494  * endpoint identified by the address \a ep.
 495  *
 496  * \return number of bytes actually wrote.
 497  */
 498 ssize_t usb_endpointWrite(int ep, const void *buffer, ssize_t size);
 499
 500 /**
 501  * Register a generic USB device driver \a dev in the USB controller.
 502  */
 503 int usb_deviceRegister(UsbDevice *dev);
 504
 505 #endif /* USB_H */