git.sur5r.net Git - freertos/blob

   1 /*\r
   2  * @brief USB ROM based hardware function prototypes\r
   3  *\r
   4  * @note\r
   5  * Copyright(C) NXP Semiconductors, 2012\r
   6   * All rights reserved.\r
   7  *\r
   8  * @par\r
   9  * Software that is described herein is for illustrative purposes only\r
  10  * which provides customers with programming information regarding the\r
  11  * LPC products.  This software is supplied "AS IS" without any warranties of\r
  12  * any kind, and NXP Semiconductors and its licensor disclaim any and\r
  13  * all warranties, express or implied, including all implied warranties of\r
  14  * merchantability, fitness for a particular purpose and non-infringement of\r
  15  * intellectual property rights.  NXP Semiconductors assumes no responsibility\r
  16  * or liability for the use of the software, conveys no license or rights under any\r
  17  * patent, copyright, mask work right, or any other intellectual property rights in\r
  18  * or to any products. NXP Semiconductors reserves the right to make changes\r
  19  * in the software without notification. NXP Semiconductors also makes no\r
  20  * representation or warranty that such application will be suitable for the\r
  21  * specified use without further testing or modification.\r
  22  *\r
  23  * @par\r
  24  * Permission to use, copy, modify, and distribute this software and its\r
  25  * documentation is hereby granted, under NXP Semiconductors' and its\r
  26  * licensor's relevant copyrights in the software, without fee, provided that it\r
  27  * is used in conjunction with NXP Semiconductors microcontrollers.  This\r
  28  * copyright, permission, and disclaimer notice must appear in all copies of\r
  29  * this code.\r
  30  */\r
  31 \r
  32 #include "error.h"\r
  33 #include "usbd.h"\r
  34 #include "usbd_core.h"\r
  35 \r
  36 #ifndef __USBHW_H__\r
  37 #define __USBHW_H__\r
  38 \r
  39 \r
  40 /** @ingroup Group_USBD\r
  41  *  @defgroup USBD_HW USB Device Controller Driver\r
  42  *  @section Sec_HWModDescription Module Description\r
  43  *  The Device Controller Driver Layer implements the routines to deal directly with the hardware.\r
  44  */\r
  45 \r
  46 /** @ingroup USBD_HW\r
  47 *  USB Endpoint/class handler Callback Events.\r
  48 *\r
  49 */\r
  50 enum USBD_EVENT_T {\r
  51   USB_EVT_SETUP =1,    /**< 1   Setup Packet received */\r
  52   USB_EVT_OUT,         /**< 2   OUT Packet received */\r
  53   USB_EVT_IN,          /**< 3    IN Packet sent */\r
  54   USB_EVT_OUT_NAK,     /**< 4   OUT Packet - Not Acknowledged */\r
  55   USB_EVT_IN_NAK,      /**< 5    IN Packet - Not Acknowledged */\r
  56   USB_EVT_OUT_STALL,   /**< 6   OUT Packet - Stalled */\r
  57   USB_EVT_IN_STALL,    /**< 7    IN Packet - Stalled */\r
  58   USB_EVT_OUT_DMA_EOT, /**< 8   DMA OUT EP - End of Transfer */\r
  59   USB_EVT_IN_DMA_EOT,  /**< 9   DMA  IN EP - End of Transfer */\r
  60   USB_EVT_OUT_DMA_NDR, /**< 10  DMA OUT EP - New Descriptor Request */\r
  61   USB_EVT_IN_DMA_NDR,  /**< 11  DMA  IN EP - New Descriptor Request */\r
  62   USB_EVT_OUT_DMA_ERR, /**< 12  DMA OUT EP - Error */\r
  63   USB_EVT_IN_DMA_ERR,  /**< 13  DMA  IN EP - Error */\r
  64   USB_EVT_RESET,       /**< 14  Reset event recieved */\r
  65   USB_EVT_SOF,         /**< 15  Start of Frame event */\r
  66   USB_EVT_DEV_STATE,   /**< 16  Device status events */\r
  67   USB_EVT_DEV_ERROR,   /**< 16  Device error events */\r
  68 };\r
  69 \r
  70 /**\r
  71  *  @brief Hardware API functions structure.\r
  72  *  @ingroup USBD_HW\r
  73  *\r
  74  *  This module exposes functions which interact directly with USB device controller hardware.\r
  75  *\r
  76  */\r
  77 typedef struct USBD_HW_API\r
  78 {\r
  79   /** @fn uint32_t GetMemSize(USBD_API_INIT_PARAM_T* param)\r
  80    *  Function to determine the memory required by the USB device stack's DCD and core layers.\r
  81    *\r
  82    *  This fuction is called by application layer before calling pUsbApi->hw->Init(), to allocate memory used\r
  83    *  by DCD and core layers. The application should allocate the memory which is accessible by USB\r
  84    *  controller/DMA controller.\r
  85    *  @note Some memory areas are not accessible by all bus masters.\r
  86    *\r
  87    *  @param param Structure containing USB device stack initialization parameters.\r
  88    *  @return Returns the required memory size in bytes.\r
  89    */\r
  90   uint32_t (*GetMemSize)(USBD_API_INIT_PARAM_T* param);\r
  91 \r
  92   /** @fn ErrorCode_t Init(USBD_HANDLE_T* phUsb, USB_CORE_DESCS_T* pDesc, USBD_API_INIT_PARAM_T* param)\r
  93    *  Function to initialize USB device stack's DCD and core layers.\r
  94    *\r
  95    *  This function is called by application layer to initialize USB hardware and core layers.\r
  96    *  On successful initialization the function returns a handle to USB device stack which should\r
  97    *  be passed to the rest of the functions.\r
  98    *\r
  99    *  \param[in,out] phUsb Pointer to the USB device stack handle of type USBD_HANDLE_T.\r
 100    *  @param  param Structure containing USB device stack initialization parameters.\r
 101    *  @return Returns @ref ErrorCode_t type to indicate success or error condition.\r
 102    *          @retval LPC_OK(0) On success\r
 103    *          @retval ERR_USBD_BAD_MEM_BUF(0x0004000b) When insufficient memory buffer is passed or memory\r
 104    *                                             is not aligned on 2048 boundary.\r
 105    */\r
 106   ErrorCode_t (*Init)(USBD_HANDLE_T* phUsb, USB_CORE_DESCS_T* pDesc, USBD_API_INIT_PARAM_T* param);\r
 107 \r
 108   /** @fn void Connect(USBD_HANDLE_T hUsb, uint32_t con)\r
 109    *  Function to make USB device visible/invisible on the USB bus.\r
 110    *\r
 111    *  This function is called after the USB initialization. This function uses the soft connect\r
 112    *  feature to make the device visible on the USB bus. This function is called only after the\r
 113    *  application is ready to handle the USB data. The enumeration process is started by the\r
 114    *  host after the device detection. The driver handles the enumeration process according to\r
 115    *  the USB descriptors passed in the USB initialization function.\r
 116    *\r
 117    *  @param hUsb Handle to the USB device stack.\r
 118    *  @param con  States whether to connect (1) or to disconnect (0).\r
 119    *  @return Nothing.\r
 120    */\r
 121   void (*Connect)(USBD_HANDLE_T hUsb, uint32_t con);\r
 122 \r
 123   /** @fn void ISR(USBD_HANDLE_T hUsb)\r
 124    *  Function to USB device controller interrupt events.\r
 125    *\r
 126    *  When the user application is active the interrupt handlers are mapped in the user flash\r
 127    *  space. The user application must provide an interrupt handler for the USB interrupt and\r
 128    *  call this function in the interrupt handler routine. The driver interrupt handler takes\r
 129    *  appropriate action according to the data received on the USB bus.\r
 130    *\r
 131    *  @param  hUsb Handle to the USB device stack.\r
 132    *  @return Nothing.\r
 133    */\r
 134   void (*ISR)(USBD_HANDLE_T hUsb);\r
 135 \r
 136   /** @fn void Reset(USBD_HANDLE_T hUsb)\r
 137    *  Function to Reset USB device stack and hardware controller.\r
 138    *\r
 139    *  Reset USB device stack and hardware controller. Disables all endpoints except EP0.\r
 140    *  Clears all pending interrupts and resets endpoint transfer queues.\r
 141    *  This function is called internally by pUsbApi->hw->init() and from reset event.\r
 142    *\r
 143    *  @param  hUsb Handle to the USB device stack.\r
 144    *  @return Nothing.\r
 145    */\r
 146   void  (*Reset)(USBD_HANDLE_T hUsb);\r
 147 \r
 148   /** @fn void ForceFullSpeed(USBD_HANDLE_T hUsb, uint32_t cfg)\r
 149    *  Function to force high speed USB device to operate in full speed mode.\r
 150    *\r
 151    *  This function is useful for testing the behaviour of current device when connected\r
 152    *  to a full speed only hosts.\r
 153    *\r
 154    *  @param hUsb Handle to the USB device stack.\r
 155    *  @param cfg  When 1 - set force full-speed or\r
 156    *                       0 - clear force full-speed.\r
 157    *  @return Nothing.\r
 158    */\r
 159   void  (*ForceFullSpeed )(USBD_HANDLE_T hUsb, uint32_t cfg);\r
 160 \r
 161   /** @fn void WakeUpCfg(USBD_HANDLE_T hUsb, uint32_t cfg)\r
 162    *  Function to configure USB device controller to wakeup host on remote events.\r
 163    *\r
 164    *  This function is called by application layer to configure the USB device controller\r
 165    *  to wakeup on remote events. It is recommended to call this function from users's\r
 166    *  USB_WakeUpCfg() callback routine registered with stack.\r
 167    *  @note User's USB_WakeUpCfg() is registered with stack by setting the USB_WakeUpCfg member \r
 168    *  of USBD_API_INIT_PARAM_T structure before calling pUsbApi->hw->Init() routine.\r
 169    *  Certain USB device controllers needed to keep some clocks always on to generate \r
 170    *  resume signaling through pUsbApi->hw->WakeUp(). This hook is provided to support \r
 171    *  such controllers. In most controllers cases this is an empty routine.\r
 172    *\r
 173    *  @param hUsb Handle to the USB device stack.\r
 174    *  @param cfg  When 1 - Configure controller to wake on remote events or\r
 175    *                       0 - Configure controller not to wake on remote events.\r
 176    *  @return Nothing.\r
 177    */\r
 178   void  (*WakeUpCfg)(USBD_HANDLE_T hUsb, uint32_t  cfg);\r
 179 \r
 180   /** @fn void SetAddress(USBD_HANDLE_T hUsb, uint32_t adr)\r
 181    *  Function to set USB address assigned by host in device controller hardware.\r
 182    *\r
 183    *  This function is called automatically when USB_REQUEST_SET_ADDRESS request is received\r
 184    *  by the stack from USB host.\r
 185    *  This interface is provided to users to invoke this function in other scenarios which are not\r
 186    *  handle by current stack. In most user applications this function is not called directly.\r
 187    *  Also this function can be used by users who are selectively modifying the USB device stack's\r
 188    *  standard handlers through callback interface exposed by the stack.\r
 189    *\r
 190    *  @param hUsb Handle to the USB device stack.\r
 191    *  @param adr  USB bus Address to which the device controller should respond. Usually\r
 192    *                  assigned by the USB host.\r
 193    *  @return Nothing.\r
 194    */\r
 195   void  (*SetAddress)(USBD_HANDLE_T hUsb, uint32_t adr);\r
 196 \r
 197   /** @fn void Configure(USBD_HANDLE_T hUsb, uint32_t cfg)\r
 198    *  Function to configure device controller hardware with selected configuration.\r
 199    *\r
 200    *  This function is called automatically when USB_REQUEST_SET_CONFIGURATION request is received\r
 201    *  by the stack from USB host.\r
 202    *  This interface is provided to users to invoke this function in other scenarios which are not\r
 203    *  handle by current stack. In most user applications this function is not called directly.\r
 204    *  Also this function can be used by users who are selectively modifying the USB device stack's\r
 205    *  standard handlers through callback interface exposed by the stack.\r
 206    *\r
 207    *  @param hUsb Handle to the USB device stack.\r
 208    *  @param cfg  Configuration index.\r
 209    *  @return Nothing.\r
 210    */\r
 211   void  (*Configure)(USBD_HANDLE_T hUsb, uint32_t  cfg);\r
 212 \r
 213   /** @fn void ConfigEP(USBD_HANDLE_T hUsb, USB_ENDPOINT_DESCRIPTOR *pEPD)\r
 214    *  Function to configure USB Endpoint according to descriptor.\r
 215    *\r
 216    *  This function is called automatically when USB_REQUEST_SET_CONFIGURATION request is received\r
 217    *  by the stack from USB host. All the endpoints associated with the selected configuration\r
 218    *  are configured.\r
 219    *  This interface is provided to users to invoke this function in other scenarios which are not\r
 220    *  handle by current stack. In most user applications this function is not called directly.\r
 221    *  Also this function can be used by users who are selectively modifying the USB device stack's\r
 222    *  standard handlers through callback interface exposed by the stack.\r
 223    *\r
 224    *  @param hUsb Handle to the USB device stack.\r
 225    *  @param pEPD Endpoint descriptor structure defined in USB 2.0 specification.\r
 226    *  @return Nothing.\r
 227    */\r
 228   void  (*ConfigEP)(USBD_HANDLE_T hUsb, USB_ENDPOINT_DESCRIPTOR *pEPD);\r
 229 \r
 230   /** @fn void DirCtrlEP(USBD_HANDLE_T hUsb, uint32_t dir)\r
 231    *  Function to set firection for USB control endpoint EP0.\r
 232    *\r
 233    *  This function is called automatically by the stack on need bassis.\r
 234    *  This interface is provided to users to invoke this function in other scenarios which are not\r
 235    *  handle by current stack. In most user applications this function is not called directly.\r
 236    *  Also this function can be used by users who are selectively modifying the USB device stack's\r
 237    *  standard handlers through callback interface exposed by the stack.\r
 238    *\r
 239    *  @param hUsb Handle to the USB device stack.\r
 240    *  @param cfg  When 1 - Set EP0 in IN transfer mode\r
 241    *                       0 - Set EP0 in OUT transfer mode\r
 242    *  @return Nothing.\r
 243    */\r
 244   void  (*DirCtrlEP)(USBD_HANDLE_T hUsb, uint32_t dir);\r
 245 \r
 246   /** @fn void EnableEP(USBD_HANDLE_T hUsb, uint32_t EPNum)\r
 247    *  Function to enable selected USB endpoint.\r
 248    *\r
 249    *  This function enables interrupts on selected endpoint.\r
 250    *\r
 251    *  @param hUsb Handle to the USB device stack.\r
 252    *  @param EPNum  Endpoint number as per USB specification.\r
 253    *                    ie. An EP1_IN is represented by 0x81 number.\r
 254    *  @return Nothing.\r
 255    */\r
 256   void  (*EnableEP)(USBD_HANDLE_T hUsb, uint32_t EPNum);\r
 257 \r
 258   /** @fn void DisableEP(USBD_HANDLE_T hUsb, uint32_t EPNum)\r
 259    *  Function to disable selected USB endpoint.\r
 260    *\r
 261    *  This function disables interrupts on selected endpoint.\r
 262    *\r
 263    *  @param hUsb Handle to the USB device stack.\r
 264    *  @param EPNum  Endpoint number as per USB specification.\r
 265    *                    ie. An EP1_IN is represented by 0x81 number.\r
 266    *  @return Nothing.\r
 267    */\r
 268   void  (*DisableEP)(USBD_HANDLE_T hUsb, uint32_t EPNum);\r
 269 \r
 270   /** @fn void ResetEP(USBD_HANDLE_T hUsb, uint32_t EPNum)\r
 271    *  Function to reset selected USB endpoint.\r
 272    *\r
 273    *  This function flushes the endpoint buffers and resets data toggle logic.\r
 274    *\r
 275    *  @param hUsb Handle to the USB device stack.\r
 276    *  @param EPNum  Endpoint number as per USB specification.\r
 277    *                    ie. An EP1_IN is represented by 0x81 number.\r
 278    *  @return Nothing.\r
 279   */\r
 280   void  (*ResetEP)(USBD_HANDLE_T hUsb, uint32_t EPNum);\r
 281 \r
 282   /** @fn void SetStallEP(USBD_HANDLE_T hUsb, uint32_t EPNum)\r
 283    *  Function to STALL selected USB endpoint.\r
 284    *\r
 285    *  Generates STALL signalling for requested endpoint.\r
 286    *\r
 287    *  @param hUsb Handle to the USB device stack.\r
 288    *  @param EPNum  Endpoint number as per USB specification.\r
 289    *                    ie. An EP1_IN is represented by 0x81 number.\r
 290    *  @return Nothing.\r
 291    */\r
 292   void  (*SetStallEP)(USBD_HANDLE_T hUsb, uint32_t EPNum);\r
 293 \r
 294   /** @fn void ClrStallEP(USBD_HANDLE_T hUsb, uint32_t EPNum)\r
 295    *  Function to clear STALL state for the requested endpoint.\r
 296    *\r
 297    *  This function clears STALL state for the requested endpoint.\r
 298    *\r
 299    *  @param hUsb Handle to the USB device stack.\r
 300    *  @param EPNum  Endpoint number as per USB specification.\r
 301    *                    ie. An EP1_IN is represented by 0x81 number.\r
 302    *  @return Nothing.\r
 303    */\r
 304   void  (*ClrStallEP)(USBD_HANDLE_T hUsb, uint32_t EPNum);\r
 305 \r
 306   /** @fn ErrorCode_t SetTestMode(USBD_HANDLE_T hUsb, uint8_t mode)\r
 307    *  Function to set high speed USB device controller in requested test mode.\r
 308    *\r
 309    *  USB-IF requires the high speed device to be put in various test modes\r
 310    *  for electrical testing. This USB device stack calls this function whenever\r
 311    *  it receives USB_REQUEST_CLEAR_FEATURE request for USB_FEATURE_TEST_MODE.\r
 312    *  Users can put the device in test mode by directly calling this function.\r
 313    *  Returns ERR_USBD_INVALID_REQ when device controller is full-speed only.\r
 314    *\r
 315    *  @param hUsb Handle to the USB device stack.\r
 316    *  @param mode  Test mode defined in USB 2.0 electrical testing specification.\r
 317    *  @return Returns @ref ErrorCode_t type to indicate success or error condition.\r
 318    *          @retval LPC_OK(0) - On success\r
 319    *          @retval ERR_USBD_INVALID_REQ(0x00040001) - Invalid test mode or\r
 320    *                                             Device controller is full-speed only.\r
 321    */\r
 322   ErrorCode_t (*SetTestMode)(USBD_HANDLE_T hUsb, uint8_t mode);\r
 323 \r
 324   /** @fn uint32_t ReadEP(USBD_HANDLE_T hUsb, uint32_t EPNum, uint8_t *pData)\r
 325    *  Function to read data received on the requested endpoint.\r
 326    *\r
 327    *  This function is called by USB stack and the application layer to read the data\r
 328    *  received on the requested endpoint.\r
 329    *\r
 330    *  @param hUsb Handle to the USB device stack.\r
 331    *  @param EPNum  Endpoint number as per USB specification.\r
 332    *                    ie. An EP1_IN is represented by 0x81 number.\r
 333    *  \param[in,out] pData Pointer to the data buffer where data is to be copied.\r
 334    *  @return Returns the number of bytes copied to the buffer.\r
 335    */\r
 336   uint32_t (*ReadEP)(USBD_HANDLE_T hUsb, uint32_t EPNum, uint8_t *pData);\r
 337 \r
 338   /** @fn uint32_t ReadReqEP(USBD_HANDLE_T hUsb, uint32_t EPNum, uint8_t *pData, uint32_t len)\r
 339    *  Function to queue read request on the specified endpoint.\r
 340    *\r
 341    *  This function is called by USB stack and the application layer to queue a read request\r
 342    *  on the specified endpoint.\r
 343    *\r
 344    *  @param hUsb Handle to the USB device stack.\r
 345    *  @param EPNum  Endpoint number as per USB specification.\r
 346    *                    ie. An EP1_IN is represented by 0x81 number.\r
 347    *  \param[in,out] pData Pointer to the data buffer where data is to be copied. This buffer\r
 348    *                       address should be accessible by USB DMA master.\r
 349    *  @param len  Length of the buffer passed.\r
 350    *  @return Returns the length of the requested buffer.\r
 351    */\r
 352   uint32_t (*ReadReqEP)(USBD_HANDLE_T hUsb, uint32_t EPNum, uint8_t *pData, uint32_t len);\r
 353 \r
 354   /** @fn uint32_t ReadSetupPkt(USBD_HANDLE_T hUsb, uint32_t EPNum, uint32_t *pData)\r
 355    *  Function to read setup packet data received on the requested endpoint.\r
 356    *\r
 357    *  This function is called by USB stack and the application layer to read setup packet data\r
 358    *  received on the requested endpoint.\r
 359    *\r
 360    *  @param hUsb Handle to the USB device stack.\r
 361    *  @param EPNum  Endpoint number as per USB specification.\r
 362    *                    ie. An EP0_IN is represented by 0x80 number.\r
 363    *  \param[in,out] pData Pointer to the data buffer where data is to be copied.\r
 364    *  @return Returns the number of bytes copied to the buffer.\r
 365    */\r
 366   uint32_t (*ReadSetupPkt)(USBD_HANDLE_T hUsb, uint32_t EPNum, uint32_t *pData);\r
 367 \r
 368   /** @fn uint32_t WriteEP(USBD_HANDLE_T hUsb, uint32_t EPNum, uint8_t *pData, uint32_t cnt)\r
 369    *  Function to write data to be sent on the requested endpoint.\r
 370    *\r
 371    *  This function is called by USB stack and the application layer to send data\r
 372    *  on the requested endpoint.\r
 373    *\r
 374    *  @param hUsb Handle to the USB device stack.\r
 375    *  @param EPNum  Endpoint number as per USB specification.\r
 376    *                    ie. An EP1_IN is represented by 0x81 number.\r
 377    *  @param pData Pointer to the data buffer from where data is to be copied.\r
 378    *  @param cnt  Number of bytes to write.\r
 379    *  @return Returns the number of bytes written.\r
 380    */\r
 381   uint32_t (*WriteEP)(USBD_HANDLE_T hUsb, uint32_t EPNum, uint8_t *pData, uint32_t cnt);\r
 382 \r
 383   /** @fn void WakeUp(USBD_HANDLE_T hUsb)\r
 384    *  Function to generate resume signaling on bus for remote host wakeup.\r
 385    *\r
 386    *  This function is called by application layer to remotely wakeup host controller \r
 387    *  when system is in suspend state. Application should indicate this remote wakeup\r
 388    *  capability by setting USB_CONFIG_REMOTE_WAKEUP in bmAttributes of Configuration \r
 389    *  Descriptor. Also this routine will generate resume signalling only if host\r
 390    *  enables USB_FEATURE_REMOTE_WAKEUP by sending SET_FEATURE request before suspending\r
 391    *  the bus.\r
 392    *  \r
 393    *  @param hUsb Handle to the USB device stack. \r
 394    *  @return Nothing.\r
 395    */\r
 396   void  (*WakeUp)(USBD_HANDLE_T hUsb);\r
 397 \r
 398   /** @fn void EnableEP(USBD_HANDLE_T hUsb, uint32_t EPNum)\r
 399    *  Function to enable/disable selected USB event.\r
 400    *\r
 401    *  This function enables interrupts on selected endpoint.\r
 402    *  \r
 403    *  @param hUsb Handle to the USB device stack. \r
 404    *  @param EPNum  Endpoint number corresponding to the eventas per USB specification. \r
 405    *                    ie. An EP1_IN is represented by 0x81 number. For device events \r
 406    *                    set this param to 0x0. \r
 407    *  @param event  Type of endpoint event. See @ref USBD_EVENT_T for more details.\r
 408    *  @param enable  1 - enable event, 0 - disable event.\r
 409    *  @return Returns @ref ErrorCode_t type to indicate success or error condition.\r
 410    *          @retval LPC_OK(0) - On success\r
 411    *          @retval ERR_USBD_INVALID_REQ(0x00040001) - Invalid event type.\r
 412    */\r
 413   ErrorCode_t  (*EnableEvent)(USBD_HANDLE_T hUsb, uint32_t EPNum, uint32_t event_type, \r
 414     uint32_t enable);\r
 415 \r
 416 } USBD_HW_API_T;\r
 417 \r
 418 \r
 419 \r
 420 \r
 421 #endif  /* __USBHW_H__ */\r