00001 /* ---------------------------------------------------------------------------- */ 00002 /* Atmel Microcontroller Software Support */ 00003 /* SAM Software Package License */ 00004 /* ---------------------------------------------------------------------------- */ 00005 /* Copyright (c) 2015, Atmel Corporation */ 00006 /* */ 00007 /* All rights reserved. */ 00008 /* */ 00009 /* Redistribution and use in source and binary forms, with or without */ 00010 /* modification, are permitted provided that the following condition is met: */ 00011 /* */ 00012 /* - Redistributions of source code must retain the above copyright notice, */ 00013 /* this list of conditions and the disclaimer below. */ 00014 /* */ 00015 /* Atmel's name may not be used to endorse or promote products derived from */ 00016 /* this software without specific prior written permission. */ 00017 /* */ 00018 /* DISCLAIMER: THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR */ 00019 /* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF */ 00020 /* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE */ 00021 /* DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, */ 00022 /* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT */ 00023 /* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, */ 00024 /* OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF */ 00025 /* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING */ 00026 /* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, */ 00027 /* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ 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