/**
 * @file xmc_usbd.h
 * @date 2015-06-20
 *
 *********************************************************************************************************************
 * XMClib v2.1.24 - XMC Peripheral Driver Library 
 *
 * Copyright (c) 2015-2019, Infineon Technologies AG
 * All rights reserved.                        
 *                                             
 * Redistribution and use in source and binary forms, with or without modification,are permitted provided that the 
 * following conditions are met:   
 *                                                                              
 * Redistributions of source code must retain the above copyright notice, this list of conditions and the following 
 * disclaimer.                        
 * 
 * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following 
 * disclaimer in the documentation and/or other materials provided with the distribution.                       
 * 
 * Neither the name of the copyright holders nor the names of its contributors may be used to endorse or promote 
 * products derived from this software without specific prior written permission.                                           
 *                                                                              
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, 
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE  
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE  FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR  
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
 * WHETHER IN CONTRACT, STRICT LIABILITY,OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                                                  
 *                                                                              
 * To improve the quality of the software, users are encouraged to share modifications, enhancements or bug fixes with 
 * Infineon Technologies AG dave@infineon.com).                                                          
 *********************************************************************************************************************
 *
 * Change History
 * --------------
 *
 * 2015-02-16:
 *     - Initial Version.<br>           
 * 2015-03-18:
 *     - Updated the doxygen comments for documentation. <br>
 *     - Updated the XMC_USBD_PATCH_VERSION to 4. <br>
 *
 * 2015-06-20:
 *     - Removed version macros and declaration of GetDriverVersion API.<br>
 *     - Updated the doxygen comments for API XMC_USBD_IsEnumDone().<br>
 *     - Updated the copy right in the file header.<br>
 *
 * @endcond 
 *
 */

#ifndef XMC_USBD_H
#define XMC_USBD_H

/**********************************************************************************************************************
 * HEADER FILES
 *********************************************************************************************************************/
#include "xmc_common.h"

#if defined(USB0)

#include <stdlib.h>
#include <string.h>
#include "xmc_usbd_regs.h"
#include "xmc_scu.h"

/**
 * @addtogroup XMClib XMC Peripheral Library
 * @{
 */

/**
 * @addtogroup USBD
 * @brief Universal Serial Bus Device (USBD) driver for the XMC4000 microcontroller family.
 *
 * The USBD is the device driver for the USB0 hardware module on XMC4000 family of microcontrollers.
 * The USB0 module can be used to establish a USB interface between outside world and XMC4000 family of controllers.
 * The USB module includes the following features in device mode:
 * -# Complies with the USB 2.0 Specification.
 * -# Support for the Full-Speed (12-Mbps) mode.
 * -# Supports up to 7 bidirectional endpoints, including control endpoint 0.
 * -# Supports SOFs in Full-Speed modes.
 * -# Supports clock gating for power saving.
 * -# Supports USB suspend/resume.
 * -# Supports USB soft disconnect.
 * -# Supports DMA mode.
 * -# Supports FIFO mode.
 * 
 * The below figure shows the overview of USB0 module in XMC4 microntroller.
 * @image html USB_module_overview.png
 * @image latex ../images/USB_module_overview.png 
 *
 * The below figure shows the USB device connection of USB0 module.
 * @image html USB_device_connection.png
 * @image latex ../images/USB_device_connection.png
 *
 * The USBD device driver supports the following features:\n
 * -# Initialize/Uninitialize the USB0 module on XMC4000 device.
 * -# Connect the USB device to host.
 * -# Get USB device state.
 * -# Set the USB device address.
 * -# Configure/Unconfigure the USB endpoints.
 * -# Stall/Abort the USB endpoints.
 * -# USB IN transfers on EP0 and non EP0 endpoints.
 * -# USB OUT transfers on EP0 and non EP0 endpoints.
 * 
 * The USBD device driver provides the configuration structure ::XMC_USBD_t which user need to configure before initializing the USB.\n
 * The following elements of configuration structure need to be initialized before calling the ::XMC_USBD_Init API:
 * -# cb_xmc_device_event of type ::XMC_USBD_SignalDeviceEvent_t.
 * -# cb_endpoint_event of type ::XMC_USBD_SignalEndpointEvent_t.
 * -# usbd_max_num_eps of type ::XMC_USBD_MAX_NUM_EPS_t.
 * -# usbd_transfer_mode of type ::XMC_USBD_TRANSFER_MODE_t.
 *
 * @{
 */

/**********************************************************************************************************************
 * MACROS
 *********************************************************************************************************************/
 
#define XMC_USBD_NUM_TX_FIFOS                          (7U) 	/**< Number of hardware transmission endpoint fifos */

#define XMC_USBD_MAX_FIFO_SIZE                         (2048U)  /**< Maximum USBD endpoint fifo size */

#define XMC_USBD_NUM_EPS                               (7U)		/**< Number of hardware endpoints */

#define	XMC_USBD_MAX_PACKET_SIZE                       (64U)	/**< Maximum packet size for all endpoints 
	                                                                (including ep0) */

/**< Maximum transfer size for endpoints.
 *
 * It's based on the maximum payload, due to the fact,
 * that we only can transfer 2^10 - 1 packets and this is less than the
 * transfer size field can hold.
 */
#define XMC_USBD_MAX_TRANSFER_SIZE                     (((uint32_t)((uint32_t)1U << (uint32_t)10U) - 1U) * (uint32_t)XMC_USBD_MAX_PACKET_SIZE)

#define XMC_USBD_MAX_TRANSFER_SIZE_EP0                 (64U)	/**< Maximum transfer size for endpoint 0*/

#define XMC_USBD_SETUP_COUNT                           (3U)		/**< The number of USB setup packets */

#define XMC_USBD_SETUP_SIZE                            (8U)		/**< The size of USB setup data */

#define XMC_USBD_EP_NUM_MASK                           (0x0FU)	/**< USB Endpoint number mask. */

#define XMC_USBD_EP_DIR_MASK                           (0x80U)	/**< USB Endpoint direction mask */

#define XMC_USBD_DCFG_DEVSPD_FS	                       (0x3U)	/*USB Full Speed device flag in DCFG register */

#define XMC_USBD_TX_FIFO_REG_OFFSET                    (0x1000U)/* First endpoint fifo register offset from base address */

#define XMC_USBD_TX_FIFO_OFFSET		                   (0x1000U)/* Offset for each fifo register */

#define XMC_USBD_ENDPOINT_NUMBER_MASK                  (0x0FU)	/**< USB Endpoint number mask to get the EP number from address. */

#define XMC_USBD_ENDPOINT_DIRECTION_MASK               (0x80U)	/**< USB Endpoint direction mask to get the EP direction from address. */

#define XMC_USBD_ENDPOINT_MAX_PACKET_SIZE_MASK         (0x07FFU)/**< USB Endpoint Maximum Packet Size mask */

#define XMC_USBD_ENDPOINT_MFRAME_TR_MASK 			         (0x1800U)/* USB Endpoint micro frame TR mask */
#define XMC_USBD_ENDPOINT_MFRAME_TR_1                  (0x0000U)/* Selects USB Endpoint micro frame TR1 */
#define XMC_USBD_ENDPOINT_MFRAME_TR_2                  (0x0800U)/* Selects USB Endpoint micro frame TR2 */
#define XMC_USBD_ENDPOINT_MFRAME_TR_3                  (0x1000U)/* Selects USB Endpoint micro frame TR3 */


#define XMC_USBD_SPEED_FULL                            (1U)		/**< Speed Mode. Full Speed */

#define XMC_USBD_EP0_BUFFER_SIZE                       (64U)	/* Endpoint 0 buffer size */

#define XMC_USBD_EP1_BUFFER_SIZE                       (64U)	/* Endpoint 1 buffer size */

#define XMC_USBD_EP2_BUFFER_SIZE                       (64U)	/* Endpoint 2 buffer size */

#define XMC_USBD_EP3_BUFFER_SIZE                       (64U)	/* Endpoint 3 buffer size */

#define XMC_USBD_EP4_BUFFER_SIZE                       (64U)	/* Endpoint 4 buffer size */

#define XMC_USBD_EP5_BUFFER_SIZE                       (64U)	/* Endpoint 5 buffer size */

#define XMC_USBD_EP6_BUFFER_SIZE                       (64U)	/* Endpoint 6 buffer size */


/**********************************************************************************************************************
 * ENUMS
 *********************************************************************************************************************/

/**
 * Defines the options for the global receive fifo packet status.
 * Use type ::XMC_USBD_GRXSTS_PKTSTS_t for this enum.
 * */
typedef enum XMC_USBD_GRXSTS_PKTSTS {
  XMC_USBD_GRXSTS_PKTSTS_GOUTNAK   = 0x1U,      				/**< Global out nack send ( triggers an interrupt ) */
  XMC_USBD_GRXSTS_PKTSTS_OUTDATA   = 0x2U,      				/**< OUT data packet received */
  XMC_USBD_GRXSTS_PKTSTS_OUTCMPL   = 0x3U,      				/**< OUT transfer completed (triggers an interrupt) */
  XMC_USBD_GRXSTS_PKTSTS_SETUPCMPL = 0x4U,      				/**< SETUP transaction completed (triggers an interrupt) */
  XMC_USBD_GRXSTS_PKTSTS_SETUP     = 0x6U       				/**< SETUP data packet received */
} XMC_USBD_GRXSTS_PKTSTS_t;

/**
*  Defines the options for the USB endpoint type. The values are from the USB 2.0 specification.
*  Use type ::XMC_USBD_ENDPOINT_TYPE_t for this enum.
*/
typedef enum XMC_USBD_ENDPOINT_TYPE {
  XMC_USBD_ENDPOINT_TYPE_CONTROL        = 0x0U,      			/**< Control endpoint */
  XMC_USBD_ENDPOINT_TYPE_ISOCHRONOUS    = 0x01U,     			/**< Isochronous endpoint */
  XMC_USBD_ENDPOINT_TYPE_BULK           = 0x02U,     			/**< Bulk endpoint */
  XMC_USBD_ENDPOINT_TYPE_INTERRUPT      = 0x03U      			/**< Interrupt endpoint */
} XMC_USBD_ENDPOINT_TYPE_t;


/**
*  Defines the options for USB device state while setting the address.
*  Use type ::XMC_USBD_SET_ADDRESS_STAGE_t for this enum.
*/
typedef enum XMC_USBD_SET_ADDRESS_STAGE {
  XMC_USBD_SET_ADDRESS_STAGE_SETUP,             				/**< Setup address */
  XMC_USBD_SET_ADDRESS_STAGE_STATUS             				/**< Status address */
} XMC_USBD_SET_ADDRESS_STAGE_t;


/**
* Defines the USB Device Status of executed operation.
* Use type ::XMC_USBD_STATUS_t for this enum.
*/
typedef enum XMC_USBD_STATUS {
  XMC_USBD_STATUS_OK       = 0U,         						/**< USBD Status: Operation succeeded*/
  XMC_USBD_STATUS_BUSY     = 2U,         						/**< Driver is busy and cannot handle request */
  XMC_USBD_STATUS_ERROR    = 1U          						/**< USBD Status: Unspecified error*/
} XMC_USBD_STATUS_t;


/**
* Defines the USB Device events.
* Use type ::XMC_USBD_EVENT_t for this enum.
*/
typedef enum XMC_USBD_EVENT {
  XMC_USBD_EVENT_POWER_ON,              						/**< USB Device Power On */
  XMC_USBD_EVENT_POWER_OFF,             						/**< USB Device Power Off */
  XMC_USBD_EVENT_CONNECT,               						/**< USB Device connected */
  XMC_USBD_EVENT_DISCONNECT,            						/**< USB Device disconnected */
  XMC_USBD_EVENT_RESET,                 						/**< USB Reset occurred */
  XMC_USBD_EVENT_HIGH_SPEED,            						/**< USB switch to High Speed occurred */
  XMC_USBD_EVENT_SUSPEND,               						/**< USB Suspend occurred */
  XMC_USBD_EVENT_RESUME,                						/**< USB Resume occurred */
  XMC_USBD_EVENT_REMOTE_WAKEUP,       							/**< USB Remote wakeup */
  XMC_USBD_EVENT_SOF, 											/**< USB Start of frame event */
  XMC_USBD_EVENT_EARLYSUSPEND,          						/**< USB Early suspend */
  XMC_USBD_EVENT_ENUMDONE,              						/**< USB enumeration done */
  XMC_USBD_EVENT_ENUMNOTDONE,           						/**< USB enumeration not done */
  XMC_USBD_EVENT_OUTEP,                 						/**< USB OUT endpoint */
  XMC_USBD_EVENT_INEP                   						/**< USB IN endpoint */
} XMC_USBD_EVENT_t;

/**
* Defines the USB IN endpoint events.
* Use type ::XMC_USBD_EVENT_IN_EP_t for this enum.
*/
typedef enum XMC_USBD_EVENT_IN_EP {
  XMC_USBD_EVENT_IN_EP_TX_COMPLET = 1U,      					/**< USB IN ep transmission complete */
  XMC_USBD_EVENT_IN_EP_DISABLED = 2U,        					/**< USB IN ep disabled */
  XMC_USBD_EVENT_IN_EP_AHB_ERROR = 4U,       					/**< USB IN ep AHB error */
  XMC_USBD_EVENT_IN_EP_TIMEOUT = 8U,         					/**< USB IN ep timeout */
} XMC_USBD_EVENT_IN_EP_t;

/**
* Defines the USB OUT endpoint events.
* Use type ::XMC_USBD_EVENT_OUT_EP_t for this enum.
*/
typedef enum XMC_USBD_EVENT_OUT_EP {
  XMC_USBD_EVENT_OUT_EP_TX_COMPLET = 1U,      					/**< USB OUT ep transmission complete */
  XMC_USBD_EVENT_OUT_EP_DISABLED = 2U,        					/**< USB OUT ep disabled */
  XMC_USBD_EVENT_OUT_EP_AHB_ERROR = 4U,       					/**< USB OUT ep AHB error */
  XMC_USBD_EVENT_OUT_EP_SETUP = 8U,           					/**< USB OUT ep setup */
} XMC_USBD_EVENT_OUT_EP_t;


/**
* Defines the generic USB endpoint events.
* Use type ::XMC_USBD_EP_EVENT_t for this enum.
*/
typedef enum XMC_USBD_EP_EVENT {
  XMC_USBD_EP_EVENT_SETUP,              						/**< SETUP packet*/
  XMC_USBD_EP_EVENT_OUT,                						/**< OUT packet*/
  XMC_USBD_EP_EVENT_IN                  						/**< IN packet*/
} XMC_USBD_EP_EVENT_t;

/**
* Defines the options for the USB data transfer modes.
* Use type ::XMC_USBD_TRANSFER_MODE_t for this enum.
*/
typedef enum XMC_USBD_TRANSFER_MODE {
  XMC_USBD_USE_DMA,  											/**< Transfer by DMA*/
  XMC_USBD_USE_FIFO  											/**< Transfer by FIFO*/
} XMC_USBD_TRANSFER_MODE_t;

/**
* Defines the options for the maximum number of endpoints used.
* Use type ::XMC_USBD_MAX_NUM_EPS_t for this enum.
*/
typedef enum XMC_USBD_MAX_NUM_EPS {
  XMC_USBD_MAX_NUM_EPS_1      = 1U,								/**< Maximum 1 endpoint used*/
  XMC_USBD_MAX_NUM_EPS_2      = 2U,								/**< Maximum 2 endpoints used*/
  XMC_USBD_MAX_NUM_EPS_3      = 3U,								/**< Maximum 3 endpoints used*/
  XMC_USBD_MAX_NUM_EPS_4      = 4U,								/**< Maximum 4 endpoints used*/
  XMC_USBD_MAX_NUM_EPS_5      = 5U,								/**< Maximum 5 endpoints used*/
  XMC_USBD_MAX_NUM_EPS_6      = 6U,								/**< Maximum 6 endpoints used*/
  XMC_USBD_MAX_NUM_EPS_7      = 7U								/**< Maximum 2 endpoints used*/
} XMC_USBD_MAX_NUM_EPS_t;

/**
* USB device/endpoint event function pointers
*/
typedef void (*XMC_USBD_SignalDeviceEvent_t)   (XMC_USBD_EVENT_t event);/**< Pointer to USB device event call back.
 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 Uses type ::XMC_USBD_EVENT_t as the argument of callback.*/
typedef void (*XMC_USBD_SignalEndpointEvent_t) (uint8_t ep_addr, XMC_USBD_EP_EVENT_t ep_event);/**< Pointer to USB endpoint event call back.
																								Uses type ::XMC_USBD_EP_EVENT_t and EP address as the argument of callback.*/

/**********************************************************************************************************************
 * DATA STRUCTURES
 *********************************************************************************************************************/

/**
 * Describes the USB Device Driver Capabilities.
 */
typedef struct XMC_USBD_CAPABILITIES {
  uint32_t event_power_on      :  1;    						/**< Signal Power On event*/
  uint32_t event_power_off     :  1;    						/**< Signal Power Off event*/
  uint32_t event_connect       :  1;    						/**< Signal Connect event*/
  uint32_t event_disconnect    :  1;    						/**< Signal Disconnect event*/
  uint32_t event_reset         :  1;    						/**< Signal Reset event*/
  uint32_t event_high_speed    :  1;    						/**< Signal switch to High-speed event*/
  uint32_t event_suspend       :  1;    						/**< Signal Suspend event*/
  uint32_t event_resume        :  1;    						/**< Signal Resume event*/
  uint32_t event_remote_wakeup :  1;    						/**< Signal Remote Wake up event*/
  uint32_t reserved            : 23;    						/**< Reserved for future use*/
} XMC_USBD_CAPABILITIES_t;

/**
 * Describes the current USB Device State.
 */
typedef struct XMC_USBD_STATE {
  uint32_t powered     : 1;        								/**< USB Device powered flag*/
  uint32_t connected   : 1;        								/**< USB Device connected flag*/
  uint32_t active      : 1;        								/**< USB Device active lag*/
  uint32_t speed       : 2;        								/**< USB Device speed */
} XMC_USBD_STATE_t;

/**
 * Describes a USB endpoint<BR>
 *
 * All information to control an endpoint is stored in this structure.
 * It contains information about the endpoints and the status of the device.
 */
typedef struct {
  union {
    uint32_t address            : 8;     						/**< The endpoint address including the direction */
      struct {
        uint32_t number         : 4;     						/**< The endpoint number.It can be from 0 to 6 */
        uint32_t pading         : 3;     						/**< Padding between number and direction */
        uint32_t direction      : 1;     						/**< The endpoint direction */
	  } address_st;
    } address_u;
  uint32_t type                 : 2;     						/**< The endpoint type */
  uint32_t isConfigured         : 1;     						/**< The flag showing, if the endpoint is configured */
  volatile uint32_t inInUse     : 1;     						/**< Sets if the selected USB IN endpoint is currently in use */
  volatile uint32_t outInUse    : 1;     						/**< Sets if the selected USB OUT endpoint is currently in use */
  uint32_t isStalled            : 1;     						/**< Sets if the selected USB endpoint is stalled. */
  uint32_t txFifoNum            : 4;     						/**< Endpoint transmit Fifo Number */
  uint32_t sendZeroLengthPacket : 1;							/**< If set, a zero length packet will be send at the end of the transfer */
  uint32_t maxPacketSize        : 7;							/**< The maximum size of packet for USB endpoint ( due to FS Speed device only 64 Byte )*/
  uint32_t maxTransferSize      : 19;							/**< The maximum amount of data the core can send at once.*/
  uint8_t *outBuffer;                    						/**< The buffer for operation as OUT endpoint */
  uint32_t outBytesAvailable;            						/**< The number of bytes available in the EP OUT buffer */
  uint32_t outBufferSize;                						/**< The size of the EP OUT buffer */
  uint32_t outOffset;                    						/**< The read offset of the EP OUT buffer */
  uint8_t *inBuffer;                     						/**< The buffer for operation as IN endpoint */
  uint32_t inBufferSize;                 						/**< The size of the EP IN buffer */
  uint8_t *xferBuffer;                   						/**< The buffer of the current transfer */
  uint32_t xferLength;                   						/**< The length of the current transfer */
  uint32_t xferCount;                    						/**< Bytes transfered of the current USB data transfer */
  uint32_t xferTotal;                    						/**< The length of total data in buffer */
} XMC_USBD_EP_t;

/**
 * Describes the XMC USB device<BR>
 *
 * All information to control an XMC USB device is stored in
 * this structure. It contains register, callbacks, information
 * about the endpoints and the status of the device.
 */
typedef struct XMC_USBD_DEVICE {
  XMC_USBD_EP_t ep[8];                                                     	/**< Endpoints of the USB device. It is of type ::XMC_USBD_EP_t */
  dwc_otg_core_global_regs_t *global_register;                             	/**< Global register interface */
  dwc_otg_device_global_regs_t *device_register;                           	/**< Device register interface */
  dwc_otg_dev_in_ep_regs_t *endpoint_in_register[(uint8_t)XMC_USBD_NUM_EPS];/**< IN Endpoint register interface */
  dwc_otg_dev_out_ep_regs_t *endpoint_out_register[(uint8_t)XMC_USBD_NUM_EPS];/**< OUT Endpoint register interface */
  volatile uint32_t *fifo[(uint8_t)XMC_USBD_NUM_TX_FIFOS];                  /**< Transmit fifo interface */
  uint16_t txfifomsk;                                                      	/**< Mask of used TX fifos */
  uint32_t IsConnected       : 1;                                           /**< Sets if device is connected */
  uint32_t IsActive          : 1;                                           /**< Sets if device is currently active */
  uint32_t IsPowered		 : 1;                                           /**< Sets if device is powered by Vbus */
  XMC_USBD_SignalDeviceEvent_t DeviceEvent_cb;                              /**< The USB device event callback. */
  XMC_USBD_SignalEndpointEvent_t EndpointEvent_cb;                          /**< The USB endpoint event callback. */
} XMC_USBD_DEVICE_t;


/**
 * USB device initialization structure
 */
typedef struct XMC_USBD_OBJ
{
  USB0_GLOBAL_TypeDef *const usbd;                   						/**< USB Module Pointer. The USB0 module base address. */
  XMC_USBD_SignalDeviceEvent_t  cb_xmc_device_event; 						/**< USB device event callback. Use ::XMC_USBD_SignalDeviceEvent_t type of function pointer. */
  XMC_USBD_SignalEndpointEvent_t cb_endpoint_event;  						/**< USB endpoint event callback. Use ::XMC_USBD_SignalEndpointEvent_t type of function pointer.*/
  XMC_USBD_MAX_NUM_EPS_t usbd_max_num_eps;           						/**< Maximum number of end points used. The maximum range can be 7.*/
  XMC_USBD_TRANSFER_MODE_t usbd_transfer_mode;       						/**< USB data transfer mode.Use ::XMC_USBD_TRANSFER_MODE_t type to specify the transfer mode. */
} XMC_USBD_t;

/**
 * Defines the access structure of the USB Device Driver.
 */
typedef struct XMC_USBD_DRIVER {


  XMC_USBD_CAPABILITIES_t (*GetCapabilities)    (void);									 /**< Pointer to @ref XMC_USBD_GetCapabilities : Get driver capabilities.*/


  XMC_USBD_STATUS_t       (*Initialize)         (XMC_USBD_t *obj);						/**< Pointer to  @ref XMC_USBD_Init : Initialize USB Device Interface.*/


  XMC_USBD_STATUS_t       (*Uninitialize)       (void);									/**< Pointer to @ref XMC_USBD_Uninitialize : De-initialize USB Device Interface.*/


  XMC_USBD_STATUS_t       (*DeviceConnect)      (void);									/**< Pointer to @ref XMC_USBD_DeviceConnect : Connect USB Device.*/


  XMC_USBD_STATUS_t       (*DeviceDisconnect)   (void);									/**< Pointer to @ref XMC_USBD_DeviceDisconnect : Disconnect USB Device.*/


  XMC_USBD_STATE_t        (*DeviceGetState)     (const XMC_USBD_t *const obj);			/**< Pointer to @ref XMC_USBD_DeviceGetState : Get current USB Device State.*/


  XMC_USBD_STATUS_t       (*DeviceSetAddress)   (uint8_t dev_addr, XMC_USBD_SET_ADDRESS_STAGE_t stage);/**< Pointer to @ref XMC_USBD_DeviceSetAddress : Set USB Device Address.*/


  XMC_USBD_STATUS_t       (*EndpointConfigure)  (uint8_t ep_addr,XMC_USBD_ENDPOINT_TYPE_t ep_type, uint16_t ep_max_packet_size);/**< Pointer to @ref XMC_USBD_EndpointConfigure : Configure USB Endpoint.*/


  XMC_USBD_STATUS_t       (*EndpointUnconfigure)(uint8_t ep_addr);						/**< Pointer to @ref XMC_USBD_EndpointUnconfigure : Unconfigure USB Endpoint.*/


  XMC_USBD_STATUS_t       (*EndpointStall)      (uint8_t ep_addr, bool stall);			/**< Pointer to @ref XMC_USBD_EndpointStall : Set/Clear Stall for USB Endpoint.*/


  XMC_USBD_STATUS_t       (*EndpointReadStart)  (uint8_t ep_addr, uint32_t len);		/**< Pointer to @ref XMC_USBD_EndpointReadStart : Start USB Endpoint Read operation.*/


  int32_t                 (*EndpointRead)       (uint8_t ep_addr, uint8_t *buf, uint32_t len);/**< Pointer to @ref XMC_USBD_EndpointRead : Read data from USB Endpoint.*/


  int32_t                 (*EndpointWrite)      (uint8_t ep_addr, const uint8_t *buf, uint32_t len); /**< Pointer to @ref XMC_USBD_EndpointWrite : Write data to USB Endpoint.*/


  XMC_USBD_STATUS_t       (*EndpointAbort)      (uint8_t ep_addr);						/**< Pointer to @ref XMC_USBD_EndpointAbort : Abort current USB Endpoint transfer.*/


  uint16_t                (*GetFrameNumber)     (void);									/**< Pointer to @ref XMC_USBD_GetFrameNumber : Get current USB Frame Number.*/


  uint32_t    	          (*IsEnumDone)         (void);									/**< Pointer to @ref XMC_USBD_IsEnumDone : Is enumeration done in Host?.*/
} const XMC_USBD_DRIVER_t;

/**
 * Defines the driver interface function table.
 * To access the XMC device controller driver interface use this table of functions.
 **/
extern const XMC_USBD_DRIVER_t Driver_USBD0;


/**
 * Defines the XMC USB device data
 * The instance of ::XMC_USBD_DEVICE_t structure describing the XMC device.
 **/
extern XMC_USBD_DEVICE_t xmc_device;

/**********************************************************************************************************************
 * API PROTOTYPES
 *********************************************************************************************************************/
 
#ifdef __cplusplus
extern "C" {
#endif

/**
 * @param	None.
 *
 * @return 	None.
 *
 * \par<b>Description:</b><BR>
 * Enables the USB module in the XMC controller.<BR>
 * It de-asserts the peripheral reset on USB0 module and enables the USB power.
 *
 * \par<b>Note:</b><BR>
 * This API is called inside the XMC_USBD_Init().\n
 *
 * \par<b>Related APIs:</b><BR>
 * XMC_USBD_Disable()\n
 **/
void XMC_USBD_Enable(void);

/**
 * @param	None.
 *
 * @return 	None.
 *
 * \par<b>Description:</b><BR>
 * Disables the USB module in the XMC controller.<BR>
 * It asserts the peripheral reset on USB0 module and disables the USB power.
 *
 * \par<b>Related APIs:</b><BR>
 * XMC_USBD_Enable()\n
 **/
void XMC_USBD_Disable(void);

/**
 * @param	event The single event that needs to be cleared. Use ::XMC_USBD_EVENT_t as argument.\n
 *
 * @return 	None.
 *
 * \par<b>Description:</b><BR>
 * Clears the selected USBD \a event.<BR>
 * It clears the event by writing to the GINTSTS register.
 *
 * \par<b>Note:</b><BR>
 * This API is called inside the USB interrupt handler to clear the event XMC_USBD_EVENT_t
 * and maintain the device state machine.\n
 *
 * \par<b>Related APIs:</b><BR>
 * ::XMC_USBD_ClearEventOUTEP(),::XMC_USBD_ClearEventINEP()\n
 **/
void XMC_USBD_ClearEvent(XMC_USBD_EVENT_t event);


/**
 * @param	event The single event or multiple events that need to be cleared.
 *
 * @param	ep_num The IN endpoint number on which the events to be cleared.
 *
 * @return 	None.
 *
 * \par<b>Description:</b><BR>
 * Clears the single event or multiple events of the selected IN endpoint.<BR>
 * The multiple events can be selected by the bitwise OR operation of ::XMC_USBD_EVENT_IN_EP_t elements.\n
 * It clears the event by programming DIEPINT register.\n
 *
 * \par<b>Note:</b><BR>
 * This API is called inside the USB IN EP interrupt handler to clear the ::XMC_USBD_EVENT_IN_EP_t event
 * and maintain the device state machine.\n
 *
 * \par<b>Related APIs:</b><BR>
 * ::XMC_USBD_ClearEventOUTEP()\n
 **/
void XMC_USBD_ClearEventINEP(uint32_t event,uint8_t ep_num);


/**
 * @param	event The single event or multiple events that need to be cleared.
 *
 * @param	ep_num The OUT endpoint number on which the events to be cleared.
 *
 * @return 	None.
 *
 * \par<b>Description:</b><BR>
 * Clears the single \a event or multiple events of the selected OUT endpoint.<BR>
 * The multiple events can be selected by the bitwise OR operation of ::XMC_USBD_EVENT_OUT_EP_t elements.
 * It clears the event by writing to DOEPINT register.
 *
 * \par<b>Note:</b><BR>
 * This API is called inside the USB OUT EP interrupt handler to clear the ::XMC_USBD_EVENT_OUT_EP_t event
 * and maintain the device state machine.\n
 *
 * \par<b>Related APIs:</b><BR>
 * ::XMC_USBD_ClearEventINEP()\n
 **/
void XMC_USBD_ClearEventOUTEP(uint32_t event,uint8_t ep_num);

/**
 * @param	event The single event or multiple events that need to be enabled.
 *
 * @return 	None.
 *
 * \par<b>Description:</b><BR>
 * Enables the event or multiple events of the OUT endpoints.<BR>
 * The multiple events can be selected by the bitwise OR operation of ::XMC_USBD_EVENT_OUT_EP_t elements.
 * It enables the event by programming DOEPMSK register.
 *
 * \par<b>Note:</b><BR>
 * This API is called inside the ::XMC_USBD_Init() to enable the OUT EP interrupts.\n
 *
 * \par<b>Related APIs:</b><BR>
 * ::XMC_USBD_EnableEventINEP()\n
 **/
void XMC_USBD_EnableEventOUTEP(uint32_t event);

/**
 * @param	event The single event or multiple events that need to be enabled.
 *
 * @return 	None.
 *
 * \par<b>Description:</b><BR>
 * Enables the \a event or multiple events of the USB IN endpoints.<BR>
 * The multiple events can be selected by the bitwise OR operation of ::XMC_USBD_EVENT_IN_EP_t elements.
 * It enables the event by programming DIEPMSK register.
 *
 * \par<b>Note:</b><BR>
 * This API is called inside the ::XMC_USBD_Init() to enable the IN EP interrupts.\n
 *
 * \par<b>Related APIs:</b><BR>
 * ::XMC_USBD_EnableEventOUTEP()\n
 **/
void XMC_USBD_EnableEventINEP(uint32_t event);

/**
 * @param	None.
 *
 * @return 	::XMC_USBD_CAPABILITIES_t.
 *
 * \par<b>Description:</b><BR>
 * Retrieves the USB device capabilities of type \a XMC_USBD_CAPABILITIES_t<BR>
 * The USB device capabilities supported by the USBD driver, like power on/off, connect/disconnect,
 * reset,suspend/resume,USB speed etc are retrieved.
 *
 * It can be called after initializing the USB device to get the information on the USBD capabilities.
 *
 **/
XMC_USBD_CAPABILITIES_t XMC_USBD_GetCapabilities(void);


/**
 * @param	obj The pointer to the USB device handle ::XMC_USBD_t.
 *
 * @return 	XMC_USBD_STATUS_t The USB device status of type ::XMC_USBD_STATUS_t.
 *
 * \par<b>Description:</b><BR>
 * Initializes the USB device to get ready for connect to USB host.<BR>
 * Enables the USB module,sets the EP buffer sizes,registers the device and EP event call backs.
 * Initializes the global,device and FIFO register base addresses.
 * Configures the global AHB,enables the global interrupt and DMA by programming GAHBCFG register.
 * Configures the USB in to device mode and enables the session request protocol by programming GUSBCFG register.
 * Configures the USB device speed to full speed by programming DCFG register.
 * Disconnects the USB device by programming DCTL register.
 * Enables the USB common and device interrupts by programming GINTMSK register.
 *
 * \par<b>Note:</b><BR>
 * This API makes the USB device ready to connect to host.The user has to explicitly call
 * the ::XMC_USBD_DeviceConnect() after the USB initialization to connect to USB host.\n
 *
 * \par<b>Related APIs:</b><BR>
 * ::XMC_USBD_DeviceConnect()\n
 **/
XMC_USBD_STATUS_t XMC_USBD_Init(XMC_USBD_t *obj);

/**
 * @param	None.
 *
 * @return 	::XMC_USBD_STATUS_t.
 *
 * \par<b>Description:</b><BR>
 * Uninitialises the USB device.<BR>
 * Disconnects the USB device by programming DCTL register and resets the XMC USB device data.
 *
 * \par<b>Note:</b><BR>
 * Once this API is called, USB device will not be accessible from host.\n
 *
 * \par<b>Related APIs:</b><BR>
 * ::XMC_USBD_Init()\n
 **/
XMC_USBD_STATUS_t XMC_USBD_Uninitialize(void);

/**
 * @param	None.
 *
 * @return 	::XMC_USBD_STATUS_t.
 *
 * \par<b>Description:</b><BR>
 * Connects the USB device to host and triggers the USB enumeration.<BR>
 * Connects the USB device to host by programming DCTL register.\n
 * It resets the soft disconnect bit, which activates the speed pull up at d+ line of USB.
 * ::XMC_USBD_Init() should be called before calling this API.
 *
 * \par<b>Note:</b><BR>
 * Once this API is called, USB host starts the enumeration process and the device should
 * handle the descriptor requests.\n
 *
 * \par<b>Related APIs:</b><BR>
 * ::XMC_USBD_Init()\n
 **/
XMC_USBD_STATUS_t XMC_USBD_DeviceConnect(void);

/**
 * @param	None.
 *
 * @return 	::XMC_USBD_STATUS_t.
 *
 * \par<b>Description:</b><BR>
 * Disconnects the USB device from host.<BR>
 * By programming DCTL register, it sets the soft disconnect bit, which deactivates\n
 * the speed pull up at d+ line of USB.
 *
 * \par<b>Note:</b><BR>
 * Once this API is called, USB device will not be accessible from host.\n
 *
 * \par<b>Related APIs:</b><BR>
 * ::XMC_USBD_DeviceConnect()\n
 **/
XMC_USBD_STATUS_t XMC_USBD_DeviceDisconnect(void);

/**
 * @param	obj The pointer to the USB device handle structure \a XMC_USBD_t.
 *
 * @return 	::XMC_USBD_STATE_t.
 *
 * \par<b>Description:</b><BR>
 * Retrieves the current USB device state.<BR>
 * Power,active,speed and connection status data are retrieved.\n
 *
 * \par<b>Note:</b><BR>
 * Before calling this API, USB should be initialized with ::XMC_USBD_Init.\n
 *
 * \par<b>Related APIs:</b><BR>
 * ::XMC_USBD_Init()\n
 **/
XMC_USBD_STATE_t XMC_USBD_DeviceGetState(const XMC_USBD_t *const obj);


/**
 * @param	address The address to be set for the USB device .
 * @param	stage 	The device request stage-setup or status ::XMC_USBD_SET_ADDRESS_STAGE_t.
 *
 * @return 	::XMC_USBD_STATUS_t.
 *
 * \par<b>Description:</b><BR>
 * Sets the USB device address.<BR>
 * The device address is programmed in the DCFG register.<BR>
 *
 * The address should be more than 0; as 0 is the default USB device address at the starting of enumeration.
 * As part of enumeration, host sends the control request to the device to set the USB address; and in turn,\n
 * in the USB device event call back handler, user has to set the address using this API for the set address request.<BR>
 *
 * The stage parameter should be XMC_USBD_SET_ADDRESS_STAGE_SETUP from the enum ::XMC_USBD_SET_ADDRESS_STAGE_t.
 *
 * \par<b>Note:</b><BR>
 * Before calling this API, USB should be initialized with ::XMC_USBD_Init () and connected to
 * USB host using ::XMC_USBD_DeviceConnect() \n
 *
 * \par<b>Related APIs:</b><BR>
 * ::XMC_USBD_Init(), ::XMC_USBD_DeviceConnect()\n
 **/
XMC_USBD_STATUS_t XMC_USBD_DeviceSetAddress(uint8_t address,XMC_USBD_SET_ADDRESS_STAGE_t stage);

/**
 * @param	ep_addr The address of the USB endpoint, which needs to be configured.
 * @param	ep_type The ::XMC_USBD_ENDPOINT_TYPE_t.
 * @param	ep_max_packet_size The maximum packet size of endpoint in USB full speed.
 *
 * @return 	::XMC_USBD_STATUS_t.
 *
 * \par<b>Description:</b><BR>
 * Configures the USB endpoint.<BR>
 * The endpoint is configured by programming the DAINT,DIEPCTL and DOEPCTL registers.<BR>
 *
 * Configures the EP type, FIFO number,maximum packet size, enables endpoint and sets the DATA0 PID.
 * This function also initializes the internal buffer handling for the specified endpoint,
 * but does not start any transfers.<BR>
 *
 * As part of enumeration, host sends the control request to the device to set the configuration; and in turn,\n
 * in the USB device event call back handler, user has to set the configuration and configure the endpoints \n
 * required for the device.\n
 *
 * \par<b>Note:</b><BR>
 * This API should only be used as part of enumeration.\n
 *
 * \par<b>Related APIs:</b><BR>
 * ::XMC_USBD_Init(),::XMC_USBD_DeviceConnect(),::XMC_USBD_EndpointUnconfigure()\n
 **/
XMC_USBD_STATUS_t XMC_USBD_EndpointConfigure(uint8_t ep_addr,
                                             XMC_USBD_ENDPOINT_TYPE_t ep_type,
		                                     uint16_t ep_max_packet_size);

/**
 * @param	ep_addr The address of the USB endpoint, which needs to be unconfigured.
 *
 * @return 	::XMC_USBD_STATUS_t.
 *
 * \par<b>Description:</b><BR>
 * Unconfigures the USB endpoint.<BR>
 * The endpoint is unconfigured by programming the DAINT,DIEPCTL and DOEPCTL registers.\n
 * Disables the endpoint, unassign the fifo, deactivate it and only send nacks.\n
 * Waits until the endpoint has finished operation and disables it. All (eventuallly) allocated buffers gets freed.
 * Forces the endpoint to stop immediately, any pending transfers are killed(Can cause device reset).
 *
 * \par<b>Related APIs:</b><BR>
 * ::XMC_USBD_EndpointConfigure()\n
 **/
XMC_USBD_STATUS_t XMC_USBD_EndpointUnconfigure(uint8_t ep_addr);

/**
 * @param	ep_addr The address of the USB endpoint, on which stall needs to be set or cleared.
 * @param	stall 	The boolean variable to decide on set or clear of stall on EP.
 *
 * @return 	::XMC_USBD_STATUS_t.
 *
 * \par<b>Description:</b><BR>
 * Set or Clear stall on the USB endpoint \a ep_addr, based on \a stall parameter.<BR>
 *
 * By programming stall bit in the doepctl and diepctl, it sets or clears the stall on the endpoint.
 * The endpoint can be stalled when a non supported request comes from the USB host.
 * The XMC_USBD_EndpointStall() should be called with \a stall set to 0, in the clear feature standard request
 * in the USB device event call back handler. *
 *
 * \par<b>Note:</b><BR>
 * The host should clear the stall set on the endpoint by sending the clear feature standard
 * request on the non EP0 endpoints. On EP0, the stall will automatically gets cleared on the next control request.\n
 *
 * \par<b>Related APIs:</b><BR>
 * ::XMC_USBD_EndpointAbort()\n
 **/
XMC_USBD_STATUS_t XMC_USBD_EndpointStall(uint8_t ep_addr, bool stall);


/**
 * @param	ep_addr The address of the USB endpoint, from which data need to be read.
 * @param	size 	The number of bytes to be read.
 *
 * @return 	::XMC_USBD_STATUS_t.
 *
 * \par<b>Description:</b><BR>
 * Prepares an endpoint to receive OUT tokens from the USB host.<BR>
 * The selected endpoint gets configured, so that it receives the specified amount of data from the host.
 * As part of streaming of OUT data, after reading the current OUT buffer using ::XMC_USBD_EndpointRead(),\n
 * user can prepare endpoint for the next OUT packet by using ::XMC_USBD_EndpointReadStart().
 *
 * The registers DOEPDMA,DOEPTSIZ and DOEPCTL are programmed to start a new read request.
 *
 * \par<b>Note:</b><BR>
 * For the data received on OUT EP buffer, use ::XMC_USBD_EndpointRead().\n
 *
 * \par<b>Related APIs:</b><BR>
 * XMC_USBD_EndpointRead()\n
 **/
XMC_USBD_STATUS_t XMC_USBD_EndpointReadStart(const uint8_t ep_addr, uint32_t size);


/**
 * @param	ep_addr The address of the USB OUT endpoint, from which data need to be read.
 * @param	buffer 	The pointer to the user buffer,in which data need to be received.
 * @param	length 	The number of bytes to be read from OUT EP.
 *
 * @return 	<BR>
 * 			The actual number of bytes received.
 *
 * \par<b>Description:</b><BR>
 * Read \a length number of bytes from an OUT endpoint \a ep_addr.<BR>
 * If data has been received for this endpoint, it gets copied into the user buffer until its full
 * or no data is left in the driver buffer.
 *
 * \par<b>Note:</b><BR>
 * For preparing the next OUT token, use ::XMC_USBD_EndpointReadStart() after ::XMC_USBD_EndpointRead().\n
 *
 *
 * \par<b>Related APIs:</b><BR>
 * ::XMC_USBD_EndpointReadStart()\n
 **/
int32_t XMC_USBD_EndpointRead(const uint8_t ep_addr,uint8_t * buffer, uint32_t length);


/**
 * @param	ep_addr The address of the USB IN endpoint, on which data should be sent.
 * @param	buffer 	The pointer to the data buffer, to write to the endpoint.
 * @param	length 	The number of bytes to be written to IN EP.
 *
 * @return 	<BR>
 * 			The actual amount of data written to the endpoint buffer.
 *
 * \par<b>Description:</b><BR>
 * Write the \a length bytes of data to an IN endpoint \a ep_addr.<BR>
 * The User data gets copied into the driver buffer or will be send directly based on the buffer concept
 * selected in the ::XMC_USBD_TRANSFER_MODE_t configuration.
 *
 * Then the endpoint is set up to transfer the data to the host.\n
 * DIEPDMA,DIEPTSIZ and DIEPCTL registers are programmed to start the IN transfer.
 *
 *
 * \par<b>Related APIs:</b><BR>
 * ::XMC_USBD_EndpointRead()\n
 **/
int32_t XMC_USBD_EndpointWrite(const uint8_t ep_addr,const uint8_t * buffer,uint32_t length);


/**
 * @param	ep_addr The address of the USB endpoint, on which the data need to be aborted.
 *
 * @return 	::XMC_USBD_STATUS_t
 *
 * \par<b>Description:</b><BR>
 * Abort the transfer on endpoint \a ep_addr.<BR>
 * On any failure with the USB transmission user can reset the endpoint into default state and clear all
 * assigned buffers, to start from a clean point. The endpoint will not be unconfigured or disabled.
 *
 * \par<b>Related APIs:</b><BR>
 * ::XMC_USBD_EndpointUnconfigure()\n
 **/
XMC_USBD_STATUS_t XMC_USBD_EndpointAbort(uint8_t ep_addr);

/**
 * @param	None.
 *
 * @return 	The 16 bit current USB frame number.
 *
 * \par<b>Description:</b><BR>
 * Read the current USB frame number.<BR> *
 * Reads the device status register (DSTS) and returns the SOFFN field.
 *
 **/
uint16_t XMC_USBD_GetFrameNumber(void);

/**
 * @param	None.
 *
 * @return 	Returns 1, if the speed enumeration is done and 0 otherwise.
 *
 * \par<b>Description:</b><BR>
 * Gets the speed enumeration completion status of the USB device.<BR>
 *
 * \par<b>Note:</b><BR>
 * This should not be used for the actual USB enumeration completion status. For the actual USB enumeration status,
 * the application layer should check for the completion of USB standard request 'Set configuration'.\n
 *
 **/
uint32_t XMC_USBD_IsEnumDone(void);


/**
 * @param	obj	The pointer to the USB device handle structure.
 *
 * @return 	None.
 *
 * \par<b>Description:</b><BR>
 * USB device default IRQ handler.<BR>
 * USBD Peripheral LLD provides default implementation of ISR.
 * The user needs to explicitly either use our default implementation or use its own one using the LLD APIs.
 *
 * For example:
 *  XMC_USBD_t *obj;
 *  void USB0_0_IRQHandler(void)
 *   {
 *    XMC_USBD_IRQHandler(obj);
 *   }
 *
 * \par<b>Note:</b><BR>
 * The user should initialize the XMC USB device configuration structure before calling
 * ::XMC_USBD_IRQHandler() in the actual USB0 IRQ handler.
 *
 **/
void XMC_USBD_IRQHandler(const XMC_USBD_t *const obj);

#ifdef __cplusplus
}
#endif

/**
 * MISRA C 2004 Deviations
 *
 * 1. Function like macro- defined- MISRA Advisory Rule 19.7
 * 2. usage of unions - MISRA Required Rule 18.4
 */

/**
 * @}
 */

/**
 * @}
 */
 
#endif /* defined(USB0) */

#endif /* XMC_USBD_H */