1 /*********************************************************************** 2 * $Id:: mw_usbd_hiduser.h 331 2012-08-09 18:54:34Z usb10131 $ 3 * 4 * Project: USB device ROM Stack 5 * 6 * Description: 7 * HID Custom User Module Definitions. 8 * 9 *********************************************************************** 10 * Copyright(C) 2011, NXP Semiconductor 11 * All rights reserved. 12 * 13 * Software that is described herein is for illustrative purposes only 14 * which provides customers with programming information regarding the 15 * products. This software is supplied "AS IS" without any warranties. 16 * NXP Semiconductors assumes no responsibility or liability for the 17 * use of the software, conveys no license or title under any patent, 18 * copyright, or mask work right to the product. NXP Semiconductors 19 * reserves the right to make changes in the software without 20 * notification. NXP Semiconductors also make no representation or 21 * warranty that such application will be suitable for the specified 22 * use without further testing or modification. 23 **********************************************************************/ 24 25 #ifndef __HIDUSER_H__ 26 #define __HIDUSER_H__ 27 28 #include "usbd.h" 29 #include "usbd_hid.h" 30 #include "usbd_core.h" 31 32 /** \file 33 * \brief Human Interface Device (HID) API structures and function prototypes. 34 * 35 * Definition of functions exported by ROM based HID function driver. 36 * 37 */ 38 39 /** \ingroup Group_USBD 40 * @defgroup USBD_HID HID Class Function Driver 41 * \section Sec_HIDModDescription Module Description 42 * HID Class Function Driver module. This module contains an internal implementation of the USB HID Class. 43 * User applications can use this class driver instead of implementing the HID class manually 44 * via the low-level HW and core APIs. 45 * 46 * This module is designed to simplify the user code by exposing only the required interface needed to interface with 47 * Devices using the USB HID Class. 48 */ 49 50 /** \brief HID report descriptor data structure. 51 * \ingroup USBD_HID 52 * 53 * \details This structure is used as part of HID function driver initialization 54 * parameter structure \ref USBD_HID_INIT_PARAM. This structure contains 55 * details of a report type supported by the application. An application 56 * can support multiple report types as a single HID device. The application 57 * should define this report type data structure per report it supports and 58 * the array of report types to USBD_HID_API::init() through \ref USBD_HID_INIT_PARAM 59 * structure. 60 * 61 * \note All descriptor pointers assigned in this structure should be on 4 byte 62 * aligned address boundary. 63 * 64 */ 65 typedef struct _HID_REPORT_T { 66 uint16_t len; /**< Size of the report descriptor in bytes. */ 67 uint8_t idle_time; /**< This value is used by stack to respond to Set_Idle & 68 GET_Idle requests for the specified report ID. The value 69 of this field specified the rate at which duplicate reports 70 are generated for the specified Report ID. For example, a 71 device with two input reports could specify an idle rate of 72 20 milliseconds for report ID 1 and 500 milliseconds for 73 report ID 2. 74 */ 75 uint8_t __pad; /**< Padding space. */ 76 uint8_t* desc; /**< Report descriptor. */ 77 } USB_HID_REPORT_T; 78 79 /** \brief USB descriptors data structure. 80 * \ingroup USBD_HID 81 * 82 * \details This module exposes functions which interact directly with USB device stack's core layer. 83 * The application layer uses this component when it has to implement custom class function driver or 84 * standard class function driver which is not part of the current USB device stack. 85 * The functions exposed by this interface are to register class specific EP0 handlers and corresponding 86 * utility functions to manipulate EP0 state machine of the stack. This interface also exposes 87 * function to register custom endpoint interrupt handler. 88 * 89 */ 90 typedef struct USBD_HID_INIT_PARAM 91 { 92 /* memory allocation params */ 93 uint32_t mem_base; /**< Base memory location from where the stack can allocate 94 data and buffers. \note The memory address set in this field 95 should be accessible by USB DMA controller. Also this value 96 should be aligned on 4 byte boundary. 97 */ 98 uint32_t mem_size; /**< The size of memory buffer which stack can use. 99 \note The \em mem_size should be greater than the size 100 returned by USBD_HID_API::GetMemSize() routine.*/ 101 /* HID paramas */ 102 uint8_t max_reports; /**< Number of HID reports supported by this instance 103 of HID class driver. 104 */ 105 uint8_t pad[3]; 106 uint8_t* intf_desc; /**< Pointer to the HID interface descriptor within the 107 descriptor array (\em high_speed_desc) passed to Init() 108 through \ref USB_CORE_DESCS_T structure. 109 */ 110 USB_HID_REPORT_T* report_data; /**< Pointer to an array of HID report descriptor 111 data structure (\ref USB_HID_REPORT_T). The number 112 of elements in the array should be same a \em max_reports 113 value. The stack uses this array to respond to 114 requests received for various HID report descriptor 115 information. \note This array should be of global scope. 116 */ 117 118 /* user defined functions */ 119 /* required functions */ 120 /** 121 * HID get report callback function. 122 * 123 * This function is provided by the application software. This function gets called 124 * when host sends a HID_REQUEST_GET_REPORT request. The setup packet data (\em pSetup) 125 * is passed to the callback so that application can extract the report ID, report 126 * type and other information need to generate the report. \note HID reports are sent 127 * via interrupt IN endpoint also. This function is called only when report request 128 * is received on control endpoint. Application should implement \em HID_EpIn_Hdlr to 129 * send reports to host via interrupt IN endpoint. 130 * 131 * 132 * \param[in] hHid Handle to HID function driver. 133 * \param[in] pSetup Pointer to setup packet received from host. 134 * \param[in, out] pBuffer Pointer to a pointer of data buffer containing report data. 135 * Pointer-to-pointer is used to implement zero-copy buffers. 136 * See \ref USBD_ZeroCopy for more details on zero-copy concept. 137 * \param[in] length Amount of data copied to destination buffer. 138 * \return The call back should returns \ref ErrorCode_t type to indicate success or error condition. 139 * \retval LPC_OK On success. 140 * \retval ERR_USBD_UNHANDLED Event is not handled hence pass the event to next in line. 141 * \retval ERR_USBD_xxx For other error conditions. 142 * 143 */ 144 ErrorCode_t (*HID_GetReport)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t** pBuffer, uint16_t* length); 145 146 /** 147 * HID set report callback function. 148 * 149 * This function is provided by the application software. This function gets called 150 * when host sends a HID_REQUEST_SET_REPORT request. The setup packet data (\em pSetup) 151 * is passed to the callback so that application can extract the report ID, report 152 * type and other information need to modify the report. An application might choose 153 * to ignore input Set_Report requests as meaningless. Alternatively these reports 154 * could be used to reset the origin of a control (that is, current position should 155 * report zero). 156 * 157 * \param[in] hHid Handle to HID function driver. 158 * \param[in] pSetup Pointer to setup packet received from host. 159 * \param[in, out] pBuffer Pointer to a pointer of data buffer containing report data. 160 * Pointer-to-pointer is used to implement zero-copy buffers. 161 * See \ref USBD_ZeroCopy for more details on zero-copy concept. 162 * \param[in] length Amount of data copied to destination buffer. 163 * \return The call back should returns \ref ErrorCode_t type to indicate success or error condition. 164 * \retval LPC_OK On success. 165 * \retval ERR_USBD_UNHANDLED Event is not handled hence pass the event to next in line. 166 * \retval ERR_USBD_xxx For other error conditions. 167 * 168 */ 169 ErrorCode_t (*HID_SetReport)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t** pBuffer, uint16_t length); 170 171 /* optional functions */ 172 173 /** 174 * Optional callback function to handle HID_GetPhysDesc request. 175 * 176 * The application software could provide this callback HID_GetPhysDesc handler to 177 * handle get physical descriptor requests sent by the host. When host requests 178 * Physical Descriptor set 0, application should return a special descriptor 179 * identifying the number of descriptor sets and their sizes. A Get_Descriptor 180 * request with the Physical Index equal to 1 should return the first Physical 181 * Descriptor set. A device could possibly have alternate uses for its items. 182 * These can be enumerated by issuing subsequent Get_Descriptor requests while 183 * incrementing the Descriptor Index. A device should return the last descriptor 184 * set to requests with an index greater than the last number defined in the HID 185 * descriptor. 186 * \note Applications which don't have physical descriptor should set this data member 187 * to zero before calling the USBD_HID_API::Init(). 188 * \n 189 * 190 * \param[in] hHid Handle to HID function driver. 191 * \param[in] pSetup Pointer to setup packet received from host. 192 * \param[in] pBuf Pointer to a pointer of data buffer containing physical descriptor 193 * data. If the physical descriptor is in USB accessible memory area 194 * application could just update the pointer or else it should copy 195 * the descriptor to the address pointed by this pointer. 196 * \param[in] length Amount of data copied to destination buffer or descriptor length. 197 * \return The call back should returns \ref ErrorCode_t type to indicate success or error condition. 198 * \retval LPC_OK On success. 199 * \retval ERR_USBD_UNHANDLED Event is not handled hence pass the event to next in line. 200 * \retval ERR_USBD_xxx For other error conditions. 201 * 202 */ 203 ErrorCode_t (*HID_GetPhysDesc)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t** pBuf, uint16_t* length); 204 205 /** 206 * Optional callback function to handle HID_REQUEST_SET_IDLE request. 207 * 208 * The application software could provide this callback to handle HID_REQUEST_SET_IDLE 209 * requests sent by the host. This callback is provided to applications to adjust 210 * timers associated with various reports, which are sent to host over interrupt 211 * endpoint. The setup packet data (\em pSetup) is passed to the callback so that 212 * application can extract the report ID, report type and other information need 213 * to modify the report's idle time. 214 * \note Applications which don't send reports on Interrupt endpoint or don't 215 * have idle time between reports should set this data member to zero before 216 * calling the USBD_HID_API::Init(). 217 * \n 218 * 219 * \param[in] hHid Handle to HID function driver. 220 * \param[in] pSetup Pointer to setup packet received from host. 221 * \param[in] idleTime Idle time to be set for the specified report. 222 * \return The call back should returns \ref ErrorCode_t type to indicate success or error condition. 223 * \retval LPC_OK On success. 224 * \retval ERR_USBD_UNHANDLED Event is not handled hence pass the event to next in line. 225 * \retval ERR_USBD_xxx For other error conditions. 226 * 227 */ 228 ErrorCode_t (*HID_SetIdle)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t idleTime); 229 230 /** 231 * Optional callback function to handle HID_REQUEST_SET_PROTOCOL request. 232 * 233 * The application software could provide this callback to handle HID_REQUEST_SET_PROTOCOL 234 * requests sent by the host. This callback is provided to applications to adjust 235 * modes of their code between boot mode and report mode. 236 * \note Applications which don't support protocol modes should set this data member 237 * to zero before calling the USBD_HID_API::Init(). 238 * \n 239 * 240 * \param[in] hHid Handle to HID function driver. 241 * \param[in] pSetup Pointer to setup packet received from host. 242 * \param[in] protocol Protocol mode. 243 * 0 = Boot Protocol 244 * 1 = Report Protocol 245 * \return The call back should returns \ref ErrorCode_t type to indicate success or error condition. 246 * \retval LPC_OK On success. 247 * \retval ERR_USBD_UNHANDLED Event is not handled hence pass the event to next in line. 248 * \retval ERR_USBD_xxx For other error conditions. 249 * 250 */ 251 ErrorCode_t (*HID_SetProtocol)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t protocol); 252 253 /** 254 * Optional Interrupt IN endpoint event handler. 255 * 256 * The application software could provide Interrupt IN endpoint event handler. 257 * Application which send reports to host on interrupt endpoint should provide 258 * an endpoint event handler through this data member. This data member is 259 * ignored if the interface descriptor \em intf_desc doesn't have any IN interrupt 260 * endpoint descriptor associated. 261 * \n 262 * 263 * \param[in] hUsb Handle to the USB device stack. 264 * \param[in] data Handle to HID function driver. 265 * \param[in] event Type of endpoint event. See \ref USBD_EVENT_T for more details. 266 * \return The call back should return \ref ErrorCode_t type to indicate success or error condition. 267 * \retval LPC_OK On success. 268 * \retval ERR_USBD_UNHANDLED Event is not handled hence pass the event to next in line. 269 * \retval ERR_USBD_xxx For other error conditions. 270 * 271 */ 272 ErrorCode_t (*HID_EpIn_Hdlr) (USBD_HANDLE_T hUsb, void* data, uint32_t event); 273 /** 274 * Optional Interrupt OUT endpoint event handler. 275 * 276 * The application software could provide Interrupt OUT endpoint event handler. 277 * Application which receives reports from host on interrupt endpoint should provide 278 * an endpoint event handler through this data member. This data member is 279 * ignored if the interface descriptor \em intf_desc doesn't have any OUT interrupt 280 * endpoint descriptor associated. 281 * \n 282 * 283 * \param[in] hUsb Handle to the USB device stack. 284 * \param[in] data Handle to HID function driver. 285 * \param[in] event Type of endpoint event. See \ref USBD_EVENT_T for more details. 286 * \return The call back should return \ref ErrorCode_t type to indicate success or error condition. 287 * \retval LPC_OK On success. 288 * \retval ERR_USBD_UNHANDLED Event is not handled hence pass the event to next in line. 289 * \retval ERR_USBD_xxx For other error conditions. 290 * 291 */ 292 ErrorCode_t (*HID_EpOut_Hdlr) (USBD_HANDLE_T hUsb, void* data, uint32_t event); 293 294 /* user override-able function */ 295 /** 296 * Optional user override-able function to replace the default HID_GetReportDesc handler. 297 * 298 * The application software could override the default HID_GetReportDesc handler with their 299 * own by providing the handler function address as this data member of the parameter 300 * structure. Application which like the default handler should set this data member 301 * to zero before calling the USBD_HID_API::Init() and also provide report data array 302 * \em report_data field. 303 * \n 304 * \note 305 * 306 * \param[in] hUsb Handle to the USB device stack. 307 * \param[in] data Pointer to the data which will be passed when callback function is called by the stack. 308 * \param[in] event Type of endpoint event. See \ref USBD_EVENT_T for more details. 309 * \return The call back should returns \ref ErrorCode_t type to indicate success or error condition. 310 * \retval LPC_OK On success. 311 * \retval ERR_USBD_UNHANDLED Event is not handled hence pass the event to next in line. 312 * \retval ERR_USBD_xxx For other error conditions. 313 * 314 */ 315 ErrorCode_t (*HID_GetReportDesc)(USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t** pBuf, uint16_t* length); 316 /** 317 * Optional user override-able function to replace the default HID class handler. 318 * 319 * The application software could override the default EP0 class handler with their 320 * own by providing the handler function address as this data member of the parameter 321 * structure. Application which like the default handler should set this data member 322 * to zero before calling the USBD_HID_API::Init(). 323 * \n 324 * \note 325 * 326 * \param[in] hUsb Handle to the USB device stack. 327 * \param[in] data Pointer to the data which will be passed when callback function is called by the stack. 328 * \param[in] event Type of endpoint event. See \ref USBD_EVENT_T for more details. 329 * \return The call back should returns \ref ErrorCode_t type to indicate success or error condition. 330 * \retval LPC_OK On success. 331 * \retval ERR_USBD_UNHANDLED Event is not handled hence pass the event to next in line. 332 * \retval ERR_USBD_xxx For other error conditions. 333 * 334 */ 335 ErrorCode_t (*HID_Ep0_Hdlr) (USBD_HANDLE_T hUsb, void* data, uint32_t event); 336 337 } USBD_HID_INIT_PARAM_T; 338 339 /** \brief HID class API functions structure. 340 * \ingroup USBD_HID 341 * 342 * This structure contains pointers to all the function exposed by HID function driver module. 343 * 344 */ 345 typedef struct USBD_HID_API 346 { 347 /** \fn uint32_t GetMemSize(USBD_HID_INIT_PARAM_T* param) 348 * Function to determine the memory required by the HID function driver module. 349 * 350 * This function is called by application layer before calling pUsbApi->hid->Init(), to allocate memory used 351 * by HID function driver module. The application should allocate the memory which is accessible by USB 352 * controller/DMA controller. 353 * \note Some memory areas are not accessible by all bus masters. 354 * 355 * \param[in] param Structure containing HID function driver module initialization parameters. 356 * \return Returns the required memory size in bytes. 357 */ 358 uint32_t (*GetMemSize)(USBD_HID_INIT_PARAM_T* param); 359 360 /** \fn ErrorCode_t init(USBD_HANDLE_T hUsb, USBD_HID_INIT_PARAM_T* param) 361 * Function to initialize HID function driver module. 362 * 363 * This function is called by application layer to initialize HID function driver 364 * module. On successful initialization the function returns a handle to HID 365 * function driver module in passed param structure. 366 * 367 * \param[in] hUsb Handle to the USB device stack. 368 * \param[in, out] param Structure containing HID function driver module 369 * initialization parameters. 370 * \return Returns \ref ErrorCode_t type to indicate success or error condition. 371 * \retval LPC_OK On success 372 * \retval ERR_USBD_BAD_MEM_BUF Memory buffer passed is not 4-byte 373 * aligned or smaller than required. 374 * \retval ERR_API_INVALID_PARAM2 Either HID_GetReport() or HID_SetReport() 375 * callback are not defined. 376 * \retval ERR_USBD_BAD_DESC HID_HID_DESCRIPTOR_TYPE is not defined 377 * immediately after interface descriptor. 378 * \retval ERR_USBD_BAD_INTF_DESC Wrong interface descriptor is passed. 379 * \retval ERR_USBD_BAD_EP_DESC Wrong endpoint descriptor is passed. 380 */ 381 ErrorCode_t (*init)(USBD_HANDLE_T hUsb, USBD_HID_INIT_PARAM_T* param); 382 383 } USBD_HID_API_T; 384 385 /*----------------------------------------------------------------------------- 386 * Private functions & structures prototypes 387 *-----------------------------------------------------------------------------*/ 388 /** @cond ADVANCED_API */ 389 390 typedef struct _HID_CTRL_T { 391 /* pointer to controller */ 392 USB_CORE_CTRL_T* pUsbCtrl; 393 /* descriptor pointers */ 394 uint8_t* hid_desc; 395 USB_HID_REPORT_T* report_data; 396 397 uint8_t protocol; 398 uint8_t if_num; /* interface number */ 399 uint8_t epin_adr; /* IN interrupt endpoint */ 400 uint8_t epout_adr; /* OUT interrupt endpoint */ 401 402 /* user defined functions */ 403 ErrorCode_t (*HID_GetReport)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t** pBuffer, uint16_t* length); 404 ErrorCode_t (*HID_SetReport)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t** pBuffer, uint16_t length); 405 ErrorCode_t (*HID_GetPhysDesc)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t** pBuf, uint16_t* length); 406 ErrorCode_t (*HID_SetIdle)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t idleTime); 407 ErrorCode_t (*HID_SetProtocol)( USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t protocol); 408 409 /* virtual overridable functions */ 410 ErrorCode_t (*HID_GetReportDesc)(USBD_HANDLE_T hHid, USB_SETUP_PACKET* pSetup, uint8_t** pBuf, uint16_t* length); 411 412 }USB_HID_CTRL_T; 413 414 /** @cond DIRECT_API */ 415 extern uint32_t mwHID_GetMemSize(USBD_HID_INIT_PARAM_T* param); 416 extern ErrorCode_t mwHID_init(USBD_HANDLE_T hUsb, USBD_HID_INIT_PARAM_T* param); 417 /** @endcond */ 418 419 /** @endcond */ 420 421 #endif /* __HIDUSER_H__ */ 422