projects / pub / USBasp.git / blob
? search:


cd32093cab8532077c086f3515c6798cb2120a40
[pub/USBasp.git] / LUFA / Drivers / USB / Class / Common / HIDParser.h
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 permission notice and warranty disclaimer appear in supporting
17 documentation, and that the name of the author not be used in
18 advertising or publicity pertaining to distribution of the
19 software without specific, written prior permission.
20
21 The author disclaim all warranties with regard to this
22 software, including all implied warranties of merchantability
23 and fitness. In no event shall the author be liable for any
24 special, indirect or consequential damages or any damages
25 whatsoever resulting from loss of use, data or profits, whether
26 in an action of contract, negligence or other tortious action,
27 arising out of or in connection with the use or performance of
28 this software.
29 */
30
31 /** \file
32 * \brief USB Human Interface Device (HID) Class report descriptor parser.
33 *
34 * This file allows for the easy parsing of complex HID report descriptors, which describes the data that
35 * a HID device transmits to the host. It also provides an easy API for extracting and processing the data
36 * elements inside a HID report sent from an attached HID device.
37 */
38
39 /** \ingroup Group_USB
40 * \defgroup Group_HIDParser HID Report Parser
41 *
42 * \section Sec_Dependencies Module Source Dependencies
43 * The following files must be built with any user project that uses this module:
44 * - LUFA/Drivers/USB/Class/Host/HIDParser.c <i>(Makefile source module name: LUFA_SRC_USB)</i>
45 *
46 * \section Sec_ModDescription Module Description
47 * Human Interface Device (HID) class report descriptor parser. This module implements a parser than is
48 * capable of processing a complete HID report descriptor, and outputting a flat structure containing the
49 * contents of the report in an a more friendly format. The parsed data may then be further processed and used
50 * within an application to process sent and received HID reports to and from an attached HID device.
51 *
52 * A HID report descriptor consists of a set of HID report items, which describe the function and layout
53 * of data exchanged between a HID device and a host, including both the physical encoding of each item
54 * (such as a button, key press or joystick axis) in the sent and received data packets - known as "reports" -
55 * as well as other information about each item such as the usages, data range, physical location and other
56 * characterstics. In this way a HID device can retain a high degree of flexibility in its capabilities, as it
57 * is not forced to comply with a given report layout or featureset.
58 *
59 * This module also contains routines for the processing of data in an actual HID report, using the parsed report
60 * descritor data as a guide for the encoding.
61 *
62 * @{
63 */
64
65 #ifndef __HIDPARSER_H__
66 #define __HIDPARSER_H__
67
68 /* Includes: */
69 #include <string.h>
70 #include <stdbool.h>
71
72 #include "HIDReportData.h"
73 #include "../Common/HID.h"
74
75 #include "../../../../Common/Common.h"
76
77 /* Enable C linkage for C++ Compilers: */
78 #if defined(__cplusplus)
79 extern "C" {
80 #endif
81
82 /* Macros: */
83 #if !defined(HID_STATETABLE_STACK_DEPTH) || defined(__DOXYGEN__)
84 /** Constant indicating the maximum stack depth of the state table. A larger state table
85 * allows for more PUSH/POP report items to be nested, but consumes more memory. By default
86 * this is set to 2 levels (allowing non-nested PUSH items) but this can be overridden by
87 * defining \c HID_STATETABLE_STACK_DEPTH to another value in the user project makefile, passing the
88 * define to the compiler using the -D compiler switch.
89 */
90 #define HID_STATETABLE_STACK_DEPTH 2
91 #endif
92
93 #if !defined(HID_USAGE_STACK_DEPTH) || defined(__DOXYGEN__)
94 /** Constant indicating the maximum stack depth of the usage table. A larger usage table
95 * allows for more USAGE items to be indicated sequentially for REPORT COUNT entries of more than
96 * one, but requires more stack space. By default this is set to 8 levels (allowing for a report
97 * item with a count of 8) but this can be overridden by defining \c HID_USAGE_STACK_DEPTH to another
98 * value in the user project makefile, passing the define to the compiler using the -D compiler
99 * switch.
100 */
101 #define HID_USAGE_STACK_DEPTH 8
102 #endif
103
104 #if !defined(HID_MAX_COLLECTIONS) || defined(__DOXYGEN__)
105 /** Constant indicating the maximum number of COLLECTION items (nested or unnested) that can be
106 * processed in the report item descriptor. A large value allows for more COLLECTION items to be
107 * processed, but consumes more memory. By default this is set to 10 collections, but this can be
108 * overridden by defining \c HID_MAX_COLLECTIONS to another value in the user project makefile, passing
109 * the define to the compiler using the -D compiler switch.
110 */
111 #define HID_MAX_COLLECTIONS 10
112 #endif
113
114 #if !defined(HID_MAX_REPORTITEMS) || defined(__DOXYGEN__)
115 /** Constant indicating the maximum number of report items (IN, OUT or FEATURE) that can be processed
116 * in the report item descriptor and stored in the user HID Report Info structure. A large value allows
117 * for more report items to be stored, but consumes more memory. By default this is set to 20 items,
118 * but this can be overridden by defining \c HID_MAX_REPORTITEMS to another value in the user project
119 * makefile, and passing the define to the compiler using the -D compiler switch.
120 */
121 #define HID_MAX_REPORTITEMS 20
122 #endif
123
124 #if !defined(HID_MAX_REPORT_IDS) || defined(__DOXYGEN__)
125 /** Constant indicating the maximum number of unique report IDs that can be processed in the report item
126 * descriptor for the report size information array in the user HID Report Info structure. A large value
127 * allows for more report ID report sizes to be stored, but consumes more memory. By default this is set
128 * to 10 items, but this can be overridden by defining \c HID_MAX_REPORT_IDS to another value in the user project
129 * makefile, and passing the define to the compiler using the -D compiler switch. Note that IN, OUT and FEATURE
130 * items sharing the same report ID consume only one size item in the array.
131 */
132 #define HID_MAX_REPORT_IDS 10
133 #endif
134
135 /** Returns the value a given HID report item (once its value has been fetched via \ref USB_GetHIDReportItemInfo())
136 * left-aligned to the given data type. This allows for signed data to be interpreted correctly, by shifting the data
137 * leftwards until the data's sign bit is in the correct position.
138 *
139 * \param[in] ReportItem HID Report Item whose retrieved value is to be aligned.
140 * \param[in] Type Data type to align the HID report item's value to.
141 *
142 * \return Left-aligned data of the given report item's pre-retrieved value for the given datatype.
143 */
144 #define HID_ALIGN_DATA(ReportItem, Type) ((Type)(ReportItem->Value << ((8 * sizeof(Type)) - ReportItem->Attributes.BitSize)))
145
146 /* Public Interface - May be used in end-application: */
147 /* Enums: */
148 /** Enum for the possible error codes in the return value of the \ref USB_ProcessHIDReport() function. */
149 enum HID_Parse_ErrorCodes_t
150 {
151 HID_PARSE_Successful = 0, /**< Successful parse of the HID report descriptor, no error. */
152 HID_PARSE_HIDStackOverflow = 1, /**< More than \ref HID_STATETABLE_STACK_DEPTH nested PUSHes in the report. */
153 HID_PARSE_HIDStackUnderflow = 2, /**< A POP was found when the state table stack was empty. */
154 HID_PARSE_InsufficientReportItems = 3, /**< More than \ref HID_MAX_REPORTITEMS report items in the report. */
155 HID_PARSE_UnexpectedEndCollection = 4, /**< An END COLLECTION item found without matching COLLECTION item. */
156 HID_PARSE_InsufficientCollectionPaths = 5, /**< More than \ref HID_MAX_COLLECTIONS collections in the report. */
157 HID_PARSE_UsageListOverflow = 6, /**< More than \ref HID_USAGE_STACK_DEPTH usages listed in a row. */
158 HID_PARSE_InsufficientReportIDItems = 7, /**< More than \ref HID_MAX_REPORT_IDS report IDs in the device. */
159 HID_PARSE_NoUnfilteredReportItems = 8, /**< All report items from the device were filtered by the filtering callback routine. */
160 };
161
162 /* Type Defines: */
163 /** \brief HID Parser Report Item Min/Max Structure.
164 *
165 * Type define for an attribute with both minimum and maximum values (e.g. Logical Min/Max).
166 */
167 typedef struct
168 {
169 uint32_t Minimum; /**< Minimum value for the attribute. */
170 uint32_t Maximum; /**< Maximum value for the attribute. */
171 } HID_MinMax_t;
172
173 /** \brief HID Parser Report Item Unit Structure.
174 *
175 * Type define for the Unit attributes of a report item.
176 */
177 typedef struct
178 {
179 uint32_t Type; /**< Unit type (refer to HID specifications for details). */
180 uint8_t Exponent; /**< Unit exponent (refer to HID specifications for details). */
181 } HID_Unit_t;
182
183 /** \brief HID Parser Report Item Usage Structure.
184 *
185 * Type define for the Usage attributes of a report item.
186 */
187 typedef struct
188 {
189 uint16_t Page; /**< Usage page of the report item. */
190 uint16_t Usage; /**< Usage of the report item. */
191 } HID_Usage_t;
192
193 /** \brief HID Parser Report Item Collection Path Structure.
194 *
195 * Type define for a COLLECTION object. Contains the collection attributes and a reference to the
196 * parent collection if any.
197 */
198 typedef struct HID_CollectionPath
199 {
200 uint8_t Type; /**< Collection type (e.g. "Generic Desktop"). */
201 HID_Usage_t Usage; /**< Collection usage. */
202 struct HID_CollectionPath* Parent; /**< Reference to parent collection, or \c NULL if root collection. */
203 } HID_CollectionPath_t;
204
205 /** \brief HID Parser Report Item Attributes Structure.
206 *
207 * Type define for all the data attributes of a report item, except flags.
208 */
209 typedef struct
210 {
211 uint8_t BitSize; /**< Size in bits of the report item's data. */
212
213 HID_Usage_t Usage; /**< Usage of the report item. */
214 HID_Unit_t Unit; /**< Unit type and exponent of the report item. */
215 HID_MinMax_t Logical; /**< Logical minimum and maximum of the report item. */
216 HID_MinMax_t Physical; /**< Physical minimum and maximum of the report item. */
217 } HID_ReportItem_Attributes_t;
218
219 /** \brief HID Parser Report Item Details Structure.
220 *
221 * Type define for a report item (IN, OUT or FEATURE) layout attributes and other details.
222 */
223 typedef struct
224 {
225 uint16_t BitOffset; /**< Bit offset in the IN, OUT or FEATURE report of the item. */
226 uint8_t ItemType; /**< Report item type, a value in \ref HID_ReportItemTypes_t. */
227 uint16_t ItemFlags; /**< Item data flags, a mask of HID_IOF_* constants. */
228 uint8_t ReportID; /**< Report ID this item belongs to, or 0x00 if device has only one report */
229 HID_CollectionPath_t* CollectionPath; /**< Collection path of the item. */
230
231 HID_ReportItem_Attributes_t Attributes; /**< Report item attributes. */
232
233 uint32_t Value; /**< Current value of the report item - use \ref HID_ALIGN_DATA() when processing
234 * a retrieved value so that it is aligned to a specific type.
235 */
236 uint32_t PreviousValue; /**< Previous value of the report item. */
237 } HID_ReportItem_t;
238
239 /** \brief HID Parser Report Size Structure.
240 *
241 * Type define for a report item size information structure, to retain the size of a device's reports by ID.
242 */
243 typedef struct
244 {
245 uint8_t ReportID; /**< Report ID of the report within the HID interface. */
246 uint16_t ReportSizeBits[3]; /**< Total number of bits in each report type for the given Report ID,
247 * indexed by the \ref HID_ReportItemTypes_t enum.
248 */
249 } HID_ReportSizeInfo_t;
250
251 /** \brief HID Parser State Structure.
252 *
253 * Type define for a complete processed HID report, including all report item data and collections.
254 */
255 typedef struct
256 {
257 uint8_t TotalReportItems; /**< Total number of report items stored in the \c ReportItems array. */
258 HID_ReportItem_t ReportItems[HID_MAX_REPORTITEMS]; /**< Report items array, including all IN, OUT
259 * and FEATURE items.
260 */
261 HID_CollectionPath_t CollectionPaths[HID_MAX_COLLECTIONS]; /**< All collection items, referenced
262 * by the report items.
263 */
264 uint8_t TotalDeviceReports; /**< Number of reports within the HID interface */
265 HID_ReportSizeInfo_t ReportIDSizes[HID_MAX_REPORT_IDS]; /**< Report sizes for each report in the interface */
266 uint16_t LargestReportSizeBits; /**< Largest report that the attached device will generate, in bits */
267 bool UsingReportIDs; /**< Indicates if the device has at least one REPORT ID
268 * element in its HID report descriptor.
269 */
270 } HID_ReportInfo_t;
271
272 /* Function Prototypes: */
273 /** Function to process a given HID report returned from an attached device, and store it into a given
274 * \ref HID_ReportInfo_t structure.
275 *
276 * \param[in] ReportData Buffer containing the device's HID report table.
277 * \param[in] ReportSize Size in bytes of the HID report table.
278 * \param[out] ParserData Pointer to a \ref HID_ReportInfo_t instance for the parser output.
279 *
280 * \return A value in the \ref HID_Parse_ErrorCodes_t enum.
281 */
282 uint8_t USB_ProcessHIDReport(const uint8_t* ReportData,
283 uint16_t ReportSize,
284 HID_ReportInfo_t* const ParserData) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);
285
286 /** Extracts the given report item's value out of the given HID report and places it into the Value
287 * member of the report item's \ref HID_ReportItem_t structure.
288 *
289 * When called on a report with an item that exists in that report, this copies the report item's Value
290 * to it's PreviousValue element for easy checking to see if an item's value has changed before processing
291 * a report. If the given item does not exist in the report, the function does not modify the report item's
292 * data.
293 *
294 * \param[in] ReportData Buffer containing an IN or FEATURE report from an attached device.
295 * \param[in,out] ReportItem Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array.
296 *
297 * \returns Boolean \c true if the item to retrieve was located in the given report, \c false otherwise.
298 */
299 bool USB_GetHIDReportItemInfo(const uint8_t* ReportData,
300 HID_ReportItem_t* const ReportItem) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
301
302 /** Retrieves the given report item's value out of the Value member of the report item's
303 * \ref HID_ReportItem_t structure and places it into the correct position in the HID report
304 * buffer. The report buffer is assumed to have the appropriate bits cleared before calling
305 * this function (i.e., the buffer should be explicitly cleared before report values are added).
306 *
307 * When called, this copies the report item's Value element to it's PreviousValue element for easy
308 * checking to see if an item's value has changed before sending a report.
309 *
310 * If the device has multiple HID reports, the first byte in the report is set to the report ID of the given item.
311 *
312 * \param[out] ReportData Buffer holding the current OUT or FEATURE report data.
313 * \param[in] ReportItem Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array.
314 */
315 void USB_SetHIDReportItemInfo(uint8_t* ReportData,
316 HID_ReportItem_t* const ReportItem) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
317
318 /** Retrieves the size of a given HID report in bytes from it's Report ID.
319 *
320 * \param[in] ParserData Pointer to a \ref HID_ReportInfo_t instance containing the parser output.
321 * \param[in] ReportID Report ID of the report whose size is to be retrieved.
322 * \param[in] ReportType Type of the report whose size is to be determined, a valued from the
323 * \ref HID_ReportItemTypes_t enum.
324 *
325 * \return Size of the report in bytes, or 0 if the report does not exist.
326 */
327 uint16_t USB_GetHIDReportSize(HID_ReportInfo_t* const ParserData,
328 const uint8_t ReportID,
329 const uint8_t ReportType) ATTR_CONST ATTR_NON_NULL_PTR_ARG(1);
330
331 /** Callback routine for the HID Report Parser. This callback <b>must</b> be implemented by the user code when
332 * the parser is used, to determine what report IN, OUT and FEATURE item's information is stored into the user
333 * \ref HID_ReportInfo_t structure. This can be used to filter only those items the application will be using, so that
334 * no RAM is wasted storing the attributes for report items which will never be referenced by the application.
335 *
336 * \param[in] CurrentItem Pointer to the current report item for user checking.
337 *
338 * \return Boolean \c true if the item should be stored into the \ref HID_ReportInfo_t structure, \c false if
339 * it should be ignored.
340 */
341 bool CALLBACK_HIDParser_FilterHIDReportItem(HID_ReportItem_t* const CurrentItem);
342
343 /* Private Interface - For use in library only: */
344 #if !defined(__DOXYGEN__)
345 /* Type Defines: */
346 typedef struct
347 {
348 HID_ReportItem_Attributes_t Attributes;
349 uint8_t ReportCount;
350 uint8_t ReportID;
351 } HID_StateTable_t;
352 #endif
353
354 /* Disable C linkage for C++ Compilers: */
355 #if defined(__cplusplus)
356 }
357 #endif
358
359 #endif
360
361 /** @} */
362
USB isp AVR programmer