+/***********************************************************************\r
+* $Id:: mw_usbd_dfuuser.h 331 2012-08-09 18:54:34Z usb10131 $\r
+*\r
+* Project: USB device ROM Stack\r
+*\r
+* Description:\r
+* Device Firmware Upgrade Class Custom User Module Definitions.\r
+*\r
+***********************************************************************\r
+* Copyright(C) 2011, NXP Semiconductor\r
+* All rights reserved.\r
+*\r
+* Software that is described herein is for illustrative purposes only\r
+* which provides customers with programming information regarding the\r
+* products. This software is supplied "AS IS" without any warranties.\r
+* NXP Semiconductors assumes no responsibility or liability for the\r
+* use of the software, conveys no license or title under any patent,\r
+* copyright, or mask work right to the product. NXP Semiconductors\r
+* reserves the right to make changes in the software without\r
+* notification. NXP Semiconductors also make no representation or\r
+* warranty that such application will be suitable for the specified\r
+* use without further testing or modification.\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
+/** \file\r
+ * \brief Device Firmware Upgrade (DFU) API structures and function prototypes.\r
+ *\r
+ * Definition of functions exported by ROM based DFU function driver.\r
+ *\r
+ */\r
+\r
+\r
+/** \ingroup Group_USBD\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
+ uint16_t pad;\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[in] block_num Destination start address. \r
+ * \param[in, out] src Pointer to a pointer to the source of data. Pointer-to-pointer\r
+ * is used to implement zero-copy buffers. See \ref USBD_ZeroCopy\r
+ * for more details on zero-copy concept.\r
+ * \param[out] 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[in] 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[in] block_num Destination start address. \r
+ * \param[in, out] dst Pointer to a pointer to the source of data. Pointer-to-pointer\r
+ * is used to implement zero-copy buffers. See \ref USBD_ZeroCopy\r
+ * for more details on zero-copy concept.\r
+ * \param[in] length Amount of data copied to destination buffer.\r
+ * \return Returns \r
+ * - DFU_STATUS_ values defined in mw_usbd_dfu.h to return error conditions. \r
+ * - 0 if there is no more data to be read. Stack will send EOF frame and set \r
+ * DFU state-machine to dfuIdle state.\r
+ * - length of the data copied, should be greater than or equal to 16. If the data copied\r
+ * is less than DFU \em wTransferSize the stack will send EOF frame and \r
+ * goes to dfuIdle state.\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 firmware download completes.\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 received. 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[in] hUsb Handle DFU control structure. \r
+ * \return Nothing. \r
+ * \r
+ */\r
+ void (*DFU_Detach)(USBD_HANDLE_T hUsb);\r
+\r
+ /** \r
+ * Optional user override-able 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[in] hUsb Handle to the USB device stack. \r
+ * \param[in] data Pointer to the data which will be passed when callback function is called by the stack. \r
+ * \param[in] 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[in] 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[in] hUsb Handle to the USB device stack. \r
+ * \param[in, out] 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() call-backs 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
+ uint16_t pad;\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
+/** @cond DIRECT_API */\r
+uint32_t mwDFU_GetMemSize(USBD_DFU_INIT_PARAM_T* param);\r
+extern ErrorCode_t mwDFU_init(USBD_HANDLE_T hUsb, USBD_DFU_INIT_PARAM_T* param, uint32_t init_state);\r
+/** @endcond */\r
+\r
+/** @endcond */\r
+\r
+#endif /* __DFUUSER_H__ */\r
projects / armstart-ibdap / blobdiff