HIDParser.h 18.4 KB
Newer Older
1
2
/*
             LUFA Library
3
     Copyright (C) Dean Camera, 2011.
4

5
  dean [at] fourwalledcubicle [dot] com
6
           www.lufa-lib.org
7
8
9
*/

/*
10
  Copyright 2011  Dean Camera (dean [at] fourwalledcubicle [dot] com)
11

12
  Permission to use, copy, modify, distribute, and sell this
13
  software and its documentation for any purpose is hereby granted
14
  without fee, provided that the above copyright notice appear in
15
  all copies and that both that the copyright notice and this
16
17
18
  permission notice and warranty disclaimer appear in supporting
  documentation, and that the name of the author not be used in
  advertising or publicity pertaining to distribution of the
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
  software without specific, written prior permission.

  The author disclaim all warranties with regard to this
  software, including all implied warranties of merchantability
  and fitness.  In no event shall the author be liable for any
  special, indirect or consequential damages or any damages
  whatsoever resulting from loss of use, data or profits, whether
  in an action of contract, negligence or other tortious action,
  arising out of or in connection with the use or performance of
  this software.
*/

/** \file
 *  \brief USB Human Interface Device (HID) Class report descriptor parser.
 *
 *  This file allows for the easy parsing of complex HID report descriptors, which describes the data that
 *  a HID device transmits to the host. It also provides an easy API for extracting and processing the data
 *  elements inside a HID report sent from an attached HID device.
 */
38

39
/** \ingroup Group_USB
40
 *  \defgroup Group_HIDParser HID Report Parser
41
 *  \brief USB Human Interface Device (HID) Class report descriptor parser.
42
43
44
 *
 *  \section Sec_Dependencies Module Source Dependencies
 *  The following files must be built with any user project that uses this module:
45
 *    - LUFA/Drivers/USB/Class/Host/HIDParser.c <i>(Makefile source module name: LUFA_SRC_USB)</i>
46
 *
47
 *  \section Sec_ModDescription Module Description
48
49
50
51
 *  Human Interface Device (HID) class report descriptor parser. This module implements a parser than is
 *  capable of processing a complete HID report descriptor, and outputting a flat structure containing the
 *  contents of the report in an a more friendly format. The parsed data may then be further processed and used
 *  within an application to process sent and received HID reports to and from an attached HID device.
52
 *
53
54
55
56
 *  A HID report descriptor consists of a set of HID report items, which describe the function and layout
 *  of data exchanged between a HID device and a host, including both the physical encoding of each item
 *  (such as a button, key press or joystick axis) in the sent and received data packets - known as "reports" -
 *  as well as other information about each item such as the usages, data range, physical location and other
57
58
 *  characteristics. In this way a HID device can retain a high degree of flexibility in its capabilities, as it
 *  is not forced to comply with a given report layout or feature-set.
59
 *
60
 *  This module also contains routines for the processing of data in an actual HID report, using the parsed report
61
 *  descriptor data as a guide for the encoding.
62
63
64
65
66
67
68
69
 *
 *  @{
 */

#ifndef __HIDPARSER_H__
#define __HIDPARSER_H__

	/* Includes: */
70
		#include "../../../../Common/Common.h"
71
72
73

		#include "HIDReportData.h"
		#include "../Common/HID.h"
74
		
75
76
77
78
79
80
81
82
83
84
	/* Enable C linkage for C++ Compilers: */
		#if defined(__cplusplus)
			extern "C" {
		#endif

	/* Macros: */
		#if !defined(HID_STATETABLE_STACK_DEPTH) || defined(__DOXYGEN__)
			/** Constant indicating the maximum stack depth of the state table. A larger state table
			 *  allows for more PUSH/POP report items to be nested, but consumes more memory. By default
			 *  this is set to 2 levels (allowing non-nested PUSH items) but this can be overridden by
85
			 *  defining \c HID_STATETABLE_STACK_DEPTH to another value in the user project makefile, passing the
86
87
88
89
			 *  define to the compiler using the -D compiler switch.
			 */
			#define HID_STATETABLE_STACK_DEPTH    2
		#endif
90

91
92
93
94
		#if !defined(HID_USAGE_STACK_DEPTH) || defined(__DOXYGEN__)
			/** Constant indicating the maximum stack depth of the usage table. A larger usage table
			 *  allows for more USAGE items to be indicated sequentially for REPORT COUNT entries of more than
			 *  one, but requires more stack space. By default this is set to 8 levels (allowing for a report
95
			 *  item with a count of 8) but this can be overridden by defining \c HID_USAGE_STACK_DEPTH to another
96
97
98
99
100
101
102
103
104
			 *  value in the user project makefile, passing the define to the compiler using the -D compiler
			 *  switch.
			 */
			#define HID_USAGE_STACK_DEPTH         8
		#endif

		#if !defined(HID_MAX_COLLECTIONS) || defined(__DOXYGEN__)
			/** Constant indicating the maximum number of COLLECTION items (nested or unnested) that can be
			 *  processed in the report item descriptor. A large value allows for more COLLECTION items to be
105
			 *  processed, but consumes more memory. By default this is set to 10 collections, but this can be
106
			 *  overridden by defining \c HID_MAX_COLLECTIONS to another value in the user project makefile, passing
107
108
109
110
			 *  the define to the compiler using the -D compiler switch.
			 */
			#define HID_MAX_COLLECTIONS           10
		#endif
111

112
		#if !defined(HID_MAX_REPORTITEMS) || defined(__DOXYGEN__)
113
			/** Constant indicating the maximum number of report items (IN, OUT or FEATURE) that can be processed
114
			 *  in the report item descriptor and stored in the user HID Report Info structure. A large value allows
115
			 *  for more report items to be stored, but consumes more memory. By default this is set to 20 items,
116
			 *  but this can be overridden by defining \c HID_MAX_REPORTITEMS to another value in the user project
117
118
119
120
			 *  makefile, and passing the define to the compiler using the -D compiler switch.
			 */
			#define HID_MAX_REPORTITEMS           20
		#endif
121

122
123
124
125
		#if !defined(HID_MAX_REPORT_IDS) || defined(__DOXYGEN__)
			/** Constant indicating the maximum number of unique report IDs that can be processed in the report item
			 *  descriptor for the report size information array in the user HID Report Info structure. A large value
			 *  allows for more report ID report sizes to be stored, but consumes more memory. By default this is set
126
			 *  to 10 items, but this can be overridden by defining \c HID_MAX_REPORT_IDS to another value in the user project
127
128
129
130
131
132
133
134
135
136
			 *  makefile, and passing the define to the compiler using the -D compiler switch. Note that IN, OUT and FEATURE
			 *  items sharing the same report ID consume only one size item in the array.
			 */
			#define HID_MAX_REPORT_IDS            10
		#endif

		/** Returns the value a given HID report item (once its value has been fetched via \ref USB_GetHIDReportItemInfo())
		 *  left-aligned to the given data type. This allows for signed data to be interpreted correctly, by shifting the data
		 *  leftwards until the data's sign bit is in the correct position.
		 *
137
138
		 *  \param[in] ReportItem  HID Report Item whose retrieved value is to be aligned.
		 *  \param[in] Type        Data type to align the HID report item's value to.
139
		 *
140
		 *  \return Left-aligned data of the given report item's pre-retrieved value for the given datatype.
141
		 */
142
		#define HID_ALIGN_DATA(ReportItem, Type) ((Type)(ReportItem->Value << ((8 * sizeof(Type)) - ReportItem->Attributes.BitSize)))
143
144

	/* Public Interface - May be used in end-application: */
145
		/* Enums: */
Dean Camera's avatar
Dean Camera committed
146
			/** Enum for the possible error codes in the return value of the \ref USB_ProcessHIDReport() function. */
147
148
149
			enum HID_Parse_ErrorCodes_t
			{
				HID_PARSE_Successful                  = 0, /**< Successful parse of the HID report descriptor, no error. */
150
				HID_PARSE_HIDStackOverflow            = 1, /**< More than \ref HID_STATETABLE_STACK_DEPTH nested PUSHes in the report. */
151
152
153
154
155
156
157
158
				HID_PARSE_HIDStackUnderflow           = 2, /**< A POP was found when the state table stack was empty. */
				HID_PARSE_InsufficientReportItems     = 3, /**< More than \ref HID_MAX_REPORTITEMS report items in the report. */
				HID_PARSE_UnexpectedEndCollection     = 4, /**< An END COLLECTION item found without matching COLLECTION item. */
				HID_PARSE_InsufficientCollectionPaths = 5, /**< More than \ref HID_MAX_COLLECTIONS collections in the report. */
				HID_PARSE_UsageListOverflow           = 6, /**< More than \ref HID_USAGE_STACK_DEPTH usages listed in a row. */
				HID_PARSE_InsufficientReportIDItems   = 7, /**< More than \ref HID_MAX_REPORT_IDS report IDs in the device. */
				HID_PARSE_NoUnfilteredReportItems     = 8, /**< All report items from the device were filtered by the filtering callback routine. */
			};
159
160

		/* Type Defines: */
161
162
163
164
165
166
			/** \brief HID Parser Report Item Min/Max Structure.
			 *
			 *  Type define for an attribute with both minimum and maximum values (e.g. Logical Min/Max).
			 */
			typedef struct
			{
167
168
				uint32_t Minimum; /**< Minimum value for the attribute. */
				uint32_t Maximum; /**< Maximum value for the attribute. */
169
170
171
172
173
174
175
176
			} HID_MinMax_t;

			/** \brief HID Parser Report Item Unit Structure.
			 *
			 *  Type define for the Unit attributes of a report item.
			 */
			typedef struct
			{
177
178
				uint32_t Type;     /**< Unit type (refer to HID specifications for details). */
				uint8_t  Exponent; /**< Unit exponent (refer to HID specifications for details). */
179
			} HID_Unit_t;
180

181
182
183
184
185
186
			/** \brief HID Parser Report Item Usage Structure.
			 *
			 *  Type define for the Usage attributes of a report item.
			 */
			typedef struct
			{
187
188
				uint16_t Page;  /**< Usage page of the report item. */
				uint16_t Usage; /**< Usage of the report item. */
189
190
191
192
193
194
195
			} HID_Usage_t;

			/** \brief HID Parser Report Item Collection Path Structure.
			 *
			 *  Type define for a COLLECTION object. Contains the collection attributes and a reference to the
			 *  parent collection if any.
			 */
196
			typedef struct HID_CollectionPath
197
			{
198
199
200
				uint8_t                    Type;   /**< Collection type (e.g. "Generic Desktop"). */
				HID_Usage_t                Usage;  /**< Collection usage. */
				struct HID_CollectionPath* Parent; /**< Reference to parent collection, or \c NULL if root collection. */
201
202
203
204
205
206
207
208
			} HID_CollectionPath_t;

			/** \brief HID Parser Report Item Attributes Structure.
			 *
			 *  Type define for all the data attributes of a report item, except flags.
			 */
			typedef struct
			{
209
				uint8_t      BitSize;  /**< Size in bits of the report item's data. */
210

211
212
213
214
				HID_Usage_t  Usage;    /**< Usage of the report item. */
				HID_Unit_t   Unit;     /**< Unit type and exponent of the report item. */
				HID_MinMax_t Logical;  /**< Logical minimum and maximum of the report item. */
				HID_MinMax_t Physical; /**< Physical minimum and maximum of the report item. */
215
			} HID_ReportItem_Attributes_t;
216

217
218
219
220
221
222
			/** \brief HID Parser Report Item Details Structure.
			 *
			 *  Type define for a report item (IN, OUT or FEATURE) layout attributes and other details.
			 */
			typedef struct
			{
223
224
225
226
227
				uint16_t                    BitOffset;      /**< Bit offset in the IN, OUT or FEATURE report of the item. */
				uint8_t                     ItemType;       /**< Report item type, a value in \ref HID_ReportItemTypes_t. */
				uint16_t                    ItemFlags;      /**< Item data flags, a mask of HID_IOF_* constants. */
				uint8_t                     ReportID;       /**< Report ID this item belongs to, or 0x00 if device has only one report */
				HID_CollectionPath_t*       CollectionPath; /**< Collection path of the item. */
228

229
				HID_ReportItem_Attributes_t Attributes;     /**< Report item attributes. */
230

231
232
233
234
				uint32_t                    Value;          /**< Current value of the report item - use \ref HID_ALIGN_DATA() when processing
				                                             *   a retrieved value so that it is aligned to a specific type.
				                                             */
				uint32_t                    PreviousValue;  /**< Previous value of the report item. */
235
			} HID_ReportItem_t;
236

237
238
239
240
241
242
			/** \brief HID Parser Report Size Structure.
			 *
			 *  Type define for a report item size information structure, to retain the size of a device's reports by ID.
			 */
			typedef struct
			{
243
244
245
246
				uint8_t  ReportID; /**< Report ID of the report within the HID interface. */
				uint16_t ReportSizeBits[3]; /**< Total number of bits in each report type for the given Report ID,
				                             *   indexed by the \ref HID_ReportItemTypes_t enum.
				                             */
247
248
249
250
251
252
253
254
			} HID_ReportSizeInfo_t;

			/** \brief HID Parser State Structure.
			 *
			 *  Type define for a complete processed HID report, including all report item data and collections.
			 */
			typedef struct
			{
255
256
257
258
259
260
261
262
263
264
265
266
267
				uint8_t              TotalReportItems; /**< Total number of report items stored in the \c ReportItems array. */
				HID_ReportItem_t     ReportItems[HID_MAX_REPORTITEMS]; /**< Report items array, including all IN, OUT
			                                                            *   and FEATURE items.
				                                                        */
				HID_CollectionPath_t CollectionPaths[HID_MAX_COLLECTIONS]; /**< All collection items, referenced
				                                                            *   by the report items.
				                                                            */
				uint8_t              TotalDeviceReports; /**< Number of reports within the HID interface */
				HID_ReportSizeInfo_t ReportIDSizes[HID_MAX_REPORT_IDS]; /**< Report sizes for each report in the interface */
				uint16_t             LargestReportSizeBits; /**< Largest report that the attached device will generate, in bits */
				bool                 UsingReportIDs; /**< Indicates if the device has at least one REPORT ID
				                                      *   element in its HID report descriptor.
				                                      */
268
			} HID_ReportInfo_t;
269

270
271
272
273
		/* Function Prototypes: */
			/** Function to process a given HID report returned from an attached device, and store it into a given
			 *  \ref HID_ReportInfo_t structure.
			 *
274
275
276
			 *  \param[in]  ReportData  Buffer containing the device's HID report table.
			 *  \param[in]  ReportSize  Size in bytes of the HID report table.
			 *  \param[out] ParserData  Pointer to a \ref HID_ReportInfo_t instance for the parser output.
277
			 *
278
			 *  \return A value in the \ref HID_Parse_ErrorCodes_t enum.
279
			 */
280
281
282
			uint8_t USB_ProcessHIDReport(const uint8_t* ReportData,
			                             uint16_t ReportSize,
			                             HID_ReportInfo_t* const ParserData) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);
283
284
285
286

			/** Extracts the given report item's value out of the given HID report and places it into the Value
			 *  member of the report item's \ref HID_ReportItem_t structure.
			 *
287
			 *  When called on a report with an item that exists in that report, this copies the report item's Value
288
289
290
			 *  to it's PreviousValue element for easy checking to see if an item's value has changed before processing
			 *  a report. If the given item does not exist in the report, the function does not modify the report item's
			 *  data.
291
			 *
292
293
			 *  \param[in]     ReportData  Buffer containing an IN or FEATURE report from an attached device.
			 *  \param[in,out] ReportItem  Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array.
294
			 *
295
			 *  \returns Boolean \c true if the item to retrieve was located in the given report, \c false otherwise.
296
			 */
297
298
			bool USB_GetHIDReportItemInfo(const uint8_t* ReportData,
			                              HID_ReportItem_t* const ReportItem) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
299
300
301
302
303
304
305
306
307
308
309

			/** Retrieves the given report item's value out of the Value member of the report item's
			 *  \ref HID_ReportItem_t structure and places it into the correct position in the HID report
			 *  buffer. The report buffer is assumed to have the appropriate bits cleared before calling
			 *  this function (i.e., the buffer should be explicitly cleared before report values are added).
			 *
			 *  When called, this copies the report item's Value element to it's PreviousValue element for easy
			 *  checking to see if an item's value has changed before sending a report.
			 *
			 *  If the device has multiple HID reports, the first byte in the report is set to the report ID of the given item.
			 *
310
311
			 *  \param[out] ReportData  Buffer holding the current OUT or FEATURE report data.
			 *  \param[in]  ReportItem  Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array.
312
			 */
313
314
315
			void USB_SetHIDReportItemInfo(uint8_t* ReportData,
			                              HID_ReportItem_t* const ReportItem) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);

316
317
			/** Retrieves the size of a given HID report in bytes from it's Report ID.
			 *
318
319
			 *  \param[in] ParserData  Pointer to a \ref HID_ReportInfo_t instance containing the parser output.
			 *  \param[in] ReportID    Report ID of the report whose size is to be retrieved.
320
			 *  \param[in] ReportType  Type of the report whose size is to be determined, a valued from the
321
			 *                         \ref HID_ReportItemTypes_t enum.
322
			 *
323
			 *  \return Size of the report in bytes, or 0 if the report does not exist.
324
			 */
325
326
			uint16_t USB_GetHIDReportSize(HID_ReportInfo_t* const ParserData,
			                              const uint8_t ReportID,
327
328
329
330
			                              const uint8_t ReportType) ATTR_CONST ATTR_NON_NULL_PTR_ARG(1);

			/** Callback routine for the HID Report Parser. This callback <b>must</b> be implemented by the user code when
			 *  the parser is used, to determine what report IN, OUT and FEATURE item's information is stored into the user
331
			 *  \ref HID_ReportInfo_t structure. This can be used to filter only those items the application will be using, so that
332
333
			 *  no RAM is wasted storing the attributes for report items which will never be referenced by the application.
			 *
334
			 *  \param[in] CurrentItem  Pointer to the current report item for user checking.
335
			 *
336
337
			 *  \return Boolean \c true if the item should be stored into the \ref HID_ReportInfo_t structure, \c false if
			 *          it should be ignored.
338
			 */
339
			bool CALLBACK_HIDParser_FilterHIDReportItem(HID_ReportItem_t* const CurrentItem);
340
341
342
343
344
345
346
347
348
349
350

	/* Private Interface - For use in library only: */
	#if !defined(__DOXYGEN__)
		/* Type Defines: */
			typedef struct
			{
				 HID_ReportItem_Attributes_t Attributes;
				 uint8_t                     ReportCount;
				 uint8_t                     ReportID;
			} HID_StateTable_t;
	#endif
351

352
353
354
355
356
357
358
359
	/* Disable C linkage for C++ Compilers: */
		#if defined(__cplusplus)
			}
		#endif

#endif

/** @} */
360