git.sur5r.net Git - armstart-ibdap/blob - inc/usbd/usbd_dfuuser.h

   1 /***********************************************************************\r
   2 * $Id:: mw_usbd_dfuuser.h 331 2012-08-09 18:54:34Z usb10131                   $\r
   3 *\r
   4 * Project: USB device ROM Stack\r
   5 *\r
   6 * Description:\r
   7 *     Device Firmware Upgrade Class Custom User Module Definitions.\r
   8 *\r
   9 ***********************************************************************\r
  10 *   Copyright(C) 2011, NXP Semiconductor\r
  11 *   All rights reserved.\r
  12 *\r
  13 * Software that is described herein is for illustrative purposes only\r
  14 * which provides customers with programming information regarding the\r
  15 * products. This software is supplied "AS IS" without any warranties.\r
  16 * NXP Semiconductors assumes no responsibility or liability for the\r
  17 * use of the software, conveys no license or title under any patent,\r
  18 * copyright, or mask work right to the product. NXP Semiconductors\r
  19 * reserves the right to make changes in the software without\r
  20 * notification. NXP Semiconductors also make no representation or\r
  21 * warranty that such application will be suitable for the specified\r
  22 * use without further testing or modification.\r
  23 **********************************************************************/\r
  24 \r
  25 #ifndef __DFUUSER_H__\r
  26 #define __DFUUSER_H__\r
  27 \r
  28 #include "usbd.h"\r
  29 #include "usbd_dfu.h"\r
  30 #include "usbd_core.h"\r
  31 \r
  32 /** \file\r
  33  *  \brief Device Firmware Upgrade (DFU) API structures and function prototypes.\r
  34  *\r
  35  *  Definition of functions exported by ROM based DFU function driver.\r
  36  *\r
  37  */\r
  38 \r
  39 \r
  40 /** \ingroup Group_USBD\r
  41  *  @defgroup USBD_DFU Device Firmware Upgrade (DFU) Class Function Driver\r
  42  *  \section Sec_MSCModDescription Module Description\r
  43  *  DFU Class Function Driver module. This module contains an internal implementation of the USB DFU Class.\r
  44  *  User applications can use this class driver instead of implementing the DFU 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 DFU Class.\r
  49  */\r
  50 \r
  51 /** \brief USB descriptors data structure.\r
  52  *  \ingroup USBD_DFU\r
  53  *\r
  54  *  \details  This module exposes functions which interact directly with USB device stack's core layer.\r
  55  *  The application layer uses this component when it has to implement custom class function driver or \r
  56  *  standard class function driver which is not part of the current USB device stack.\r
  57  *  The functions exposed by this interface are to register class specific EP0 handlers and corresponding\r
  58  *  utility functions to manipulate EP0 state machine of the stack. This interface also exposes\r
  59  *  function to register custom endpoint interrupt handler.\r
  60  *\r
  61  */\r
  62 typedef struct USBD_DFU_INIT_PARAM\r
  63 {\r
  64   /* memory allocation params */\r
  65   uint32_t mem_base;  /**< Base memory location from where the stack can allocate\r
  66                       data and buffers. \note The memory address set in this field\r
  67                       should be accessible by USB DMA controller. Also this value\r
  68                       should be aligned on 4 byte boundary.\r
  69                       */\r
  70   uint32_t mem_size;  /**< The size of memory buffer which stack can use. \r
  71                       \note The \em mem_size should be greater than the size \r
  72                       returned by USBD_DFU_API::GetMemSize() routine.*/\r
  73   /* DFU paramas */\r
  74   uint16_t wTransferSize; /**< DFU transfer block size in number of bytes.\r
  75                           This value should match the value set in DFU descriptor\r
  76                           provided as part of the descriptor array \r
  77                           (\em high_speed_desc) passed to Init() through \r
  78                           \ref USB_CORE_DESCS_T structure.  */\r
  79 \r
  80   uint16_t pad;\r
  81   /** Pointer to the DFU interface descriptor within the descriptor\r
  82   * array (\em high_speed_desc) passed to Init() through \ref USB_CORE_DESCS_T \r
  83   * structure.  \r
  84   */\r
  85   uint8_t* intf_desc;\r
  86   /* user defined functions */\r
  87   /** \r
  88   *  DFU Write callback function.\r
  89   *\r
  90   *  This function is provided by the application software. This function gets called \r
  91   *  when host sends a write command. For application using zero-copy buffer scheme\r
  92   *  this function is called for the first time with \em length parameter set to 0.\r
  93   *  The application code should update the buffer pointer.\r
  94   *  \r
  95   *  \param[in] block_num Destination start address. \r
  96   *  \param[in, out] src  Pointer to a pointer to the source of data. Pointer-to-pointer\r
  97   *                     is used to implement zero-copy buffers. See \ref USBD_ZeroCopy\r
  98   *                     for more details on zero-copy concept.\r
  99   *  \param[out] bwPollTimeout  Pointer to a 3 byte buffer which the callback implementer\r
 100   *                     should fill with the amount of minimum time, in milliseconds, \r
 101   *                     that the host should wait before sending a subsequent\r
 102   *                     DFU_GETSTATUS request. \r
 103   *  \param[in] length  Number of bytes to be written.\r
 104   *  \return Returns DFU_STATUS_ values defined in mw_usbd_dfu.h. \r
 105   *                                             \r
 106   */\r
 107   uint8_t (*DFU_Write)( uint32_t block_num, uint8_t** src, uint32_t length, uint8_t* bwPollTimeout);\r
 108 \r
 109   /** \r
 110   *  DFU Read callback function.\r
 111   *\r
 112   *  This function is provided by the application software. This function gets called \r
 113   *  when host sends a read command.\r
 114   *  \r
 115   *  \param[in] block_num Destination start address. \r
 116   *  \param[in, out] dst  Pointer to a pointer to the source of data. Pointer-to-pointer\r
 117   *                       is used to implement zero-copy buffers. See \ref USBD_ZeroCopy\r
 118   *                       for more details on zero-copy concept.\r
 119   *  \param[in] length  Amount of data copied to destination buffer.\r
 120   *  \return Returns \r
 121   *                 - DFU_STATUS_ values defined in mw_usbd_dfu.h to return error conditions. \r
 122   *                 - 0 if there is no more data to be read. Stack will send EOF frame and set \r
 123   *                     DFU state-machine to dfuIdle state.\r
 124   *                 - length of the data copied, should be greater than or equal to 16. If the data copied\r
 125   *                   is less than DFU \em wTransferSize the stack will send EOF frame and \r
 126   *                   goes to dfuIdle state.\r
 127   *                                             \r
 128   */\r
 129   uint32_t (*DFU_Read)( uint32_t block_num, uint8_t** dst, uint32_t length);\r
 130 \r
 131   /** \r
 132   *  DFU done callback function.\r
 133   *\r
 134   *  This function is provided by the application software. This function gets called \r
 135   *  after firmware download completes.\r
 136   *  \r
 137   *  \return Nothing. \r
 138   *                                             \r
 139   */\r
 140   void (*DFU_Done)(void);\r
 141 \r
 142   /** \r
 143   *  DFU detach callback function.\r
 144   *\r
 145   *  This function is provided by the application software. This function gets called \r
 146   *  after USB_REQ_DFU_DETACH is received. Applications which set USB_DFU_WILL_DETACH\r
 147   *  bit in DFU descriptor should define this function. As part of this function\r
 148   *  application can call Connect() routine to disconnect and then connect back with \r
 149   *  host. For application which rely on WinUSB based host application should use this\r
 150   *  feature since USB reset can be invoked only by kernel drivers on Windows host. \r
 151   *  By implementing this feature host doen't have to issue reset instead the device\r
 152   *  has to do it automatically by disconnect and connect procedure.\r
 153   *  \r
 154   *  \param[in] hUsb Handle DFU control structure. \r
 155   *  \return Nothing. \r
 156   *                                             \r
 157   */\r
 158   void (*DFU_Detach)(USBD_HANDLE_T hUsb);\r
 159 \r
 160   /** \r
 161   *  Optional user override-able function to replace the default DFU class handler.\r
 162   *\r
 163   *  The application software could override the default EP0 class handler with their\r
 164   *  own by providing the handler function address as this data member of the parameter\r
 165   *  structure. Application which like the default handler should set this data member\r
 166   *  to zero before calling the USBD_DFU_API::Init().\r
 167   *  \n\r
 168   *  \note \r
 169   *  \r
 170   *  \param[in] hUsb Handle to the USB device stack. \r
 171   *  \param[in] data Pointer to the data which will be passed when callback function is called by the stack. \r
 172   *  \param[in] event  Type of endpoint event. See \ref USBD_EVENT_T for more details.\r
 173   *  \return The call back should returns \ref ErrorCode_t type to indicate success or error condition.\r
 174   *          \retval LPC_OK On success.\r
 175   *          \retval ERR_USBD_UNHANDLED  Event is not handled hence pass the event to next in line. \r
 176   *          \retval ERR_USBD_xxx  For other error conditions. \r
 177   *                                             \r
 178   */\r
 179   ErrorCode_t (*DFU_Ep0_Hdlr) (USBD_HANDLE_T hUsb, void* data, uint32_t event);\r
 180 \r
 181 } USBD_DFU_INIT_PARAM_T;\r
 182 \r
 183 \r
 184 /** \brief DFU class API functions structure.\r
 185  *  \ingroup USBD_DFU\r
 186  *\r
 187  *  This module exposes functions which interact directly with USB device controller hardware.\r
 188  *\r
 189  */\r
 190 typedef struct USBD_DFU_API\r
 191 {\r
 192   /** \fn uint32_t GetMemSize(USBD_DFU_INIT_PARAM_T* param)\r
 193    *  Function to determine the memory required by the DFU function driver module.\r
 194    * \r
 195    *  This function is called by application layer before calling pUsbApi->dfu->Init(), to allocate memory used \r
 196    *  by DFU function driver module. The application should allocate the memory which is accessible by USB\r
 197    *  controller/DMA controller. \r
 198    *  \note Some memory areas are not accessible by all bus masters.\r
 199    *\r
 200    *  \param[in] param Structure containing DFU function driver module initialization parameters.\r
 201    *  \return Returns the required memory size in bytes.\r
 202    */\r
 203   uint32_t (*GetMemSize)(USBD_DFU_INIT_PARAM_T* param);\r
 204 \r
 205   /** \fn ErrorCode_t init(USBD_HANDLE_T hUsb, USBD_DFU_INIT_PARAM_T* param)\r
 206    *  Function to initialize DFU function driver module.\r
 207    * \r
 208    *  This function is called by application layer to initialize DFU function driver module. \r
 209    *\r
 210    *  \param[in] hUsb Handle to the USB device stack. \r
 211    *  \param[in, out] param Structure containing DFU function driver module initialization parameters.\r
 212    *  \return Returns \ref ErrorCode_t type to indicate success or error condition.\r
 213    *          \retval LPC_OK On success\r
 214    *          \retval ERR_USBD_BAD_MEM_BUF  Memory buffer passed is not 4-byte aligned or smaller than required. \r
 215    *          \retval ERR_API_INVALID_PARAM2 Either DFU_Write() or DFU_Done() or DFU_Read() call-backs are not defined.\r
 216    *          \retval ERR_USBD_BAD_DESC  \r
 217    *            - USB_DFU_DESCRIPTOR_TYPE is not defined immediately after \r
 218    *              interface descriptor.\r
 219    *            - wTransferSize in descriptor doesn't match the value passed \r
 220    *              in param->wTransferSize.\r
 221    *            - DFU_Detach() is not defined while USB_DFU_WILL_DETACH is set \r
 222    *              in DFU descriptor.\r
 223    *          \retval ERR_USBD_BAD_INTF_DESC  Wrong interface descriptor is passed. \r
 224    */\r
 225   ErrorCode_t (*init)(USBD_HANDLE_T hUsb, USBD_DFU_INIT_PARAM_T* param, uint32_t init_state);\r
 226 \r
 227 } USBD_DFU_API_T;\r
 228 \r
 229 /*-----------------------------------------------------------------------------\r
 230  *  Private functions & structures prototypes\r
 231  *-----------------------------------------------------------------------------*/\r
 232 /** @cond  ADVANCED_API */\r
 233 \r
 234 typedef struct _USBD_DFU_CTRL_T\r
 235 {\r
 236   /*ALIGNED(4)*/ DFU_STATUS_T dfu_req_get_status;\r
 237   uint16_t pad;\r
 238   uint8_t dfu_state;\r
 239   uint8_t dfu_status;\r
 240   uint8_t download_done;\r
 241   uint8_t if_num;                  /* interface number */\r
 242 \r
 243   uint8_t* xfr_buf;\r
 244   USB_DFU_FUNC_DESCRIPTOR* dfu_desc;\r
 245 \r
 246   USB_CORE_CTRL_T*  pUsbCtrl;\r
 247   /* user defined functions */\r
 248   /* return DFU_STATUS_ values defined in mw_usbd_dfu.h */\r
 249   uint8_t (*DFU_Write)( uint32_t block_num, uint8_t** src, uint32_t length, uint8_t* bwPollTimeout);\r
 250   /* return \r
 251   * DFU_STATUS_ : values defined in mw_usbd_dfu.h in case of errors\r
 252   * 0 : If end of memory reached\r
 253   * length : Amount of data copied to destination buffer\r
 254   */\r
 255   uint32_t (*DFU_Read)( uint32_t block_num, uint8_t** dst, uint32_t length);\r
 256   /* callback called after download is finished */\r
 257   void (*DFU_Done)(void);\r
 258   /* callback called after USB_REQ_DFU_DETACH is recived */\r
 259   void (*DFU_Detach)(USBD_HANDLE_T hUsb);\r
 260 \r
 261 } USBD_DFU_CTRL_T;\r
 262 \r
 263 /** @cond  DIRECT_API */\r
 264 uint32_t mwDFU_GetMemSize(USBD_DFU_INIT_PARAM_T* param);\r
 265 extern ErrorCode_t mwDFU_init(USBD_HANDLE_T hUsb, USBD_DFU_INIT_PARAM_T* param, uint32_t init_state);\r
 266 /** @endcond */\r
 267 \r
 268 /** @endcond */\r
 269 \r
 270 #endif  /* __DFUUSER_H__ */\r