git.sur5r.net Git - freertos/blob

   1 /*\r
   2  * @brief Definition of functions exported by ROM based CDC function driver\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_cdc.h"\r
  35 \r
  36 #ifndef __CDCUSER_H__\r
  37 #define __CDCUSER_H__\r
  38 \r
  39 \r
  40 /** @ingroup Group_USBD_Class\r
  41  *  @defgroup USBD_CDC Communication Device Class (CDC) Function Driver\r
  42  *  @section Sec_CDCModDescription Module Description\r
  43  *  CDC Class Function Driver module. This module contains an internal implementation of the USB CDC Class.\r
  44  *  User applications can use this class driver instead of implementing the CDC class manually\r
  45  *  via the low-level USBD_HW and USBD_Core APIs.\r
  46  *\r
  47  *  This module is designed to simplify the user code by exposing only the required interface needed to interface with\r
  48  *  Devices using the USB CDC Class.\r
  49  */\r
  50 \r
  51 /*----------------------------------------------------------------------------\r
  52   We need a buffer for incomming data on USB port because USB receives\r
  53   much faster than  UART transmits\r
  54  *---------------------------------------------------------------------------*/\r
  55 /* Buffer masks */\r
  56 #define CDC_BUF_SIZE               (128)               /* Output buffer in bytes (power 2) */\r
  57                                                        /* large enough for file transfer */\r
  58 #define CDC_BUF_MASK               (CDC_BUF_SIZE-1ul)\r
  59 \r
  60 /** @brief Communication Device Class function driver initilization parameter data structure.\r
  61  *  @ingroup USBD_CDC\r
  62  *\r
  63  *  @details  This data structure is used to pass initialization parameters to the \r
  64  *  Communication Device Class function driver's init function.\r
  65  *\r
  66  */\r
  67 typedef struct USBD_CDC_INIT_PARAM\r
  68 {\r
  69   /* memory allocation params */\r
  70   uint32_t mem_base;  /**< Base memory location from where the stack can allocate\r
  71                       data and buffers. @note The memory address set in this field\r
  72                       should be accessible by USB DMA controller. Also this value\r
  73                       should be aligned on 4 byte boundary.\r
  74                       */\r
  75   uint32_t mem_size;  /**< The size of memory buffer which stack can use. \r
  76                       @note The \em mem_size should be greater than the size \r
  77                       returned by USBD_CDC_API::GetMemSize() routine.*/\r
  78   /** Pointer to the control interface descriptor within the descriptor\r
  79   * array (\em high_speed_desc) passed to Init() through @ref USB_CORE_DESCS_T \r
  80   * structure. The stack assumes both HS and FS use same BULK endpoints. \r
  81   */\r
  82   uint8_t* cif_intf_desc;\r
  83   /** Pointer to the data interface descriptor within the descriptor\r
  84   * array (\em high_speed_desc) passed to Init() through @ref USB_CORE_DESCS_T \r
  85   * structure. The stack assumes both HS and FS use same BULK endpoints. \r
  86   */\r
  87   uint8_t* dif_intf_desc;\r
  88 \r
  89   /* user defined functions */\r
  90 \r
  91   /* required functions */\r
  92   /** \r
  93   *  Communication Interface Class specific get request callback function.\r
  94   *\r
  95   *  This function is provided by the application software. This function gets called \r
  96   *  when host sends CIC management element get requests. The setup packet data (\em pSetup)\r
  97   *  is passed to the callback so that application can extract the CIC request type\r
  98   *  and other associated data. By default the stack will ssign \em pBuffer pointer\r
  99   *  to \em EP0Buff allocated at init. The application code can directly write data \r
 100   *  into this buffer as long as data is less than 64 byte. If more data has to be sent \r
 101   *  then application code should update \em pBuffer pointer and length accordingly.\r
 102   *   \r
 103   *  \r
 104   *  @param hCdc Handle to CDC function driver. \r
 105   *  @param pSetup Pointer to setup packet recived from host. \r
 106   *  @param pBuffer  Pointer to a pointer of data buffer containing request data. \r
 107   *                       Pointer-to-pointer is used to implement zero-copy buffers.\r
 108   *  @param length  Amount of data to be sent back to host.\r
 109   *  @return The call back should returns @ref ErrorCode_t type to indicate success or error condition.\r
 110   *          @retval LPC_OK On success.\r
 111   *          @retval ERR_USBD_UNHANDLED  Event is not handled hence pass the event to next in line. \r
 112   *          @retval ERR_USBD_xxx  For other error conditions. \r
 113   *                                             \r
 114   */\r
 115   ErrorCode_t (*CIC_GetRequest)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t** pBuffer, uint16_t* length); \r
 116   \r
 117   /** \r
 118   *  Communication Interface Class specific set request callback function.\r
 119   *\r
 120   *  This function is provided by the application software. This function gets called \r
 121   *  when host sends a CIC management element requests. The setup packet data (\em pSetup)\r
 122   *  is passed to the callback so that application can extract the CIC request type\r
 123   *  and other associated data. If a set request has data associated, then this callback\r
 124   *  is called twice. \r
 125   *  (1) First when setup request is recived, at this time application code could update\r
 126   *  \em pBuffer pointer to point to the intended destination. The length param is set to 0\r
 127   *  so that application code knows this is first time. By default the stack will\r
 128   *  assign \em pBuffer pointer to \em EP0Buff allocated at init. Note, if data length is \r
 129   *  greater than 64 bytes and application code doesn't update \em pBuffer pointer the \r
 130   *  stack will send STALL condition to host.\r
 131   *  (2) Second when the data is recived from the host. This time the length param is set\r
 132   *  with number of data bytes recived.\r
 133   *  \r
 134   *  @param hCdc Handle to CDC function driver. \r
 135   *  @param pSetup Pointer to setup packet recived from host. \r
 136   *  @param pBuffer  Pointer to a pointer of data buffer containing request data. \r
 137   *                       Pointer-to-pointer is used to implement zero-copy buffers.\r
 138   *  @param length  Amount of data copied to destination buffer.\r
 139   *  @return The call back should returns @ref ErrorCode_t type to indicate success or error condition.\r
 140   *          @retval LPC_OK On success.\r
 141   *          @retval ERR_USBD_UNHANDLED  Event is not handled hence pass the event to next in line. \r
 142   *          @retval ERR_USBD_xxx  For other error conditions. \r
 143   *                                             \r
 144   */\r
 145   ErrorCode_t (*CIC_SetRequest)( USBD_HANDLE_T hCdc, USB_SETUP_PACKET* pSetup, uint8_t** pBuffer, uint16_t length);\r
 146 \r
 147   /** \r
 148   *  Communication Device Class specific BULK IN endpoint handler.\r
 149   *\r
 150   *  The application software should provide the BULK IN endpoint handler.\r
 151   *  Applications should transfer data depending on the communication protocol type set in descriptors. \r
 152   *  \n\r
 153   *  @note \r
 154   *  \r
 155   *  @param hUsb Handle to the USB device stack. \r
 156   *  @param data Pointer to the data which will be passed when callback function is called by the stack. \r
 157   *  @param event  Type of endpoint event. See @ref USBD_EVENT_T for more details.\r
 158   *  @return The call back should returns @ref ErrorCode_t type to indicate success or error condition.\r
 159   *          @retval LPC_OK On success.\r
 160   *          @retval ERR_USBD_UNHANDLED  Event is not handled hence pass the event to next in line. \r
 161   *          @retval ERR_USBD_xxx  For other error conditions. \r
 162   *                                             \r
 163   */\r
 164   ErrorCode_t (*CDC_BulkIN_Hdlr) (USBD_HANDLE_T hUsb, void* data, uint32_t event);\r
 165 \r
 166   /** \r
 167   *  Communication Device Class specific BULK OUT endpoint handler.\r
 168   *\r
 169   *  The application software should provide the BULK OUT endpoint handler.\r
 170   *  Applications should transfer data depending on the communication protocol type set in descriptors. \r
 171   *  \n\r
 172   *  @note \r
 173   *  \r
 174   *  @param hUsb Handle to the USB device stack. \r
 175   *  @param data Pointer to the data which will be passed when callback function is called by the stack. \r
 176   *  @param event  Type of endpoint event. See @ref USBD_EVENT_T for more details.\r
 177   *  @return The call back should returns @ref ErrorCode_t type to indicate success or error condition.\r
 178   *          @retval LPC_OK On success.\r
 179   *          @retval ERR_USBD_UNHANDLED  Event is not handled hence pass the event to next in line. \r
 180   *          @retval ERR_USBD_xxx  For other error conditions. \r
 181   *                                             \r
 182   */\r
 183   ErrorCode_t (*CDC_BulkOUT_Hdlr) (USBD_HANDLE_T hUsb, void* data, uint32_t event);\r
 184 \r
 185   ErrorCode_t (*SendEncpsCmd) (USBD_HANDLE_T hCDC, uint8_t* buffer, uint16_t len);\r
 186   ErrorCode_t (*GetEncpsResp) (USBD_HANDLE_T hCDC, uint8_t** buffer, uint16_t* len);\r
 187   ErrorCode_t (*SetCommFeature) (USBD_HANDLE_T hCDC, uint16_t feature, uint8_t* buffer, uint16_t len);\r
 188   ErrorCode_t (*GetCommFeature) (USBD_HANDLE_T hCDC, uint16_t feature, uint8_t** pBuffer, uint16_t* len);\r
 189   ErrorCode_t (*ClrCommFeature) (USBD_HANDLE_T hCDC, uint16_t feature);\r
 190   ErrorCode_t (*SetCtrlLineState) (USBD_HANDLE_T hCDC, uint16_t state);\r
 191   ErrorCode_t (*SendBreak) (USBD_HANDLE_T hCDC, uint16_t mstime);\r
 192   ErrorCode_t (*SetLineCode) (USBD_HANDLE_T hCDC, CDC_LINE_CODING* line_coding);\r
 193 \r
 194   /** \r
 195   *  Optional Communication Device Class specific INTERRUPT IN endpoint handler.\r
 196   *\r
 197   *  The application software should provide the INT IN endpoint handler.\r
 198   *  Applications should transfer data depending on the communication protocol type set in descriptors. \r
 199   *  \n\r
 200   *  @note \r
 201   *  \r
 202   *  @param hUsb Handle to the USB device stack. \r
 203   *  @param data Pointer to the data which will be passed when callback function is called by the stack. \r
 204   *  @param event  Type of endpoint event. See @ref USBD_EVENT_T for more details.\r
 205   *  @return The call back should returns @ref ErrorCode_t type to indicate success or error condition.\r
 206   *          @retval LPC_OK On success.\r
 207   *          @retval ERR_USBD_UNHANDLED  Event is not handled hence pass the event to next in line. \r
 208   *          @retval ERR_USBD_xxx  For other error conditions. \r
 209   *                                             \r
 210   */\r
 211   ErrorCode_t (*CDC_InterruptEP_Hdlr) (USBD_HANDLE_T hUsb, void* data, uint32_t event);\r
 212 \r
 213   /** \r
 214   *  Optional user overridable function to replace the default CDC class handler.\r
 215   *\r
 216   *  The application software could override the default EP0 class handler with their\r
 217   *  own by providing the handler function address as this data member of the parameter\r
 218   *  structure. Application which like the default handler should set this data member\r
 219   *  to zero before calling the USBD_CDC_API::Init().\r
 220   *  \n\r
 221   *  @note \r
 222   *  \r
 223   *  @param hUsb Handle to the USB device stack. \r
 224   *  @param data Pointer to the data which will be passed when callback function is called by the stack. \r
 225   *  @param event  Type of endpoint event. See @ref USBD_EVENT_T for more details.\r
 226   *  @return The call back should returns @ref ErrorCode_t type to indicate success or error condition.\r
 227   *          @retval LPC_OK On success.\r
 228   *          @retval ERR_USBD_UNHANDLED  Event is not handled hence pass the event to next in line. \r
 229   *          @retval ERR_USBD_xxx  For other error conditions. \r
 230   *                                             \r
 231   */\r
 232   ErrorCode_t (*CDC_Ep0_Hdlr) (USBD_HANDLE_T hUsb, void* data, uint32_t event);\r
 233 \r
 234 } USBD_CDC_INIT_PARAM_T;\r
 235 \r
 236 /** @brief CDC class API functions structure.\r
 237  *  @ingroup USBD_CDC\r
 238  *\r
 239  *  This module exposes functions which interact directly with USB device controller hardware.\r
 240  *\r
 241  */\r
 242 typedef struct USBD_CDC_API\r
 243 {\r
 244   /** @fn uint32_t GetMemSize(USBD_CDC_INIT_PARAM_T* param)\r
 245    *  Function to determine the memory required by the CDC function driver module.\r
 246    * \r
 247    *  This function is called by application layer before calling pUsbApi->CDC->Init(), to allocate memory used \r
 248    *  by CDC function driver module. The application should allocate the memory which is accessible by USB\r
 249    *  controller/DMA controller. \r
 250    *  @note Some memory areas are not accessible by all bus masters.\r
 251    *\r
 252    *  @param param Structure containing CDC function driver module initialization parameters.\r
 253    *  @return Returns the required memory size in bytes.\r
 254    */\r
 255   uint32_t (*GetMemSize)(USBD_CDC_INIT_PARAM_T* param);\r
 256   \r
 257   /** @fn ErrorCode_t init(USBD_HANDLE_T hUsb, USBD_CDC_INIT_PARAM_T* param)\r
 258    *  Function to initialize CDC function driver module.\r
 259    * \r
 260    *  This fuction is called by application layer to initialize CDC function driver module. \r
 261    *\r
 262    *  @param hUsb Handle to the USB device stack. \r
 263    *  @param param Structure containing CDC function driver module initialization parameters.\r
 264    *  @return Returns @ref ErrorCode_t type to indicate success or error condition.\r
 265    *          @retval LPC_OK On success\r
 266    *          @retval ERR_USBD_BAD_MEM_BUF  Memory buffer passed is not 4-byte \r
 267    *              aligned or smaller than required. \r
 268    *          @retval ERR_API_INVALID_PARAM2 Either CDC_Write() or CDC_Read() or\r
 269    *              CDC_Verify() callbacks are not defined. \r
 270    *          @retval ERR_USBD_BAD_INTF_DESC  Wrong interface descriptor is passed. \r
 271    *          @retval ERR_USBD_BAD_EP_DESC  Wrong endpoint descriptor is passed. \r
 272    */\r
 273   ErrorCode_t (*init)(USBD_HANDLE_T hUsb, USBD_CDC_INIT_PARAM_T* param, USBD_HANDLE_T* phCDC);\r
 274 \r
 275   /** @fn ErrorCode_t SendNotification(USBD_HANDLE_T hCdc, uint8_t bNotification, uint16_t data)\r
 276    *  Function to initialize CDC function driver module.\r
 277    * \r
 278    *  This fuction is called by application layer to initialize CDC function driver module. \r
 279    *\r
 280    *  @param hUsb Handle to the USB device stack. \r
 281    *  @param param Structure containing CDC function driver module initialization parameters.\r
 282    *  @return Returns @ref ErrorCode_t type to indicate success or error condition.\r
 283    *          @retval LPC_OK On success\r
 284    *          @retval ERR_USBD_BAD_MEM_BUF  Memory buffer passed is not 4-byte \r
 285    *              aligned or smaller than required. \r
 286    *          @retval ERR_API_INVALID_PARAM2 Either CDC_Write() or CDC_Read() or\r
 287    *              CDC_Verify() callbacks are not defined. \r
 288    *          @retval ERR_USBD_BAD_INTF_DESC  Wrong interface descriptor is passed. \r
 289    *          @retval ERR_USBD_BAD_EP_DESC  Wrong endpoint descriptor is passed. \r
 290    */\r
 291   ErrorCode_t (*SendNotification)(USBD_HANDLE_T hCdc, uint8_t bNotification, uint16_t data);\r
 292 \r
 293 } USBD_CDC_API_T;\r
 294 \r
 295 /*-----------------------------------------------------------------------------\r
 296  *  Private functions & structures prototypes\r
 297  *-----------------------------------------------------------------------------*/\r
 298 /** @cond  ADVANCED_API */\r
 299 \r
 300 typedef struct _CDC_CTRL_T\r
 301 {\r
 302   USB_CORE_CTRL_T*  pUsbCtrl;\r
 303   /* notification buffer */\r
 304   uint8_t notice_buf[12];\r
 305   CDC_LINE_CODING line_coding;\r
 306  \r
 307   uint8_t cif_num;                 /* control interface number */\r
 308   uint8_t dif_num;                 /* data interface number */\r
 309   uint8_t epin_num;                /* BULK IN endpoint number */\r
 310   uint8_t epout_num;               /* BULK OUT endpoint number */\r
 311   uint8_t epint_num;               /* Interrupt IN endpoint number */\r
 312 \r
 313   /* user defined functions */\r
 314   ErrorCode_t (*SendEncpsCmd) (USBD_HANDLE_T hCDC, uint8_t* buffer, uint16_t len);\r
 315   ErrorCode_t (*GetEncpsResp) (USBD_HANDLE_T hCDC, uint8_t** buffer, uint16_t* len);\r
 316   ErrorCode_t (*SetCommFeature) (USBD_HANDLE_T hCDC, uint16_t feature, uint8_t* buffer, uint16_t len);\r
 317   ErrorCode_t (*GetCommFeature) (USBD_HANDLE_T hCDC, uint16_t feature, uint8_t** pBuffer, uint16_t* len);\r
 318   ErrorCode_t (*ClrCommFeature) (USBD_HANDLE_T hCDC, uint16_t feature);\r
 319   ErrorCode_t (*SetCtrlLineState) (USBD_HANDLE_T hCDC, uint16_t state);\r
 320   ErrorCode_t (*SendBreak) (USBD_HANDLE_T hCDC, uint16_t state);\r
 321   ErrorCode_t (*SetLineCode) (USBD_HANDLE_T hCDC, CDC_LINE_CODING* line_coding);\r
 322 \r
 323   /* virtual functions */\r
 324   ErrorCode_t (*CIC_GetRequest)( USBD_HANDLE_T hCdc, USB_SETUP_PACKET* pSetup, uint8_t** pBuffer, uint16_t* length);\r
 325   ErrorCode_t (*CIC_SetRequest)( USBD_HANDLE_T hCdc, USB_SETUP_PACKET* pSetup, uint8_t** pBuffer, uint16_t length);\r
 326 \r
 327 }USB_CDC_CTRL_T;\r
 328 \r
 329 \r
 330 /** @endcond */\r
 331 \r
 332 void UsbdCdc_IO_Buffer_Sync_Task(void);\r
 333 void UsbdCdc_SendData(uint8_t* buffer, uint32_t cnt);\r
 334 uint32_t UsbdCdc_RecvData(uint8_t* buffer, uint32_t len);\r
 335 \r
 336 \r
 337 #endif  /* __CDCUSER_H__ */\r
 338 \r