projects / pub / USBasp.git / blob
? search:
summary | shortlog | log | commit | commitdiff | tree
blame | history | raw | HEAD
Update copyright year to 2010.
[pub/USBasp.git] / LUFA / Drivers / USB / Class / Host / HIDParser.h
1 /*
2 LUFA Library
3 Copyright (C) Dean Camera, 2010.
4
5 dean [at] fourwalledcubicle [dot] com
6 www.fourwalledcubicle.com
7 */
8
9 /*
10 Copyright 2010 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 *
33 * USB Human Interface Device (HID) Class report descriptor processing routines. This file allows for the easy
34 * parsing of the complex HID report descriptor, which describes the data that the device transmits to the host.
35 *
36 */
37
38 /** \ingroup Group_USB
39 * @defgroup Group_HIDParser HID Report Parser
40 *
41 * \section Sec_Dependencies Module Source Dependencies
42 * The following files must be built with any user project that uses this module:
43 * - LUFA/Drivers/USB/Class/Host/HIDParser.c
44 *
45 * \section Module Description
46 * Functions, macros, variables, enums and types related to the parsing of HID class device report descriptors.
47 *
48 * The processed HID report is presented back to the user application as a flat structure containing each report
49 * item's IN, OUT and FEATURE items along with each item's attributes.
50 *
51 * This library portion also allows for easy setting and retrieval of data from a HID report, including devices
52 * with multiple reports on the one HID interface.
53 *
54 * @{
55 */
56
57 #ifndef __HIDPARSER_H__
58 #define __HIDPARSER_H__
59
60 /* Includes: */
61 #include <string.h>
62 #include <stdbool.h>
63
64 #include "HIDReportData.h"
65 #include "../Common/HID.h"
66
67 #include "../../../../Common/Common.h"
68
69 /* Enable C linkage for C++ Compilers: */
70 #if defined(__cplusplus)
71 extern "C" {
72 #endif
73
74 /* Macros: */
75 #if !defined(HID_STATETABLE_STACK_DEPTH) || defined(__DOXYGEN__)
76 /** Constant indicating the maximum stack depth of the state table. A larger state table
77 * allows for more PUSH/POP report items to be nested, but consumes more memory. By default
78 * this is set to 2 levels (allowing non-nested PUSH items) but this can be overridden by
79 * defining HID_STATETABLE_STACK_DEPTH to another value in the user project makefile, passing the
80 * define to the compiler using the -D compiler switch.
81 */
82 #define HID_STATETABLE_STACK_DEPTH 2
83 #endif
84
85 #if !defined(HID_USAGE_STACK_DEPTH) || defined(__DOXYGEN__)
86 /** Constant indicating the maximum stack depth of the usage table. A larger usage table
87 * allows for more USAGE items to be indicated sequentially for REPORT COUNT entries of more than
88 * one, but requires more stack space. By default this is set to 8 levels (allowing for a report
89 * item with a count of 8) but this can be overridden by defining HID_USAGE_STACK_DEPTH to another
90 * value in the user project makefile, passing the define to the compiler using the -D compiler
91 * switch.
92 */
93 #define HID_USAGE_STACK_DEPTH 8
94 #endif
95
96 #if !defined(HID_MAX_COLLECTIONS) || defined(__DOXYGEN__)
97 /** Constant indicating the maximum number of COLLECTION items (nested or unnested) that can be
98 * processed in the report item descriptor. A large value allows for more COLLECTION items to be
99 * processed, but consumes more memory. By default this is set to 5 collections, but this can be
100 * overridden by defining HID_MAX_COLLECTIONS to another value in the user project makefile, passing
101 * the define to the compiler using the -D compiler switch.
102 */
103 #define HID_MAX_COLLECTIONS 10
104 #endif
105
106 #if !defined(HID_MAX_REPORTITEMS) || defined(__DOXYGEN__)
107 /** Constant indicating the maximum number of report items (IN, OUT or FEATURE) that can be processed
108 * in the report item descriptor and stored in the user HID Report Info structure. A large value allows
109 * for more report items to be stored, but consumes more memory. By default this is set to 20 items,
110 * but this can be overridden by defining HID_MAX_REPORTITEMS to another value in the user project
111 * makefile, and passing the define to the compiler using the -D compiler switch.
112 */
113 #define HID_MAX_REPORTITEMS 20
114 #endif
115
116 #if !defined(HID_MAX_REPORT_IDS) || defined(__DOXYGEN__)
117 /** Constant indicating the maximum number of unique report IDs that can be processed in the report item
118 * descriptor for the report size information array in the user HID Report Info structure. A large value
119 * allows for more report ID report sizes to be stored, but consumes more memory. By default this is set
120 * to 5 items, but this can be overridden by defining HID_MAX_REPORT_IDS to another value in the user project
121 * makefile, and passing the define to the compiler using the -D compiler switch. Note that IN, OUT and FEATURE
122 * items sharing the same report ID consume only one size item in the array.
123 */
124 #define HID_MAX_REPORT_IDS 10
125 #endif
126
127 /** Returns the value a given HID report item (once its value has been fetched via \ref USB_GetHIDReportItemInfo())
128 * left-aligned to the given data type. This allows for signed data to be interpreted correctly, by shifting the data
129 * leftwards until the data's sign bit is in the correct position.
130 *
131 * \param[in] reportitem HID Report Item whose retrieved value is to be aligned
132 * \param[in] type Data type to align the HID report item's value to
133 *
134 * \return Left-aligned data of the given report item's pre-retrived value for the given datatype
135 */
136 #define HID_ALIGN_DATA(reportitem, type) ((type)(reportitem->Value << (sizeof(type) - reportitem->Attributes.BitSize)))
137
138 /* Public Interface - May be used in end-application: */
139 /* Enums: */
140 /** Enum for the possible error codes in the return value of the \ref USB_ProcessHIDReport() function */
141 enum HID_Parse_ErrorCodes_t
142 {
143 HID_PARSE_Successful = 0, /**< Successful parse of the HID report descriptor, no error. */
144 HID_PARSE_HIDStackOverflow = 1, /**< More than \ref HID_STATETABLE_STACK_DEPTH nested PUSHes in the report. */
145 HID_PARSE_HIDStackUnderflow = 2, /**< A POP was found when the state table stack was empty. */
146 HID_PARSE_InsufficientReportItems = 3, /**< More than \ref HID_MAX_REPORTITEMS report items in the report. */
147 HID_PARSE_UnexpectedEndCollection = 4, /**< An END COLLECTION item found without matching COLLECTION item. */
148 HID_PARSE_InsufficientCollectionPaths = 5, /**< More than \ref HID_MAX_COLLECTIONS collections in the report. */
149 HID_PARSE_UsageListOverflow = 6, /**< More than \ref HID_USAGE_STACK_DEPTH usages listed in a row. */
150 HID_PARSE_InsufficientReportIDItems = 7, /**< More than \ref HID_MAX_REPORT_IDS report IDs in the device. */
151 HID_PARSE_NoUnfilteredReportItems = 8, /**< All report items from the device were filtered by the filtering callback routine. */
152 };
153
154 /* Type Defines: */
155 /** Type define for an attribute with both minimum and maximum values (e.g. Logical Min/Max). */
156 typedef struct
157 {
158 uint32_t Minimum; /**< Minimum value for the attribute. */
159 uint32_t Maximum; /**< Maximum value for the attribute. */
160 } HID_MinMax_t;
161
162 /** Type define for the Unit attributes of a report item. */
163 typedef struct
164 {
165 uint32_t Type; /**< Unit type (refer to HID specifications for details). */
166 uint8_t Exponent; /**< Unit exponent (refer to HID specifications for details). */
167 } HID_Unit_t;
168
169 /** Type define for the Usage attributes of a report item. */
170 typedef struct
171 {
172 uint16_t Page; /**< Usage page of the report item. */
173 uint16_t Usage; /**< Usage of the report item. */
174 } HID_Usage_t;
175
176 /** Type define for a COLLECTION object. Contains the collection attributes and a reference to the
177 * parent collection if any.
178 */
179 typedef struct CollectionPath
180 {
181 uint8_t Type; /**< Collection type (e.g. "Generic Desktop"). */
182 HID_Usage_t Usage; /**< Collection usage. */
183 struct CollectionPath* Parent; /**< Reference to parent collection, or NULL if root collection. */
184 } HID_CollectionPath_t;
185
186 /** Type define for all the data attributes of a report item, except flags. */
187 typedef struct
188 {
189 uint8_t BitSize; /**< Size in bits of the report item's data. */
190
191 HID_Usage_t Usage; /**< Usage of the report item. */
192 HID_Unit_t Unit; /**< Unit type and exponent of the report item. */
193 HID_MinMax_t Logical; /**< Logical minimum and maximum of the report item. */
194 HID_MinMax_t Physical; /**< Physical minimum and maximum of the report item. */
195 } HID_ReportItem_Attributes_t;
196
197 /** Type define for a report item (IN, OUT or FEATURE) attributes and other details. */
198 typedef struct
199 {
200 uint16_t BitOffset; /**< Bit offset in the IN, OUT or FEATURE report of the item. */
201 uint8_t ItemType; /**< Report item type, a value in HID_Types_t. */
202 uint16_t ItemFlags; /**< Item data flags, such as constant/variable, etc. */
203 uint8_t ReportID; /**< Report ID this item belongs to, or 0x00 if device has only one report */
204 HID_CollectionPath_t* CollectionPath; /**< Collection path of the item. */
205
206 HID_ReportItem_Attributes_t Attributes; /**< Report item attributes. */
207
208 uint32_t Value; /**< Current value of the report item - use \ref HID_ALIGN_DATA() when processing
209 * a retrieved value so that it is aligned to a specific type.
210 */
211 uint32_t PreviousValue; /**< Previous value of the report item. */
212 } HID_ReportItem_t;
213
214 /** Type define for a report item size information structure */
215 typedef struct
216 {
217 uint8_t ReportID; /** Report ID of the report within the HID interface */
218 uint8_t ReportSizeBits[3]; /** Total number of bits in each report type for the given Report ID,
219 * indexed by the \ref HID_ReportItemTypes_t enum
220 */
221 } HID_ReportSizeInfo_t;
222
223 /** Type define for a complete processed HID report, including all report item data and collections. */
224 typedef struct
225 {
226 uint8_t TotalReportItems; /**< Total number of report items stored in the
227 * ReportItems array.
228 */
229 HID_ReportItem_t ReportItems[HID_MAX_REPORTITEMS]; /**< Report items array, including
230 * all IN, OUT and FEATURE items.
231 */
232 HID_CollectionPath_t CollectionPaths[HID_MAX_COLLECTIONS]; /**< All collection items, referenced
233 * by the report items.
234 */
235 uint8_t TotalDeviceReports; /**< Number of reports within the HID interface */
236 HID_ReportSizeInfo_t ReportIDSizes[HID_MAX_REPORT_IDS]; /**< Report sizes for each report in the interface */
237 uint16_t LargestReportSizeBits; /**< Largest report that the attached device will generate, in bits */
238 bool UsingReportIDs; /**< Indicates if the device has at least one REPORT ID
239 * element in its HID report descriptor.
240 */
241 } HID_ReportInfo_t;
242
243 /* Function Prototypes: */
244 /** Function to process a given HID report returned from an attached device, and store it into a given
245 * \ref HID_ReportInfo_t structure.
246 *
247 * \param[in] ReportData Buffer containing the device's HID report table
248 * \param[in] ReportSize Size in bytes of the HID report table
249 * \param[out] ParserData Pointer to a \ref HID_ReportInfo_t instance for the parser output
250 *
251 * \return A value in the \ref HID_Parse_ErrorCodes_t enum
252 */
253 uint8_t USB_ProcessHIDReport(const uint8_t* ReportData, uint16_t ReportSize, HID_ReportInfo_t* const ParserData)
254 ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);
255
256 /** Extracts the given report item's value out of the given HID report and places it into the Value
257 * member of the report item's \ref HID_ReportItem_t structure.
258 *
259 * When called, this copies the report item's Value element to it's PreviousValue element for easy
260 * checking to see if an item's value has changed before processing a report.
261 *
262 * \param[in] ReportData Buffer containing an IN or FEATURE report from an attached device
263 * \param[in,out] ReportItem Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array
264 *
265 * \returns Boolean true if the item to retrieve was located in the given report, false otherwise
266 */
267 bool USB_GetHIDReportItemInfo(const uint8_t* ReportData, HID_ReportItem_t* const ReportItem)
268 ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
269
270 /** Retrieves the given report item's value out of the Value member of the report item's
271 * \ref HID_ReportItem_t structure and places it into the correct position in the HID report
272 * buffer. The report buffer is assumed to have the appropriate bits cleared before calling
273 * this function (i.e., the buffer should be explicitly cleared before report values are added).
274 *
275 * When called, this copies the report item's Value element to it's PreviousValue element for easy
276 * checking to see if an item's value has changed before sending a report.
277 *
278 * If the device has multiple HID reports, the first byte in the report is set to the report ID of the given item.
279 *
280 * \param[out] ReportData Buffer holding the current OUT or FEATURE report data
281 * \param[in] ReportItem Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array
282 */
283 void USB_SetHIDReportItemInfo(uint8_t* ReportData, HID_ReportItem_t* const ReportItem)
284 ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
285
286 /** Retrieves the size of a given HID report in bytes from it's Report ID.
287 *
288 * \param[in] ParserData Pointer to a \ref HID_ReportInfo_t instance containing the parser output
289 * \param[in] ReportID Report ID of the report whose size is to be retrieved
290 * \param[in] ReportType Type of the report whose size is to be determined, a valued from the
291 * \ref HID_ReportItemTypes_t enum
292 *
293 * \return Size of the report in bytes, or 0 if the report does not exist
294 */
295 uint16_t USB_GetHIDReportSize(HID_ReportInfo_t* const ParserData, const uint8_t ReportID,
296 const uint8_t ReportType) ATTR_CONST ATTR_NON_NULL_PTR_ARG(1);
297
298 /** Callback routine for the HID Report Parser. This callback <b>must</b> be implemented by the user code when
299 * the parser is used, to determine what report IN, OUT and FEATURE item's information is stored into the user
300 * HID_ReportInfo_t structure. This can be used to filter only those items the application will be using, so that
301 * no RAM is wasted storing the attributes for report items which will never be referenced by the application.
302 *
303 * \param[in] CurrentItem Pointer to the current report item for user checking
304 *
305 * \return Boolean true if the item should be stored into the HID_ReportInfo_t structure, false if it should be ignored
306 */
307 bool CALLBACK_HIDParser_FilterHIDReportItem(HID_ReportItem_t* CurrentItem);
308
309 /* Private Interface - For use in library only: */
310 #if !defined(__DOXYGEN__)
311 /* Type Defines: */
312 typedef struct
313 {
314 HID_ReportItem_Attributes_t Attributes;
315 uint8_t ReportCount;
316 uint8_t ReportID;
317 } HID_StateTable_t;
318 #endif
319
320 /* Disable C linkage for C++ Compilers: */
321 #if defined(__cplusplus)
322 }
323 #endif
324
325 #endif
326
327 /** @} */
USB isp AVR programmer