[freertos] /

/*\r
 * @brief Definition of functions exported by ROM based DFU function driver\r
 *\r
 * @note\r
 * Copyright(C) NXP Semiconductors, 2012\r
  * All rights reserved.\r
 *\r
 * @par\r
 * Software that is described herein is for illustrative purposes only\r
 * which provides customers with programming information regarding the\r
 * LPC products.  This software is supplied "AS IS" without any warranties of\r
 * any kind, and NXP Semiconductors and its licensor disclaim any and\r
 * all warranties, express or implied, including all implied warranties of\r
 * merchantability, fitness for a particular purpose and non-infringement of\r
 * intellectual property rights.  NXP Semiconductors assumes no responsibility\r
 * or liability for the use of the software, conveys no license or rights under any\r
 * patent, copyright, mask work right, or any other intellectual property rights in\r
 * or to any products. NXP Semiconductors reserves the right to make changes\r
 * in the software without notification. NXP Semiconductors also makes no\r
 * representation or warranty that such application will be suitable for the\r
 * specified use without further testing or modification.\r
 *\r
 * @par\r
 * Permission to use, copy, modify, and distribute this software and its\r
 * documentation is hereby granted, under NXP Semiconductors' and its\r
 * licensor's relevant copyrights in the software, without fee, provided that it\r
 * is used in conjunction with NXP Semiconductors microcontrollers.  This\r
 * copyright, permission, and disclaimer notice must appear in all copies of\r
 * this code.\r
 */\r
\r
#ifndef __DFUUSER_H__\r
#define __DFUUSER_H__\r
\r
#include "usbd.h"\r
#include "usbd_dfu.h"\r
#include "usbd_core.h"\r
\r
\r
/** @ingroup Group_USBD_Class\r
 *  @defgroup USBD_DFU Device Firmware Upgrade (DFU) Class Function Driver\r
 *  @section Sec_MSCModDescription Module Description\r
 *  DFU Class Function Driver module. This module contains an internal implementation of the USB DFU Class.\r
 *  User applications can use this class driver instead of implementing the DFU class manually\r
 *  via the low-level USBD_HW and USBD_Core APIs.\r
 *\r
 *  This module is designed to simplify the user code by exposing only the required interface needed to interface with\r
 *  Devices using the USB DFU Class.\r
 */\r
\r
/** @brief USB descriptors data structure.\r
 *  @ingroup USBD_DFU\r
 *\r
 *  @details  This module exposes functions which interact directly with USB device stack's core layer.\r
 *  The application layer uses this component when it has to implement custom class function driver or\r
 *  standard class function driver which is not part of the current USB device stack.\r
 *  The functions exposed by this interface are to register class specific EP0 handlers and corresponding\r
 *  utility functions to manipulate EP0 state machine of the stack. This interface also exposes\r
 *  function to register custom endpoint interrupt handler.\r
 *\r
 */\r
typedef struct USBD_DFU_INIT_PARAM\r
{\r
  /* memory allocation params */\r
  uint32_t mem_base;  /**< Base memory location from where the stack can allocate\r
                      data and buffers. @note The memory address set in this field\r
                      should be accessible by USB DMA controller. Also this value\r
                      should be aligned on 4 byte boundary.\r
                      */\r
  uint32_t mem_size;  /**< The size of memory buffer which stack can use.\r
                      @note The \em mem_size should be greater than the size\r
                      returned by USBD_DFU_API::GetMemSize() routine.*/\r
  /* DFU paramas */\r
  uint16_t wTransferSize; /**< DFU transfer block size in number of bytes.\r
                          This value should match the value set in DFU descriptor\r
                          provided as part of the descriptor array\r
                          (\em high_speed_desc) passed to Init() through\r
                          @ref USB_CORE_DESCS_T structure.  */\r
\r
  /** Pointer to the DFU interface descriptor within the descriptor\r
  * array (\em high_speed_desc) passed to Init() through @ref USB_CORE_DESCS_T\r
  * structure.\r
  */\r
  uint8_t* intf_desc;\r
  /* user defined functions */\r
  /**\r
  *  DFU Write callback function.\r
  *\r
  *  This function is provided by the application software. This function gets called\r
  *  when host sends a write command. For application using zero-copy buffer scheme\r
  *  this function is called for the first time with \em length parameter set to 0.\r
  *  The application code should update the buffer pointer.\r
  *\r
  *  @param block_num Destination start address.\r
  *  @param src  Pointer to a pointer to the source of data. Pointer-to-pointer\r
  *                       is used to implement zero-copy buffers.\r
  *  @param bwPollTimeout  Pointer to a 3 byte buffer which the callback implementer\r
  *                     should fill with the amount of minimum time, in milliseconds, \r
  *                     that the host should wait before sending a subsequent\r
  *                     DFU_GETSTATUS request. \r
  *  @param length  Number of bytes to be written.\r
  *  @return Returns DFU_STATUS_ values defined in mw_usbd_dfu.h.\r
  *\r
  */\r
  uint8_t (*DFU_Write)( uint32_t block_num, uint8_t** src, uint32_t length, uint8_t* bwPollTimeout);\r
\r
  /**\r
  *  DFU Read callback function.\r
  *\r
  *  This function is provided by the application software. This function gets called\r
  *  when host sends a read command.\r
  *\r
  *  @param block_num Destination start address.\r
  *  @param dst  Pointer to a pointer to the source of data. Pointer-to-pointer\r
  *                       is used to implement zero-copy buffers.\r
  *  @param length  Amount of data copied to destination buffer.\r
  *  @return Returns DFU_STATUS_ values defined in mw_usbd_dfu.h.\r
  *\r
  */\r
  uint32_t (*DFU_Read)( uint32_t block_num, uint8_t** dst, uint32_t length);\r
\r
  /**\r
  *  DFU done callback function.\r
  *\r
  *  This function is provided by the application software. This function gets called\r
  *  after download is finished.\r
  *\r
  *  @return Nothing.\r
  *\r
  */\r
  void (*DFU_Done)(void);\r
\r
  /**\r
  *  DFU detach callback function.\r
  *\r
  *  This function is provided by the application software. This function gets called\r
  *  after USB_REQ_DFU_DETACH is recieved. Applications which set USB_DFU_WILL_DETACH\r
  *  bit in DFU descriptor should define this function. As part of this function\r
  *  application can call Connect() routine to disconnect and then connect back with\r
  *  host. For application which rely on WinUSB based host application should use this\r
  *  feature since USB reset can be invoked only by kernel drivers on Windows host.\r
  *  By implementing this feature host doen't have to issue reset instead the device\r
  *  has to do it automatically by disconnect and connect procedure.\r
  *\r
  *  @param hUsb Handle DFU control structure.\r
  *  @return Nothing.\r
  *\r
  */\r
  void (*DFU_Detach)(USBD_HANDLE_T hUsb);\r
\r
  /**\r
  *  Optional user overridable function to replace the default DFU class handler.\r
  *\r
  *  The application software could override the default EP0 class handler with their\r
  *  own by providing the handler function address as this data member of the parameter\r
  *  structure. Application which like the default handler should set this data member\r
  *  to zero before calling the USBD_DFU_API::Init().\r
  *  \n\r
  *  @note\r
  *\r
  *  @param hUsb Handle to the USB device stack.\r
  *  @param data Pointer to the data which will be passed when callback function is called by the stack.\r
  *  @param event  Type of endpoint event. See @ref USBD_EVENT_T for more details.\r
  *  @return The call back should returns @ref ErrorCode_t type to indicate success or error condition.\r
  *          @retval LPC_OK On success.\r
  *          @retval ERR_USBD_UNHANDLED  Event is not handled hence pass the event to next in line.\r
  *          @retval ERR_USBD_xxx  For other error conditions.\r
  *\r
  */\r
  ErrorCode_t (*DFU_Ep0_Hdlr) (USBD_HANDLE_T hUsb, void* data, uint32_t event);\r
\r
} USBD_DFU_INIT_PARAM_T;\r
\r
\r
/** @brief DFU class API functions structure.\r
 *  @ingroup USBD_DFU\r
 *\r
 *  This module exposes functions which interact directly with USB device controller hardware.\r
 *\r
 */\r
typedef struct USBD_DFU_API\r
{\r
  /** @fn uint32_t GetMemSize(USBD_DFU_INIT_PARAM_T* param)\r
   *  Function to determine the memory required by the DFU function driver module.\r
   *\r
   *  This function is called by application layer before calling pUsbApi->dfu->Init(), to allocate memory used\r
   *  by DFU function driver module. The application should allocate the memory which is accessible by USB\r
   *  controller/DMA controller.\r
   *  @note Some memory areas are not accessible by all bus masters.\r
   *\r
   *  @param param Structure containing DFU function driver module initialization parameters.\r
   *  @return Returns the required memory size in bytes.\r
   */\r
  uint32_t (*GetMemSize)(USBD_DFU_INIT_PARAM_T* param);\r
\r
  /** @fn ErrorCode_t init(USBD_HANDLE_T hUsb, USBD_DFU_INIT_PARAM_T* param)\r
   *  Function to initialize DFU function driver module.\r
   *\r
   *  This function is called by application layer to initialize DFU function driver module.\r
   *\r
   *  @param hUsb Handle to the USB device stack.\r
   *  @param param Structure containing DFU function driver module initialization parameters.\r
   *  @return Returns @ref ErrorCode_t type to indicate success or error condition.\r
   *          @retval LPC_OK On success\r
   *          @retval ERR_USBD_BAD_MEM_BUF  Memory buffer passed is not 4-byte aligned or smaller than required.\r
   *          @retval ERR_API_INVALID_PARAM2 Either DFU_Write() or DFU_Done() or DFU_Read() callbacks are not defined.\r
   *          @retval ERR_USBD_BAD_DESC\r
   *            - USB_DFU_DESCRIPTOR_TYPE is not defined immediately after\r
   *              interface descriptor.\r
   *            - wTransferSize in descriptor doesn't match the value passed\r
   *              in param->wTransferSize.\r
   *            - DFU_Detach() is not defined while USB_DFU_WILL_DETACH is set\r
   *              in DFU descriptor.\r
   *          @retval ERR_USBD_BAD_INTF_DESC  Wrong interface descriptor is passed.\r
   */\r
  ErrorCode_t (*init)(USBD_HANDLE_T hUsb, USBD_DFU_INIT_PARAM_T* param, uint32_t init_state);\r
\r
} USBD_DFU_API_T;\r
\r
/*-----------------------------------------------------------------------------\r
 *  Private functions & structures prototypes\r
 *-----------------------------------------------------------------------------*/\r
/** @cond  ADVANCED_API */\r
\r
typedef struct _USBD_DFU_CTRL_T\r
{\r
  /*ALIGNED(4)*/ DFU_STATUS_T dfu_req_get_status;\r
  uint8_t dfu_state;\r
  uint8_t dfu_status;\r
  uint8_t download_done;\r
  uint8_t if_num;                  /* interface number */\r
\r
  uint8_t* xfr_buf;\r
  USB_DFU_FUNC_DESCRIPTOR* dfu_desc;\r
\r
  USB_CORE_CTRL_T*  pUsbCtrl;\r
  /* user defined functions */\r
  /* return DFU_STATUS_ values defined in mw_usbd_dfu.h */\r
  uint8_t (*DFU_Write)( uint32_t block_num, uint8_t** src, uint32_t length, uint8_t* bwPollTimeout);\r
  /* return\r
  * DFU_STATUS_ : values defined in mw_usbd_dfu.h in case of errors\r
  * 0 : If end of memory reached\r
  * length : Amount of data copied to destination buffer\r
  */\r
  uint32_t (*DFU_Read)( uint32_t block_num, uint8_t** dst, uint32_t length);\r
  /* callback called after download is finished */\r
  void (*DFU_Done)(void);\r
  /* callback called after USB_REQ_DFU_DETACH is recived */\r
  void (*DFU_Detach)(USBD_HANDLE_T hUsb);\r
\r
} USBD_DFU_CTRL_T;\r
\r
\r
/** @endcond */\r
\r
#endif  /* __DFUUSER_H__ */\r