SAMV71 Xplained Ultra Software Package 1.3

USBD.h

Go to the documentation of this file.
00001 /* ----------------------------------------------------------------------------
00002  *         SAM Software Package License 
00003  * ----------------------------------------------------------------------------
00004  * Copyright (c) 2014, Atmel Corporation
00005  *
00006  * All rights reserved.
00007  *
00008  * Redistribution and use in source and binary forms, with or without
00009  * modification, are permitted provided that the following conditions are met:
00010  *
00011  * - Redistributions of source code must retain the above copyright notice,
00012  * this list of conditions and the disclaimer below.
00013  *
00014  * Atmel's name may not be used to endorse or promote products derived from
00015  * this software without specific prior written permission.
00016  *
00017  * DISCLAIMER: THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR
00018  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
00019  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
00020  * DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,
00021  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
00022  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
00023  * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00024  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00025  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
00026  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00027  * ----------------------------------------------------------------------------
00028  */
00029 
00030 /**
00031  * \file
00032  *
00033  * \section Purpose
00034  *
00035  * Collection of methods for using the USB device controller on AT91
00036  * Microcontrollers.
00037  *
00038  * \section Usage
00039  *
00040  * Please refer to the corresponding application note.
00041  * - \ref usbd_framework AT91 USB device framework
00042  * - \ref usbd_api USBD API
00043  *
00044  */
00045 
00046 #ifndef USBD_H
00047 #define USBD_H
00048 
00049 /*----------------------------------------------------------------------------
00050  *         Headers
00051  *----------------------------------------------------------------------------*/
00052 
00053 
00054 #include "USBDescriptors.h"
00055 #include "USBRequests.h"
00056 
00057 #include "USBLib_Types.h"
00058 
00059 #include <stdio.h>
00060 
00061 /*------------------------------------------------------------------------------
00062  *      Definitions
00063  *------------------------------------------------------------------------------*/
00064 
00065 /* Define attribute */
00066 #if defined   ( __CC_ARM   ) /* Keil ¦̀Vision 4 */
00067     #define WEAK __attribute__ ((weak))
00068 #elif defined ( __ICCARM__ ) /* IAR Ewarm 5.41+ */
00069     #define WEAK __weak
00070 #elif defined (  __GNUC__  ) /* GCC CS3 2009q3-68 */
00071     #define WEAK __attribute__ ((weak))
00072 #endif
00073 
00074 /* Define NO_INIT attribute */
00075 #if defined   ( __CC_ARM   )
00076     #define NO_INIT
00077 #elif defined ( __ICCARM__ )
00078     #define NO_INIT __no_init
00079 #elif defined (  __GNUC__  )
00080     #define NO_INIT
00081 #endif
00082 
00083 extern uint8_t ForceFS;
00084 /** \addtogroup usbd_interface
00085  *@{*/
00086 
00087 /**
00088  * \addtogroup usbd_rc USB device API return codes
00089  *  @{
00090  * This section lists the return codes for the USB device driver API
00091  * - \ref USBD_STATUS_SUCCESS
00092  * - \ref USBD_STATUS_LOCKED
00093  * - \ref USBD_STATUS_ABORTED
00094  * - \ref USBD_STATUS_RESET
00095  */
00096 
00097 /** Indicates the operation was successful. */
00098 #define USBD_STATUS_SUCCESS             USBRC_SUCCESS
00099 /** Endpoint/device is already busy. */
00100 #define USBD_STATUS_LOCKED              USBRC_BUSY
00101 /** Operation has been aborted (error or stall). */
00102 #define USBD_STATUS_ABORTED             USBRC_ABORTED
00103 /** Operation has been cancelled (by user). */
00104 #define USBD_STATUS_CANCELED            USBRC_CANCELED
00105 /** Operation has been aborted because the device init/reset/un-configure. */
00106 #define USBD_STATUS_RESET               USBRC_RESET
00107 /** Part of operation successfully done. */
00108 #define USBD_STATUS_PARTIAL_DONE        USBRC_PARTIAL_DONE
00109 /** Operation failed because parameter error */
00110 #define USBD_STATUS_INVALID_PARAMETER   USBRC_PARAM_ERR
00111 /** Operation failed because in unexpected state */
00112 #define USBD_STATUS_WRONG_STATE         USBRC_STATE_ERR
00113 /** Operation failed because SW not supported */
00114 #define USBD_STATUS_SW_NOT_SUPPORTED    USBRC_SW_NOT_SUPPORTED
00115 /** Operation failed because HW not supported */
00116 #define USBD_STATUS_HW_NOT_SUPPORTED    USBRC_HW_NOT_SUPPORTED
00117 /** @}*/
00118 
00119 /** \addtogroup usbd_states USB device states
00120  *  @{
00121  * This section lists the device states of the USB device driver.
00122  * - \ref USBD_STATE_SUSPENDED
00123  * - \ref USBD_STATE_ATTACHED
00124  * - \ref USBD_STATE_POWERED
00125  * - \ref USBD_STATE_DEFAULT
00126  * - \ref USBD_STATE_ADDRESS
00127  * - \ref USBD_STATE_CONFIGURED
00128  */
00129 
00130 /** The device is currently suspended. */
00131 #define USBD_STATE_SUSPENDED            0
00132 /** USB cable is plugged into the device. */
00133 #define USBD_STATE_ATTACHED             1
00134 /** Host is providing +5V through the USB cable. */
00135 #define USBD_STATE_POWERED              2
00136 /** Device has been reset. */
00137 #define USBD_STATE_DEFAULT              3
00138 /** The device has been given an address on the bus. */
00139 #define USBD_STATE_ADDRESS              4
00140 /** A valid configuration has been selected. */
00141 #define USBD_STATE_CONFIGURED           5
00142 /**  @}*/
00143 
00144 /*----------------------------------------------------------------------------
00145  *         Types
00146  *----------------------------------------------------------------------------*/
00147 
00148 /**
00149  * \brief Buffer struct used for multi-buffer-listed transfer.
00150  *
00151  * The driver can process 255 bytes of buffers or buffer list window.
00152  */
00153 typedef struct _USBDTransferBuffer {
00154     /** Pointer to frame buffer */
00155     uint8_t * pBuffer;
00156     /** Size of the frame (up to 64K-1) */
00157     uint16_t size;
00158     /** Bytes transferred */
00159     uint16_t transferred;
00160     /** Bytes in FIFO */
00161     uint16_t buffered;
00162     /** Bytes remaining */
00163     uint16_t remaining;
00164 } USBDTransferBuffer;
00165 
00166 #pragma pack(1)
00167 #if defined   ( __CC_ARM   ) /* Keil ¦̀Vision 4 */
00168 #elif defined ( __ICCARM__ ) /* IAR Ewarm 5.41+ */
00169 #define __attribute__(...)
00170 #elif defined (  __GNUC__  ) /* GCC CS3 2009q3-68 */
00171 #endif
00172 
00173 /**
00174  * \brief Struct used for USBD DMA Link List Transfer Descriptor, must be 16-bytes
00175  * aligned.
00176  *
00177  * (For USB, DMA transfer is linked to EPs and FIFO address is EP defined)
00178  */
00179 typedef struct _USBDDmaDescriptor {
00180     /** Pointer to Next Descriptor */
00181     void* pNxtDesc;
00182     /** Pointer to data buffer address */
00183     void* pDataAddr;
00184     /** DMA Control setting register value */
00185     uint32_t   ctrlSettings:8,      /** Control settings */
00186                    reserved:8,      /** Not used */
00187                    bufferLength:16; /** Length of buffer */
00188     /** Loaded to DMA register, OK to modify */
00189     uint32_t used;
00190 } __attribute__((aligned(16))) USBDDmaDescriptor;
00191 
00192 #pragma pack()
00193 
00194 /**
00195  * Callback used by transfer functions (USBD_Read & USBD_Write) to notify
00196  * that a transaction is complete.
00197  */
00198 typedef void (*TransferCallback)(void *pArg,
00199                                  uint8_t status,
00200                                  uint32_t transferred,
00201                                  uint32_t remaining);
00202 
00203 /**
00204  * Callback used by MBL transfer functions (USBD_Read & USBD_Write) to notify
00205  * that a transaction is complete.
00206  * \param pArg     Pointer to callback arguments.
00207  * \param status   USBD status.
00208  */
00209 typedef void (*MblTransferCallback)(void *pArg,
00210                                     uint8_t status);
00211 
00212 /**@}*/
00213 
00214 /*------------------------------------------------------------------------------
00215  *         Exported functions
00216  *------------------------------------------------------------------------------*/
00217 
00218 extern void USBD_Init(void);
00219 
00220 extern void USBD_ConfigureSpeed(uint8_t forceFS);
00221 
00222 extern void USBD_Connect(void);
00223 
00224 extern void USBD_Disconnect(void);
00225 
00226 extern uint8_t USBD_Write(
00227     uint8_t bEndpoint,
00228     const void *pData,
00229     uint32_t size,
00230     TransferCallback callback,
00231     void *pArg);
00232 
00233 extern uint8_t USBD_Read(
00234     uint8_t bEndpoint,
00235     void *pData,
00236     uint32_t dLength,
00237     TransferCallback fCallback,
00238     void *pArg);
00239 
00240 extern uint8_t USBD_Stall(uint8_t bEndpoint);
00241 
00242 extern void USBD_Halt(uint8_t bEndpoint);
00243 
00244 extern void USBD_Unhalt(uint8_t bEndpoint);
00245 
00246 extern void USBD_ConfigureEndpoint(const USBEndpointDescriptor *pDescriptor);
00247 
00248 extern uint8_t USBD_IsHalted(uint8_t bEndpoint);
00249 
00250 extern void USBD_RemoteWakeUp(void);
00251 
00252 extern void USBD_SetAddress(uint8_t address);
00253 
00254 extern void USBD_SetConfiguration(uint8_t cfgnum);
00255 
00256 extern uint8_t USBD_GetState(void);
00257 
00258 extern uint8_t USBD_IsHighSpeed(void);
00259 
00260 extern void USBD_Test(uint8_t bIndex);
00261 
00262 extern void USBD_SuspendHandler(void);
00263 extern void USBD_ResumeHandler(void);
00264 extern void USBD_ResetHandler(void);
00265 extern void USBD_RequestHandler(uint8_t bEndpoint,
00266                                 const USBGenericRequest * pRequest);
00267 
00268 
00269 extern void USBDCallbacks_Initialized(void);
00270 extern void USBDCallbacks_Reset(void);
00271 extern void USBDCallbacks_Suspended(void);
00272 extern void USBDCallbacks_Resumed(void);
00273 extern void USBDCallbacks_RequestReceived(const USBGenericRequest *request);
00274 
00275 extern void USBD_ForceFullSpeed(void);
00276 
00277 #endif /*#ifndef USBD_H*/
00278 
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines