2 * @brief Device mode driver for the library USB HID Class driver
\r
5 * Copyright(C) NXP Semiconductors, 2012
\r
6 * Copyright(C) Dean Camera, 2011, 2012
\r
7 * All rights reserved.
\r
10 * Software that is described herein is for illustrative purposes only
\r
11 * which provides customers with programming information regarding the
\r
12 * LPC products. This software is supplied "AS IS" without any warranties of
\r
13 * any kind, and NXP Semiconductors and its licensor disclaim any and
\r
14 * all warranties, express or implied, including all implied warranties of
\r
15 * merchantability, fitness for a particular purpose and non-infringement of
\r
16 * intellectual property rights. NXP Semiconductors assumes no responsibility
\r
17 * or liability for the use of the software, conveys no license or rights under any
\r
18 * patent, copyright, mask work right, or any other intellectual property rights in
\r
19 * or to any products. NXP Semiconductors reserves the right to make changes
\r
20 * in the software without notification. NXP Semiconductors also makes no
\r
21 * representation or warranty that such application will be suitable for the
\r
22 * specified use without further testing or modification.
\r
25 * Permission to use, copy, modify, and distribute this software and its
\r
26 * documentation is hereby granted, under NXP Semiconductors' and its
\r
27 * licensor's relevant copyrights in the software, without fee, provided that it
\r
28 * is used in conjunction with NXP Semiconductors microcontrollers. This
\r
29 * copyright, permission, and disclaimer notice must appear in all copies of
\r
33 /** @ingroup Group_USBClassHID
\r
34 * @defgroup Group_USBClassHIDDevice HID Class Device Mode Driver
\r
36 * @section Sec_Dependencies Module Source Dependencies
\r
37 * The following files must be built with any user project that uses this module:
\r
38 * - nxpUSBlib/Drivers/USB/Class/Device/HID.c <i>(Makefile source module name: NXPUSBLIB_SRC_USBCLASS)</i>
\r
40 * @section Sec_ModDescription Module Description
\r
41 * Device Mode USB Class driver framework interface, for the HID USB Class driver.
\r
46 #ifndef _HID_CLASS_DEVICE_H_
\r
47 #define _HID_CLASS_DEVICE_H_
\r
50 #include "../../USB.h"
\r
51 #include "../Common/HIDClassCommon.h"
\r
53 /* Enable C linkage for C++ Compilers: */
\r
54 #if defined(__cplusplus)
\r
58 /* Preprocessor Checks: */
\r
59 #if !defined(__INCLUDE_FROM_HID_DRIVER)
\r
60 #error Do not include this file directly. Include LPCUSBlib/Drivers/USB.h instead.
\r
63 /* Public Interface - May be used in end-application: */
\r
65 /** @brief HID Class Device Mode Configuration and State Structure.
\r
67 * Class state structure. An instance of this structure should be made for each HID interface
\r
68 * within the user application, and passed to each of the HID class driver functions as the
\r
69 * \c HIDInterfaceInfo parameter. This stores each HID interface's configuration and state information.
\r
71 * @note Due to technical limitations, the HID device class driver does not utilize a separate OUT
\r
72 * endpoint for host->device communications. Instead, the host->device data (if any) is sent to
\r
73 * the device via the control endpoint.
\r
77 uint8_t InterfaceNumber; /**< Interface number of the HID interface within the device. */
\r
79 uint8_t ReportINEndpointNumber; /**< Endpoint number of the HID interface's IN report endpoint. */
\r
80 uint16_t ReportINEndpointSize; /**< Size in bytes of the HID interface's IN report endpoint. */
\r
81 bool ReportINEndpointDoubleBank; /**< Indicates if the HID interface's IN report endpoint should use double banking. */
\r
83 void *PrevReportINBuffer; /**< Pointer to a buffer where the previously created HID input report can be
\r
84 * stored by the driver, for comparison purposes to detect report changes that
\r
85 * must be sent immediately to the host. This should point to a buffer big enough
\r
86 * to hold the largest HID input report sent from the HID interface. If this is set
\r
87 * to \c NULL, it is up to the user to force transfers when needed in the
\r
88 * @ref CALLBACK_HID_Device_CreateHIDReport() callback function.
\r
90 * @note Due to the single buffer, the internal driver can only correctly compare
\r
91 * subsequent reports with identical report IDs. In multiple report devices,
\r
92 * this buffer should be set to \c NULL and the decision to send reports made
\r
93 * by the user application instead.
\r
95 uint8_t PrevReportINBufferSize; /**< Size in bytes of the given input report buffer. This is used to create a
\r
96 * second buffer of the same size within the driver so that subsequent reports
\r
97 * can be compared. If the user app is to determine when reports are to be sent
\r
98 * exclusively (i.e. @ref PrevReportINBuffer is \c NULL) this value must still be
\r
99 * set to the size of the largest report the device can issue to the host.
\r
101 uint8_t PortNumber; /**< Port number that this interface is running.*/
\r
102 } Config; /**< Config data for the USB class interface within the device. All elements in this section
\r
103 * <b>must</b> be set or the interface will fail to enumerate and operate correctly.
\r
107 bool UsingReportProtocol; /**< Indicates if the HID interface is set to Boot or Report protocol mode. */
\r
108 uint16_t IdleCount; /**< Report idle period, in milliseconds, set by the host. */
\r
109 uint16_t IdleMSRemaining; /**< Total number of milliseconds remaining before the idle period elapsed - this
\r
110 * should be decremented by the user application if non-zero each millisecond. */
\r
111 } State; /**< State data for the USB class interface within the device. All elements in this section
\r
112 * are reset to their defaults when the interface is enumerated.
\r
115 } USB_ClassInfo_HID_Device_t;
\r
117 /* Function Prototypes: */
\r
119 * @brief Configures the endpoints of a given HID interface, ready for use. This should be linked to the library
\r
120 * @ref EVENT_USB_Device_ConfigurationChanged() event so that the endpoints are configured when the configuration
\r
121 * containing the given HID interface is selected.
\r
123 * @param HIDInterfaceInfo : Pointer to a structure containing a HID Class configuration and state.
\r
125 * @return Boolean \c true if the endpoints were successfully configured, \c false otherwise.
\r
127 bool HID_Device_ConfigureEndpoints(USB_ClassInfo_HID_Device_t *const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
\r
130 * @brief Processes incoming control requests from the host, that are directed to the given HID class interface. This should be
\r
131 * linked to the library @ref EVENT_USB_Device_ControlRequest() event.
\r
133 * @param HIDInterfaceInfo : Pointer to a structure containing a HID Class configuration and state.
\r
136 void HID_Device_ProcessControlRequest(USB_ClassInfo_HID_Device_t *const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
\r
139 * @brief General management task for a given HID class interface, required for the correct operation of the interface. This should
\r
140 * be called frequently in the main program loop, before the master USB management task @ref USB_USBTask().
\r
142 * @param HIDInterfaceInfo : Pointer to a structure containing a HID Class configuration and state.
\r
145 void HID_Device_USBTask(USB_ClassInfo_HID_Device_t *const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
\r
148 * @brief HID class driver callback for the user creation of a HID IN report. This callback may fire in response to either
\r
149 * HID class control requests from the host, or by the normal HID endpoint polling procedure. Inside this callback the
\r
150 * user is responsible for the creation of the next HID input report to be sent to the host.
\r
152 * @param HIDInterfaceInfo : Pointer to a structure containing a HID Class configuration and state.
\r
153 * @param ReportID : If preset to a non-zero value, this is the report ID being requested by the host. If zero,
\r
154 * this should be set to the report ID of the generated HID input report (if any). If multiple
\r
155 * reports are not sent via the given HID interface, this parameter should be ignored.
\r
156 * @param ReportType : Type of HID report to generate, either @ref HID_REPORT_ITEM_In or @ref HID_REPORT_ITEM_Feature.
\r
157 * @param ReportData : Pointer to a buffer where the generated HID report should be stored.
\r
158 * @param ReportSize : Number of bytes in the generated input report, or zero if no report is to be sent.
\r
160 * @return Boolean \c true to force the sending of the report even if it is identical to the previous report and still within
\r
161 * the idle period (useful for devices which report relative movement), \c false otherwise.
\r
163 bool CALLBACK_HID_Device_CreateHIDReport(USB_ClassInfo_HID_Device_t *const HIDInterfaceInfo,
\r
164 uint8_t *const ReportID,
\r
165 const uint8_t ReportType,
\r
167 uint16_t *const ReportSize) ATTR_NON_NULL_PTR_ARG(1)
\r
168 ATTR_NON_NULL_PTR_ARG(2) ATTR_NON_NULL_PTR_ARG(4) ATTR_NON_NULL_PTR_ARG(5);
\r
171 * @brief HID class driver callback for the user processing of a received HID OUT report. This callback may fire in response to
\r
172 * either HID class control requests from the host, or by the normal HID endpoint polling procedure. Inside this callback
\r
173 * the user is responsible for the processing of the received HID output report from the host.
\r
175 * @param HIDInterfaceInfo : Pointer to a structure containing a HID Class configuration and state.
\r
176 * @param ReportID : Report ID of the received output report. If multiple reports are not received via the given HID
\r
177 * interface, this parameter should be ignored.
\r
178 * @param ReportType : Type of received HID report, either @ref HID_REPORT_ITEM_Out or @ref HID_REPORT_ITEM_Feature.
\r
179 * @param ReportData : Pointer to a buffer where the received HID report is stored.
\r
180 * @param ReportSize : Size in bytes of the received report from the host.
\r
183 void CALLBACK_HID_Device_ProcessHIDReport(USB_ClassInfo_HID_Device_t *const HIDInterfaceInfo,
\r
184 const uint8_t ReportID,
\r
185 const uint8_t ReportType,
\r
186 const void *ReportData,
\r
187 const uint16_t ReportSize) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(4);
\r
189 /* Inline Functions: */
\r
191 * @brief Indicates that a millisecond of idle time has elapsed on the given HID interface, and the interface's idle count should be
\r
192 * decremented. This should be called once per millisecond so that hardware key-repeats function correctly. It is recommended
\r
193 * that this be called by the @ref EVENT_USB_Device_StartOfFrame() event, once SOF events have been enabled via
\r
194 * @ref USB_Device_EnableSOFEvents().
\r
196 * @param HIDInterfaceInfo : Pointer to a structure containing a HID Class configuration and state.
\r
198 PRAGMA_ALWAYS_INLINE
\r
199 static inline void HID_Device_MillisecondElapsed(USB_ClassInfo_HID_Device_t *const HIDInterfaceInfo) ATTR_ALWAYS_INLINE
\r
200 ATTR_NON_NULL_PTR_ARG(1);
\r
201 static inline void HID_Device_MillisecondElapsed(USB_ClassInfo_HID_Device_t *const HIDInterfaceInfo)
\r
203 if (HIDInterfaceInfo->State.IdleMSRemaining) {
\r
204 HIDInterfaceInfo->State.IdleMSRemaining--;
\r
208 /* Disable C linkage for C++ Compilers: */
\r
209 #if defined(__cplusplus)
\r
projects / freertos / blob