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