BeRTOS
usb.h
Go to the documentation of this file.
00001 
00047 #ifndef USB_H
00048 #define USB_H
00049 
00050 #include <cpu/byteorder.h>
00051 
00052 #define usb_cpu_to_le16(x)  cpu_to_le16(x)
00053 #define usb_le16_to_cpu(x)  le16_to_cpu(x)
00054 #define usb_cpu_to_le32(x)  cpu_to_le32(x)
00055 #define usb_le32_to_cpu(x)  le32_to_cpu(x)
00056 
00057 /* State of a USB device */
00058 enum usb_device_state {
00059         USB_STATE_NOTATTACHED = 0,
00060 
00061         /* chapter 9 device states */
00062         USB_STATE_ATTACHED,
00063         USB_STATE_POWERED,                      /* wired */
00064         USB_STATE_DEFAULT,                      /* limited function */
00065         USB_STATE_ADDRESS,
00066         USB_STATE_CONFIGURED,                   /* most functions */
00067 };
00068 
00069 /*
00070  * USB directions
00071  *
00072  * This bit flag is used in endpoint descriptors' bEndpointAddress field.
00073  * It's also one of three fields in control requests bRequestType.
00074  */
00075 #define USB_DIR_OUT         0       /* to device */
00076 #define USB_DIR_IN          0x80        /* to host */
00077 #define USB_DIR_MASK            0x80
00078 
00079 /*
00080  * USB types, the second of three bRequestType fields
00081  */
00082 #define USB_TYPE_MASK           (0x03 << 5)
00083 #define USB_TYPE_STANDARD       (0x00 << 5)
00084 #define USB_TYPE_CLASS          (0x01 << 5)
00085 #define USB_TYPE_VENDOR         (0x02 << 5)
00086 #define USB_TYPE_RESERVED       (0x03 << 5)
00087 
00088 /*
00089  * USB recipients, the third of three bRequestType fields
00090  */
00091 #define USB_RECIP_MASK          0x1f
00092 #define USB_RECIP_DEVICE        0x00
00093 #define USB_RECIP_INTERFACE     0x01
00094 #define USB_RECIP_ENDPOINT      0x02
00095 #define USB_RECIP_OTHER         0x03
00096 
00097 /*
00098  * USB standard requests, for the bRequest field of a SETUP packet.
00099  */
00100 #define USB_REQ_GET_STATUS      0x00
00101 #define USB_REQ_CLEAR_FEATURE       0x01
00102 #define USB_REQ_SET_FEATURE     0x03
00103 #define USB_REQ_SET_ADDRESS     0x05
00104 #define USB_REQ_GET_DESCRIPTOR      0x06
00105 #define USB_REQ_SET_DESCRIPTOR      0x07
00106 #define USB_REQ_GET_CONFIGURATION   0x08
00107 #define USB_REQ_SET_CONFIGURATION   0x09
00108 #define USB_REQ_GET_INTERFACE       0x0A
00109 #define USB_REQ_SET_INTERFACE       0x0B
00110 #define USB_REQ_SYNCH_FRAME     0x0C
00111 
00112 /*
00113  * Descriptor types ... USB 2.0 spec table 9.5
00114  */
00115 #define USB_DT_DEVICE           0x01
00116 #define USB_DT_CONFIG           0x02
00117 #define USB_DT_STRING           0x03
00118 #define USB_DT_INTERFACE        0x04
00119 #define USB_DT_ENDPOINT         0x05
00120 #define USB_DT_DEVICE_QUALIFIER     0x06
00121 #define USB_DT_OTHER_SPEED_CONFIG   0x07
00122 #define USB_DT_INTERFACE_POWER      0x08
00123 
00124 /*
00125  * Conventional codes for class-specific descriptors.  The convention is
00126  * defined in the USB "Common Class" Spec (3.11).  Individual class specs
00127  * are authoritative for their usage, not the "common class" writeup.
00128  */
00129 #define USB_DT_CS_DEVICE        (USB_TYPE_CLASS | USB_DT_DEVICE)
00130 #define USB_DT_CS_CONFIG        (USB_TYPE_CLASS | USB_DT_CONFIG)
00131 #define USB_DT_CS_STRING        (USB_TYPE_CLASS | USB_DT_STRING)
00132 #define USB_DT_CS_INTERFACE     (USB_TYPE_CLASS | USB_DT_INTERFACE)
00133 #define USB_DT_CS_ENDPOINT      (USB_TYPE_CLASS | USB_DT_ENDPOINT)
00134 
00144 typedef struct UsbCtrlRequest
00145 {
00146     uint8_t mRequestType;
00147     uint8_t bRequest;
00148     uint16_t wValue;
00149     uint16_t wIndex;
00150     uint16_t wLength;
00151 } PACKED UsbCtrlRequest;
00152 
00158 typedef struct UsbDescHeader
00159 {
00160     uint8_t bLength;
00161     uint8_t bDescriptorType;
00162 } PACKED UsbDescHeader;
00163 
00169 typedef struct UsbDeviceDesc
00170 {
00171     uint8_t bLength;
00172     uint8_t bDescriptorType;
00173     uint16_t bcdUSB;
00174     uint8_t bDeviceClass;
00175     uint8_t bDeviceSubClass;
00176     uint8_t bDeviceProtocol;
00177     uint8_t bMaxPacketSize0;
00178     uint16_t idVendor;
00179     uint16_t idProduct;
00180     uint16_t bcdDevice;
00181     uint8_t iManufacturer;
00182     uint8_t iProduct;
00183     uint8_t iSerialNumber;
00184     uint8_t bNumConfigurations;
00185 } PACKED UsbDeviceDesc;
00186 
00192 typedef struct UsbStringDesc
00193 {
00194     uint8_t bLength;
00195     uint8_t bDescriptorType;
00196     uint8_t data[0];
00197 } PACKED UsbStringDesc;
00198 
00199 #define USB_STRING_1(__a, ...) __a "\x00"
00200 #define USB_STRING_2(__a, ...) __a "\x00" USB_STRING_1(__VA_ARGS__)
00201 #define USB_STRING_3(__a, ...) __a "\x00" USB_STRING_2(__VA_ARGS__)
00202 #define USB_STRING_4(__a, ...) __a "\x00" USB_STRING_3(__VA_ARGS__)
00203 #define USB_STRING_5(__a, ...) __a "\x00" USB_STRING_4(__VA_ARGS__)
00204 #define USB_STRING_6(__a, ...) __a "\x00" USB_STRING_5(__VA_ARGS__)
00205 #define USB_STRING_7(__a, ...) __a "\x00" USB_STRING_6(__VA_ARGS__)
00206 #define USB_STRING_8(__a, ...) __a "\x00" USB_STRING_7(__VA_ARGS__)
00207 #define USB_STRING_9(__a, ...) __a "\x00" USB_STRING_8(__VA_ARGS__)
00208 #define USB_STRING_10(__a, ...) __a "\x00" USB_STRING_9(__VA_ARGS__)
00209 #define USB_STRING_11(__a, ...) __a "\x00" USB_STRING_10(__VA_ARGS__)
00210 #define USB_STRING_12(__a, ...) __a "\x00" USB_STRING_11(__VA_ARGS__)
00211 #define USB_STRING_13(__a, ...) __a "\x00" USB_STRING_12(__VA_ARGS__)
00212 #define USB_STRING_14(__a, ...) __a "\x00" USB_STRING_13(__VA_ARGS__)
00213 #define USB_STRING_15(__a, ...) __a "\x00" USB_STRING_14(__VA_ARGS__)
00214 #define USB_STRING_16(__a, ...) __a "\x00" USB_STRING_15(__VA_ARGS__)
00215 
00223 #define USB_STRING(...) PP_CAT(USB_STRING_, PP_COUNT(__VA_ARGS__))(__VA_ARGS__)
00224 
00234 #define DEFINE_USB_STRING(__name, __text)               \
00235     struct {                            \
00236         UsbDescHeader __header;                 \
00237         uint8_t __body[sizeof(__text)];             \
00238     } PACKED __name = {                     \
00239         .__header = {                       \
00240             .bLength =                  \
00241                 cpu_to_le16((uint16_t)sizeof(__name)),  \
00242             .bDescriptorType = USB_DT_STRING,       \
00243         },                          \
00244         .__body = {__text},                 \
00245     }
00246 
00247 /*
00248  * Device and/or Interface Class codes as found in bDeviceClass or
00249  * bInterfaceClass and defined by www.usb.org documents.
00250  */
00251 #define USB_CLASS_PER_INTERFACE     0   /* for DeviceClass */
00252 #define USB_CLASS_AUDIO         1
00253 #define USB_CLASS_COMM          2
00254 #define USB_CLASS_HID           3
00255 #define USB_CLASS_PHYSICAL      5
00256 #define USB_CLASS_STILL_IMAGE       6
00257 #define USB_CLASS_PRINTER       7
00258 #define USB_CLASS_MASS_STORAGE      8
00259 #define USB_CLASS_HUB           9
00260 #define USB_CLASS_CDC_DATA      0x0a
00261 #define USB_CLASS_CSCID         0x0b    /* chip+ smart card */
00262 #define USB_CLASS_CONTENT_SEC       0x0d    /* content security */
00263 #define USB_CLASS_VIDEO         0x0e
00264 #define USB_CLASS_WIRELESS_CONTROLLER   0xe0
00265 #define USB_CLASS_MISC          0xef
00266 #define USB_CLASS_APP_SPEC      0xfe
00267 #define USB_CLASS_VENDOR_SPEC       0xff
00268 
00269 /* USB Device subclasses */
00270 #define USB_CDC_SUBCLASS_ACM                    0x02
00271 #define USB_CDC_SUBCLASS_ETHERNET               0x06
00272 #define USB_CDC_SUBCLASS_WHCM                   0x08
00273 #define USB_CDC_SUBCLASS_DMM                    0x09
00274 #define USB_CDC_SUBCLASS_MDLM                   0x0a
00275 #define USB_CDC_SUBCLASS_OBEX                   0x0b
00276 #define USB_CDC_SUBCLASS_EEM                    0x0c
00277 #define USB_CDC_SUBCLASS_NCM                    0x0d
00278 
00284 typedef struct UsbConfigDesc
00285 {
00286     uint8_t bLength;
00287     uint8_t bDescriptorType;
00288     uint16_t wTotalLength;
00289     uint8_t bNumInterfaces;
00290     uint8_t bConfigurationValue;
00291     uint8_t iConfiguration;
00292     uint8_t bmAttributes;
00293     uint8_t bMaxPower;
00294 } PACKED UsbConfigDesc;
00295 
00296 /* from config descriptor bmAttributes */
00297 #define USB_CONFIG_ATT_ONE      (1 << 7)    /* must be set */
00298 #define USB_CONFIG_ATT_SELFPOWER    (1 << 6)    /* self powered */
00299 #define USB_CONFIG_ATT_WAKEUP       (1 << 5)    /* can wakeup */
00300 #define USB_CONFIG_ATT_BATTERY      (1 << 4)    /* battery powered */
00301 
00307 typedef struct UsbInterfaceDesc
00308 {
00309     uint8_t bLength;
00310     uint8_t bDescriptorType;
00311     uint8_t bInterfaceNumber;
00312     uint8_t bAlternateSetting;
00313     uint8_t bNumEndpoints;
00314     uint8_t bInterfaceClass;
00315     uint8_t bInterfaceSubClass;
00316     uint8_t bInterfaceProtocol;
00317     uint8_t iInterface;
00318 } PACKED UsbInterfaceDesc;
00319 
00325 typedef struct UsbEndpointDesc
00326 {
00327     uint8_t bLength;
00328     uint8_t bDescriptorType;
00329     uint8_t bEndpointAddress;
00330     uint8_t bmAttributes;
00331     uint16_t wMaxPacketSize;
00332     uint8_t bInterval;
00333 } PACKED UsbEndpointDesc;
00334 
00335 /*
00336  * Endpoints
00337  */
00338 #define USB_ENDPOINT_NUMBER_MASK    0x0f    /* in bEndpointAddress */
00339 #define USB_ENDPOINT_DIR_MASK       USB_DIR_MASK
00340 
00341 #define USB_ENDPOINT_SYNCTYPE       0x0c
00342 #define USB_ENDPOINT_SYNC_NONE      (0 << 2)
00343 #define USB_ENDPOINT_SYNC_ASYNC     (1 << 2)
00344 #define USB_ENDPOINT_SYNC_ADAPTIVE  (2 << 2)
00345 #define USB_ENDPOINT_SYNC_SYNC      (3 << 2)
00346 
00347 #define USB_ENDPOINT_XFERTYPE_MASK  0x03    /* in bmAttributes */
00348 #define USB_ENDPOINT_XFER_CONTROL   0
00349 #define USB_ENDPOINT_XFER_ISOC      1
00350 #define USB_ENDPOINT_XFER_BULK      2
00351 #define USB_ENDPOINT_XFER_INT       3
00352 #define USB_ENDPOINT_MAX_ADJUSTABLE 0x80
00353 
00357 typedef struct UsbDevice
00358 {
00359     UsbDeviceDesc *device;              
00360     const UsbDescHeader **config;       
00361     const UsbStringDesc **strings;      
00362 
00363     /* Callbacks */
00364     void (*event_cb)(UsbCtrlRequest *); 
00365 
00366     /* Private data */
00367     bool configured;                    
00368 } UsbDevice;
00369 
00373 INLINE int usb_endpointNum(const UsbEndpointDesc *epd)
00374 {
00375     return epd->bEndpointAddress & USB_ENDPOINT_NUMBER_MASK;
00376 }
00377 
00381 INLINE int usb_endpointType(const struct UsbEndpointDesc *epd)
00382 {
00383     return epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK;
00384 }
00385 
00389 INLINE int usb_endpointDirIn(const struct UsbEndpointDesc *epd)
00390 {
00391     return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_IN);
00392 }
00393 
00397 INLINE int usb_endpointDirOut(const struct UsbEndpointDesc *epd)
00398 {
00399     return ((epd->bEndpointAddress & USB_ENDPOINT_DIR_MASK) == USB_DIR_OUT);
00400 }
00401 
00405 INLINE int usb_endpointXferBulk(const struct UsbEndpointDesc *epd)
00406 {
00407     return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
00408         USB_ENDPOINT_XFER_BULK);
00409 }
00410 
00414 INLINE int usb_endpointXferControl(const struct UsbEndpointDesc *epd)
00415 {
00416     return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
00417         USB_ENDPOINT_XFER_CONTROL);
00418 }
00419 
00423 INLINE int usb_endpointXferInt(const struct UsbEndpointDesc *epd)
00424 {
00425     return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
00426         USB_ENDPOINT_XFER_INT);
00427 }
00428 
00432 INLINE int usb_endpointXferIsoc(const struct UsbEndpointDesc *epd)
00433 {
00434     return ((epd->bmAttributes & USB_ENDPOINT_XFERTYPE_MASK) ==
00435         USB_ENDPOINT_XFER_ISOC);
00436 }
00437 
00441 INLINE int usb_endpointIsBulkIn(const struct UsbEndpointDesc *epd)
00442 {
00443     return usb_endpointXferBulk(epd) && usb_endpointDirIn(epd);
00444 }
00445 
00449 INLINE int usb_endpointIsBulkOut(const struct UsbEndpointDesc *epd)
00450 {
00451     return usb_endpointXferBulk(epd) && usb_endpointDirOut(epd);
00452 }
00453 
00457 INLINE int usb_endpointIsIntIn(const struct UsbEndpointDesc *epd)
00458 {
00459     return usb_endpointXferInt(epd) && usb_endpointDirIn(epd);
00460 }
00461 
00465 INLINE int usb_endpointIsIntOut(const struct UsbEndpointDesc *epd)
00466 {
00467     return usb_endpointXferInt(epd) && usb_endpointDirOut(epd);
00468 }
00469 
00473 INLINE int usb_endpointIsIsocIn(const struct UsbEndpointDesc *epd)
00474 {
00475     return usb_endpointXferIsoc(epd) && usb_endpointDirIn(epd);
00476 }
00477 
00481 INLINE int usb_endpointIsIsocOut(const struct UsbEndpointDesc *epd)
00482 {
00483     return usb_endpointXferIsoc(epd) && usb_endpointDirOut(epd);
00484 }
00485 
00498 ssize_t usb_endpointReadTimeout(int ep, void *buffer, ssize_t size,
00499                 ticks_t timeout);
00500 
00501 INLINE ssize_t usb_endpointRead(int ep, void *buffer, ssize_t size)
00502 {
00503     return usb_endpointReadTimeout(ep, buffer, size, -1);
00504 }
00505 
00518 ssize_t usb_endpointWriteTimeout(int ep, const void *buffer, ssize_t size,
00519                 ticks_t timeout);
00520 
00521 INLINE ssize_t usb_endpointWrite(int ep, const void *buffer, ssize_t size)
00522 {
00523     return usb_endpointWriteTimeout(ep, buffer, size, -1);
00524 }
00525 
00529 int usb_deviceRegister(UsbDevice *dev);
00530 
00531 #endif /* USB_H */