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