protocol/usb_hid/USB_Host_Shield_2.0/UsbCore.h

   1 /* Copyright (C) 2011 Circuits At Home, LTD. All rights reserved.
   2
   3 This software may be distributed and modified under the terms of the GNU
   4 General Public License version 2 (GPL2) as published by the Free Software
   5 Foundation and appearing in the file GPL2.TXT included in the packaging of
   6 this file. Please note that GPL2 Section 2[b] requires that all works based
   7 on this software must also be made publicly available under the terms of
   8 the GPL2 ("Copyleft").
   9
  10 Contact information
  11 -------------------
  12
  13 Circuits At Home, LTD
  14 Web      :  http://www.circuitsathome.com
  15 e-mail   :  support@circuitsathome.com
  16  */
  17
  18 #if !defined(_usb_h_) || defined(USBCORE_H)
  19 #error "Never include UsbCore.h directly; include Usb.h instead"
  20 #else
  21 #define USBCORE_H
  22
  23 // Not used anymore? If anyone uses this, please let us know so that this may be
  24 // moved to the proper place, settings.h.
  25 //#define USB_METHODS_INLINE
  26
  27 /* shield pins. First parameter - SS pin, second parameter - INT pin */
  28 #ifdef BOARD_BLACK_WIDDOW
  29 typedef MAX3421e<P6, P3> MAX3421E; // Black Widow
  30 #elif defined(CORE_TEENSY) && (defined(__AVR_AT90USB646__) || defined(__AVR_AT90USB1286__))
  31 #if EXT_RAM
  32 typedef MAX3421e<P20, P7> MAX3421E; // Teensy++ 2.0 with XMEM2
  33 #else
  34 typedef MAX3421e<P9, P8> MAX3421E; // Teensy++ 1.0 and 2.0
  35 #endif
  36 #elif defined(BOARD_MEGA_ADK)
  37 typedef MAX3421e<P53, P54> MAX3421E; // Arduino Mega ADK
  38 #elif defined(ARDUINO_AVR_BALANDUINO)
  39 typedef MAX3421e<P20, P19> MAX3421E; // Balanduino
  40 #elif defined(__ARDUINO_X86__) && PLATFORM_ID == 0x06
  41 typedef MAX3421e<P3, P2> MAX3421E; // The Intel Galileo supports much faster read and write speed at pin 2 and 3
  42 #else
  43 typedef MAX3421e<P10, P9> MAX3421E; // Official Arduinos (UNO, Duemilanove, Mega, 2560, Leonardo, Due etc.), Intel Edison, Intel Galileo 2 or Teensy 2.0 and 3.0
  44 #endif
  45
  46 /* Common setup data constant combinations  */
  47 #define bmREQ_GET_DESCR     USB_SETUP_DEVICE_TO_HOST|USB_SETUP_TYPE_STANDARD|USB_SETUP_RECIPIENT_DEVICE     //get descriptor request type
  48 #define bmREQ_SET           USB_SETUP_HOST_TO_DEVICE|USB_SETUP_TYPE_STANDARD|USB_SETUP_RECIPIENT_DEVICE     //set request type for all but 'set feature' and 'set interface'
  49 #define bmREQ_CL_GET_INTF   USB_SETUP_DEVICE_TO_HOST|USB_SETUP_TYPE_CLASS|USB_SETUP_RECIPIENT_INTERFACE     //get interface request type
  50
  51 // D7           data transfer direction (0 - host-to-device, 1 - device-to-host)
  52 // D6-5         Type (0- standard, 1 - class, 2 - vendor, 3 - reserved)
  53 // D4-0         Recipient (0 - device, 1 - interface, 2 - endpoint, 3 - other, 4..31 - reserved)
  54
  55 // USB Device Classes
  56 #define USB_CLASS_USE_CLASS_INFO        0x00    // Use Class Info in the Interface Descriptors
  57 #define USB_CLASS_AUDIO                 0x01    // Audio
  58 #define USB_CLASS_COM_AND_CDC_CTRL      0x02    // Communications and CDC Control
  59 #define USB_CLASS_HID                   0x03    // HID
  60 #define USB_CLASS_PHYSICAL              0x05    // Physical
  61 #define USB_CLASS_IMAGE                 0x06    // Image
  62 #define USB_CLASS_PRINTER               0x07    // Printer
  63 #define USB_CLASS_MASS_STORAGE          0x08    // Mass Storage
  64 #define USB_CLASS_HUB                   0x09    // Hub
  65 #define USB_CLASS_CDC_DATA              0x0a    // CDC-Data
  66 #define USB_CLASS_SMART_CARD            0x0b    // Smart-Card
  67 #define USB_CLASS_CONTENT_SECURITY      0x0d    // Content Security
  68 #define USB_CLASS_VIDEO                 0x0e    // Video
  69 #define USB_CLASS_PERSONAL_HEALTH       0x0f    // Personal Healthcare
  70 #define USB_CLASS_DIAGNOSTIC_DEVICE     0xdc    // Diagnostic Device
  71 #define USB_CLASS_WIRELESS_CTRL         0xe0    // Wireless Controller
  72 #define USB_CLASS_MISC                  0xef    // Miscellaneous
  73 #define USB_CLASS_APP_SPECIFIC          0xfe    // Application Specific
  74 #define USB_CLASS_VENDOR_SPECIFIC       0xff    // Vendor Specific
  75
  76 // Additional Error Codes
  77 #define USB_DEV_CONFIG_ERROR_DEVICE_NOT_SUPPORTED       0xD1
  78 #define USB_DEV_CONFIG_ERROR_DEVICE_INIT_INCOMPLETE     0xD2
  79 #define USB_ERROR_UNABLE_TO_REGISTER_DEVICE_CLASS       0xD3
  80 #define USB_ERROR_OUT_OF_ADDRESS_SPACE_IN_POOL          0xD4
  81 #define USB_ERROR_HUB_ADDRESS_OVERFLOW                  0xD5
  82 #define USB_ERROR_ADDRESS_NOT_FOUND_IN_POOL             0xD6
  83 #define USB_ERROR_EPINFO_IS_NULL                        0xD7
  84 #define USB_ERROR_INVALID_ARGUMENT                      0xD8
  85 #define USB_ERROR_CLASS_INSTANCE_ALREADY_IN_USE         0xD9
  86 #define USB_ERROR_INVALID_MAX_PKT_SIZE                  0xDA
  87 #define USB_ERROR_EP_NOT_FOUND_IN_TBL                   0xDB
  88 #define USB_ERROR_CONFIG_REQUIRES_ADDITIONAL_RESET      0xE0
  89 #define USB_ERROR_FailGetDevDescr                       0xE1
  90 #define USB_ERROR_FailSetDevTblEntry                    0xE2
  91 #define USB_ERROR_FailGetConfDescr                      0xE3
  92 #define USB_ERROR_TRANSFER_TIMEOUT                      0xFF
  93
  94 #define USB_XFER_TIMEOUT        5000    // (5000) USB transfer timeout in milliseconds, per section 9.2.6.1 of USB 2.0 spec
  95 //#define USB_NAK_LIMIT         32000   // NAK limit for a transfer. 0 means NAKs are not counted
  96 #define USB_RETRY_LIMIT         3       // 3 retry limit for a transfer
  97 #define USB_SETTLE_DELAY        200     // settle delay in milliseconds
  98
  99 #define USB_NUMDEVICES          16      //number of USB devices
 100 //#define HUB_MAX_HUBS          7       // maximum number of hubs that can be attached to the host controller
 101 #define HUB_PORT_RESET_DELAY    20      // hub port reset delay 10 ms recomended, can be up to 20 ms
 102
 103 /* USB state machine states */
 104 #define USB_STATE_MASK                                      0xf0
 105
 106 #define USB_STATE_DETACHED                                  0x10
 107 #define USB_DETACHED_SUBSTATE_INITIALIZE                    0x11
 108 #define USB_DETACHED_SUBSTATE_WAIT_FOR_DEVICE               0x12
 109 #define USB_DETACHED_SUBSTATE_ILLEGAL                       0x13
 110 #define USB_ATTACHED_SUBSTATE_SETTLE                        0x20
 111 #define USB_ATTACHED_SUBSTATE_RESET_DEVICE                  0x30
 112 #define USB_ATTACHED_SUBSTATE_WAIT_RESET_COMPLETE           0x40
 113 #define USB_ATTACHED_SUBSTATE_WAIT_SOF                      0x50
 114 #define USB_ATTACHED_SUBSTATE_WAIT_RESET                    0x51
 115 #define USB_ATTACHED_SUBSTATE_GET_DEVICE_DESCRIPTOR_SIZE    0x60
 116 #define USB_STATE_ADDRESSING                                0x70
 117 #define USB_STATE_CONFIGURING                               0x80
 118 #define USB_STATE_RUNNING                                   0x90
 119 #define USB_STATE_ERROR                                     0xa0
 120
 121 class USBDeviceConfig {
 122 public:
 123
 124         virtual uint8_t Init(uint8_t parent, uint8_t port, bool lowspeed) {
 125                 return 0;
 126         }
 127
 128         virtual uint8_t ConfigureDevice(uint8_t parent, uint8_t port, bool lowspeed) {
 129                 return 0;
 130         }
 131
 132         virtual uint8_t Release() {
 133                 return 0;
 134         }
 135
 136         virtual uint8_t Poll() {
 137                 return 0;
 138         }
 139
 140         virtual uint8_t GetAddress() {
 141                 return 0;
 142         }
 143
 144         virtual void ResetHubPort(uint8_t port) {
 145                 return;
 146         } // Note used for hubs only!
 147
 148         virtual bool VIDPIDOK(uint16_t vid, uint16_t pid) {
 149                 return false;
 150         }
 151
 152         virtual bool DEVCLASSOK(uint8_t klass) {
 153                 return false;
 154         }
 155
 156         virtual bool DEVSUBCLASSOK(uint8_t subklass) {
 157                 return true;
 158         }
 159
 160 };
 161
 162 /* USB Setup Packet Structure   */
 163 typedef struct {
 164
 165         union { // offset   description
 166                 uint8_t bmRequestType; //   0      Bit-map of request type
 167
 168                 struct {
 169                         uint8_t recipient : 5; //          Recipient of the request
 170                         uint8_t type : 2; //          Type of request
 171                         uint8_t direction : 1; //          Direction of data X-fer
 172                 } __attribute__((packed));
 173         } ReqType_u;
 174         uint8_t bRequest; //   1      Request
 175
 176         union {
 177                 uint16_t wValue; //   2      Depends on bRequest
 178
 179                 struct {
 180                         uint8_t wValueLo;
 181                         uint8_t wValueHi;
 182                 } __attribute__((packed));
 183         } wVal_u;
 184         uint16_t wIndex; //   4      Depends on bRequest
 185         uint16_t wLength; //   6      Depends on bRequest
 186 } __attribute__((packed)) SETUP_PKT, *PSETUP_PKT;
 187
 188
 189
 190 // Base class for incoming data parser
 191
 192 class USBReadParser {
 193 public:
 194         virtual void Parse(const uint16_t len, const uint8_t *pbuf, const uint16_t &offset) = 0;
 195 };
 196
 197 class USB : public MAX3421E {
 198         AddressPoolImpl<USB_NUMDEVICES> addrPool;
 199         USBDeviceConfig* devConfig[USB_NUMDEVICES];
 200         uint8_t bmHubPre;
 201
 202 public:
 203         USB(void);
 204
 205         void SetHubPreMask() {
 206                 bmHubPre |= bmHUBPRE;
 207         };
 208
 209         void ResetHubPreMask() {
 210                 bmHubPre &= (~bmHUBPRE);
 211         };
 212
 213         AddressPool& GetAddressPool() {
 214                 return (AddressPool&)addrPool;
 215         };
 216
 217         uint8_t RegisterDeviceClass(USBDeviceConfig *pdev) {
 218                 for(uint8_t i = 0; i < USB_NUMDEVICES; i++) {
 219                         if(!devConfig[i]) {
 220                                 devConfig[i] = pdev;
 221                                 return 0;
 222                         }
 223                 }
 224                 return USB_ERROR_UNABLE_TO_REGISTER_DEVICE_CLASS;
 225         };
 226
 227         void ForEachUsbDevice(UsbDeviceHandleFunc pfunc) {
 228                 addrPool.ForEachUsbDevice(pfunc);
 229         };
 230         uint8_t getUsbTaskState(void);
 231         void setUsbTaskState(uint8_t state);
 232
 233         EpInfo* getEpInfoEntry(uint8_t addr, uint8_t ep);
 234         uint8_t setEpInfoEntry(uint8_t addr, uint8_t epcount, EpInfo* eprecord_ptr);
 235
 236         /* Control requests */
 237         uint8_t getDevDescr(uint8_t addr, uint8_t ep, uint16_t nbytes, uint8_t* dataptr);
 238         uint8_t getConfDescr(uint8_t addr, uint8_t ep, uint16_t nbytes, uint8_t conf, uint8_t* dataptr);
 239
 240         uint8_t getConfDescr(uint8_t addr, uint8_t ep, uint8_t conf, USBReadParser *p);
 241
 242         uint8_t getStrDescr(uint8_t addr, uint8_t ep, uint16_t nbytes, uint8_t index, uint16_t langid, uint8_t* dataptr);
 243         uint8_t setAddr(uint8_t oldaddr, uint8_t ep, uint8_t newaddr);
 244         uint8_t setConf(uint8_t addr, uint8_t ep, uint8_t conf_value);
 245         /**/
 246         uint8_t ctrlData(uint8_t addr, uint8_t ep, uint16_t nbytes, uint8_t* dataptr, bool direction);
 247         uint8_t ctrlStatus(uint8_t ep, bool direction, uint16_t nak_limit);
 248         uint8_t inTransfer(uint8_t addr, uint8_t ep, uint16_t *nbytesptr, uint8_t* data);
 249         uint8_t outTransfer(uint8_t addr, uint8_t ep, uint16_t nbytes, uint8_t* data);
 250         uint8_t dispatchPkt(uint8_t token, uint8_t ep, uint16_t nak_limit);
 251
 252         void Task(void);
 253
 254         uint8_t DefaultAddressing(uint8_t parent, uint8_t port, bool lowspeed);
 255         uint8_t Configuring(uint8_t parent, uint8_t port, bool lowspeed);
 256         uint8_t ReleaseDevice(uint8_t addr);
 257
 258         uint8_t ctrlReq(uint8_t addr, uint8_t ep, uint8_t bmReqType, uint8_t bRequest, uint8_t wValLo, uint8_t wValHi,
 259                 uint16_t wInd, uint16_t total, uint16_t nbytes, uint8_t* dataptr, USBReadParser *p);
 260
 261 private:
 262         void init();
 263         uint8_t SetAddress(uint8_t addr, uint8_t ep, EpInfo **ppep, uint16_t *nak_limit);
 264         uint8_t OutTransfer(EpInfo *pep, uint16_t nak_limit, uint16_t nbytes, uint8_t *data);
 265         uint8_t InTransfer(EpInfo *pep, uint16_t nak_limit, uint16_t *nbytesptr, uint8_t *data);
 266         uint8_t AttemptConfig(uint8_t driver, uint8_t parent, uint8_t port, bool lowspeed);
 267 };
 268
 269 #if 0 //defined(USB_METHODS_INLINE)
 270 //get device descriptor
 271
 272 inline uint8_t USB::getDevDescr(uint8_t addr, uint8_t ep, uint16_t nbytes, uint8_t* dataptr) {
 273         return ( ctrlReq(addr, ep, bmREQ_GET_DESCR, USB_REQUEST_GET_DESCRIPTOR, 0x00, USB_DESCRIPTOR_DEVICE, 0x0000, nbytes, dataptr));
 274 }
 275 //get configuration descriptor
 276
 277 inline uint8_t USB::getConfDescr(uint8_t addr, uint8_t ep, uint16_t nbytes, uint8_t conf, uint8_t* dataptr) {
 278         return ( ctrlReq(addr, ep, bmREQ_GET_DESCR, USB_REQUEST_GET_DESCRIPTOR, conf, USB_DESCRIPTOR_CONFIGURATION, 0x0000, nbytes, dataptr));
 279 }
 280 //get string descriptor
 281
 282 inline uint8_t USB::getStrDescr(uint8_t addr, uint8_t ep, uint16_t nuint8_ts, uint8_t index, uint16_t langid, uint8_t* dataptr) {
 283         return ( ctrlReq(addr, ep, bmREQ_GET_DESCR, USB_REQUEST_GET_DESCRIPTOR, index, USB_DESCRIPTOR_STRING, langid, nuint8_ts, dataptr));
 284 }
 285 //set address
 286
 287 inline uint8_t USB::setAddr(uint8_t oldaddr, uint8_t ep, uint8_t newaddr) {
 288         return ( ctrlReq(oldaddr, ep, bmREQ_SET, USB_REQUEST_SET_ADDRESS, newaddr, 0x00, 0x0000, 0x0000, NULL));
 289 }
 290 //set configuration
 291
 292 inline uint8_t USB::setConf(uint8_t addr, uint8_t ep, uint8_t conf_value) {
 293         return ( ctrlReq(addr, ep, bmREQ_SET, USB_REQUEST_SET_CONFIGURATION, conf_value, 0x00, 0x0000, 0x0000, NULL));
 294 }
 295
 296 #endif // defined(USB_METHODS_INLINE)
 297
 298 #endif /* USBCORE_H */