2016-10-20 15:46:56 +00:00
/**
* @ file xmc_usbd . h
2016-10-21 22:29:25 +00:00
* @ date 2015 - 06 - 20
2016-10-20 15:46:56 +00:00
*
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
2016-10-21 22:29:25 +00:00
* XMClib v2 .1 .8 - XMC Peripheral Driver Library
2016-10-20 15:46:56 +00:00
*
2016-10-21 22:29:25 +00:00
* Copyright ( c ) 2015 - 2016 , Infineon Technologies AG
2016-10-20 15:46:56 +00:00
* 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 */