1 /*******************************************************************************
2  * Copyright 2019-2020 Microchip FPGA Embedded Systems Solutions.
3  *
4  * SPDX-License-Identifier: MIT
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a copy
7  * of this software and associated documentation files (the "Software"), to
8  * deal in the Software without restriction, including without limitation the
9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10  * sell copies of the Software, and to permit persons to whom the Software is
11  * furnished to do so, subject to the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included in
14  * all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22  * IN THE SOFTWARE.
23  *
24  * PolarFire SoC MSS USB Driver Stack
25  *      USB Logical Layer (USB-LL)
26  *          USBH driver
27  *
28  *  USBH driver public API.
29  *
30  */
31 /*=========================================================================*//**
32   @mainpage PolarFire SoC MSS USB Host driver (USBH)
33 
34   ==============================================================================
35   Introduction
36   ==============================================================================
37   The USB Host Driver (USBH) is part of the USB-LL layer of the MSS USB driver
38   stack. The USBH driver implements the core functionality of the USB host mode
39   operations. The USBH driver is responsible for the following functionalities.
40     - Device attach and detach handling
41     - Enumeration and USB Standard requests
42     - Device Suspend, Resume and Reset handling
43     - USB transfers management
44     - USBH-Class call-back interface
45     - Application call-back interface
46 
47   ==============================================================================
48   Theory of Operation
49   ==============================================================================
50   The following steps are involved in the operation of the USBH driver:
51     - Configuration
52     - Initialization
53     - USBH-Class Interface
54     - Application Interface
55     - Data transfer
56 
57   The USBH driver operation depends on user configuration provided in
58   mss_usb_config.h.
59 
60   --------------------------------
61   Configuration
62   --------------------------------
63   The following parameter must be defined in the mss_usb_config.h file to
64   operate the MSS USB hardware block in USB Host mode.
65 
66   MSS_USB_HOST_MODE   Configures the MSS USB Driver Stack to operate in USB
67   host mode.
68 
69   --------------------------------
70   Initialization
71   --------------------------------
72   The USBH driver must be initialized by calling the MSS_USBH_init()
73   initialization function with a parameter to provide the application call-back
74   interface. Once initialized the USBH driver is ready to detect the attach
75   event on the USB port. The application call-back interface is used to provide
76   information about the events on the USB bus to the application. The
77   MSS_USBH_task() is the main task of the USBH driver which implements the state
78   machines for monitoring the USB bus activities. This function must be called
79   repeatedly by the application to allow USBH driver to run it's state machines.
80   A timer/scheduler can be used to call this function at regular intervals or it
81   can be called from the main continuous foreground loop of the application.
82   The function MSS_USBH_1ms_tick() must be called to provide a 1milisecond time
83   tick to the USBH driver. This time tick is used by the USBH driver to track
84   the enumeration process and other housekeeping purposes. The
85   MSS_USBH_get_milis() function is provided to get the number of milliseconds
86   lapsed from the system reset. The MSS_USBH_test_mode() function is provided to
87   force the MSS USB in test modes as required by the USB compliance test
88   specification. This function has no use in normal operations with a attached
89   USB device.
90 
91   --------------------------------
92   USBH-Class Call-back Interface
93   --------------------------------
94   This driver encapsulates the generic USB protocol functionality from the USB
95   class functionality. This driver needs the USBH-Class driver to implement a
96   set of call-back functions to pass on the control to the USBH-Class driver for
97   handling the USB class specific functionality. This driver provides a data
98   type mss_usbh_class_cb_t which must be implemented by the USBH-Class driver.
99   This data type is the collection of call-back functions which must be
100   implemented by the USBH-Class driver. Implementing all the elements of this
101   structure may not be necessary for a specific USB class. The USBH-Class driver
102   must define a structure of type mss_usbh_class_cb_t and implement its required
103   elements. The function MSS_USBH_register_class_driver() must be used to inform
104   the USBH driver about this call-back interface and the supported USB Class
105   information
106   The table below lists the prototypes of the call-back functions which are part
107   of the mss_usbh_class_cb_t   type and the event in which they are called.
108 
109   | Call-back Element      | Event                                             |
110   |------------------------|---------------------------------------------------|
111   | usbh_class_allocate    | Called when a match is found between the class    |
112   |                        | sub-class code and protocol code of the attached  |
113   |                        | device and the corresponding parameters provided  |
114   |                        | by the USBH-Class driver in the class_id parameter|
115   | usbh_class_release     | Called when the device for which this USBH-Class  |
116   |                        | driver is assigned is detached                    |
117   | usbh_class_cep_xfr_done| Called when a transfer started by this USBH-Class |
118   |                        | driver is complete                                |
119   | usbh_class_tx_done     | Called when a transfer started on the OUT pipe by |
120   |                        | this USBH-Class driver is complete                |
121   | usbh_class_rx_done     | Called when a transfer started on the IN pipe by  |
122   |                        | this USBH-Class driver is complete                |
123   | usbh_class_sof         | The function pointed by the usbh_class_sof element|
124   |                        | will be called when a new (micro) frame starts    |
125 
126   --------------------------------
127   Application Call-back Interface
128   --------------------------------
129   The USBH driver uses interrupts to respond to the events on MSS USB. The
130   USBH driver handles the enumeration of the attached device internally.
131   The enumeration process can take long time (hundreds of milliseconds) to
132   complete. The USBH driver uses application call-back interface to inform the
133   application about the events on the USB bus as they happen. The application
134   may implement these call-back functions to take application specific action
135   on each event or to provide error/status messages to the user.
136 
137   The table below lists the prototypes of the call-back functions which are
138   part of the mss_usbh_user_cb_t type and the event in which they are called.
139 
140   | Element                         | Call-back Event                          |
141   |---------------------------------|------------------------------------------|
142   | usbh_tdev_attached              | Called when a device-attach event is     |
143   |                                 | detected by the USBH driver. At this     |
144   |                                 | point the device is not enumerated.      |
145   | usbh_tdev_dettached             | Called when a device-detach event is     |
146   |                                 | detected by the USBH driver              |
147   | usbh_tdev_oc_error              | Called when an over-current condition is |
148   |                                 | detected by the USBH driver              |
149   | usbh_tdev_enumerated            | Called when the attached device is       |
150   |                                 | successfully enumerated                  |
151   | usbh_tdev_class_driver_assigned | Called when a matching class driver is   |
152   |                                 | assigned to the attached device          |
153   | usbh_tdev_not_supported         | Called when a device which is not        |
154   |                                 | supported by the USBH driver is detected |
155   | usbh_tdev_permanent_error       | Called if there was error during data    |
156   |                                 | transfer operations with the attached    |
157   |                                 | device                                   |
158 
159   --------------------------------
160   Data transfer
161   --------------------------------
162   The USB host uses pipe, a representation of logical connection from endpoint
163   on MSS USB to the endpoint on the target device. The transmit pipe or the
164   receive pipe must first be configured before starting the data transfer on it.
165   The functions MSS_USBH_configure_in_pipe() and MSS_USBH_configure_out_pipe()
166   must be used to configure an IN(data moving from device to host) and an
167   OUT(data moving from host to device) pipe respectively.
168 
169   The application must use MSS_USBH_write_out_pipe() function to start data
170   transmission on a OUT pipe. This function prepares the MSS USB to transmit
171   data to the device. However, actual transmission happens depending on the
172   transfer type and the selected interval. This function is non-blocking.
173   The USBH-Class driver will be informed about data transmission completion or
174   transmission errors by a call to its call-back function. Please refer
175   USBH-Class Interface section above for more details.
176 
177   To receive data from attached USB device, application must use
178   MSS_USBH_read_in_pipe() function. This function prepares the MSS USB to
179   receive data from the attached device. However, actual data transfer happens
180   depending on the transfer type and the selected interval. This function is
181   non-blocking. On receiving data or in case of errors during this operation
182   the USBH-Class driver will be informed about it by calling a call-back
183   function. Please refer the USBH-Class Interface section above for more
184   details.
185 
186   This driver supports multi-packet Bulk transfer (both IN and OUT), to make
187   sure that it is able to use the full bandwidth offered by USB Bulk transfers.
188   When a transfer size of more than wMaxPktSize is provided to this driver using
189   MSS_USBH_write_out_pipe() function or MSS_USBH_read_in_pipe() function, this
190   driver handles this multi-packet transfer internally by dividing it into
191   multiple Bulk transfers of wMaxPktSize each. This way no application
192   intervention is required till the total multi-packet Bulk transfer is
193   complete.
194 
195   The USBH driver supports Bulk transfers using the DMA inside MSS USB or
196   without using the internal DMA. It is advised that the USBH driver is
197   configured to use the internal DMA in order to free up the application from
198   transferring data to/from MSS USB hardware block. However, the internal DMA
199   can access only aligned address. Care must be taken that the buffer address
200   provided to the USBH driver must be modulo-4. This is not a requirement when
201   the MSS USB driver is configured not to use internal DMA.
202 
203   All the control transfers happen on the control pipe. The control pipe is
204   shared by the USBH driver and the USBH-Class driver. When the USBH-Class
205   driver needs to perform control transfer on the attached device, it must first
206   configure the control pipe using the MSS_USBH_configure_control_pipe()
207   function. The MSS_USBH_start_control_xfr() function can be used to start the
208   control transfer After the control pope is configured. The data direction is
209   determined by a parameter provided with this function. The USBH-Class driver
210   will be informed about the data transfer completion or the error status by
211   calling a call-back function. Please refer the USBH-Class Interface section
212   above for more details. The control transfer can be started by a USBH-Class
213   driver only when the control pipe is free.The MSS_USBH_get_cep_state()
214   function can be used to know the current state of the control pipe. At the
215   start of the control transfer the USBH driver must send a setup-packet to the
216   attached device in the setup phase. The function
217   MSS_USBH_construct_get_descr_command() can be used to construct the setup
218   packet as per the USB specification for the transfer to be performed. This
219   function formats the setup packet depending on the parameters provided with
220   this function.
221 
222   The application may choose to keep the MSS USB in suspend state to conserve
223   power to the USB device, and the MSS USB, In this state the MSS USB does not
224   send any frames on the bus and there will be no bus activity. This will also
225   ensure that the attached device enters suspend state as specified in the
226   USB2.0 specification. The USBH driver provides the MSS_USBH_suspend() function
227   to suspend the MSS USB. The  MSS_USBH_resume() function must be used to
228   resume the normal operations.
229 
230   The table below provides the list of all the functions provided by USBH
231   driver.
232 
233   | function                     | Description                                 |
234   |------------------------------|---------------------------------------------|
235   | MSS_USBH_init()              | Initialize the MSS USB to operate in the    |
236   |                              | host mode                                   |
237   |                              |                                             |
238   | MSS_USBH_task()              | Main task of the USBH driver where the state|
239   |                              | machines are implemented                    |
240   |                              |                                             |
241   | MSS_USBH_register_class_     | Used to register the class driver handle    |
242   | driver()                     | with the USBH driver                        |
243   |                              |                                             |
244   | MSS_USBH_configure_control_  | Configures the control pipe for control     |
245   | pipe()                       | transfers with the attached device          |
246   |                              |                                             |
247   | MSS_USBH_configure_in_pipe() | Configures the IN pipe for the USB IN       |
248   |                              | transfers with the attached device          |
249   |                              |                                             |
250   | MSS_USBH_configure_out_pipe()| Configures the OUT pipe for the USB OUT     |
251   |                              | transfers with the attached device          |
252   |                              |                                             |
253   | MSS_USBH_write_out_pipe()    | Writes data on to the attached device using |
254   |                              | the OUT pipe                                |
255   |                              |                                             |
256   | MSS_USBH_read_in_pipe()      | Reads data from the attached device using   |
257   |                              | the IN pipe                                 |
258   |                              |                                             |
259   | MSS_USBH_get_tdev_state()    | Used to find out the current state of the   |
260   |                              | attached device                             |
261   |                              |                                             |
262   | MSS_USBH_suspend()           | Suspends the MSS USB core. No frames are    |
263   |                              | transferred                                 |
264   |                              |                                             |
265   | MSS_USBH_resume()            | Resumes the previously suspended MSS USB    |
266   |                              |                                             |
267   | MSS_USBH_get_std_dev_descr() | Reads the device descriptor from the        |
268   |                              | attached device                             |
269   |                              |                                             |
270   | MSS_USBH_1ms_tick()          | Time stamping and housekeeping function     |
271   |                              |                                             |
272   | MSS_USBH_get_milis()         | Used to know the number of milliseconds     |
273   |                              | lapsed after reset                          |
274   |                              |                                             |
275   | MSS_USBH_construct_get_descr | Formats the provided parameters into a USB  |
276   | _command()                   | standard setup packet for GET_DESCRIPTOR    |
277   |                              | command                                     |
278   |                              |                                             |
279   | MSS_USBH_start_control_xfr() | Starts a control transfer on previously     |
280   |                              | configured control pipe                     |
281   |                              |                                             |
282   | MSS_USBH_get_cep_state()     | Provides the current state of the control   |
283   |                              | pipe                                        |
284   |                              |                                             |
285   | MSS_USBH_test_mode()         | Initiates compliance test mode as specified |
286   |                              | by the parameter.                           |
287 
288  *//*=========================================================================*/
289 
290 #ifndef __MSS_USB_HOST_H_
291 #define __MSS_USB_HOST_H_
292 
293 #include "mss_usb_common_cif.h"
294 #include "mss_usb_common_reg_io.h"
295 
296 #ifdef __cplusplus
297 extern "C" {
298 #endif
299 
300 #ifdef MSS_USB_HOST_ENABLED
301 
302 /*-------------------------------------------------------------------------*//**
303  Constant values exported by USBH driver
304 */
305 
306 /*-------------------------------------------------------------------------*//**
307   The following constants are used to identify the exact reason due to which the
308   USBH driver is not supporting the attached device. One of these values is
309   passed as a parameter to the call-back function usbh_tdev_not_supported when
310   USBH driver detects respective condition.
311 */
312 /*
313   Devices operating at the USB full speed are not supported.
314  */
315 #define FS_DEV_NOT_SUPPORTED                            -15
316 
317 /*
318   Devices operating at the USB low speed are not supported.
319  */
320 #define LS_DEV_NOT_SUPPORTED                            -14
321 
322 /*
323   Device belonging to the USB HUB class is detected. The Hub class is not
324   supported by the USBH driver.
325  */
326 #define HUB_CLASS_NOT_SUPPORTED                         -13
327 
328 /*
329   Attached device class description does not match the class description
330   supported by the registered class driver.
331  */
332 #define CLASS_DRIVER_NOT_MATCHED                        -12
333 
334 /*
335   The registered class driver is already in assigned state when new device
336   attachment is detected.
337  */
338 #define CLASS_DRIVER_NOT_FREE                           -11
339 
340 /*
341   The power requirement for the attached device, as described in the bMaxPower
342   field of configuration descriptor, can not be supported by the USBH driver.
343  */
344 #define CONF_DESC_POWER_LIM_EXCEED                      -10
345 
346 /*
347   The value received in bDescriptorType field in configuration descriptor is
348   invalid.
349 */
350 #define CONF_DESC_WRONG_DESC_TYPE                       -9
351 
352 /*
353   The value received in bLength field of the configuration descriptor does not
354   match the standard value (9) as specified in the USB2.0 specification.
355  */
356 #define CONF_DESC_WRONG_LENGTH                          -8
357 
358 /*
359   The value received in bMaxPacketSize0 field of the device descriptor is not 8
360   for a LS device.
361  */
362 #define DEV_DESC_LS_MAXPKTSZ0_NOT8                      -7
363 
364 /*
365   The value received in bMaxPacketSize0 field of the device descriptor is not 64
366   for a HS device.
367  */
368 #define DEV_DESC_HS_MAXPKTSZ0_NOT64                     -6
369 
370 /*
371   The value received in bcdDevice field of the device descriptor for a HS device
372   does not indicate USB2.0
373  */
374 #define DEV_DESC_HS_USBBCD_NOT200                       -5
375 
376 /*
377   The value received in the bMaxPacketSize0 field of the device descriptor is
378   invalid. For LS device this value must be 8. For HS device this value must be
379   64. For FS device this value must be 8, 16, 32, or 64.
380  */
381 #define DEV_DESC_WRONG_MAXPKTSZ0                        -4
382 
383 /*
384   The value received in the bcdDevice field of the device descriptor is invalid.
385   For HS device this value must indicate USB2.0.
386  */
387 #define DEV_DESC_WRONG_USBBCD                           -3
388 
389 /*
390   The value received in the bDescriptorType field in device descriptor is
391   invalid.
392  */
393 #define DEV_DESC_WRONG_DESC_TYPE                        -2
394 
395 /*
396   The value received in the bLength field of the device descriptor does not
397   match the standard value (18).
398  */
399 #define DEV_DESC_WRONG_LENGTH                           -1
400 
401 /*
402   The following constants are used as the return values for the call-back
403   functions, implemented by the USBH-Class driver as part of mss_usbh_class_cb_t
404   type, which are called by the USBH driver. The USBH driver uses these values
405   to infer whether or not the call-back function was successfully executed. The
406   current control transfer is stalled if the return value is USB_FAIL.
407  */
408 #define USB_FAIL                                        0u
409 #define USB_SUCCESS                                     1u
410 
411 /*-------------------------------------------------------------------------*//**
412   Data structures exported by USBH driver
413  */
414 
415 /*-------------------------------------------------------------------------*//**
416   The mss_usbh_class_cb_t provides the prototype of the structure that must be
417   implemented by the USBH-Class driver to provide the call-back functions which
418   will be called by the USBH driver to communicate events on the target device.
419 
420   class_id
421   The class_id parameter is the place-holder for identifying the USBH-Class
422   driver which is implementing this call-back interface. This parameter is used
423   by the USBH driver to identify and assign the class driver to the attached
424   device.The MSS_USBH_register_class_driver() function must be used to register
425   a class driver with the the USBH driver. This parameter must be of the form:
426 
427   | Class id bit  |                  Description                               |
428   |-------------- |------------------------------------------------------------|
429   |  D7 - D0      |                  USB Std Protocol code                     |
430   |  D15 - D8     |                  USB Std sub-class code                    |
431   |  D23 - D16    |                  USB Std class code                        |
432   |  D31 - D24    |                            0x00                            |
433 
434   usbh_class_allocate
435   The function pointed by the usbh_class_allocate element will be called when a
436   match is found between the class code, sub-class code and protocol code of the
437   attached device and the corresponding parameters provided by the USBH-Class
438   driver in class_id parameter. The tdev_addr parameter provides the non-zero
439   device address assigned to the attached device by the USBH driver.
440 
441   usbh_class_release
442   The function pointed by the usbh_class_release element will be called when the
443   device for which this USBH-Class driver is assigned is detached. The tdev_addr
444   parameter provides the non-zero device address assigned to the attached device
445   by the USBH driver.
446 
447   usbh_class_cep_xfr_done
448   The function pointed by the usbh_class_cep_xfr_done element will be called
449   when a control transfer started by this USBH-Class driver is complete. The
450   tdev_addr parameter provides the non-zero device address assigned to the
451   attached device by the USBH driver. The status parameter indicates whether or
452   not the current control transfer was completed successfully. The count
453   parameter provides the number of bytes transferred in the current control
454   transfer. The status parameter provides the error status of current control
455   transfer. A non-zero value indicates that there was an error.
456 
457   usbh_class_tx_done
458   The function pointed by the usbh_class_tx_done element will be called
459   when a transfer started on OUT pipe by this USBH-Class driver is complete.
460   The tdev_addr parameter provides the non-zero device address assigned to the
461   attached device by USBH driver. The status parameter indicates whether or not
462   the current transfer was completed successfully. The count parameter provides
463   the number of bytes transferred in the current control transfer. The status
464   parameter provides the error status of the current control transfer. A
465   non-zero value indicates that there was an error.
466 
467   usbh_class_rx_done
468   The function pointed by the usbh_class_rx_done element will be called
469   when a transfer started on the IN pipe by this USBH-Class driver is complete.
470   The tdev_addr parameter provides the non-zero device address assigned to the
471   attached device by the USBH driver. The status parameter indicates whether or
472   not the current transfer was completed successfully. The count parameter
473   provides the number of bytes transferred in the current control transfer.
474   The status parameter provides the error status of current control transfer.
475   A non-zero value indicates that there was an error.
476 
477   usbh_class_sof
478   The function pointed by the usbh_class_sof element will be called when a new
479   micro frame starts. The frame_number provides the number of the current
480   micro frame.
481 
482 */
483 typedef struct mss_usbh_class_cb {
484     uint32_t class_id;
485     uint8_t (*usbh_class_allocate)(uint8_t tdev_addr);
486     uint8_t (*usbh_class_release)(uint8_t tdev_addr);
487     uint8_t (*usbh_class_cep_xfr_done)(uint8_t tdev_addr,
488                                        uint8_t status,
489                                        uint32_t count);
490 
491     uint8_t (*usbh_class_tx_done)(uint8_t tdev_addr,
492                                   uint8_t status,
493                                   uint32_t count);
494 
495     uint8_t (*usbh_class_rx_done)(uint8_t tdev_addr,
496                                   uint8_t status,
497                                   uint32_t count);
498 
499     uint8_t (*usbh_class_sof)(uint32_t frame_number);
500 }mss_usbh_class_cb_t;
501 
502 /*-------------------------------------------------------------------------*//**
503   The mss_usbh_tdev_info_t type provides the prototype for the detailed
504   information of the attached device. Some of the parameters are only applicable
505   when multi-point support is enabled on MSS USB. Multi-point support is
506   currently not enabled in the USBH driver.
507 
508   addr
509   The addr parameter provides the device address assigned to the attached device
510   by the USBH driver.
511 
512   speed
513   The speed parameter indicates the USB speed of operation at which the USBH
514   driver is communicating with the attached device.
515 
516   state
517   The state parameter provides the current state of the attached device. E.g.
518   address, Configured etc.
519 
520   hub_addr
521   The hub_addr parameter provides the address of the hub to which the device is
522   attached. This parameter is meaningful only when Multi-Point support is
523   enabled. Multi-point support is currently not enabled in the USBH driver.
524 
525   hub_port
526   The hub_port parameter provides the port number of the hub to which the device
527   is attached. This parameter is meaningful only when Multi-Point support is
528   enabled. Multi-point support is currently not enabled in the USBH driver.
529 
530   hub_mtt
531   The hub_mtt parameter indicates whether or not the hub to which the device is
532   attached supports multiple transaction translators. This parameter is
533   meaningful only when Multi-Point support is enabled. Multi-point support is
534   currently not enabled in the USBH driver.
535 
536   maxpktsz0
537   The maxpktsz0 parameter provides the maximum packet size of the control
538   endpoint on the attached device.
539 
540   state
541   The state parameter provides the current state of the attached device.
542   E.g. address, Configured etc.
543 
544   class_handle
545   The class_handle parameter is the class handle registered with the USBH driver
546   using MSS_USBH_register_class_driver() function. This handle is used by the
547   USBH driver to call the call-back functions implemented by the USBH-Class
548   driver.
549 
550  */
551 typedef struct mss_usbh_target_info {
552     uint8_t addr;
553     mss_usb_device_speed_t speed;
554     mss_usb_state_t state;
555     uint8_t hub_addr;
556     uint8_t hub_port;
557     uint8_t hub_mtt;
558     uint16_t tdev_maxpktsz0;
559     mss_usbh_class_cb_t* class_handle;
560 } mss_usbh_tdev_info_t;
561 
562 /*-------------------------------------------------------------------------*//**
563   The mss_usbh_user_cb_t provides the prototype of the structure that must be
564   implemented by the application to provide the call-back functions which will
565   be called by the USBH driver to communicate events on the target device. These
566   call-back functions can be used by the application to know the USBH driver
567   state and information about the attached device from the USBH driver.
568   These events are not specific to any USB class.
569 
570   usbh_tdev_attached
571   The function pointed by the usbh_tdev_attached element will be called when a
572   device attach even is detected by the USBH driver. At this point the device is
573   not enumerated. The speed parameter indicates the USB speed of operation at
574   which the USBH driver is going to communicate with the attached device.
575 
576   usbh_tdev_dettached
577   The function pointed by the usbh_tdev_dettached element will be called when
578   a device detach even is detected by the USBH driver.
579 
580   usbh_tdev_oc_error
581   The function pointed by the usbh_tdev_oc_error element will be called when an
582   over-current condition is detected by the USBH driver.
583 
584   usbh_tdev_enumerated
585   The function pointed by the usbh_tdev_enumerated element will be called when
586   the attached device is successfully enumerated. At this point the device
587   descriptor is successfully read from the attached device. No class specific
588   information is read from the device yet. The tdev_info parameter gives the
589   information about the attached device.
590 
591   usbh_tdev_class_driver_assigned
592   The function pointed by the usbh_tdev_class_driver_assigned element will be
593   called when a matching class driver is assigned to the attached device.
594   The class driver must be previously registered with the USBH driver using
595   MSS_USBH_register_class_driver() function.
596 
597   usbh_tdev_not_supported
598   The function pointed by the usbh_tdev_not_supported element will be called
599   when a device which is not supported by the USBH driver is attached. The
600   error_code parameter provides the exact reason why the device is not
601   supported.
602   E.g. devices belonging to Hub class are not supported.
603 
604   usbh_tdev_ permanent_error
605   The function pointed by the usbh_tdev_permanent_error element will be called
606   if there is error during data transfer operations with the attached device
607   persists after retries. On detecting an error in data transfer with the
608   attached device, the USBH driver retries for maximum three times.
609 */
610 typedef struct mss_usbh_user_cb
611 {
612     void (*usbh_tdev_attached)(mss_usb_device_speed_t speed);
613     void (*usbh_tdev_dettached)(void);
614     void (*usbh_tdev_oc_error)(void);
615     void (*usbh_tdev_enumerated)(mss_usbh_tdev_info_t tdev_info);
616     void (*usbh_tdev_class_driver_assigned) (void);
617     void (*usbh_tdev_not_supported)(int8_t error_code);
618     void (*usbh_tdev_permanent_error)(void);
619 } mss_usbh_user_cb_t;
620 
621 /*-------------------------------------------------------------------------*//**
622  Data structures internally used by USBH driver
623 */
624 
625 /*-------------------------------------------------------------------------*//**
626   The dev_desc_t provides the prototype of the structure for the standard USB
627   device descriptor. All the parameters of this structure are as per the
628   standard setup packet defined in the USB2.0 specification.
629 
630   bLength
631   The bLength parameter indicates the length of the device descriptor in bytes.
632   The meaning of this parameter is exactly as defined by the USB2.0
633   specification.
634 
635   bDescriptorType
636   The bDescriptorType parameter indicates the standard descriptor type of this
637   descriptor. The meaning of this parameter is exactly as defined by the USB2.0
638   specification.
639 
640   bcdUSB
641   The bcdUSB parameter indicates the USB standard (BCD format) supported by the
642   device. The meaning of this parameter is exactly as defined by the USB2.0
643   specification.
644 
645   bDeviceClass
646   The bDeviceClass parameter indicates the standard USB class supported by the
647   device. The meaning of this parameter is exactly as defined by the USB2.0
648   specification.
649 
650   bDeviceSubClass
651   The bDeviceSubClass parameter indicates the standard USB sub-class supported
652   by the device. The meaning of this parameter is exactly as defined by the
653   USB2.0 specification.
654 
655   bDeviceProtocol
656   The bDeviceProtocol parameter indicates the standard USB data transfer
657   protocol supported by the device. The meaning of this parameter is exactly as
658   defined by the USB2.0 specification.
659 
660   bMaxPacketSize0
661   The bMaxPacketSize0 parameter indicates the Maximum packet size of the
662   Endpoint0 on the device. The meaning of this parameter is exactly as defined
663   by the USB2.0 specification.
664 
665   idVendor
666   The idVendor parameter indicates Vendor ID of the connected device. The
667   meaning of this parameter is exactly as defined by the USB2.0 specification.
668 
669   idProduct
670   The idProduct parameter indicates Product ID of the connected device. The
671   meaning of this parameter is exactly as defined by the USB2.0 specification.
672 
673   bcdDevice
674   The bcdDevice parameter indicates release number (BCD format) of the connected
675   device. The meaning of this parameter is exactly as defined by the USB2.0
676   specification.
677 
678   iManufacturer
679   The iManufacturer parameter indicates the index of the string descriptor
680   describing the manufacture name of the connected device. The meaning of this
681   parameter is exactly as defined by the USB2.0 specification.
682 
683   iProduct
684   The iProduct parameter indicates index of string descriptor describing the
685   product name of the connected device. The meaning of this parameter is exactly
686   as defined by the USB2.0 specification.
687 
688   iSerialNumber
689   The iSerialNumber parameter indicates the index of the string descriptor
690   describing the serial number of the connected device. The meaning of this
691   parameter is exactly as defined by the USB2.0 specification.
692 
693   bNumConfigurations
694   The bNumConfigurations parameter indicates number of configurations supported
695   by the connected device. The meaning of this parameter is exactly as defined
696   by the USB2.0 specification.
697 
698   reserved
699   The reserved parameter does not have a specific meaning. It is provided to
700   make the structure word aligned.
701 */
702 typedef struct
703 {
704     uint8_t   bLength;
705     uint8_t   bDescriptorType;
706     uint16_t  bcdUSB;
707     uint8_t   bDeviceClass;
708     uint8_t   bDeviceSubClass;
709     uint8_t   bDeviceProtocol;
710     uint8_t   bMaxPacketSize0;
711     uint16_t  idVendor;
712     uint16_t  idProduct;
713     uint16_t  bcdDevice;
714     uint8_t   iManufacturer;
715     uint8_t   iProduct;
716     uint8_t   iSerialNumber;
717     uint8_t   bNumConfigurations;
718     uint16_t  reserved; /*Word alignment*/
719 }dev_desc_t;
720 
721 /*-------------------------------------------------------------------------*//**
722   The def_conf_desc_t provides the prototype of the structure for the standard
723   USB configuration descriptor. All the parameters of this structure are as per
724   the standard setup packet defined in the USB2.0 specification.
725 
726   bLength
727   The bLength parameter indicates the length of the configuration descriptor in
728   bytes. The meaning of this parameter is exactly as defined by the USB2.0
729   specification.
730 
731   bDescriptorType
732   The bDescriptorType parameter indicates the standard descriptor type of this
733   descriptor. The meaning of this parameter is exactly as defined by the USB2.0
734   specification.
735 
736   bTotalLength
737   The bTotalLength parameter indicates the total length (in bytes) of the
738   configuration descriptor including the class specific subordinate descriptors.
739   The meaning of this parameter is exactly as defined by the USB2.0
740   specification.
741 
742   bNumInterface
743   The bNumInterfaces parameter indicates the number of interfaces supported by
744   this configuration. The meaning of this parameter is exactly as defined by
745   the USB2.0 specification.
746 
747   bConfigurationValue
748   The bConfigurationValue parameter indicates the value to be use as an argument
749   to SET_CONFIGURATION request to select this configuration. The meaning of this
750   parameter is exactly as defined by the USB2.0 specification.
751 
752   iConfiguration
753   The iConfiguration parameter indicates the index of the string descriptor
754   describing this configuration. The meaning of this parameter is exactly as
755   defined by the USB2.0 specification.
756 
757   bmAttributes
758   The bmAttributes parameter provides configuration characteristics of this
759   configuration. The meaning of this parameter is exactly as defined by the
760   USB2.0 specification.
761 
762   bMaxPower
763   The bMaxPower parameter indicates the Maximum power consumption of the USB
764   device from the bus in this specific configuration when the device is fully
765   operational. The meaning of this parameter is exactly as defined by the
766   USB2.0 specification.
767 
768   upended_desc
769   The upended_desc parameter can be used to store the class specific subordinate
770   descriptor information. This might be useful to retrieve some basic
771   information about the selected configuration.
772 */
773 typedef struct {
774     uint8_t bLength;
775     uint8_t bDescriptorType;
776     uint16_t wTotalLength;
777     uint8_t bNumInterfaces;
778     uint8_t bConfigurationValue;
779     uint8_t iConfiguration;
780     uint8_t bmAttributes;
781     uint8_t bMaxPower;
782     uint8_t upended_desc[11];
783 }def_conf_desc_t;
784 
785 
786 /*---------------------------USBH Public APIs---------------------------------*/
787 
788 /*-------------------------------------------------------------------------*//**
789   The MSS_USBH_init() function initializes the MSS USB driver in the USB host
790   mode. This function initializes the internal data structures and readies the
791   MSS USB hardware block to detect the device attachment event. This function
792   also configures the control endpoint to keep it ready for communicating with
793   the detected device on the USB port. The parameter app_cb provided with this
794   function must be implemented by the application. This driver uses the app_cb
795   to inform the application about the events on the USB bus by calling the
796   appropriate callback element.
797 
798   The MSS_USBH_init() function must be called before any other function to
799   initialize the USBH driver in the USB host mode.
800 
801   @param app_cb
802     The app_cb parameter provides the pointer to the structure of type
803     mss_usbh_user_cb_t. This structure is used to call the user call-back
804     functions by the USBH driver. These call-back functions can be used to
805     provide error/status messages to the user for the application specific
806     handling of the events.
807 
808   @return
809     This function does not return any value.
810 
811   Example:
812   @code
813       mss_usbh_user_cb_t MSS_USBH_user_cb =
814       {
815           USB_DEV_attached,
816           USB_DEV_dettached,
817           USB_DEV_oc_error,
818           USB_DEV_enumerated,
819           USB_DEV_class_driver_assigned,
820           USB_DEV_not_supported,
821           USB_DEV_permanent_erro
822       };
823 
824       MSS_USBH_init(&MSS_USBH_user_cb);
825       MSS_USBH_register_class_driver(MSS_USBH_HID_get_handle());
826   @endcode
827 */
828 void
829 MSS_USBH_init
830 (
831     mss_usbh_user_cb_t* app_cb
832 );
833 
834 /*-------------------------------------------------------------------------*//**
835   The MSS_USBH_task() function is the main task of the USBH driver. This
836   function must be called repeatedly by the application to allow the USBH driver
837   to perform the housekeeping tasks. A timer/scheduler can be used to call this
838   function at regular intervals or it can be called from the main continuous
839   foreground loop of the application.
840 
841   @param
842     This function does not take any parameters.
843 
844   @return
845     This function does not return any value.
846 
847   Example:
848   @code
849       void
850       Host_controller_task
851       (
852           void
853       )
854       {
855           MSS_USBH_task();
856           MSS_USBH_HID_task();
857           switch (c_state)
858           {
859               case CONTROLLER_IDLE:
860                   if(USBH_MSD_DEVICE_READY == MSS_USBH_MSC_get_state())
861                   {
862                        c_state = CONTROLLER_INQUIRY;
863                   }
864                   break;
865                 .
866               default:
867                   break;
868           }
869       }
870   @endcode
871 */
872 void
873 MSS_USBH_task
874 (
875     void
876 );
877 
878 /*-------------------------------------------------------------------------*//**
879   The MSS_USBH_register_class_driver() function must be used by the application
880   to register a USBH-Class driver with the USBH driver. The application must
881   first get the handle from the USBH-Class driver before assigning it to the
882   USBH driver. Refer the USBH-Class section to know how to get a handle from the
883   USBH-Class driver. This handle is used by the USBH driver to communicate with
884   the USBH-Class driver.
885 
886   @param class_handle
887     The class_handle parameter specifies the class driver handle to be
888     registered with the USBH driver.
889 
890   @return
891     This function returns zero when execution was successful.
892 
893   Example:
894   @code
895       mss_usbh_user_cb_t MSS_USBH_user_cb =
896       {
897           USB_DEV_attached,
898           USB_DEV_dettached,
899           USB_DEV_oc_error,
900           USB_DEV_enumerated,
901           USB_DEV_class_driver_assigned,
902           USB_DEV_not_supported,
903           USB_DEV_permanent_erro
904       };
905 
906       MSS_USBH_init(&MSS_USBH_user_cb);
907       MSS_USBH_register_class_driver(MSS_USBH_HID_get_handle());
908   @endcode
909 */
910 int8_t
911 MSS_USBH_register_class_driver
912 (
913     void* class_handle
914 );
915 
916 /*-------------------------------------------------------------------------*//**
917   The MSS_USBH_configure_control_pipe() function is used to configure the
918   control pipe for the control transactions with attached device with the
919   address provided in target_addr parameter. This function also enables the
920   control pipe interrupt.
921 
922   This function must be called before any other function for the control pipe.
923 
924   @param target_addr
925     The target_addr parameter is address of the attached device with which the
926     MSS USB needs to communicate.
927 
928   @return
929     This function returns zero when execution was successful.
930 
931   Example:
932   @code
933       typedef enum {
934           TDEV_R,
935           TDEV_RHP1,
936           TDEV_RHP2
937       } tdev_id_t;
938 
939       MSS_USBH_configure_control_pipe(TDEV_R);
940   @endcode
941 */
942 int8_t
943 MSS_USBH_configure_control_pipe
944 (
945     uint8_t target_addr
946 );
947 
948 /*-------------------------------------------------------------------------*//**
949   The MSS_USBH_configure_in_pipe() function is used to configure the IN pipe
950   for the IN transactions with the attached device with the address provided in
951   the target_addr parameter. This function also enables the IN pipe interrupt.
952 
953   This function must be called before any other function for the IN pipe.
954 
955   @param target_addr
956     The target_addr parameter is the address of the attached device with which
957     MSS USB needs to communicate.
958 
959   @param inpipe_num
960     The inpipe_num parameter indicates the IN pipe number (endpoint) on MSS USB
961     which must be used for IN transfers with the attached device.
962 
963   @param target_ep
964     The target_ep parameter indicates the IN endpoint number on the attached
965     device with which MSS USB needs to communicate.
966 
967   @param fifo_addr
968     The fifo_addr parameter is the address of the FIFO in the MSS USB internal
969     RAM. The valid FIFO address values are from 0x00 to 0xFFF8. The FIFO Address
970     must be a multiple of 8. If the value provided is not a multiple of 8, then
971     the immediate lower value which is a multiple of 8 is taken as the FIFO
972     address.
973     E.g. If the provided value is 0x09, the actual value taken by the driver is
974     0x08. If the provided value is less than 0x08 then the FIFO address is taken
975     as 0x00.
976 
977   @param fifo_size
978     The fifo_size parameter provides the endpoint FIFO size in the USB core
979     internal RAM. The valid FIFO size values are 8, 16, 32, 64, 128, 512, 1024,
980     2048, 4096. The MSS USB assigns 8 byte FIFO by default if the FIFO size is
981     not configured.
982 
983   @param max_pkt_size
984     The max_pkt_size parameter provides the maximum packet size of the USB
985     transfer. This value must be equal to the maximum packet size as mentioned
986     in the endpoint descriptor which is used during enumeration process.
987 
988     Note: This value must be less than or equal to the FIFO size value.
989 
990 
991   @param num_usb_pkt
992     The num_usb_pkt parameter has different meanings for different types of
993     transfers.
994 
995     Low bandwidth ISO/interrupt transfers - This parameter must always be 1u.
996     This parameter represents the number of packets transferred in one (micro)
997     frame.
998 
999     High bandwidth ISO transfers - This parameter represents the number of
1000     packets transferred in one (Micro) frame. In this case, this parameter can
1001     have a value of 1 2 or 3. High bandwidth ISO transfers are not yet
1002     implemented.
1003 
1004     Bulk transfers. - For Bulk transfer this value must always be 1u. This
1005     parameter is  be used with the auto-amalgamation/auto-split feature where it
1006     indicates number of bulk packets to be auto-amalgamated/auto-split in bulk
1007     transfer. The auto-amalgamation/auto-split feature is implemented but not
1008     yet tested.
1009 
1010   @param dma_enable
1011     The dma_enable parameter specifies whether or not the internal DMA must be
1012     used for the data transfer from the provided buffer to the USB FIFO.
1013 
1014   @param dma_channel
1015     The dma_channel parameter specifies the internal DMA channel to be used for
1016     the data transfers. DMA channel will be associated with selected endpoint.
1017     A unique DMA channel must be selected to transfer data on individual
1018     endpoints. This parameter is ignored when dma_enable parameter indicates
1019     that the DMA must not be used.
1020 
1021   @param xfr_type
1022     The xfr_type parameter specifies the type of transfer to be performed on the
1023     specified endpoint. All other types of transfers (Interrupt, Isochronous,
1024     and Bulk) can be selected except the control transfer.
1025 
1026   @param add_zlp
1027     The add_zlp parameter indicates whether to expect a zero length packet (ZLP)
1028     if the transfer size is exact a multiple of wMaxPacketSize. This parameter
1029     is only applicable for bulk transfers. For all other transfer types this
1030     parameter is ignored.
1031 
1032   @param interval
1033     The interval parameter for interrupt and isochronous transfers defines the
1034     polling interval for the currently-selected IN pipe. For bulk transfers,
1035     this parameter indicates the number of frames/microframes after which the IN
1036     pipe must timeout on receiving a stream of NAK responses. The valid values
1037     for this parameter are as mentioned in the table below.
1038 
1039     | Transfer Type    |  Speed     | Valid values                             |
1040     |------------------|------------|------------------------------------------|
1041     |  Interrupt       | LS or FS   | 1 – 255                                  |
1042     |  Interrupt       |    HS      | 1,2,4,8,16,32,64…32768 microframes       |
1043     |                  |            |                                          |
1044     |  Isochronous     | FS or HS   | 1,2,4,8,16,32,64…32768 frames/microframes|
1045     |                  |            |                                          |
1046     |  Bulk            |    HS      | 0,2,4,8,16,32,64…32768 microframes       |
1047     |                  |            | Note:Value 0 disables the NAK Timeout    |
1048     |                  |            | detection on Bulk endpoint               |
1049 
1050   @return
1051     This function returns zero when execution was successful.
1052 
1053   Example:
1054   @code
1055       case USBH_MSC_CONFIG_BULK_ENDPOINTS:
1056           MSS_USBH_configure_out_pipe(g_msd_tdev_addr,
1057                                       USBH_MSC_BULK_TX_PIPE,
1058                                       g_tdev_out_ep.num,
1059                                       USBH_MSC_BULK_TX_PIPE_FIFOADDR,
1060                                       USBH_MSC_BULK_TX_PIPE_FIFOSZ,
1061                                       g_tdev_out_ep.maxpktsz,
1062                                       1,
1063                                       DMA_DISABLE,
1064                                       MSS_USB_DMA_CHANNEL_NA,
1065                                       MSS_USB_XFR_BULK,
1066                                       NO_ZLP_TO_XFR,
1067                                       32768u);
1068 
1069           MSS_USBH_configure_in_pipe(g_msd_tdev_addr,
1070                                      USBH_MSC_BULK_RX_PIPE,
1071                                      g_tdev_in_ep.num,
1072                                      USBH_MSC_BULK_RX_PIPE_FIFOADDR,
1073                                      USBH_MSC_BULK_RX_PIPE_FIFOSZ,
1074                                      g_tdev_in_ep.maxpktsz,
1075                                      1,
1076                                      DMA_DISABLE,
1077                                      MSS_USB_DMA_CHANNEL_NA,
1078                                      MSS_USB_XFR_BULK,
1079                                      NO_ZLP_TO_XFR,
1080                                      32768u);
1081 
1082           g_msc_state = USBH_MSC_TEST_UNIT_READY_CPHASE;
1083       break;
1084   @endcode
1085  */
1086 int8_t
1087 MSS_USBH_configure_in_pipe
1088 (
1089     uint8_t target_addr,
1090     uint8_t inpipe_num,
1091     uint8_t target_ep,
1092     uint16_t fifo_addr,
1093     uint16_t fifo_size,
1094     uint16_t max_pkt_size,
1095     uint8_t num_usb_pkt,
1096     uint8_t dma_enable,
1097     mss_usb_dma_channel_t dma_channel,
1098     mss_usb_xfr_type_t xfr_type,
1099     uint32_t add_zlp,
1100     uint32_t interval
1101 );
1102 
1103 /*-------------------------------------------------------------------------*//**
1104   The MSS_USBH_configure_out_pipe() function is used to configure the OUT pipe
1105   for the OUT transactions with attached device with the address provided in the
1106   target_addr parameter. This function also enables the OUT pipe interrupt.
1107 
1108   This function must be called before any other function for the OUT pipe.
1109 
1110   @param target_addr
1111     The target_addr parameter is the address of the attached device with which
1112     MSS USB needs to communicate.
1113 
1114   @param outpipe_num
1115     The outpipe_num parameter indicates the OUT pipe number (endpoint) on MSS
1116     USB which must be used for OUT transfers with the attached device.
1117 
1118   @param target_ep
1119     The target_ep parameter indicates the OUT endpoint number on the attached
1120     device with which MSS USB needs to communicate.
1121 
1122   @param fifo_addr
1123     The fifo_addr parameter is the address of the FIFO in the MSS USB internal
1124     ram. The valid FIFO address values are from 0x00 to 0xFFF8. The FIFO address
1125     must be a multiple of 8. If the value provided is not a multiple of 8, then
1126     the immediate lower value which is a multiple of 8 is taken as the FIFO
1127     address.
1128     E.g. If the provided value is 0x09, the actual value taken by the driver is
1129     0x08. If the provided value is less than 0x08 then the  FIFO address is
1130     taken as 0x00.
1131 
1132   @param fifo_size
1133     The fifo_size parameter provides the endpoint FIFO size in the USB core
1134     internal RAM. The valid FIFO size values are 8, 16, 32, 64, 128, 512, 1024,
1135     2048, 4096. The MSS USB assigns 8 byte FIFO by default if the FIFO size is
1136     not configured.
1137 
1138   @param max_pkt_size
1139     The max_pkt_size parameter provides the maximum packet size of the USB
1140     transfer. This value must be equal to the maximum packet size as mentioned
1141     in the endpoint descriptor which is used during enumeration process.
1142 
1143     Note: This value must be less than or equal to the FIFO size value.
1144 
1145   @param num_usb_pkt
1146     The num_usb_pkt parameter has different meanings for different types of
1147     transfers.
1148 
1149     Low bandwidth ISO/interrupt transfers - This parameter must always be '1u'.
1150     This parameter represents the number of packets transferred in one (micro)
1151     frame.
1152 
1153     High bandwidth ISO transfers - This parameter represents the number of
1154     packets transferred in one (Micro) frame. In this case, this parameter can
1155     have a value of 1 2 or 3. High bandwidth ISO transfers are not yet
1156     implemented.
1157 
1158     Bulk transfers. - For Bulk transfer this value must always be '1u'. This
1159     parameter will be used with the auto-amalgamation/auto-split feature where
1160     it indicates the number of bulk packets to be auto-amalgamated/auto-split
1161     in bulk transfer. The auto-amalgamation/auto-split feature is implemented
1162     but not yet tested.
1163 
1164   @param dma_enable
1165     The dma_enable parameter specifies whether or not the internal DMA must be
1166     used for the data transfer from the provided buffer to the USB FIFO.
1167 
1168   @param dma_channel
1169     The dma_channel parameter specifies the internal DMA channel to be used for
1170     the data transfers. The DMA channel will be associated with the specified
1171     endpoint. A unique DMA channel must be selected to transfer data on
1172     individual endpoints. This parameter is ignored when the dma_enable
1173     parameter indicates that the DMA must not be used.
1174 
1175   @param xfr_type
1176     The xfr_type parameter specifies the type of transfer to be performed on the
1177     specified endpoint. All other types of transfers (Interrupt, Isochronous,
1178     and Bulk) can be selected except control transfer.
1179 
1180   @param add_zlp
1181     The add_zlp parameter indicates whether to send a zero length packet (ZLP)
1182     if the transfer size is a exact multiple of wMaxPacketSize. This parameter
1183     is only applicable for Bulk transfers. For all other transfer types this
1184     parameter is ignored.
1185 
1186   @param interval
1187     The interval parameter for interrupt and isochronous transfers, defines the
1188     polling interval for the currently-selected OUT pipe. For the bulk
1189     transfers, this parameter indicates the number of frames/microframes after
1190     which the OUT Pipe must time out on receiving a stream of NAK responses.
1191     The valid values for this parameter are as mentioned in the table below.
1192 
1193     | Transfer Type    |  Speed    | Valid values                              |
1194     |------------------|-----------|-------------------------------------------|
1195     |  Interrupt       | LS or FS  | 1 – 255                                   |
1196     |  Interrupt       |    HS     | 1,2,4,8,16,32,64…32768 microframes        |
1197     |                  |           |                                           |
1198     |  Isochronous     | FS or HS  | 1,2,4,8,16,32,64…32768 frames/microframes |
1199     |                  |           |                                           |
1200     |  Bulk            |    HS     | 0,2,4,8,16,32,64…32768 microframes        |
1201     |                  |           | Note:Value 0 disables the NAK Timeout     |
1202     |                  |           | detection on Bulk endpoint                |
1203 
1204   @return
1205     This function returns zero when execution was successful.
1206 
1207   Example:
1208   @code
1209       case USBH_MSC_CONFIG_BULK_ENDPOINTS:
1210           MSS_USBH_configure_out_pipe(g_msd_tdev_addr,
1211                                       USBH_MSC_BULK_TX_PIPE,
1212                                       g_tdev_out_ep.num,
1213                                       USBH_MSC_BULK_TX_PIPE_FIFOADDR,
1214                                       USBH_MSC_BULK_TX_PIPE_FIFOSZ,
1215                                       g_tdev_out_ep.maxpktsz,
1216                                       1,
1217                                       DMA_DISABLE,
1218                                       MSS_USB_DMA_CHANNEL_NA,
1219                                       MSS_USB_XFR_BULK,
1220                                       NO_ZLP_TO_XFR,
1221                                       32768u);
1222 
1223           MSS_USBH_configure_in_pipe(g_msd_tdev_addr,
1224                                      USBH_MSC_BULK_RX_PIPE,
1225                                      g_tdev_in_ep.num,
1226                                      USBH_MSC_BULK_RX_PIPE_FIFOADDR,
1227                                      USBH_MSC_BULK_RX_PIPE_FIFOSZ,
1228                                      g_tdev_in_ep.maxpktsz,
1229                                      1,
1230                                      DMA_DISABLE,
1231                                      MSS_USB_DMA_CHANNEL_NA,
1232                                      MSS_USB_XFR_BULK,
1233                                      NO_ZLP_TO_XFR,
1234                                      32768u);
1235 
1236           g_msc_state = USBH_MSC_TEST_UNIT_READY_CPHASE;
1237       break;
1238   @endcode
1239 */
1240 int8_t
1241 MSS_USBH_configure_out_pipe
1242 (
1243     uint8_t target_addr,
1244     uint8_t outpipe_num,
1245     uint8_t target_ep,
1246     uint16_t fifo_addr,
1247     uint16_t fifo_size,
1248     uint16_t max_pkt_size,
1249     uint8_t num_usb_pkt,
1250     uint8_t dma_enable,
1251     mss_usb_dma_channel_t dma_channel,
1252     mss_usb_xfr_type_t xfr_type,
1253     uint32_t add_zlp,
1254     uint32_t interval
1255 );
1256 
1257 /*-------------------------------------------------------------------------*//**
1258   The MSS_USBH_write_out_pipe() function writes the data provided by the user
1259   into the previously configured out pipe FIFO. The data is ready to be
1260   transferred after calling this function. The Data will be transferred by the
1261   MSS USB according to the transfer type and interval parameter set for this
1262   OUT pipe using MSS_USBH_configure_out_pipe() function. This function is
1263   non-blocking.A call-back function will be called to indicate the status of
1264   this transfer after the status phase of the current OUT transaction is
1265   complete.
1266 
1267   @param target_addr
1268     The target_addr parameter is the address of the attached device with which
1269     the MSS USB needs to communicate.
1270 
1271   @param outpipe_num
1272     The outpipe_num parameter indicates the OUT pipe number (endpoint) on the
1273     MSS USB which must be used for the OUT transfers with the attached device.
1274 
1275   @param target_ep
1276     The target_ep parameter indicates the OUT endpoint number on the attached
1277     device with which MSS USB needs to communicate.
1278 
1279   @param max_pkt_size
1280     The max_pkt_size parameter provides the maximum packet size of the USB
1281     transfer. This value must be equal to the maximum packet size as mentioned
1282     in the endpoint descriptor which is used during enumeration process.
1283 
1284   @param buf
1285     The buf parameter is the address of the buffer provided by the user from
1286     which the data is copied to the selected pipe buffer.
1287 
1288   @param length
1289     The length parameter specifies the length of the data buffer in bytes.
1290 
1291   @return
1292     This function does not return a value.
1293 
1294   Example:
1295   @code
1296       case USBH_MSC_TEST_UNIT_READY_CPHASE:
1297           MSS_USBH_MSC_construct_cbw_cb6byte(USB_MSC_SCSI_TEST_UNIT_READY,
1298                                              0u,
1299                                              &g_bot_cbw);
1300 
1301           MSS_USBH_write_out_pipe(g_msd_tdev_addr,
1302                                   USBH_MSC_BULK_TX_PIPE,
1303                                   g_tdev_out_ep.num,
1304                                   g_tdev_out_ep.maxpktsz,
1305                                   (uint8_t*)&g_bot_cbw,
1306                                   31u);
1307 
1308           g_msc_state = USBH_MSC_TEST_UNIT_READY_SPHASE;
1309       break;
1310   @endcode
1311  */
1312 int8_t
1313 MSS_USBH_write_out_pipe
1314 (
1315     uint8_t target_addr,
1316     uint8_t outpipe_num,
1317     uint8_t tdev_ep_num,
1318     uint16_t maxpktsz,
1319     uint8_t* buf,
1320     uint32_t length
1321 );
1322 
1323 /*-------------------------------------------------------------------------*//**
1324   The MSS_USBH_read_in_pipe() function writes the data provided by the user into
1325   the previously configured out pipe FIFO. The data is ready to be transferred
1326   after calling this function. The data will be transferred by the MSS USB
1327   according to the transfer type and the interval parameter set for this OUT
1328   pipe using theMSS_USBH_configure_in_pipe() function.  This function is
1329   non-blocking. A call-back function will be called to indicate the status of
1330   this transfer after the status phase of the current IN transaction is
1331   complete.
1332 
1333   @param target_addr
1334     The target_addr parameter is the address of the attached device with which
1335     the MSS USB needs to communicate.
1336 
1337   @param outpipe_num
1338     The outpipe_num parameter indicates the OUT pipe number (endpoint) on MSS
1339     USB which must be used for the OUT transfers with the attached device.
1340 
1341   @param target_ep
1342     The target_ep parameter indicates the OUT endpoint number on the attached
1343     device with which the MSS USB needs to communicate.
1344 
1345   @param max_pkt_size
1346     The max_pkt_size parameter provides the maximum packet size of the USB
1347     transfer. This value must be equal to the maximum packet size as mentioned
1348     in the endpoint descriptor which is used during enumeration process.
1349 
1350   @param buf
1351     The buf parameter is the address of the buffer provided by the user from
1352     which the data is copied to the selected pipe buffer.
1353 
1354   @param length
1355     The length parameter specifies the length of the data buffer in bytes.
1356 
1357   @return
1358     This function does not return a value.
1359 
1360   Example:
1361   @code
1362       case USBH_MSC_TEST_UNIT_READY_SPHASE:
1363               if(g_usbh_msc_tx_event)
1364               {
1365                   g_usbh_msc_tx_event = 0;
1366                   g_msc_state = USBH_MSC_TEST_UNIT_READY_WAITCOMPLETE;
1367                   MSS_USBH_read_in_pipe(g_msd_tdev_addr,
1368                                         USBH_MSC_BULK_RX_PIPE,
1369                                         g_tdev_in_ep.num,
1370                                         g_tdev_in_ep.maxpktsz,
1371                                         (uint8_t*)&g_bot_csw,
1372                                         13u);
1373               }
1374           break;
1375   @endcode
1376  */
1377 int8_t
1378 MSS_USBH_read_in_pipe
1379 (
1380     uint8_t target_addr,
1381     uint8_t inpipe_num,
1382     uint8_t tdev_ep_num,
1383     uint16_t tdev_ep_maxpktsz,
1384     uint8_t* buf,
1385     uint32_t length
1386 );
1387 
1388 /*-------------------------------------------------------------------------*//**
1389   The MSS_USBH_get_tdev_state() function can be used to find out the current
1390   state of the attached device. E.g. ADDRESS, CONFIGURED etc. (as defined by
1391   USB2.0).
1392 
1393   @param target_addr
1394     The target_addr parameter is the address of the attached device with which
1395     the MSS USB needs to communicate.
1396 
1397   @return
1398     This function returns a value of type mss_usb_state_t indicating the current
1399     state of the attached device.
1400 
1401   Example:
1402   @code
1403       static mss_usb_state_t msd_tdev_state = MSS_USB_NOT_ATTACHED_STATE;
1404       msd_tdev_state = MSS_USBH_get_tdev_state(g_msd_tdev_addr);
1405   @endcode
1406 
1407  */
1408 mss_usb_state_t
1409 MSS_USBH_get_tdev_state
1410 (
1411     uint8_t target_addr
1412 );
1413 
1414 /*-------------------------------------------------------------------------*//**
1415   The MSS_USBH_suspend() function can be used to suspend the MSS USB. The MSS
1416   USB will complete the current transaction then stop the transaction scheduler
1417   and frame counter. No further transactions will be started and no SOF packets
1418   will be generated.
1419 
1420   @param
1421     This function does not take any parameters.
1422 
1423   @return
1424     This function does not return any value.
1425 
1426   Example:
1427   @code
1428   @endcode
1429 */
1430 void
1431 MSS_USBH_suspend
1432 (
1433     void
1434 );
1435 
1436 /*-------------------------------------------------------------------------*//**
1437   The MSS_USBH_resume() function can be used to resume the previously suspended
1438   MSS USB. If the MSS USB was in suspend mode then it will start the transaction
1439   scheduler and frame counter after calling this function.
1440 
1441   @param
1442     This function does not take any parameters.
1443 
1444   @return
1445     This function does not return any value.
1446 
1447   Example:
1448   @code
1449   @endcode
1450 */
1451 void
1452 MSS_USBH_resume
1453 (
1454     void
1455 );
1456 
1457 /*-------------------------------------------------------------------------*//**
1458   The MSS_USBH_1ms_tick() function must be used to provide the 1ms time tick to
1459   the USBH driver. This time reference is used by the USBH driver to keep track
1460   of different time delays required during enumeration process. This way the
1461   application need not wait for the enumeration to complete which may take long
1462   time.
1463 
1464   @param
1465     This function does not take any parameters.
1466 
1467   @return
1468     This function does not return any value.
1469 
1470   Example:
1471   @code
1472       void SysTick_Handler(void)
1473       {
1474           MSS_USBH_task();
1475           MSS_USBH_HID_task();
1476           MSS_USBH_1ms_tick();
1477       }
1478   @endcode
1479 */
1480 void
1481 MSS_USBH_1ms_tick
1482 (
1483     void
1484 );
1485 
1486 /*-------------------------------------------------------------------------*//**
1487   The MSS_USBH_get_milis() function is used to find out the number of
1488   milliseconds elapsed from the time when last reset occurred.
1489 
1490   @param
1491     This function does not take any parameters.
1492 
1493   @return
1494     This function returns a 32-bit unsigned integer value. This value indicates
1495     the number of milliseconds elapsed from the time when the last reset
1496     occurred. This integer value will overflow after approximately 49Hrs after
1497     reset.
1498 
1499   Example:
1500   @code
1501       case USBH_MSC_WAIT_SET_CONFIG:
1502           if(g_usbh_msc_cep_event)
1503           {
1504               g_usbh_msc_cep_event = 0;
1505               wait_mili = MSS_USBH_get_milis();
1506               g_msc_state = USBH_MSC_WAIT_DEV_SETTLE;
1507           }
1508       break;
1509 
1510       case USBH_MSC_WAIT_DEV_SETTLE:
1511           if((MSS_USBH_get_milis() - wait_mili) > 60)
1512           {
1513               g_msc_state = USBH_MSC_GET_MAX_LUN;
1514           }
1515       break;
1516   @endcode
1517 */
1518 uint32_t
1519 MSS_USBH_get_milis
1520 (
1521     void
1522 );
1523 
1524 /*-------------------------------------------------------------------------*//**
1525   The MSS_USBH_construct_get_descr_command() function is be used to construct
1526   the setup packet which is to be sent on the USB bus. This function formats the
1527   provided parameters into a USB standard format GET_DESCRIPTOR request and
1528   stores it in the location provided by the buf parameter.
1529 
1530   @param buf
1531     The buf parameter is the address of the buffer where the formatted
1532     GET_DESCRIPTOR request is stored.
1533 
1534   @param xfr_dir
1535     The xfr_dir parameter indicates the direction of the data transfer on the
1536     USB bus. The value USB_STD_REQ_DATA_DIR_IN indicates that the direction of
1537     the data transfer is from the USB device to USB host (USB IN transaction).
1538     The value USB_STD_REQ_DATA_DIR_OUT indicates that the direction of the data
1539     transfer is from the USB host to the USB device (USB OUT transaction).
1540 
1541   @param req_type
1542     The req_type parameter indicates the request type. The request type can be
1543     one of the following: standard request, class request or vendor request.
1544 
1545   @param recip_type
1546     The recip_type parameter indicates the recipient type on the USB device. The
1547     request recipient on the attached device can be one of the following:
1548     device, endpoint or interface.
1549 
1550   @param request
1551     The request parameter indicates the request that needs to be sent to the
1552     attached device.
1553 
1554   @param desc_type
1555     The desc_type parameter indicates the descriptor type that needs to be
1556     requested from the attached device.
1557 
1558   @param strng_idx
1559     The strng_idx parameter indicates the index of the string descriptor when
1560     the desc_type parameter indicates STRING TYPE.
1561 
1562   @param length
1563     The length parameter indicates the number of bytes to be received from
1564     attached device as part of the requested descriptor.
1565 
1566   @return
1567     This function does not return any value.
1568 
1569   Example:
1570   @code
1571       MSS_USBH_configure_control_pipe(g_msd_tdev_addr);
1572       memset(std_req_buf, 0u, 8*(sizeof(uint8_t)));
1573       MSS_USBH_construct_get_descr_command(std_req_buf,
1574                                            USB_STD_REQ_DATA_DIR_IN,
1575                                            USB_STANDARD_REQUEST,
1576                                            USB_STD_REQ_RECIPIENT_DEVICE,
1577                                            USB_STD_REQ_GET_DESCRIPTOR,
1578                                            USB_CONFIGURATION_DESCRIPTOR_TYPE,
1579                                            0,
1580                                            32u);
1581 
1582       g_msc_state = USBH_MSC_WAIT_GET_CLASS_DESCR;
1583       MSS_USBH_start_control_xfr(std_req_buf,
1584                                  (uint8_t*)&g_msd_conf_desc,
1585                                  USB_STD_REQ_DATA_DIR_IN,
1586                                  32u);
1587   @endcode
1588  */
1589 void
1590 MSS_USBH_construct_get_descr_command
1591 (
1592     uint8_t* buf,
1593     uint8_t xfr_dir,
1594     uint8_t req_type,
1595     uint8_t recip_type,
1596     uint8_t request,
1597     uint8_t desc_type,
1598     uint8_t strng_idx,
1599     uint16_t length
1600 );
1601 
1602 /*-------------------------------------------------------------------------*//**
1603   The MSS_USBH_start_control_xfr() function must be used to start a control
1604   transfer with the attached USB device. This is a non-blocking function.
1605   This function prepares the control pipe for the control transfer. A call-back
1606   function will be called to indicate the status of the transfer after the
1607   status phase of the control transfer is complete.
1608 
1609   @param cbuf_addr
1610     The cbuf_addf parameter is the address of the buffer where the USB request
1611     setup packet is available.
1612 
1613   @param dbuf_addr
1614     The dbuf_addf parameter is the address of the buffer for the data phase of
1615     the control transfer. The USBD driver will put the data received from
1616     attached device in this buffer for the USB IN transfers. The data from this
1617     buffer will be sent to the attached device for the USB OUT transfers.
1618 
1619   @param data_dir
1620     The data_dir parameter indicates the direction of the data flow in the data
1621     phase of the control transfer. The value USB_STD_REQ_DATA_DIR_IN indicates
1622     that the direction of the data transfer is from the USB device to the USB
1623     host (USB IN transaction). The value USB_STD_REQ_DATA_DIR_OUT indicates
1624     that the direction of the data transfer is from the USB host to the USB
1625     device (USB OUT transaction).
1626 
1627   @param data_len
1628     The data_len parameter indicates the number of bytes to be transferred
1629     during the data phase of the control transfer.
1630 
1631   @return
1632     This function returns zero when execution was successful.
1633 
1634   Example:
1635   @code
1636       MSS_USBH_configure_control_pipe(g_msd_tdev_addr);
1637       memset(std_req_buf, 0u, 8*(sizeof(uint8_t)));
1638       MSS_USBH_construct_get_descr_command(std_req_buf,
1639                                            USB_STD_REQ_DATA_DIR_IN,
1640                                            USB_STANDARD_REQUEST,
1641                                            USB_STD_REQ_RECIPIENT_DEVICE,
1642                                            USB_STD_REQ_GET_DESCRIPTOR,
1643                                            USB_CONFIGURATION_DESCRIPTOR_TYPE,
1644                                            0,
1645                                            32u);
1646 
1647       g_msc_state = USBH_MSC_WAIT_GET_CLASS_DESCR;
1648       MSS_USBH_start_control_xfr(std_req_buf,
1649                                  (uint8_t*)&g_msd_conf_desc,
1650                                  USB_STD_REQ_DATA_DIR_IN,
1651                                  32u);
1652 @endcode
1653  */
1654 uint8_t
1655 MSS_USBH_start_control_xfr
1656 (
1657     uint8_t* cbuf_addr,
1658     uint8_t* dbuf_addr,
1659     uint8_t  data_dir,
1660     uint32_t data_len
1661 );
1662 
1663 /*-------------------------------------------------------------------------*//**
1664   The MSS_USBH_get_cep_state() function can be used to find out the current
1665   state of the control pipe. A new control transfer can be started when the
1666   control pipe is in the MSS_USB_CEP_IDLE state.
1667 
1668   @param
1669     This function does not take any parameters.
1670 
1671   @return
1672     This function returns a value of type mss_usb_ep_state_t indicating the
1673     current state of the control pipe.
1674 
1675   Example:
1676   @code
1677       mss_usb_ep_state_t cep_st;
1678       cep_st = MSS_USBH_get_cep_state();
1679       if(MSS_USB_CEP_IDLE == cep_st)
1680       {
1681           MSS_USBH_configure_control_pipe(g_msd_tdev_addr);
1682           memset(std_req_buf, 0u, 8*(sizeof(uint8_t)));
1683           MSS_USBH_construct_get_descr_command(std_req_buf,
1684                                               USB_STD_REQ_DATA_DIR_IN,
1685                                               USB_STANDARD_REQUEST,
1686                                               USB_STD_REQ_RECIPIENT_DEVICE,
1687                                               USB_STD_REQ_GET_DESCRIPTOR,
1688                                               USB_CONFIGURATION_DESCRIPTOR_TYPE,
1689                                               0,
1690                                               32u);
1691 
1692           g_msc_state = USBH_MSC_WAIT_GET_CLASS_DESCR;
1693           MSS_USBH_start_control_xfr(std_req_buf,
1694                                      (uint8_t*)&g_msd_conf_desc,
1695                                      USB_STD_REQ_DATA_DIR_IN,
1696                                      32u);
1697       }
1698   @endcode
1699 */
1700 mss_usb_ep_state_t
1701 MSS_USBH_get_cep_state
1702 (
1703     void
1704 );
1705 
1706 /*-------------------------------------------------------------------------*//**
1707   The MSS_USBH_test_mode() function can be used to initiate one of the
1708   compliance test modes in the MSS USB. This function is useful only for
1709   compliance test procedures. The MSS USB goes into the specified test mode once
1710   this function is executed. A hard reset is required to resume normal
1711   operations.
1712 
1713   @param test_case
1714     The test_case parameter indicates the compliance test that need to be
1715     executed.The compliance tests could be one of the following:
1716         Test-J (USB_TEST_MODE_SELECTOR_TEST_J),
1717         Test-K (USB_TEST_MODE_SELECTOR_TEST_K),
1718         SE0-NAK (USB_TEST_MODE_SELECTOR_TEST_SE0NAK),
1719         Test-Packet (USB_TEST_MODE_SELECTOR_TEST_PACKET)
1720 
1721   @return
1722     This function does not return any value.
1723 
1724   Example:
1725   @code
1726       case '1':
1727           MSS_USBH_test_mode(USB_TEST_MODE_SELECTOR_TEST_PACKET);
1728           MSS_UART_polled_tx_string(&g_mss_uart1,
1729                                     (uint8_t *)"\n\n\r Test-Packet started...");
1730       break;
1731 
1732       case '2':
1733           MSS_USBH_test_mode(USB_TEST_MODE_SELECTOR_TEST_J);
1734           MSS_UART_polled_tx_string(&g_mss_uart1,
1735                                          (uint8_t *)"\n\n\r Test-J started...");
1736       break;
1737 
1738       case '3':
1739           MSS_USBH_test_mode(USB_TEST_MODE_SELECTOR_TEST_K);
1740           MSS_UART_polled_tx_string(&g_mss_uart1,
1741                                          (uint8_t *)"\n\n\r Test-K started...");
1742       break;
1743 
1744       case '4':
1745           MSS_USBH_test_mode(USB_TEST_MODE_SELECTOR_TEST_SE0NAK);
1746           MSS_UART_polled_tx_string(&g_mss_uart1,
1747                                    (uint8_t *)"\n\n\r Test-SE0-NAK started...");
1748       break;
1749 
1750       case '5':
1751           MSS_USBH_test_mode(USB_TEST_MODE_SELECTOR_TEST_FORCE_ENA);
1752           MSS_UART_polled_tx_string(&g_mss_uart1,
1753                                 (uint8_t *)"\n\n\r Test-Force-Host started...");
1754       break;
1755 
1756       default:
1757           invalid_selection_menu();
1758       break;
1759   @endcode
1760  */
1761 void
1762 MSS_USBH_test_mode
1763 (
1764     uint8_t test_case
1765 );
1766 
1767 /*-------------------------------------------------------------------------*//**
1768   The MSS_USBH_get_std_dev_descr() function can be used to get the 8 byte USB
1769   standard device descriptor from the attached device. This function is provided
1770   specifically for the �Standard Descriptor� test case of USB-IF compliance
1771   procedure. This function might not be useful In general scenarios.
1772 
1773   @param buffer
1774     The buffer parameter is the pointer to the buffer where the USB standard
1775     device descriptor received from the attached device will be stored.
1776 
1777   @return
1778     This function returns zero on successful execution.
1779 
1780   Example:
1781   @code
1782       mss_usb_ep_state_t cep_st;
1783       cep_st = MSS_USBH_get_cep_state();
1784       if(MSS_USB_CEP_IDLE == cep_st)
1785       {
1786           MSS_USBH_configure_control_pipe(g_msd_tdev_addr);
1787           memset(std_req_buf, 0u, 8*(sizeof(uint8_t)));
1788           MSS_USBH_construct_get_descr_command(std_req_buf,
1789                                               USB_STD_REQ_DATA_DIR_IN,
1790                                               USB_STANDARD_REQUEST,
1791                                               USB_STD_REQ_RECIPIENT_DEVICE,
1792                                               USB_STD_REQ_GET_DESCRIPTOR,
1793                                               USB_CONFIGURATION_DESCRIPTOR_TYPE,
1794                                               0,
1795                                               32u);
1796 
1797           g_msc_state = USBH_MSC_WAIT_GET_CLASS_DESCR;
1798           MSS_USBH_start_control_xfr(std_req_buf,
1799                                      (uint8_t*)&g_msd_conf_desc,
1800                                      USB_STD_REQ_DATA_DIR_IN,
1801                                      32u);
1802       }
1803   @endcode
1804  */
1805 int8_t
1806 MSS_USBH_get_std_dev_descr
1807 (
1808     uint8_t* buffer
1809 );
1810 
1811 void
1812 MSS_USBH_abort_in_pipe
1813 (
1814     mss_usb_ep_num_t inpipe_num
1815 );
1816 
1817 void
1818 MSS_USBH_abort_out_pipe
1819 (
1820     mss_usb_ep_num_t outpipe_num
1821 );
1822 
1823 #endif /* MSS_USB_HOST_ENABLED */
1824 
1825 #ifdef __cplusplus
1826 }
1827 #endif
1828 
1829 #endif  /* __MSS_USB_HOST_H_ */
1830