1 /* 2 * Copyright (c) 2015 - 2016, Freescale Semiconductor, Inc. 3 * Copyright 2016 NXP 4 * All rights reserved. 5 * 6 * SPDX-License-Identifier: BSD-3-Clause 7 */ 8 9 #ifndef _USB_HOST_HID_H_ 10 #define _USB_HOST_HID_H_ 11 12 /******************************************************************************* 13 * HID class public structure, enumerations, macros, functions 14 ******************************************************************************/ 15 16 /******************************************************************************* 17 * Definitions 18 ******************************************************************************/ 19 20 /*! 21 * @addtogroup usb_host_hid_drv 22 * @{ 23 */ 24 25 /*! @brief HID class-specific request (get report) */ 26 #define USB_HOST_HID_GET_REPORT (0x01U) 27 /*! @brief HID class-specific request (get idle) */ 28 #define USB_HOST_HID_GET_IDLE (0x02U) 29 /*! @brief HID class-specific request (get protocol) */ 30 #define USB_HOST_HID_GET_PROTOCOL (0x03U) 31 /*! @brief HID class-specific request (set report) */ 32 #define USB_HOST_HID_SET_REPORT (0x09U) 33 /*! @brief HID class-specific request (set idle) */ 34 #define USB_HOST_HID_SET_IDLE (0x0AU) 35 /*! @brief HID class-specific request (set protocol) */ 36 #define USB_HOST_HID_SET_PROTOCOL (0x0BU) 37 38 /*! @brief HID class code */ 39 #define USB_HOST_HID_CLASS_CODE (3U) 40 /*! @brief HID sub-class code */ 41 #define USB_HOST_HID_SUBCLASS_CODE_NONE (0U) 42 /*! @brief HID sub-class code */ 43 #define USB_HOST_HID_SUBCLASS_CODE_BOOT (1U) 44 /*! @brief HID class protocol code */ 45 #define USB_HOST_HID_PROTOCOL_KEYBOARD (1U) 46 /*! @brief HID class protocol code */ 47 #define USB_HOST_HID_PROTOCOL_MOUSE (2U) 48 /*! @brief HID class protocol code */ 49 #define USB_HOST_HID_PROTOCOL_NONE (0U) 50 51 /*! @brief HID get/set protocol request data code */ 52 #define USB_HOST_HID_REQUEST_PROTOCOL_BOOT (0U) 53 /*! @brief HID get/set protocol request data code */ 54 #define USB_HOST_HID_REQUEST_PROTOCOL_REPORT (1U) 55 56 /*! @brief HID instance structure and HID usb_host_class_handle pointer to this structure */ 57 typedef struct _usb_host_hid_instance 58 { 59 usb_host_handle hostHandle; /*!< This instance's related host handle*/ 60 usb_device_handle deviceHandle; /*!< This instance's related device handle*/ 61 usb_host_interface_handle interfaceHandle; /*!< This instance's related interface handle*/ 62 usb_host_pipe_handle controlPipe; /*!< This instance's related device control pipe*/ 63 usb_host_pipe_handle inPipe; /*!< HID interrupt in pipe*/ 64 usb_host_pipe_handle outPipe; /*!< HID interrupt out pipe*/ 65 transfer_callback_t inCallbackFn; /*!< HID interrupt in transfer callback function pointer*/ 66 void *inCallbackParam; /*!< HID interrupt in transfer callback parameter*/ 67 transfer_callback_t outCallbackFn; /*!< HID interrupt out transfer callback function pointer*/ 68 void *outCallbackParam; /*!< HID interrupt out transfer callback parameter*/ 69 transfer_callback_t controlCallbackFn; /*!< HID control transfer callback function pointer*/ 70 void *controlCallbackParam; /*!< HID control transfer callback parameter*/ 71 usb_host_transfer_t *controlTransfer; /*!< Ongoing control transfer*/ 72 #if ((defined USB_HOST_CONFIG_CLASS_AUTO_CLEAR_STALL) && USB_HOST_CONFIG_CLASS_AUTO_CLEAR_STALL) 73 uint8_t *stallDataBuffer; /*!< keep the data buffer for stall transfer's data*/ 74 uint32_t stallDataLength; /*!< keep the data length for stall transfer's data*/ 75 #endif 76 77 uint16_t inPacketSize; /*!< HID interrupt in maximum packet size*/ 78 uint16_t outPacketSize; /*!< HID interrupt out maximum packet size*/ 79 } usb_host_hid_instance_t; 80 81 /*! @brief HID descriptor structure according to the 6.2.1 in HID specification */ 82 typedef struct _usb_host_hid_descriptor 83 { 84 uint8_t bLength; /*!< Total size of the HID descriptor*/ 85 uint8_t bDescriptorType; /*!< Constant name specifying type of HID descriptor*/ 86 uint8_t bcdHID[2]; /*!< Numeric expression identifying the HID Class Specification release*/ 87 uint8_t bCountryCode; /*!< Numeric expression identifying country code of the localized hardware*/ 88 uint8_t bNumDescriptors; /*!< Numeric expression specifying the number of class descriptors*/ 89 uint8_t bHidDescriptorType; /*!< Constant name identifying type of class descriptor*/ 90 uint8_t wDescriptorLength[2]; /*!< Numeric expression that is the total size of the Report descriptor*/ 91 } usb_host_hid_descriptor_t; 92 93 /*! @brief HID descriptor structure according to the 6.2.1 in HID specification */ 94 typedef struct _usb_host_hid_class_descriptor 95 { 96 uint8_t bHidDescriptorType; /*!< Constant name specifying type of optional descriptor*/ 97 uint8_t wDescriptorLength[2]; /*!< Numeric expression that is the total size of the optional descriptor*/ 98 } usb_host_hid_class_descriptor_t; 99 100 /******************************************************************************* 101 * API 102 ******************************************************************************/ 103 104 #ifdef __cplusplus 105 extern "C" { 106 #endif 107 108 /*! 109 * @name USB host HID class APIs 110 * @{ 111 */ 112 113 /*! 114 * @brief Initializes the HID instance. 115 * 116 * This function allocate the resource for the HID instance. 117 * 118 * @param[in] deviceHandle The device handle. 119 * @param[out] classHandle Return class handle. 120 * 121 * @retval kStatus_USB_Success The device is initialized successfully. 122 * @retval kStatus_USB_AllocFail Allocate memory fail. 123 */ 124 extern usb_status_t USB_HostHidInit(usb_device_handle deviceHandle, usb_host_class_handle *classHandle); 125 126 /*! 127 * @brief Sets the interface. 128 * 129 * This function binds the interface with the HID instance. 130 * 131 * @param[in] classHandle The class handle. 132 * @param[in] interfaceHandle The interface handle. 133 * @param[in] alternateSetting The alternate setting value. 134 * @param[in] callbackFn This callback is called after this function completes. 135 * @param[in] callbackParam The first parameter in the callback function. 136 * 137 * @retval kStatus_USB_Success The device is initialized successfully. 138 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 139 * @retval kStatus_USB_Busy There is no idle transfer. 140 * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSendSetup. 141 * @retval kStatus_USB_Busy Callback return status, there is no idle pipe. 142 * @retval kStatus_USB_TransferStall Callback return status, the transfer is stalled by the device. 143 * @retval kStatus_USB_Error Callback return status, open pipe fail. See the USB_HostOpenPipe. 144 */ 145 extern usb_status_t USB_HostHidSetInterface(usb_host_class_handle classHandle, 146 usb_host_interface_handle interfaceHandle, 147 uint8_t alternateSetting, 148 transfer_callback_t callbackFn, 149 void *callbackParam); 150 151 /*! 152 * @brief Deinitializes the HID instance. 153 * 154 * This function frees the resources for the HID instance. 155 * 156 * @param[in] deviceHandle The device handle. 157 * @param[in] classHandle The class handle. 158 * 159 * @retval kStatus_USB_Success The device is de-initialized successfully. 160 */ 161 extern usb_status_t USB_HostHidDeinit(usb_device_handle deviceHandle, usb_host_class_handle classHandle); 162 163 /*! 164 * @brief Gets the pipe maximum packet size. 165 * 166 * @param[in] classHandle The class handle. 167 * @param[in] pipeType Its value is USB_ENDPOINT_CONTROL, USB_ENDPOINT_ISOCHRONOUS, USB_ENDPOINT_BULK or 168 * USB_ENDPOINT_INTERRUPT. 169 * See the usb_spec.h 170 * @param[in] direction Pipe direction. 171 * 172 * @retval 0 The classHandle is NULL. 173 * @retval Maximum packet size. 174 */ 175 extern uint16_t USB_HostHidGetPacketsize(usb_host_class_handle classHandle, uint8_t pipeType, uint8_t direction); 176 177 /*! 178 * @brief HID get report descriptor. 179 * 180 * This function implements the HID report descriptor request. 181 * 182 * @param[in] classHandle The class handle. 183 * @param[out] buffer The buffer pointer. 184 * @param[in] buffer_len The buffer length. 185 * @param[in] callbackFn This callback is called after this function completes. 186 * @param[in] callbackParam The first parameter in the callback function. 187 * 188 * @retval kStatus_USB_Success Request successful. 189 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 190 * @retval kStatus_USB_Busy There is no idle transfer. 191 * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSendSetup. 192 */ 193 extern usb_status_t USB_HostHidGetReportDescriptor(usb_host_class_handle classHandle, 194 uint8_t *buffer, 195 uint16_t buffer_len, 196 transfer_callback_t callbackFn, 197 void *callbackParam); 198 199 /*! 200 * @brief Receives data. 201 * 202 * This function implements the HID receiving data. 203 * 204 * @param[in] classHandle The class handle. 205 * @param[out] buffer The buffer pointer. 206 * @param[in] bufferLength The buffer length. 207 * @param[in] callbackFn This callback is called after this function completes. 208 * @param[in] callbackParam The first parameter in the callback function. 209 * 210 * @retval kStatus_USB_Success Receive request successfully. 211 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 212 * @retval kStatus_USB_Busy There is no idle transfer. 213 * @retval kStatus_USB_Error Pipe is not initialized. 214 * Or, send transfer fail. See the USB_HostRecv. 215 */ 216 extern usb_status_t USB_HostHidRecv(usb_host_class_handle classHandle, 217 uint8_t *buffer, 218 uint32_t bufferLength, 219 transfer_callback_t callbackFn, 220 void *callbackParam); 221 222 /*! 223 * @brief Sends data. 224 * 225 * This function implements the HID sending data. 226 * 227 * @param[in] classHandle The class handle. 228 * @param[in] buffer The buffer pointer. 229 * @param[in] bufferLength The buffer length. 230 * @param[in] callbackFn This callback is called after this function completes. 231 * @param[in] callbackParam The first parameter in the callback function. 232 * 233 * @retval kStatus_USB_Success Send request successfully. 234 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 235 * @retval kStatus_USB_Busy There is no idle transfer. 236 * @retval kStatus_USB_Error Pipe is not initialized. 237 * Or, send transfer fail. See the USB_HostSend. 238 */ 239 extern usb_status_t USB_HostHidSend(usb_host_class_handle classHandle, 240 uint8_t *buffer, 241 uint32_t bufferLength, 242 transfer_callback_t callbackFn, 243 void *callbackParam); 244 245 /*! 246 * @brief HID get idle. 247 * 248 * This function implements the HID class-specific request (get idle). 249 * 250 * @param[in] classHandle The class handle. 251 * @param[in] reportId Report ID. 252 * @param[out] idleRate Return idle rate value. 253 * @param[in] callbackFn This callback is called after this function completes. 254 * @param[in] callbackParam The first parameter in the callback function. 255 * 256 * @retval kStatus_USB_Success Request successful. 257 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 258 * @retval kStatus_USB_Busy There is no idle transfer. 259 * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSendSetup. 260 */ 261 extern usb_status_t USB_HostHidGetIdle(usb_host_class_handle classHandle, 262 uint8_t reportId, 263 uint8_t *idleRate, 264 transfer_callback_t callbackFn, 265 void *callbackParam); 266 267 /*! 268 * @brief HID set idle. 269 * 270 * This function implements the HID class-specific request (set idle). 271 * 272 * @param[in] classHandle The class handle. 273 * @param[in] reportId Report ID. 274 * @param[in] idleRate Idle rate value. 275 * @param[in] callbackFn This callback is called after this function completes. 276 * @param[in] callbackParam The first parameter in the callback function. 277 * 278 * @retval kStatus_USB_Success Request successful. 279 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 280 * @retval kStatus_USB_Busy There is no idle transfer. 281 * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSendSetup. 282 */ 283 extern usb_status_t USB_HostHidSetIdle(usb_host_class_handle classHandle, 284 uint8_t reportId, 285 uint8_t idleRate, 286 transfer_callback_t callbackFn, 287 void *callbackParam); 288 289 /*! 290 * @brief HID get protocol. 291 * 292 * This function implements the HID class-specific request (get protocol). 293 * 294 * @param[in] classHandle The class handle. 295 * @param[out] protocol Return protocol value. 296 * @param[in] callbackFn This callback is called after this function completes. 297 * @param[in] callbackParam The first parameter in the callback function. 298 * 299 * @retval kStatus_USB_Success Request successful. 300 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 301 * @retval kStatus_USB_Busy There is no idle transfer. 302 * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSendSetup. 303 */ 304 extern usb_status_t USB_HostHidGetProtocol(usb_host_class_handle classHandle, 305 uint8_t *protocol, 306 transfer_callback_t callbackFn, 307 void *callbackParam); 308 309 /*! 310 * @brief HID set protocol. 311 * 312 * This function implements the HID class-specific request (set protocol). 313 * 314 * @param[in] classHandle The class handle. 315 * @param[in] protocol Protocol value. 316 * @param[in] callbackFn This callback is called after this function completes. 317 * @param[in] callbackParam The first parameter in the callback function. 318 * 319 * @retval kStatus_USB_Success Request successful. 320 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 321 * @retval kStatus_USB_Busy There is no idle transfer. 322 * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSendSetup. 323 */ 324 extern usb_status_t USB_HostHidSetProtocol(usb_host_class_handle classHandle, 325 uint8_t protocol, 326 transfer_callback_t callbackFn, 327 void *callbackParam); 328 329 /*! 330 * @brief HID get report. 331 * 332 * This function implements the HID class-specific request (get report). 333 * 334 * @param[in] classHandle The class handle. 335 * @param[in] reportId Report ID. 336 * @param[in] reportType Report type. 337 * @param[out] buffer The buffer pointer. 338 * @param[in] bufferLength The buffer length. 339 * @param[in] callbackFn This callback is called after this function completes. 340 * @param[in] callbackParam The first parameter in the callback function. 341 * 342 * @retval kStatus_USB_Success Request successful. 343 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 344 * @retval kStatus_USB_Busy There is no idle transfer. 345 * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSendSetup. 346 */ 347 extern usb_status_t USB_HostHidGetReport(usb_host_class_handle classHandle, 348 uint8_t reportId, 349 uint8_t reportType, 350 uint8_t *buffer, 351 uint32_t bufferLength, 352 transfer_callback_t callbackFn, 353 void *callbackParam); 354 355 /*! 356 * @brief HID set report. 357 * 358 * This function implements the HID class-specific request (set report). 359 * 360 * @param[in] classHandle The class handle. 361 * @param[in] reportId Report ID. 362 * @param[in] reportType Report type. 363 * @param[in] buffer The buffer pointer. 364 * @param[in] bufferLength The buffer length. 365 * @param[in] callbackFn This callback is called after this function completes. 366 * @param[in] callbackParam The first parameter in the callback function. 367 * 368 * @retval kStatus_USB_Success Request successful. 369 * @retval kStatus_USB_InvalidHandle The classHandle is NULL pointer. 370 * @retval kStatus_USB_Busy There is no idle transfer. 371 * @retval kStatus_USB_Error Send transfer fail. See the USB_HostSendSetup. 372 */ 373 extern usb_status_t USB_HostHidSetReport(usb_host_class_handle classHandle, 374 uint8_t reportId, 375 uint8_t reportType, 376 uint8_t *buffer, 377 uint32_t bufferLength, 378 transfer_callback_t callbackFn, 379 void *callbackParam); 380 381 /*! @}*/ 382 383 #ifdef __cplusplus 384 } 385 #endif 386 387 /*! @}*/ 388 389 #endif /* _USB_HOST_HID_H_ */ 390
