git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_A5_SAMA5D4x_EK_IAR/AtmelFiles/usb/include/USBD.h

   1 /* ----------------------------------------------------------------------------\r
   2  *         ATMEL Microcontroller Software Support\r
   3  * ----------------------------------------------------------------------------\r
   4  * Copyright (c) 2008, Atmel Corporation\r
   5  *\r
   6  * All rights reserved.\r
   7  *\r
   8  * Redistribution and use in source and binary forms, with or without\r
   9  * modification, are permitted provided that the following conditions are met:\r
  10  *\r
  11  * - Redistributions of source code must retain the above copyright notice,\r
  12  * this list of conditions and the disclaimer below.\r
  13  *\r
  14  * Atmel's name may not be used to endorse or promote products derived from\r
  15  * this software without specific prior written permission.\r
  16  *\r
  17  * DISCLAIMER: THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR\r
  18  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF\r
  19  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE\r
  20  * DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,\r
  21  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT\r
  22  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,\r
  23  * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF\r
  24  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING\r
  25  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,\r
  26  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\r
  27  * ----------------------------------------------------------------------------\r
  28  */\r
  29 \r
  30 /**\r
  31  * \file\r
  32  *\r
  33  * \section Purpose\r
  34  *\r
  35  * Collection of methods for using the USB device controller on AT91\r
  36  * microcontrollers.\r
  37  *\r
  38  * \section Usage\r
  39  *\r
  40  * Please refer to the corresponding application note.\r
  41  * - \ref usbd_framework AT91 USB device framework\r
  42  * - \ref usbd_api USBD API\r
  43  *\r
  44  */\r
  45 \r
  46 #ifndef USBD_H\r
  47 #define USBD_H\r
  48 \r
  49 /*----------------------------------------------------------------------------\r
  50  *         Headers\r
  51  *----------------------------------------------------------------------------*/\r
  52 \r
  53 \r
  54 #include "USBDescriptors.h"\r
  55 #include "USBRequests.h"\r
  56 \r
  57 #include "USBLib_Types.h"\r
  58 \r
  59 #include <stdio.h>\r
  60 \r
  61 /*------------------------------------------------------------------------------\r
  62  *      Definitions\r
  63  *------------------------------------------------------------------------------*/\r
  64 \r
  65 /* Define attribute */\r
  66 #if defined   ( __CC_ARM   ) /* Keil ¦ÌVision 4 */\r
  67     #define WEAK __attribute__ ((weak))\r
  68 #elif defined ( __ICCARM__ ) /* IAR Ewarm 5.41+ */\r
  69     #define WEAK __weak\r
  70 #elif defined (  __GNUC__  ) /* GCC CS3 2009q3-68 */\r
  71     #define WEAK __attribute__ ((weak))\r
  72 #endif\r
  73 \r
  74 /* Define NO_INIT attribute */\r
  75 #if defined   ( __CC_ARM   )\r
  76     #define NO_INIT\r
  77 #elif defined ( __ICCARM__ )\r
  78     #define NO_INIT __no_init\r
  79 #elif defined (  __GNUC__  )\r
  80     #define NO_INIT\r
  81 #endif\r
  82 \r
  83 \r
  84 /** \addtogroup usbd_interface\r
  85  *@{*/\r
  86 \r
  87 /**\r
  88  * \addtogroup usbd_rc USB device API return codes\r
  89  *  @{\r
  90  * This section lists the return codes for the USB device driver API\r
  91  * - \ref USBD_STATUS_SUCCESS\r
  92  * - \ref USBD_STATUS_LOCKED\r
  93  * - \ref USBD_STATUS_ABORTED\r
  94  * - \ref USBD_STATUS_RESET\r
  95  */\r
  96 \r
  97 /** Indicates the operation was successful. */\r
  98 #define USBD_STATUS_SUCCESS             USBRC_SUCCESS\r
  99 /** Endpoint/device is already busy. */\r
 100 #define USBD_STATUS_LOCKED              USBRC_BUSY\r
 101 /** Operation has been aborted (error or stall). */\r
 102 #define USBD_STATUS_ABORTED             USBRC_ABORTED\r
 103 /** Operation has been canceled (by user). */\r
 104 #define USBD_STATUS_CANCELED            USBRC_CANCELED\r
 105 /** Operation has been aborted because the device init/reset/un-configure. */\r
 106 #define USBD_STATUS_RESET               USBRC_RESET\r
 107 /** Part ot operation successfully done. */\r
 108 #define USBD_STATUS_PARTIAL_DONE        USBRC_PARTIAL_DONE\r
 109 /** Operation failed because parameter error */\r
 110 #define USBD_STATUS_INVALID_PARAMETER   USBRC_PARAM_ERR\r
 111 /** Operation failed because in unexpected state */\r
 112 #define USBD_STATUS_WRONG_STATE         USBRC_STATE_ERR\r
 113 /** Operation failed because SW not supported */\r
 114 #define USBD_STATUS_SW_NOT_SUPPORTED    USBRC_SW_NOT_SUPPORTED\r
 115 /** Operation failed because HW not supported */\r
 116 #define USBD_STATUS_HW_NOT_SUPPORTED    USBRC_HW_NOT_SUPPORTED\r
 117 /** @}*/\r
 118 \r
 119 /** \addtogroup usbd_states USB device states\r
 120  *  @{\r
 121  * This section lists the device states of the USB device driver.\r
 122  * - \ref USBD_STATE_SUSPENDED\r
 123  * - \ref USBD_STATE_ATTACHED\r
 124  * - \ref USBD_STATE_POWERED\r
 125  * - \ref USBD_STATE_DEFAULT\r
 126  * - \ref USBD_STATE_ADDRESS\r
 127  * - \ref USBD_STATE_CONFIGURED\r
 128  */\r
 129 \r
 130 /** The device is currently suspended. */\r
 131 #define USBD_STATE_SUSPENDED            0\r
 132 /** USB cable is plugged into the device. */\r
 133 #define USBD_STATE_ATTACHED             1\r
 134 /** Host is providing +5V through the USB cable. */\r
 135 #define USBD_STATE_POWERED              2\r
 136 /** Device has been reset. */\r
 137 #define USBD_STATE_DEFAULT              3\r
 138 /** The device has been given an address on the bus. */\r
 139 #define USBD_STATE_ADDRESS              4\r
 140 /** A valid configuration has been selected. */\r
 141 #define USBD_STATE_CONFIGURED           5\r
 142 /**  @}*/\r
 143 \r
 144 /*----------------------------------------------------------------------------\r
 145  *         Types\r
 146  *----------------------------------------------------------------------------*/\r
 147 \r
 148 /**\r
 149  * \brief Buffer struct used for multi-buffer-listed transfer.\r
 150  *\r
 151  * The driver can process 255 bytes of buffers or buffer list window.\r
 152  */\r
 153 typedef struct _USBDTransferBuffer {\r
 154     /** Pointer to frame buffer */\r
 155     uint8_t * pBuffer;\r
 156     /** Size of the frame (up to 64K-1) */\r
 157     uint16_t size;\r
 158     /** Bytes transferred */\r
 159     uint16_t transferred;\r
 160     /** Bytes in FIFO */\r
 161     uint16_t buffered;\r
 162     /** Bytes remaining */\r
 163     uint16_t remaining;\r
 164 } USBDTransferBuffer;\r
 165 \r
 166 #pragma pack(1)\r
 167 #if defined   ( __CC_ARM   ) /* Keil ¦ÌVision 4 */\r
 168 #elif defined ( __ICCARM__ ) /* IAR Ewarm 5.41+ */\r
 169 #define __attribute__(...)\r
 170 #elif defined (  __GNUC__  ) /* GCC CS3 2009q3-68 */\r
 171 #endif\r
 172 \r
 173 /**\r
 174  * \brief Struct used for USBD DMA Link List Transfer Descriptor, must be 16-bytes\r
 175  * aligned.\r
 176  *\r
 177  * (For USB, DMA transfer is linked to EPs and FIFO address is EP defined)\r
 178  */\r
 179 typedef struct _USBDDmaDescriptor {\r
 180     /** Pointer to Next Descriptor */\r
 181     void* pNxtDesc;\r
 182     /** Pointer to data buffer address */\r
 183     void* pDataAddr;\r
 184     /** DMA Control setting register value */\r
 185     uint32_t   ctrlSettings:8,      /** Control settings */\r
 186                    reserved:8,      /** Not used */\r
 187                    bufferLength:16; /** Length of buffer */\r
 188     /** Loaded to DMA register, OK to modify */\r
 189     uint32_t used;\r
 190 } __attribute__((aligned(16))) USBDDmaDescriptor;\r
 191 \r
 192 #pragma pack()\r
 193 \r
 194 /**\r
 195  * Callback used by transfer functions (USBD_Read & USBD_Write) to notify\r
 196  * that a transaction is complete.\r
 197  */\r
 198 typedef void (*TransferCallback)(void *pArg,\r
 199                                  uint8_t status,\r
 200                                  uint32_t transferred,\r
 201                                  uint32_t remaining);\r
 202 \r
 203 /**\r
 204  * Callback used by MBL transfer functions (USBD_Read & USBD_Write) to notify\r
 205  * that a transaction is complete.\r
 206  * \param pArg     Pointer to callback arguments.\r
 207  * \param status   USBD status.\r
 208  */\r
 209 typedef void (*MblTransferCallback)(void *pArg,\r
 210                                     uint8_t status);\r
 211 \r
 212 /**@}*/\r
 213 \r
 214 /*------------------------------------------------------------------------------\r
 215  *         Exported functions\r
 216  *------------------------------------------------------------------------------*/\r
 217 \r
 218 //extern void USBD_IrqHandler(void);\r
 219 \r
 220 extern void USBD_Init(void);\r
 221 \r
 222 extern void USBD_ConfigureSpeed(uint8_t forceFS);\r
 223 \r
 224 extern void USBD_Connect(void);\r
 225 \r
 226 extern void USBD_Disconnect(void);\r
 227 \r
 228 extern uint8_t USBD_Write(\r
 229     uint8_t bEndpoint,\r
 230     const void *pData,\r
 231     uint32_t size,\r
 232     TransferCallback callback,\r
 233     void *pArg);\r
 234 \r
 235 extern uint8_t USBD_Read(\r
 236     uint8_t bEndpoint,\r
 237     void *pData,\r
 238     uint32_t dLength,\r
 239     TransferCallback fCallback,\r
 240     void *pArg);\r
 241 \r
 242 extern uint8_t USBD_Stall(uint8_t bEndpoint);\r
 243 \r
 244 extern void USBD_Halt(uint8_t bEndpoint);\r
 245 \r
 246 extern void USBD_Unhalt(uint8_t bEndpoint);\r
 247 \r
 248 extern void USBD_ConfigureEndpoint(const USBEndpointDescriptor *pDescriptor);\r
 249 \r
 250 extern uint8_t USBD_IsHalted(uint8_t bEndpoint);\r
 251 \r
 252 extern void USBD_RemoteWakeUp(void);\r
 253 \r
 254 extern void USBD_SetAddress(uint8_t address);\r
 255 \r
 256 extern void USBD_SetConfiguration(uint8_t cfgnum);\r
 257 \r
 258 extern uint8_t USBD_GetState(void);\r
 259 \r
 260 extern uint8_t USBD_IsHighSpeed(void);\r
 261 \r
 262 extern void USBD_Test(uint8_t bIndex);\r
 263 \r
 264 extern void USBD_SuspendHandler(void);\r
 265 extern void USBD_ResumeHandler(void);\r
 266 extern void USBD_ResetHandler(void);\r
 267 extern void USBD_RequestHandler(uint8_t bEndpoint,\r
 268                                 const USBGenericRequest * pRequest);\r
 269 \r
 270 \r
 271 extern void USBDCallbacks_Initialized(void);\r
 272 extern void USBDCallbacks_Reset(void);\r
 273 extern void USBDCallbacks_Suspended(void);\r
 274 extern void USBDCallbacks_Resumed(void);\r
 275 extern void USBDCallbacks_RequestReceived(const USBGenericRequest *request);\r
 276 \r
 277 #endif /*#ifndef USBD_H*/\r
 278 \r