1 /* 2 * Copyright (c) 2015, Freescale Semiconductor, Inc. 3 * Copyright 2016 NXP 4 * All rights reserved. 5 * 6 * SPDX-License-Identifier: BSD-3-Clause 7 */ 8 9 #ifndef __USB_DEVICE_HID_H__ 10 #define __USB_DEVICE_HID_H__ 11 12 /*! 13 * @addtogroup usb_device_hid_drv 14 * @{ 15 */ 16 17 /******************************************************************************* 18 * Definitions 19 ******************************************************************************/ 20 21 /*! @brief The class code of the HID class */ 22 #define USB_DEVICE_CONFIG_HID_CLASS_CODE (0x03U) 23 24 /*! @brief Request code to get report of HID class. */ 25 #define USB_DEVICE_HID_REQUEST_GET_REPORT (0x01U) 26 #define USB_DEVICE_HID_REQUEST_GET_REPORT_TYPE_INPUT (0x01U) 27 #define USB_DEVICE_HID_REQUEST_GET_REPORT_TYPE_OUPUT (0x02U) 28 #define USB_DEVICE_HID_REQUEST_GET_REPORT_TYPE_FEATURE (0x03U) 29 /*! @brief Request code to get idle of HID class. */ 30 #define USB_DEVICE_HID_REQUEST_GET_IDLE (0x02U) 31 /*! @brief Request code to get protocol of HID class. */ 32 #define USB_DEVICE_HID_REQUEST_GET_PROTOCOL (0x03U) 33 /*! @brief Request code to set report of HID class. */ 34 #define USB_DEVICE_HID_REQUEST_SET_REPORT (0x09U) 35 /*! @brief Request code to set idle of HID class. */ 36 #define USB_DEVICE_HID_REQUEST_SET_IDLE (0x0AU) 37 /*! @brief Request code to set protocol of HID class. */ 38 #define USB_DEVICE_HID_REQUEST_SET_PROTOCOL (0x0BU) 39 40 /*! @brief Available common EVENT types in HID class callback */ 41 typedef enum _usb_device_hid_event 42 { 43 kUSB_DeviceHidEventSendResponse = 0x01U, /*!< Send data completed or cancelled etc*/ 44 kUSB_DeviceHidEventRecvResponse, /*!< Data received or cancelled etc*/ 45 kUSB_DeviceHidEventGetReport, /*!< Get report request */ 46 kUSB_DeviceHidEventGetIdle, /*!< Get idle request */ 47 kUSB_DeviceHidEventGetProtocol, /*!< Get protocol request */ 48 kUSB_DeviceHidEventSetReport, /*!< Set report request */ 49 kUSB_DeviceHidEventSetIdle, /*!< Set idle request */ 50 kUSB_DeviceHidEventSetProtocol, /*!< Set protocol request */ 51 kUSB_DeviceHidEventRequestReportBuffer, /*!< Get buffer to save the data of the set report request. */ 52 } usb_device_hid_event_t; 53 54 /*! 55 * @brief The device HID GET/SET report structure. 56 * 57 * This structure is used to pass data when the event type is kUSB_DeviceHidEventGetReport, 58 * kUSB_DeviceHidEventSetReport, and kUSB_DeviceHidEventRequestReportBuffer. 59 * 1. kUSB_DeviceHidEventGetReport 60 * The structure is used to save the report buffer and report length got from the application. 61 * The reportBuffer is the report data buffer address filled by the application. 62 * The reportLength is the report length. 63 * The reportType is the requested report type. 64 * The reportId is the requested report ID. 65 * 66 * 2. kUSB_DeviceHidEventSetReport 67 * The structure is used to pass the report data received from the host to the application. 68 * The reportBuffer is buffer address of the report data received from the host. 69 * The reportLength is the report data length. 70 * The reportType is the requested report type. 71 * The reportId is the requested report ID. 72 * 73 * 3. kUSB_DeviceHidEventRequestReportBuffer 74 * The structure is used to get the buffer to save the report data sent by the host. 75 * The reportBuffer is buffer address to receive to report data. It is filled by the application. 76 * The reportLength is the requested report data buffer length. 77 * The reportType is the requested report type. 78 * The reportId is the requested report ID. 79 */ 80 typedef struct _usb_device_hid_report_struct 81 { 82 uint8_t *reportBuffer; /*!< The report buffer address */ 83 uint32_t reportLength; /*!< The report data length */ 84 uint8_t reportType; /*!< The report type */ 85 uint8_t reportId; /*!< The report ID */ 86 } usb_device_hid_report_struct_t; 87 88 /*! @brief The HID device class status structure */ 89 typedef struct _usb_device_hid_struct 90 { 91 usb_device_handle handle; /*!< The device handle */ 92 usb_device_class_config_struct_t *configStruct; /*!< The configuration of the class. */ 93 usb_device_interface_struct_t *interfaceHandle; /*!< Current interface handle */ 94 uint8_t *interruptInPipeDataBuffer; /*!< IN pipe data buffer backup when stall */ 95 uint32_t interruptInPipeDataLen; /*!< IN pipe data length backup when stall */ 96 uint8_t *interruptOutPipeDataBuffer; /*!< OUT pipe data buffer backup when stall */ 97 uint32_t interruptOutPipeDataLen; /*!< OUT pipe data length backup when stall */ 98 uint8_t configuration; /*!< Current configuration */ 99 uint8_t interfaceNumber; /*!< The interface number of the class */ 100 uint8_t alternate; /*!< Current alternate setting of the interface */ 101 uint8_t idleRate; /*!< The idle rate of the HID device */ 102 uint8_t protocol; /*!< Current protocol */ 103 uint8_t interruptInPipeBusy; /*!< Interrupt IN pipe busy flag */ 104 uint8_t interruptOutPipeBusy; /*!< Interrupt OUT pipe busy flag */ 105 uint8_t interruptInPipeStall; /*!< Interrupt IN pipe stall flag */ 106 uint8_t interruptOutPipeStall; /*!< Interrupt OUT pipe stall flag */ 107 } usb_device_hid_struct_t; 108 109 /******************************************************************************* 110 * API 111 ******************************************************************************/ 112 113 #if defined(__cplusplus) 114 extern "C" { 115 #endif 116 117 /*! 118 * @brief Initializes the HID class. 119 * 120 * This function is used to initialize the HID class. This function only can be called by #USB_DeviceClassInit. 121 * 122 * @param[in] controllerId The controller ID of the USB IP. See the enumeration #usb_controller_index_t. 123 * @param[in] config The class configuration information. 124 * @param[out] handle An parameter used to return pointer of the HID class handle to the caller. 125 * 126 * @return A USB error code or kStatus_USB_Success. 127 */ 128 extern usb_status_t USB_DeviceHidInit(uint8_t controllerId, 129 usb_device_class_config_struct_t *config, 130 class_handle_t *handle); 131 132 /*! 133 * @brief Deinitializes the device HID class. 134 * 135 * The function deinitializes the device HID class. This function only can be called by #USB_DeviceClassDeinit. 136 * 137 * @param[in] handle The HID class handle got from usb_device_class_config_struct_t::classHandle. 138 * 139 * @return A USB error code or kStatus_USB_Success. 140 */ 141 extern usb_status_t USB_DeviceHidDeinit(class_handle_t handle); 142 143 /*! 144 * @brief Handles the event passed to the HID class. 145 * 146 * This function handles the event passed to the HID class. This function only can be called by #USB_DeviceClassEvent. 147 * 148 * @param[in] handle The HID class handle received from the usb_device_class_config_struct_t::classHandle. 149 * @param[in] event The event codes. See the enumeration usb_device_class_event_t. 150 * @param[in,out] param The parameter type is determined by the event code. 151 * 152 * @return A USB error code or kStatus_USB_Success. 153 * @retval kStatus_USB_Success Free device handle successfully. 154 * @retval kStatus_USB_InvalidParameter The device handle not be found. 155 * @retval kStatus_USB_InvalidRequest The request is invalid, and the control pipe is stalled by the caller. 156 */ 157 extern usb_status_t USB_DeviceHidEvent(void *handle, uint32_t event, void *param); 158 159 /*! 160 * @name USB device HID class APIs 161 * @{ 162 */ 163 164 /*! 165 * @brief Sends data through a specified endpoint. 166 * 167 * The function is used to send data through a specified endpoint. 168 * The function calls #USB_DeviceSendRequest internally. 169 * 170 * @param[in] handle The HID class handle received from usb_device_class_config_struct_t::classHandle. 171 * @param[in] ep Endpoint index. 172 * @param[in] buffer The memory address to hold the data need to be sent. 173 * @param[in] length The data length to be sent. 174 * 175 * @return A USB error code or kStatus_USB_Success. 176 * 177 * @note The function can only be called in the same context. 178 * 179 * @note The return value indicates whether the sending request is successful or not. The transfer done is notified by 180 * usb_device_hid_interrupt_in. 181 * Currently, only one transfer request can be supported for one specific endpoint. 182 * If there is a specific requirement to support multiple transfer requests for a specific endpoint, the application 183 * should implement a queue in the application level. 184 * The subsequent transfer can begin only when the previous transfer is done (a notification is received through the 185 * endpoint 186 * callback). 187 */ 188 extern usb_status_t USB_DeviceHidSend(class_handle_t handle, uint8_t ep, uint8_t *buffer, uint32_t length); 189 190 /*! 191 * @brief Receives data through a specified endpoint. 192 * 193 * The function is used to receive data through a specified endpoint. 194 * The function calls #USB_DeviceRecvRequest internally. 195 * 196 * @param[in] handle The HID class handle received from the usb_device_class_config_struct_t::classHandle. 197 * @param[in] ep Endpoint index. 198 * @param[in] buffer The memory address to save the received data. 199 * @param[in] length The data length to be received. 200 * 201 * @return A USB error code or kStatus_USB_Success. 202 * 203 * @note The function can only be called in the same context. 204 * 205 * @note The return value indicates whether the receiving request is successful or not. The transfer done is notified by 206 * usb_device_hid_interrupt_out. 207 * Currently, only one transfer request can be supported for a specific endpoint. 208 * If there is a specific requirement to support multiple transfer requests for a specific endpoint, the application 209 * should implement a queue in the application level. 210 * The subsequent transfer can begin only when the previous transfer is done (a notification is received through the 211 * endpoint 212 * callback). 213 */ 214 extern usb_status_t USB_DeviceHidRecv(class_handle_t handle, uint8_t ep, uint8_t *buffer, uint32_t length); 215 216 /*! @}*/ 217 218 #if defined(__cplusplus) 219 } 220 #endif 221 222 /*! @}*/ 223 224 #endif /* __USB_DEVICE_HID_H__ */ 225
