2 * @brief Host 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_USBClassHIDHost HID Class Host 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 * - LPCUSBlib/Drivers/USB/Class/Host/HID.c <i>(Makefile source module name: LPCUSBlib_SRC_USBCLASS)</i>
\r
40 * @section Sec_ModDescription Module Description
\r
41 * Host Mode USB Class driver framework interface, for the HID USB Class driver.
\r
46 #ifndef __HID_CLASS_HOST_H__
\r
47 #define __HID_CLASS_HOST_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 /** Error code for some HID Host functions, indicating a logical (and not hardware) error. */
\r
66 #define HID_ERROR_LOGICAL 0x80
\r
69 /** @brief HID Class Host Mode Configuration and State Structure.
\r
71 * Class state structure. An instance of this structure should be made within the user application,
\r
72 * and passed to each of the HID class driver functions as the \c HIDInterfaceInfo parameter. This
\r
73 * stores each HID interface's configuration and state information.
\r
79 uint8_t DataINPipeNumber; /**< Pipe number of the HID interface's IN data pipe. */
\r
80 bool DataINPipeDoubleBank; /**< Indicates if the HID interface's IN data pipe should use double banking. */
\r
82 uint8_t DataOUTPipeNumber; /**< Pipe number of the HID interface's OUT data pipe. */
\r
83 bool DataOUTPipeDoubleBank; /**< Indicates if the HID interface's OUT data pipe should use double banking. */
\r
85 uint8_t HIDInterfaceProtocol; /**< HID interface protocol value to match against if a specific
\r
86 * boot subclass protocol is required, a protocol value from the
\r
87 * @ref HID_Descriptor_ClassSubclassProtocol_t enum.
\r
89 #if !defined(HID_HOST_BOOT_PROTOCOL_ONLY)
\r
90 HID_ReportInfo_t* HIDParserData; /**< HID parser data to store the parsed HID report data, when boot protocol
\r
93 * @note When the \c HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined,
\r
94 * this method is unavailable.
\r
98 uint8_t PortNumber; /**< Port number that this interface is running.
\r
100 } Config; /**< Config data for the USB class interface within the device. All elements in this section
\r
101 * <b>must</b> be set or the interface will fail to enumerate and operate correctly.
\r
105 bool IsActive; /**< Indicates if the current interface instance is connected to an attached device, valid
\r
106 * after @ref HID_Host_ConfigurePipes() is called and the Host state machine is in the
\r
107 * Configured state.
\r
109 uint8_t InterfaceNumber; /**< Interface index of the HID interface within the attached device. */
\r
111 uint16_t DataINPipeSize; /**< Size in bytes of the HID interface's IN data pipe. */
\r
112 uint16_t DataOUTPipeSize; /**< Size in bytes of the HID interface's OUT data pipe. */
\r
114 bool SupportsBootProtocol; /**< Indicates if the current interface instance supports the HID Boot
\r
115 * Protocol when enabled via @ref HID_Host_SetBootProtocol().
\r
117 bool DeviceUsesOUTPipe; /**< Indicates if the current interface instance uses a separate OUT data pipe for
\r
118 * OUT reports, or if OUT reports are sent via the control pipe instead.
\r
120 bool UsingBootProtocol; /**< Indicates that the interface is currently initialized in Boot Protocol mode */
\r
121 uint16_t HIDReportSize; /**< Size in bytes of the HID report descriptor in the device. */
\r
123 uint8_t LargestReportSize; /**< Largest report the device will send, in bytes. */
\r
124 } State; /**< State data for the USB class interface within the device. All elements in this section
\r
125 * <b>may</b> be set to initial values, but may also be ignored to default to sane values when
\r
126 * the interface is enumerated.
\r
128 } USB_ClassInfo_HID_Host_t;
\r
131 /** Enum for the possible error codes returned by the @ref HID_Host_ConfigurePipes() function. */
\r
132 enum HID_Host_EnumerationFailure_ErrorCodes_t
\r
134 HID_ENUMERROR_NoError = 0, /**< Configuration Descriptor was processed successfully. */
\r
135 HID_ENUMERROR_InvalidConfigDescriptor = 1, /**< The device returned an invalid Configuration Descriptor. */
\r
136 HID_ENUMERROR_NoCompatibleInterfaceFound = 2, /**< A compatible HID interface was not found in the device's Configuration Descriptor. */
\r
137 HID_ENUMERROR_PipeConfigurationFailed = 3, /**< One or more pipes for the specified interface could not be configured correctly. */
\r
140 /* Function Prototypes: */
\r
141 /** @brief Host interface configuration routine, to configure a given HID host interface instance using the Configuration
\r
142 * Descriptor read from an attached USB device. This function automatically updates the given HID Host instance's
\r
143 * state values and configures the pipes required to communicate with the interface if it is found within the
\r
144 * device. This should be called once after the stack has enumerated the attached device, while the host state
\r
145 * machine is in the Addressed state.
\r
147 * @note Once the device pipes are configured, the HID device's reporting protocol <b>must</b> be set via a call
\r
148 * to either the @ref HID_Host_SetBootProtocol() or @ref HID_Host_SetReportProtocol() function.
\r
150 * @param HIDInterfaceInfo : Pointer to a structure containing a HID Class host configuration and state.
\r
151 * @param ConfigDescriptorSize : Length of the attached device's Configuration Descriptor.
\r
152 * @param DeviceConfigDescriptor : Pointer to a buffer containing the attached device's Configuration Descriptor.
\r
154 * @return A value from the @ref HID_Host_EnumerationFailure_ErrorCodes_t enum.
\r
156 uint8_t HID_Host_ConfigurePipes(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo,
\r
157 uint16_t ConfigDescriptorSize,
\r
158 void* DeviceConfigDescriptor) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);
\r
161 /** @brief Receives a HID IN report from the attached HID device, when a report has been received on the HID IN Data pipe.
\r
163 * @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the
\r
166 * @note The destination buffer should be large enough to accommodate the largest report that the attached device
\r
169 * @param HIDInterfaceInfo : Pointer to a structure containing a HID Class host configuration and state.
\r
170 * @param Buffer : Buffer to store the received report into.
\r
172 * @return An error code from the @ref Pipe_Stream_RW_ErrorCodes_t enum.
\r
174 uint8_t HID_Host_ReceiveReport(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo,
\r
175 void* Buffer) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
\r
177 #if !defined(HID_HOST_BOOT_PROTOCOL_ONLY)
\r
178 /** @brief Receives a HID IN report from the attached device, by the report ID.
\r
180 * @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the
\r
183 * @note When the \c HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, this method is unavailable.
\r
185 * @param HIDInterfaceInfo : Pointer to a structure containing a HID Class host configuration and state.
\r
186 * @param ReportID : Report ID of the received report if ControlRequest is false, set by the to the Report ID to fetch.
\r
187 * @param Buffer Buffer to store the received report into.
\r
189 * @return A value from the @ref USB_Host_SendControlErrorCodes_t enum.
\r
191 uint8_t HID_Host_ReceiveReportByID(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo,
\r
192 const uint8_t ReportID,
\r
193 void* Buffer) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);
\r
196 /** @brief Sends an OUT or FEATURE report to the currently attached HID device, using the device's OUT pipe if available,
\r
197 * or the device's Control pipe if not.
\r
199 * @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the
\r
202 * @note When the \c HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, the ReportID parameter is removed
\r
203 * from the parameter list of this function.
\r
205 * @param HIDInterfaceInfo : Pointer to a structure containing a HID Class host configuration and state.
\r
206 * @param ReportID : Report ID of the report to send to the device, or 0 if the device does not use report IDs.
\r
207 * @param ReportType : Type of report to issue to the device, either @ref HID_REPORT_ITEM_Out or @ref HID_REPORT_ITEM_Feature.
\r
208 * @param Buffer : Buffer containing the report to send to the attached device.
\r
209 * @param ReportSize : Report size in bytes to send to the attached device.
\r
211 * @return An error code from the @ref USB_Host_SendControlErrorCodes_t enum if the DeviceUsesOUTPipe flag is set in
\r
212 * the interface's state structure, a value from the @ref Pipe_Stream_RW_ErrorCodes_t enum otherwise.
\r
214 uint8_t HID_Host_SendReportByID(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo,
\r
215 #if !defined(HID_HOST_BOOT_PROTOCOL_ONLY)
\r
216 const uint8_t ReportID,
\r
218 const uint8_t ReportType,
\r
220 const uint16_t ReportSize) ATTR_NON_NULL_PTR_ARG(1)
\r
221 #if !defined(HID_HOST_BOOT_PROTOCOL_ONLY)
\r
222 ATTR_NON_NULL_PTR_ARG(4);
\r
224 ATTR_NON_NULL_PTR_ARG(3);
\r
227 /** @brief Determines if a HID IN report has been received from the attached device on the data IN pipe.
\r
229 * @pre This function must only be called when the Host state machine is in the @ref HOST_STATE_Configured state or the
\r
232 * @param HIDInterfaceInfo : Pointer to a structure containing a HID Class host configuration and state.
\r
234 * @return Boolean \c true if a report has been received, \c false otherwise.
\r
236 bool HID_Host_IsReportReceived(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
\r
238 /** @brief Switches the attached HID device's reporting protocol over to the Boot Report protocol mode, on supported devices.
\r
240 * @note When the \c HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, this method must still be called
\r
241 * to explicitly place the attached device into boot protocol mode before use.
\r
243 * @param HIDInterfaceInfo : Pointer to a structure containing a HID Class host configuration and state.
\r
245 * @return @ref HID_ERROR_LOGICAL if the device does not support Boot Protocol mode, a value from the
\r
246 * @ref USB_Host_SendControlErrorCodes_t enum otherwise.
\r
248 uint8_t HID_Host_SetBootProtocol(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
\r
250 /** @brief Sets the idle period for the attached HID device to the specified interval. The HID idle period determines the rate
\r
251 * at which the device should send a report, when no state changes have ocurred; i.e. on HID keyboards, this sets the
\r
252 * hardware key repeat interval.
\r
254 * @param HIDInterfaceInfo : Pointer to a structure containing a HID Class host configuration and state.
\r
255 * @param MS : Idle period as a multiple of four milliseconds, zero to disable hardware repeats
\r
257 * @return A value from the @ref USB_Host_SendControlErrorCodes_t enum.
\r
259 uint8_t HID_Host_SetIdlePeriod(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo,
\r
260 const uint16_t MS) ATTR_NON_NULL_PTR_ARG(1);
\r
262 #if !defined(HID_HOST_BOOT_PROTOCOL_ONLY)
\r
263 /** @brief Switches the attached HID device's reporting protocol over to the standard Report protocol mode. This also retrieves
\r
264 * and parses the device's HID report descriptor, so that the size of each report can be determined in advance.
\r
266 * @note Whether this function is used or not, the @ref CALLBACK_HIDParser_FilterHIDReportItem() callback from the HID
\r
267 * Report Parser this function references <b>must</b> be implemented in the user code.
\r
270 * @note When the \c HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, this method is unavailable.
\r
272 * @param HIDInterfaceInfo : Pointer to a structure containing a HID Class host configuration and state.
\r
274 * @return A value from the @ref USB_Host_SendControlErrorCodes_t enum if an error occurs while retrieving the HID
\r
275 * Report descriptor or the setting of the Report protocol, @ref HID_ERROR_LOGICAL if the HID interface does
\r
276 * not have a valid @ref HID_ReportInfo_t structure set in its configuration, a mask of @ref HID_ERROR_LOGICAL
\r
277 * and a value from the @ref HID_Parse_ErrorCodes_t otherwise.
\r
279 uint8_t HID_Host_SetReportProtocol(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
\r
282 /* Inline Functions: */
\r
283 /** @brief General management task for a given Human Interface Class host class interface, required for the correct operation of
\r
284 * the interface. This should be called frequently in the main program loop, before the master USB management task
\r
285 * @ref USB_USBTask().
\r
287 * @param HIDInterfaceInfo : Pointer to a structure containing a HID Class host configuration and state.
\r
290 static inline void HID_Host_USBTask(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
\r
291 static inline void HID_Host_USBTask(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo)
\r
293 (void)HIDInterfaceInfo;
\r
296 /* Private Interface - For use in library only: */
\r
297 #if !defined(__DOXYGEN__)
\r
298 /* Function Prototypes: */
\r
299 #if defined(__INCLUDE_FROM_HID_HOST_C)
\r
300 static uint8_t DCOMP_HID_Host_NextHIDInterface(void* const CurrentDescriptor)
\r
301 ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);
\r
302 static uint8_t DCOMP_HID_Host_NextHIDDescriptor(void* const CurrentDescriptor)
\r
303 ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);
\r
304 static uint8_t DCOMP_HID_Host_NextHIDInterfaceEndpoint(void* const CurrentDescriptor)
\r
305 ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(1);
\r
309 /* Disable C linkage for C++ Compilers: */
\r
310 #if defined(__cplusplus)
\r
projects / freertos / blob