--- /dev/null
+/***********************************************************************\r
+* $Id:: mw_usbd_hiduser.h 331 2012-08-09 18:54:34Z usb10131 $\r
+*\r
+* Project: USB device ROM Stack\r
+*\r
+* Description:\r
+* HID 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 __HIDUSER_H__\r
+#define __HIDUSER_H__\r
+\r
+#include "usbd.h"\r
+#include "usbd_hid.h"\r
+#include "usbd_core.h"\r
+\r
+/** \file\r
+ * \brief Human Interface Device (HID) API structures and function prototypes.\r
+ *\r
+ * Definition of functions exported by ROM based HID function driver.\r
+ *\r
+ */\r
+\r
+/** \ingroup Group_USBD\r
+ * @defgroup USBD_HID HID Class Function Driver\r
+ * \section Sec_HIDModDescription Module Description\r
+ * HID Class Function Driver module. This module contains an internal implementation of the USB HID Class.\r
+ * User applications can use this class driver instead of implementing the HID class manually\r
+ * via the low-level HW and 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 HID Class.\r
+ */\r
+\r
+/** \brief HID report descriptor data structure. \r
+ * \ingroup USBD_HID\r
+ *\r
+ * \details This structure is used as part of HID function driver initialization \r
+ * parameter structure \ref USBD_HID_INIT_PARAM. This structure contains\r
+ * details of a report type supported by the application. An application\r
+ * can support multiple report types as a single HID device. The application\r
+ * should define this report type data structure per report it supports and\r
+ * the array of report types to USBD_HID_API::init() through \ref USBD_HID_INIT_PARAM\r
+ * structure. \r
+ *\r
+ * \note All descriptor pointers assigned in this structure should be on 4 byte\r
+ * aligned address boundary. \r
+ *\r
+ */\r
+typedef struct _HID_REPORT_T {\r
+ uint16_t len; /**< Size of the report descriptor in bytes. */ \r
+ uint8_t idle_time; /**< This value is used by stack to respond to Set_Idle & \r
+ GET_Idle requests for the specified report ID. The value\r
+ of this field specified the rate at which duplicate reports \r
+ are generated for the specified Report ID. For example, a \r
+ device with two input reports could specify an idle rate of \r
+ 20 milliseconds for report ID 1 and 500 milliseconds for \r
+ report ID 2.\r
+ */\r
+ uint8_t __pad; /**< Padding space. */\r
+ uint8_t* desc; /**< Report descriptor. */\r
+} USB_HID_REPORT_T;\r
+\r
+/** \brief USB descriptors data structure. \r
+ * \ingroup USBD_HID\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_HID_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_HID_API::GetMemSize() routine.*/\r
+ /* HID paramas */\r
+ uint8_t max_reports; /**< Number of HID reports supported by this instance\r
+ of HID class driver. \r
+ */\r
+ uint8_t pad[3];\r
+ uint8_t* intf_desc; /**< Pointer to the HID interface descriptor within the \r
+ descriptor array (\em high_speed_desc) passed to Init()\r
+ through \ref USB_CORE_DESCS_T structure. \r
+ */\r
+ USB_HID_REPORT_T* report_data; /**< Pointer to an array of HID report descriptor\r
+ data structure (\ref USB_HID_REPORT_T). The number\r
+ of elements in the array should be same a \em max_reports\r
+ value. The stack uses this array to respond to \r
+ requests received for various HID report descriptor\r
+ information. \note This array should be of global scope.\r
+ */\r
+\r
+ /* user defined functions */\r
+ /* required functions */\r
+ /** \r
+ * HID get report callback function.\r
+ *\r
+ * This function is provided by the application software. This function gets called \r
+ * when host sends a HID_REQUEST_GET_REPORT request. The setup packet data (\em pSetup)\r
+ * is passed to the callback so that application can extract the report ID, report\r
+ * type and other information need to generate the report. \note HID reports are sent\r
+ * via interrupt IN endpoint also. This function is called only when report request\r
+ * is received on control endpoint. Application should implement \em HID_EpIn_Hdlr to\r
+ * send reports to host via interrupt IN endpoint.\r
+ * \r
+ * \r
+ * \param[in] hHid Handle to HID function driver. \r
+ * \param[in] pSetup Pointer to setup packet received from host.\r
+ * \param[in, out] pBuffer Pointer to a pointer of data buffer containing report data. \r
+ * Pointer-to-pointer is used to implement zero-copy buffers. \r
+ * See \ref USBD_ZeroCopy for more details on zero-copy concept.\r
+ * \param[in] length Amount of data copied to destination buffer.\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 (*HID_GetReport)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t** pBuffer, uint16_t* length); \r
+ \r
+ /** \r
+ * HID set report callback function.\r
+ *\r
+ * This function is provided by the application software. This function gets called \r
+ * when host sends a HID_REQUEST_SET_REPORT request. The setup packet data (\em pSetup)\r
+ * is passed to the callback so that application can extract the report ID, report\r
+ * type and other information need to modify the report. An application might choose \r
+ * to ignore input Set_Report requests as meaningless. Alternatively these reports \r
+ * could be used to reset the origin of a control (that is, current position should \r
+ * report zero).\r
+ * \r
+ * \param[in] hHid Handle to HID function driver. \r
+ * \param[in] pSetup Pointer to setup packet received from host.\r
+ * \param[in, out] pBuffer Pointer to a pointer of data buffer containing report data. \r
+ * Pointer-to-pointer is used to implement zero-copy buffers. \r
+ * See \ref USBD_ZeroCopy for more details on zero-copy concept.\r
+ * \param[in] length Amount of data copied to destination buffer.\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 (*HID_SetReport)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t** pBuffer, uint16_t length);\r
+ \r
+ /* optional functions */\r
+ \r
+ /** \r
+ * Optional callback function to handle HID_GetPhysDesc request.\r
+ *\r
+ * The application software could provide this callback HID_GetPhysDesc handler to\r
+ * handle get physical descriptor requests sent by the host. When host requests \r
+ * Physical Descriptor set 0, application should return a special descriptor\r
+ * identifying the number of descriptor sets and their sizes. A Get_Descriptor \r
+ * request with the Physical Index equal to 1 should return the first Physical \r
+ * Descriptor set. A device could possibly have alternate uses for its items. \r
+ * These can be enumerated by issuing subsequent Get_Descriptor requests while \r
+ * incrementing the Descriptor Index. A device should return the last descriptor\r
+ * set to requests with an index greater than the last number defined in the HID \r
+ * descriptor.\r
+ * \note Applications which don't have physical descriptor should set this data member\r
+ * to zero before calling the USBD_HID_API::Init().\r
+ * \n\r
+ * \r
+ * \param[in] hHid Handle to HID function driver. \r
+ * \param[in] pSetup Pointer to setup packet received from host.\r
+ * \param[in] pBuf Pointer to a pointer of data buffer containing physical descriptor \r
+ * data. If the physical descriptor is in USB accessible memory area\r
+ * application could just update the pointer or else it should copy \r
+ * the descriptor to the address pointed by this pointer.\r
+ * \param[in] length Amount of data copied to destination buffer or descriptor length.\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 (*HID_GetPhysDesc)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t** pBuf, uint16_t* length);\r
+\r
+ /** \r
+ * Optional callback function to handle HID_REQUEST_SET_IDLE request.\r
+ *\r
+ * The application software could provide this callback to handle HID_REQUEST_SET_IDLE\r
+ * requests sent by the host. This callback is provided to applications to adjust\r
+ * timers associated with various reports, which are sent to host over interrupt \r
+ * endpoint. The setup packet data (\em pSetup) is passed to the callback so that\r
+ * application can extract the report ID, report type and other information need \r
+ * to modify the report's idle time.\r
+ * \note Applications which don't send reports on Interrupt endpoint or don't\r
+ * have idle time between reports should set this data member to zero before \r
+ * calling the USBD_HID_API::Init().\r
+ * \n\r
+ * \r
+ * \param[in] hHid Handle to HID function driver. \r
+ * \param[in] pSetup Pointer to setup packet received from host.\r
+ * \param[in] idleTime Idle time to be set for the specified report.\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 (*HID_SetIdle)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t idleTime); \r
+ \r
+ /** \r
+ * Optional callback function to handle HID_REQUEST_SET_PROTOCOL request.\r
+ *\r
+ * The application software could provide this callback to handle HID_REQUEST_SET_PROTOCOL\r
+ * requests sent by the host. This callback is provided to applications to adjust\r
+ * modes of their code between boot mode and report mode. \r
+ * \note Applications which don't support protocol modes should set this data member\r
+ * to zero before calling the USBD_HID_API::Init().\r
+ * \n\r
+ * \r
+ * \param[in] hHid Handle to HID function driver. \r
+ * \param[in] pSetup Pointer to setup packet received from host.\r
+ * \param[in] protocol Protocol mode. \r
+ * 0 = Boot Protocol\r
+ * 1 = Report Protocol\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 (*HID_SetProtocol)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t protocol); \r
+ \r
+ /** \r
+ * Optional Interrupt IN endpoint event handler.\r
+ *\r
+ * The application software could provide Interrupt IN endpoint event handler. \r
+ * Application which send reports to host on interrupt endpoint should provide\r
+ * an endpoint event handler through this data member. This data member is\r
+ * ignored if the interface descriptor \em intf_desc doesn't have any IN interrupt \r
+ * endpoint descriptor associated. \r
+ * \n\r
+ * \r
+ * \param[in] hUsb Handle to the USB device stack. \r
+ * \param[in] data Handle to HID function driver. \r
+ * \param[in] event Type of endpoint event. See \ref USBD_EVENT_T for more details.\r
+ * \return The call back should return \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 (*HID_EpIn_Hdlr) (USBD_HANDLE_T hUsb, void* data, uint32_t event);\r
+ /** \r
+ * Optional Interrupt OUT endpoint event handler.\r
+ *\r
+ * The application software could provide Interrupt OUT endpoint event handler. \r
+ * Application which receives reports from host on interrupt endpoint should provide\r
+ * an endpoint event handler through this data member. This data member is\r
+ * ignored if the interface descriptor \em intf_desc doesn't have any OUT interrupt \r
+ * endpoint descriptor associated. \r
+ * \n\r
+ * \r
+ * \param[in] hUsb Handle to the USB device stack. \r
+ * \param[in] data Handle to HID function driver. \r
+ * \param[in] event Type of endpoint event. See \ref USBD_EVENT_T for more details.\r
+ * \return The call back should return \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 (*HID_EpOut_Hdlr) (USBD_HANDLE_T hUsb, void* data, uint32_t event);\r
+\r
+ /* user override-able function */\r
+ /** \r
+ * Optional user override-able function to replace the default HID_GetReportDesc handler.\r
+ *\r
+ * The application software could override the default HID_GetReportDesc 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_HID_API::Init() and also provide report data array\r
+ * \em report_data field.\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 (*HID_GetReportDesc)(USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t** pBuf, uint16_t* length);\r
+ /** \r
+ * Optional user override-able function to replace the default HID 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_HID_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 (*HID_Ep0_Hdlr) (USBD_HANDLE_T hUsb, void* data, uint32_t event);\r
+\r
+} USBD_HID_INIT_PARAM_T;\r
+\r
+/** \brief HID class API functions structure.\r
+ * \ingroup USBD_HID\r
+ *\r
+ * This structure contains pointers to all the function exposed by HID function driver module.\r
+ *\r
+ */\r
+typedef struct USBD_HID_API \r
+{\r
+ /** \fn uint32_t GetMemSize(USBD_HID_INIT_PARAM_T* param)\r
+ * Function to determine the memory required by the HID function driver module.\r
+ * \r
+ * This function is called by application layer before calling pUsbApi->hid->Init(), to allocate memory used \r
+ * by HID 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 HID function driver module initialization parameters.\r
+ * \return Returns the required memory size in bytes.\r
+ */\r
+ uint32_t (*GetMemSize)(USBD_HID_INIT_PARAM_T* param);\r
+\r
+ /** \fn ErrorCode_t init(USBD_HANDLE_T hUsb, USBD_HID_INIT_PARAM_T* param)\r
+ * Function to initialize HID function driver module.\r
+ * \r
+ * This function is called by application layer to initialize HID function driver \r
+ * module. On successful initialization the function returns a handle to HID \r
+ * function driver module in passed param structure. \r
+ *\r
+ * \param[in] hUsb Handle to the USB device stack. \r
+ * \param[in, out] param Structure containing HID function driver module \r
+ * 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 \r
+ * aligned or smaller than required. \r
+ * \retval ERR_API_INVALID_PARAM2 Either HID_GetReport() or HID_SetReport()\r
+ * callback are not defined. \r
+ * \retval ERR_USBD_BAD_DESC HID_HID_DESCRIPTOR_TYPE is not defined \r
+ * immediately after interface descriptor. \r
+ * \retval ERR_USBD_BAD_INTF_DESC Wrong interface descriptor is passed. \r
+ * \retval ERR_USBD_BAD_EP_DESC Wrong endpoint descriptor is passed. \r
+ */\r
+ ErrorCode_t (*init)(USBD_HANDLE_T hUsb, USBD_HID_INIT_PARAM_T* param);\r
+\r
+} USBD_HID_API_T;\r
+\r
+/*-----------------------------------------------------------------------------\r
+ * Private functions & structures prototypes\r
+ *-----------------------------------------------------------------------------*/\r
+/** @cond ADVANCED_API */\r
+\r
+typedef struct _HID_CTRL_T {\r
+ /* pointer to controller */\r
+ USB_CORE_CTRL_T* pUsbCtrl;\r
+ /* descriptor pointers */\r
+ uint8_t* hid_desc;\r
+ USB_HID_REPORT_T* report_data;\r
+\r
+ uint8_t protocol;\r
+ uint8_t if_num; /* interface number */\r
+ uint8_t epin_adr; /* IN interrupt endpoint */\r
+ uint8_t epout_adr; /* OUT interrupt endpoint */\r
+\r
+ /* user defined functions */\r
+ ErrorCode_t (*HID_GetReport)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t** pBuffer, uint16_t* length); \r
+ ErrorCode_t (*HID_SetReport)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t** pBuffer, uint16_t length);\r
+ ErrorCode_t (*HID_GetPhysDesc)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t** pBuf, uint16_t* length);\r
+ ErrorCode_t (*HID_SetIdle)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t idleTime); \r
+ ErrorCode_t (*HID_SetProtocol)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t protocol); \r
+\r
+ /* virtual overridable functions */ \r
+ ErrorCode_t (*HID_GetReportDesc)(USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t** pBuf, uint16_t* length);\r
+\r
+}USB_HID_CTRL_T;\r
+\r
+/** @cond DIRECT_API */\r
+extern uint32_t mwHID_GetMemSize(USBD_HID_INIT_PARAM_T* param);\r
+extern ErrorCode_t mwHID_init(USBD_HANDLE_T hUsb, USBD_HID_INIT_PARAM_T* param);\r
+/** @endcond */\r
+\r
+/** @endcond */\r
+\r
+#endif /* __HIDUSER_H__ */\r
projects / armstart-ibdap / blobdiff