1 /******************************************************************************* 2 * Copyright 2019-2020 Microchip FPGA Embedded Systems Solutions. 3 * 4 * SPDX-License-Identifier: MIT 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining a copy 7 * of this software and associated documentation files (the "Software"), to 8 * deal in the Software without restriction, including without limitation the 9 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 10 * sell copies of the Software, and to permit persons to whom the Software is 11 * furnished to do so, subject to the following conditions: 12 * 13 * The above copyright notice and this permission notice shall be included in 14 * all copies or substantial portions of the Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 22 * IN THE SOFTWARE. 23 * 24 * PolarFire SoC MSS USB Driver Stack 25 * USB Logical Layer (USB-LL) 26 * USBD-HID class driver 27 * 28 * Header file for mss_usb_device_hid.c 29 * 30 */ 31 /*=========================================================================*//** 32 @mainpage PolarFire SoC MSS USB driver 33 USBD-HID class driver 34 35 @section intro_sec Introduction 36 The Human Interface Device class driver implements the USB HID class 37 functionality specified by the USB-IF. This driver supports the HID mouse 38 functionality. The USB control transfers and Interrupt transfers are used to 39 implement this functionality. With this driver, the PolarFire SoC device 40 appears as a Human interface class Mouse device when connected to USB host, 41 This driver can be extended to be used for other HID class functionalities. 42 43 This driver uses the USBD-Class driver template to implement the HID class 44 functionality. 45 46 @section theory_op Theory of Operation 47 The following steps are involved in the operation of the USBD-HID driver: 48 - Configuration 49 - Initialization 50 - Enumeration 51 - Class Specific requests 52 - data transfer 53 Configuration 54 The MSS USB driver stack must first be configured in the USB device mode using 55 the MSS_USB_PERIPHERAL_MODE constant to use this driver. No other 56 configuration is necessary. 57 58 Initialization 59 The HID class driver must be initialized using the MSS_USBD_HID_init() function. 60 Once initialized, this driver will get configured by the USBD driver during 61 the enumeration process. The call-back function usbd_hid_init_cb() is 62 implemented by this driver which will be called by the USBD driver when the 63 host configures this device. The USBD_HID_get_descriptor() function is 64 implemented to provide class specific descriptor table to the USBD driver. 65 66 This driver defines descriptor table which contains a configuration descriptor, 67 an Interface descriptor, a HID class descriptor and an Interrupt IN endpoint 68 descriptor for successful enumeration as a HID class device. 69 70 Note: For successful enumeration, device specific descriptors must be provided 71 by application using MSS_USBD_set_desc_cb_handler() function to the 72 USBD driver. Since device, string descriptors etc. are not specific to a USB 73 class they are not part of HID Class driver. 74 75 Class Specific requests 76 The requests specific to HID Class are handled internally by this driver. The 77 call-back function usbd_hid_process_request_cb(), is implemented by this 78 driver which processes the HID class specific requests. 79 80 Data transfer 81 This driver only needs to perform the USB IN transfers on the Interrupt 82 endpoint. The period at which this transfer is repeated is defined by the 83 endpoint descriptor during enumeration process. The application must use the 84 MSS_USBD_HID_tx_report() function to provide the report to be transmitted. 85 The application can use the MSS_USBD_HID_tx_done() function to know if the 86 previously provided report is transmitted over USB. This driver implements 87 the usbd_hid_tx_complete_cb() function which will be called by the USBD 88 driver when the data transfers is complete. 89 90 *//*=========================================================================*/ 91 92 #ifndef __MSS_USB_DEVICE_HID_H_ 93 #define __MSS_USB_DEVICE_HID_H_ 94 95 #ifdef __cplusplus 96 extern "C" { 97 #endif 98 99 #ifdef MSS_USB_DEVICE_ENABLED 100 /******************************************************************************* 101 * Public constants and data structures from HID class driver. 102 */ 103 /******************************************************************************* 104 USBD-HID configuration definitions: These values will be used by HID driver 105 to configure the MSS USB core endpoints. These values are also used for 106 generating the descriptor tables which are sent to the USB host during 107 enumeration. 108 109 Note1: 110 You are allowed to modify these values according to requirement. 111 Make sure that the values here are in accordance with the user descriptors 112 device descriptor etc), USB 2.0 standard and USB Core Driver operation speed 113 (MSS_USB_DEVICE_HS or MSS_USB_DEVICE_FS) 114 115 Note2: 116 If you change these constants make sure that the speed dependent descriptor are 117 updated accordingly. 118 */ 119 120 #define HID_INTR_TX_EP MSS_USB_TX_EP_1 121 #define HID_INTR_TX_EP_FIFO_ADDR 0x200u 122 #define HID_INTR_TX_EP_FIFO_SIZE 64u 123 #define HID_INTR_TX_EP_MAX_PKT_SIZE 64u 124 125 126 /*Full configuration descriptor length*/ 127 #define HID_CONFIG_DESCR_LENGTH (USB_STD_CONFIG_DESCR_LEN + \ 128 USB_STD_INTERFACE_DESCR_LEN + \ 129 USB_HID_DESCR_LENGTH + \ 130 USB_STD_ENDPOINT_DESCR_LEN) 131 132 /***************************************************************************//** 133 The mss_usbd_hid_state_t is used to provide the information of the current 134 state of the HID class driver.This type is intended to be used by the application 135 to know if this driver is been configured by the USB host. i.e. the enumeration 136 is complete and data transfers can be started. 137 138 USBD_HID_NOT_CONFIGURED -- The USB HID class driver is not configured and it 139 cannot perform the data transfers. 140 USBD_HID_CONFIGURED -- The USB HID class driver is configured by the host 141 and it can perform the data transfers. 142 */ 143 typedef enum mss_usbd_hid_state { 144 USBD_HID_NOT_CONFIGURED, 145 USBD_HID_CONFIGURED 146 }mss_usbd_hid_state_t; 147 148 /***************************************************************************//** 149 mss_usbd_hid_report_t 150 The mss_usbd_hid_report_t type provides the prototype for the report to be 151 sent to the host. The application must provide the report data using this type. 152 153 buttons 154 The buttons parameter provides the current state of the Button0 to Button5 on 155 mouse in bit0 to bit5 of this parameter. 156 157 x_move 158 The x_move parameter provides the current x co-ordinate of the mouse. 159 160 y_move 161 The y-move parameter provides the current y co-ordinate of the mouse. 162 163 wheel 164 The wheel parameter provides the current wheel position of the mouse. 165 */ 166 typedef struct mss_usbd_hid_report { 167 int8_t buttons; 168 int8_t x_move; 169 int8_t y_move; 170 int8_t wheel; 171 } mss_usbd_hid_report_t; 172 173 /***************************************************************************//** 174 * Exported function from HID Class driver. 175 *******************************************************************************/ 176 /***************************************************************************//** 177 @brief MSS_USBD_HID_init() 178 The MSS_USBD_HID_init() function must be used by the application to initialize 179 the USBD-HID driver before transmitting the report data. 180 181 @param speed 182 The speed parameter indicates the USB speed at which the USBD-HID driver must 183 operate. 184 185 @return 186 This function does not return any value. 187 188 Example: 189 @code 190 // Assign call-back function handler structure needed by USBD driver 191 MSS_USBD_set_desc_cb_handler(&hid_mouse_descr_cb); 192 193 //Initialize USB Device Core driver 194 MSS_USBD_init(MSS_USB_DEVICE_FS); 195 196 //Initialize HID Class driver. 197 MSS_USBD_HID_init(MSS_USB_DEVICE_FS); 198 199 @endcode 200 */ 201 void 202 MSS_USBD_HID_init 203 ( 204 mss_usb_device_speed_t speed 205 ); 206 207 /***************************************************************************//** 208 @brief MSS_USBD_HID_tx_report() 209 The MSS_USBD_HID_tx_report() function can be used by the application to provide 210 the buffer containing the report data to the HID class driver. The report data 211 will be loaded into the TX endpoint and will be transmitted when the next IN 212 packet arrives from the host. 213 214 @param buf 215 The buf parameter indicates the address of the buffer containing the HID 216 report data. 217 218 @param length 219 The length parameter indicates the number of bytes to be transmitted. 220 221 @return 222 This function return a non-zero value if the function was successfully 223 executed. A zero return value indicates that the transmission was not started. 224 225 Example: 226 @code 227 @endcode 228 */ 229 uint32_t 230 MSS_USBD_HID_tx_report 231 ( 232 uint8_t* buf, 233 uint32_t length 234 ); 235 236 /***************************************************************************//** 237 @brief MSS_USBD_HID_tx_done() 238 The MSS_USBD_HID_tx_done() function can be used by the application to find out 239 if the transmission of the previously provided report is complete. 240 241 @param 242 This function takes no parameters. 243 244 @return 245 This function returns a non-zero value to indicate the previously provided 246 report is successfully transmitted. A zero value indicates that the 247 transmission is not yet complete. 248 249 Example: 250 @code 251 if(MSS_USBD_HID_tx_done()) 252 { 253 MSS_USBD_HID_tx_report ((uint8_t*)&report, sizeof(report)); 254 } 255 256 @endcode 257 */ 258 uint8_t 259 MSS_USBD_HID_tx_done 260 ( 261 void 262 ); 263 264 #endif //MSS_USB_DEVICE_ENABLED 265 266 #ifdef __cplusplus 267 } 268 #endif 269 270 #endif /* __MSS_USB_DEVICE_HID_H_ */ 271