2 * @brief USB Human Interface Device (HID) Class report descriptor parser
\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_USB
\r
34 * @defgroup Group_HIDParser HID Report Parser
\r
35 * @brief USB Human Interface Device (HID) Class report descriptor parser.
\r
37 * @section Sec_Dependencies Module Source Dependencies
\r
38 * The following files must be built with any user project that uses this module:
\r
39 * - nxpUSBlib/Drivers/USB/Class/Host/HIDParser.c <i>(Makefile source module name: NXPUSBLIB_SRC_USB)</i>
\r
41 * @section Sec_ModDescription Module Description
\r
42 * Human Interface Device (HID) class report descriptor parser. This module implements a parser than is
\r
43 * capable of processing a complete HID report descriptor, and outputting a flat structure containing the
\r
44 * contents of the report in an a more friendly format. The parsed data may then be further processed and used
\r
45 * within an application to process sent and received HID reports to and from an attached HID device.
\r
47 * A HID report descriptor consists of a set of HID report items, which describe the function and layout
\r
48 * of data exchanged between a HID device and a host, including both the physical encoding of each item
\r
49 * (such as a button, key press or joystick axis) in the sent and received data packets - known as "reports" -
\r
50 * as well as other information about each item such as the usages, data range, physical location and other
\r
51 * characteristics. In this way a HID device can retain a high degree of flexibility in its capabilities, as it
\r
52 * is not forced to comply with a given report layout or feature-set.
\r
54 * This module also contains routines for the processing of data in an actual HID report, using the parsed report
\r
55 * descriptor data as a guide for the encoding.
\r
60 #ifndef __HIDPARSER_H__
\r
61 #define __HIDPARSER_H__
\r
64 #include "../../../../Common/Common.h"
\r
66 #include "HIDReportData.h"
\r
67 #include "HIDClassCommon.h"
\r
69 /* Enable C linkage for C++ Compilers: */
\r
70 #if defined(__cplusplus)
\r
75 #if !defined(HID_STATETABLE_STACK_DEPTH) || defined(__DOXYGEN__)
\r
76 /** Constant indicating the maximum stack depth of the state table. A larger state table
\r
77 * allows for more PUSH/POP report items to be nested, but consumes more memory. By default
\r
78 * this is set to 2 levels (allowing non-nested PUSH items) but this can be overridden by
\r
79 * defining \c HID_STATETABLE_STACK_DEPTH to another value in the user project makefile, passing the
\r
80 * define to the compiler using the -D compiler switch.
\r
82 #define HID_STATETABLE_STACK_DEPTH 2
\r
85 #if !defined(HID_USAGE_STACK_DEPTH) || defined(__DOXYGEN__)
\r
86 /** Constant indicating the maximum stack depth of the usage table. A larger usage table
\r
87 * allows for more USAGE items to be indicated sequentially for REPORT COUNT entries of more than
\r
88 * one, but requires more stack space. By default this is set to 8 levels (allowing for a report
\r
89 * item with a count of 8) but this can be overridden by defining \c HID_USAGE_STACK_DEPTH to another
\r
90 * value in the user project makefile, passing the define to the compiler using the -D compiler
\r
93 #define HID_USAGE_STACK_DEPTH 8
\r
96 #if !defined(HID_MAX_COLLECTIONS) || defined(__DOXYGEN__)
\r
97 /** Constant indicating the maximum number of COLLECTION items (nested or unnested) that can be
\r
98 * processed in the report item descriptor. A large value allows for more COLLECTION items to be
\r
99 * processed, but consumes more memory. By default this is set to 10 collections, but this can be
\r
100 * overridden by defining \c HID_MAX_COLLECTIONS to another value in the user project makefile, passing
\r
101 * the define to the compiler using the -D compiler switch.
\r
103 #define HID_MAX_COLLECTIONS 10
\r
106 #if !defined(HID_MAX_REPORTITEMS) || defined(__DOXYGEN__)
\r
107 /** Constant indicating the maximum number of report items (IN, OUT or FEATURE) that can be processed
\r
108 * in the report item descriptor and stored in the user HID Report Info structure. A large value allows
\r
109 * for more report items to be stored, but consumes more memory. By default this is set to 20 items,
\r
110 * but this can be overridden by defining \c HID_MAX_REPORTITEMS to another value in the user project
\r
111 * makefile, and passing the define to the compiler using the -D compiler switch.
\r
113 #define HID_MAX_REPORTITEMS 20
\r
116 #if !defined(HID_MAX_REPORT_IDS) || defined(__DOXYGEN__)
\r
117 /** Constant indicating the maximum number of unique report IDs that can be processed in the report item
\r
118 * descriptor for the report size information array in the user HID Report Info structure. A large value
\r
119 * allows for more report ID report sizes to be stored, but consumes more memory. By default this is set
\r
120 * to 10 items, but this can be overridden by defining \c HID_MAX_REPORT_IDS to another value in the user project
\r
121 * makefile, and passing the define to the compiler using the -D compiler switch. Note that IN, OUT and FEATURE
\r
122 * items sharing the same report ID consume only one size item in the array.
\r
124 #define HID_MAX_REPORT_IDS 10
\r
127 /** Returns the value a given HID report item (once its value has been fetched via @ref USB_GetHIDReportItemInfo())
\r
128 * left-aligned to the given data type. This allows for signed data to be interpreted correctly, by shifting the data
\r
129 * leftwards until the data's sign bit is in the correct position.
\r
131 * @param ReportItem HID Report Item whose retrieved value is to be aligned.
\r
132 * @param Type Data type to align the HID report item's value to.
\r
134 * @return Left-aligned data of the given report item's pre-retrieved value for the given datatype.
\r
136 #define HID_ALIGN_DATA(ReportItem, Type) ((Type)(ReportItem->Value << ((8 * sizeof(Type)) - ReportItem->Attributes.BitSize)))
\r
138 /* Public Interface - May be used in end-application: */
\r
140 /** Enum for the possible error codes in the return value of the @ref USB_ProcessHIDReport() function. */
\r
141 enum HID_Parse_ErrorCodes_t
\r
143 HID_PARSE_Successful = 0, /**< Successful parse of the HID report descriptor, no error. */
\r
144 HID_PARSE_HIDStackOverflow = 1, /**< More than @ref HID_STATETABLE_STACK_DEPTH nested PUSHes in the report. */
\r
145 HID_PARSE_HIDStackUnderflow = 2, /**< A POP was found when the state table stack was empty. */
\r
146 HID_PARSE_InsufficientReportItems = 3, /**< More than @ref HID_MAX_REPORTITEMS report items in the report. */
\r
147 HID_PARSE_UnexpectedEndCollection = 4, /**< An END COLLECTION item found without matching COLLECTION item. */
\r
148 HID_PARSE_InsufficientCollectionPaths = 5, /**< More than @ref HID_MAX_COLLECTIONS collections in the report. */
\r
149 HID_PARSE_UsageListOverflow = 6, /**< More than @ref HID_USAGE_STACK_DEPTH usages listed in a row. */
\r
150 HID_PARSE_InsufficientReportIDItems = 7, /**< More than @ref HID_MAX_REPORT_IDS report IDs in the device. */
\r
151 HID_PARSE_NoUnfilteredReportItems = 8, /**< All report items from the device were filtered by the filtering callback routine. */
\r
154 /* Type Defines: */
\r
155 /** @brief HID Parser Report Item Min/Max Structure.
\r
157 * Type define for an attribute with both minimum and maximum values (e.g. Logical Min/Max).
\r
161 uint32_t Minimum; /**< Minimum value for the attribute. */
\r
162 uint32_t Maximum; /**< Maximum value for the attribute. */
\r
165 /** @brief HID Parser Report Item Unit Structure.
\r
167 * Type define for the Unit attributes of a report item.
\r
171 uint32_t Type; /**< Unit type (refer to HID specifications for details). */
\r
172 uint8_t Exponent; /**< Unit exponent (refer to HID specifications for details). */
\r
175 /** @brief HID Parser Report Item Usage Structure.
\r
177 * Type define for the Usage attributes of a report item.
\r
181 uint16_t Page; /**< Usage page of the report item. */
\r
182 uint16_t Usage; /**< Usage of the report item. */
\r
185 /** @brief HID Parser Report Item Collection Path Structure.
\r
187 * Type define for a COLLECTION object. Contains the collection attributes and a reference to the
\r
188 * parent collection if any.
\r
190 typedef struct HID_CollectionPath
\r
192 uint8_t Type; /**< Collection type (e.g. "Generic Desktop"). */
\r
193 HID_Usage_t Usage; /**< Collection usage. */
\r
194 struct HID_CollectionPath* Parent; /**< Reference to parent collection, or \c NULL if root collection. */
\r
195 } HID_CollectionPath_t;
\r
197 /** @brief HID Parser Report Item Attributes Structure.
\r
199 * Type define for all the data attributes of a report item, except flags.
\r
203 uint8_t BitSize; /**< Size in bits of the report item's data. */
\r
205 HID_Usage_t Usage; /**< Usage of the report item. */
\r
206 HID_Unit_t Unit; /**< Unit type and exponent of the report item. */
\r
207 HID_MinMax_t Logical; /**< Logical minimum and maximum of the report item. */
\r
208 HID_MinMax_t Physical; /**< Physical minimum and maximum of the report item. */
\r
209 } HID_ReportItem_Attributes_t;
\r
211 /** @brief HID Parser Report Item Details Structure.
\r
213 * Type define for a report item (IN, OUT or FEATURE) layout attributes and other details.
\r
217 uint16_t BitOffset; /**< Bit offset in the IN, OUT or FEATURE report of the item. */
\r
218 uint8_t ItemType; /**< Report item type, a value in @ref HID_ReportItemTypes_t. */
\r
219 uint16_t ItemFlags; /**< Item data flags, a mask of HID_IOF_* constants. */
\r
220 uint8_t ReportID; /**< Report ID this item belongs to, or 0x00 if device has only one report */
\r
221 HID_CollectionPath_t* CollectionPath; /**< Collection path of the item. */
\r
223 HID_ReportItem_Attributes_t Attributes; /**< Report item attributes. */
\r
225 uint32_t Value; /**< Current value of the report item - use @ref HID_ALIGN_DATA() when processing
\r
226 * a retrieved value so that it is aligned to a specific type.
\r
228 uint32_t PreviousValue; /**< Previous value of the report item. */
\r
229 } HID_ReportItem_t;
\r
231 /** @brief HID Parser Report Size Structure.
\r
233 * Type define for a report item size information structure, to retain the size of a device's reports by ID.
\r
237 uint8_t ReportID; /**< Report ID of the report within the HID interface. */
\r
238 uint16_t ReportSizeBits[3]; /**< Total number of bits in each report type for the given Report ID,
\r
239 * indexed by the @ref HID_ReportItemTypes_t enum.
\r
241 } HID_ReportSizeInfo_t;
\r
243 /** @brief HID Parser State Structure.
\r
245 * Type define for a complete processed HID report, including all report item data and collections.
\r
249 uint8_t TotalReportItems; /**< Total number of report items stored in the \c ReportItems array. */
\r
250 HID_ReportItem_t ReportItems[HID_MAX_REPORTITEMS]; /**< Report items array, including all IN, OUT
\r
251 * and FEATURE items.
\r
253 HID_CollectionPath_t CollectionPaths[HID_MAX_COLLECTIONS]; /**< All collection items, referenced
\r
254 * by the report items.
\r
256 uint8_t TotalDeviceReports; /**< Number of reports within the HID interface */
\r
257 HID_ReportSizeInfo_t ReportIDSizes[HID_MAX_REPORT_IDS]; /**< Report sizes for each report in the interface */
\r
258 uint16_t LargestReportSizeBits; /**< Largest report that the attached device will generate, in bits */
\r
259 bool UsingReportIDs; /**< Indicates if the device has at least one REPORT ID
\r
260 * element in its HID report descriptor.
\r
262 } HID_ReportInfo_t;
\r
264 /* Function Prototypes: */
\r
265 /** Function to process a given HID report returned from an attached device, and store it into a given
\r
266 * @ref HID_ReportInfo_t structure.
\r
268 * @param ReportData Buffer containing the device's HID report table.
\r
269 * @param ReportSize Size in bytes of the HID report table.
\r
270 * \param[out] ParserData Pointer to a @ref HID_ReportInfo_t instance for the parser output.
\r
272 * @return A value in the @ref HID_Parse_ErrorCodes_t enum.
\r
274 uint8_t USB_ProcessHIDReport(const uint8_t* ReportData,
\r
275 uint16_t ReportSize,
\r
276 HID_ReportInfo_t* const ParserData) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);
\r
278 /** Extracts the given report item's value out of the given HID report and places it into the Value
\r
279 * member of the report item's @ref HID_ReportItem_t structure.
\r
281 * When called on a report with an item that exists in that report, this copies the report item's \c Value
\r
282 * to its \c PreviousValue element for easy checking to see if an item's value has changed before processing
\r
283 * a report. If the given item does not exist in the report, the function does not modify the report item's
\r
286 * @param ReportData Buffer containing an IN or FEATURE report from an attached device.
\r
287 * \param[in,out] ReportItem Pointer to the report item of interest in a @ref HID_ReportInfo_t ReportItem array.
\r
289 * \returns Boolean \c true if the item to retrieve was located in the given report, \c false otherwise.
\r
291 bool USB_GetHIDReportItemInfo(const uint8_t* ReportData,
\r
292 HID_ReportItem_t* const ReportItem) ATTR_NON_NULL_PTR_ARG(1);
\r
294 /** Retrieves the given report item's value out of the \c Value member of the report item's
\r
295 * @ref HID_ReportItem_t structure and places it into the correct position in the HID report
\r
296 * buffer. The report buffer is assumed to have the appropriate bits cleared before calling
\r
297 * this function (i.e., the buffer should be explicitly cleared before report values are added).
\r
299 * When called, this copies the report item's \c Value element to its \c PreviousValue element for easy
\r
300 * checking to see if an item's value has changed before sending a report.
\r
302 * If the device has multiple HID reports, the first byte in the report is set to the report ID of the given item.
\r
304 * \param[out] ReportData Buffer holding the current OUT or FEATURE report data.
\r
305 * @param ReportItem Pointer to the report item of interest in a @ref HID_ReportInfo_t ReportItem array.
\r
307 void USB_SetHIDReportItemInfo(uint8_t* ReportData,
\r
308 HID_ReportItem_t* const ReportItem) ATTR_NON_NULL_PTR_ARG(1);
\r
310 /** Retrieves the size of a given HID report in bytes from its Report ID.
\r
312 * @param ParserData Pointer to a @ref HID_ReportInfo_t instance containing the parser output.
\r
313 * @param ReportID Report ID of the report whose size is to be determined.
\r
314 * @param ReportType Type of the report whose size is to be determined, a value from the
\r
315 * @ref HID_ReportItemTypes_t enum.
\r
317 * @return Size of the report in bytes, or \c 0 if the report does not exist.
\r
319 uint16_t USB_GetHIDReportSize(HID_ReportInfo_t* const ParserData,
\r
320 const uint8_t ReportID,
\r
321 const uint8_t ReportType) ATTR_CONST ATTR_NON_NULL_PTR_ARG(1);
\r
323 /** Callback routine for the HID Report Parser. This callback <b>must</b> be implemented by the user code when
\r
324 * the parser is used, to determine what report IN, OUT and FEATURE item's information is stored into the user
\r
325 * @ref HID_ReportInfo_t structure. This can be used to filter only those items the application will be using, so that
\r
326 * no RAM is wasted storing the attributes for report items which will never be referenced by the application.
\r
328 * Report item pointers passed to this callback function may be cached by the user application for later use
\r
329 * when processing report items. This provides faster report processing in the user application than would
\r
330 * a search of the entire parsed report item table for each received or sent report.
\r
332 * @param CurrentItem Pointer to the current report item for user checking.
\r
334 * @return Boolean \c true if the item should be stored into the @ref HID_ReportInfo_t structure, \c false if
\r
335 * it should be ignored.
\r
337 bool CALLBACK_HIDParser_FilterHIDReportItem(HID_ReportItem_t* const CurrentItem);
\r
339 /* Private Interface - For use in library only: */
\r
340 #if !defined(__DOXYGEN__)
\r
341 /* Type Defines: */
\r
344 HID_ReportItem_Attributes_t Attributes;
\r
345 uint8_t ReportCount;
\r
347 } HID_StateTable_t;
\r
350 /* Disable C linkage for C++ Compilers: */
\r
351 #if defined(__cplusplus)
\r
projects / freertos / blob