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