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


ad242fe5655ed8edd791965dcd633d578f825b0e
[pub/USBasp.git] / LUFA / Drivers / USB / Class / HIDParser.h
1 /*
2 LUFA Library
3 Copyright (C) Dean Camera, 2009.
4
5 dean [at] fourwalledcubicle [dot] com
6 www.fourwalledcubicle.com
7 */
8
9 /*
10 Copyright 2009 Dean Camera (dean [at] fourwalledcubicle [dot] com)
11
12 Permission to use, copy, modify, and distribute this software
13 and its documentation for any purpose and without fee is hereby
14 granted, provided that the above copyright notice appear in all
15 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 * The processed report is presented back to the user application as a flat structure containing each report
37 * item's IN, OUT and FEATURE (if desired) items along with each item's attributes.
38 *
39 * This library portion also allows for easy setting and retrieval of data from a HID report, including devices
40 * with multiple reports on the one HID interface.
41 *
42 * By default, FEATURE reports and IN/OUT reports with constant data are ignored in the HID report when processed
43 * to save on memory. This can be overridden by defining the HID_ENABLE_FEATURE_PROCESSING or
44 * HID_INCLUDE_CONSTANT_DATA_ITEMS tokens in the user project makefile, passing them to the compiler via the -D
45 * switch.
46 */
47
48 /** \ingroup Group_USB
49 * @defgroup Group_HIDParser HID Report Parser
50 *
51 * Functions, macros, variables, enums and types related to the parsing of HID class device report descriptors.
52 *
53 * @{
54 */
55
56 #ifndef __HIDPARSER_H__
57 #define __HIDPARSER_H__
58
59 /* Includes: */
60 #include <string.h>
61 #include <stdbool.h>
62
63 #include "HIDReportData.h"
64
65 #include "../../../Common/Common.h"
66
67 /* Enable C linkage for C++ Compilers: */
68 #if defined(__cplusplus)
69 extern "C" {
70 #endif
71
72 /* Preprocessor checks and defines: */
73 #if !defined(HID_STATETABLE_STACK_DEPTH) || defined(__DOXYGEN__)
74 /** Constant indicating the maximum stack depth of the state table. A larger state table
75 * allows for more PUSH/POP report items to be nested, but consumes more memory. By default
76 * this is set to 3 levels (allowing for two PUSHes to be nested) but this can be overridden by
77 * defining HID_STATETABLE_STACK_DEPTH to another value in the user project makefile, passing the
78 * define to the compiler using the -D compiler switch.
79 */
80 #define HID_STATETABLE_STACK_DEPTH 3
81 #endif
82
83 #if !defined(HID_USAGE_STACK_DEPTH) || defined(__DOXYGEN__)
84 /** Constant indicating the maximum stack depth of the usage table. A larger usage table
85 * allows for more USAGE items to be indicated sequentially for REPORT COUNT entries of more than
86 * one, but requires more stack space. By default this is set to 8 levels (allowing for a report
87 * item with a count of 8) but this can be overridden by defining HID_USAGE_STACK_DEPTH to another
88 * value in the user project makefile, passing the define to the compiler using the -D compiler
89 * switch.
90 */
91 #define HID_USAGE_STACK_DEPTH 8
92 #endif
93
94 #if !defined(HID_MAX_COLLECTIONS) || defined(__DOXYGEN__)
95 /** Constant indicating the maximum number of COLLECTION items (nested or unnested) that can be
96 * processed in the report item descriptor. A large value allows for more COLLECTION items to be
97 * processed, but consumes more memory. By default this is set to 5 collections, but this can be
98 * overridden by defining HID_MAX_COLLECTIONS to another value in the user project makefile, passing
99 * the define to the compiler using the -D compiler switch.
100 */
101 #define HID_MAX_COLLECTIONS 5
102 #endif
103
104 #if !defined(HID_MAX_REPORTITEMS) || defined(__DOXYGEN__)
105 /** Constant indicating the maximum number of report items (IN, OUT or FEATURE if enabled) that can be
106 * processed in the report item descriptor. A large value allows for more report items to be
107 * processed, but consumes more memory. By default this is set to 30 items, but this can be
108 * overridden by defining HID_MAX_REPORTITEMS 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_REPORTITEMS 30
112 #endif
113
114 /* Public Interface - May be used in end-application: */
115 /* Enums: */
116 /** Enum for indicating what type of report item an entry in a HID_ReportInfo_t ReportItem array is */
117 enum HID_ReportItemTypes_t
118 {
119 REPORT_ITEM_TYPE_In = 0, /**< Indicates that the item is an IN report type. */
120 REPORT_ITEM_TYPE_Out = 1, /**< Indicates that the item is an OUT report type. */
121 REPORT_ITEM_TYPE_Feature = 2, /**< Indicates that the item is a FEATURE report type. */
122 };
123
124 /** Enum for the possible error codes in the return value of the ProcessHIDReport() function */
125 enum HID_Parse_ErrorCodes_t
126 {
127 HID_PARSE_Successful = 0, /**< Successful parse of the HID report descriptor, no error. */
128 HID_PARSE_HIDStackOverflow = 1, /**< More than HID_STATETABLE_STACK_DEPTH nested PUSHes in the report. */
129 HID_PARSE_HIDStackUnderflow = 2, /**< A POP was found when the state table stack was empty. */
130 HID_PARSE_InsufficientReportItems = 3, /**< More than HID_MAX_REPORTITEMS report items in the report. */
131 HID_PARSE_UnexpectedEndCollection = 4, /**< END COLLECTION found without matching COLLECTION item. */
132 HID_PARSE_InsufficientCollectionPaths = 5, /**< More than HID_MAX_COLLECTIONS collections in the report. */
133 HID_PARSE_UsageStackOverflow = 6, /**< More than HID_USAGE_STACK_DEPTH usages listed in a row. */
134 };
135
136 /* Type Defines: */
137 /** Type define for an attribute with both minimum and maximum values (e.g. Logical Min/Max). */
138 typedef struct
139 {
140 uint32_t Minimum; /**< Minimum value for the attribute. */
141 uint32_t Maximum; /**< Maximum value for the attribute. */
142 } HID_MinMax_t;
143
144 /** Type define for the Unit attributes of a report item. */
145 typedef struct
146 {
147 uint32_t Type; /**< Unit type (refer to HID specifications for details). */
148 uint8_t Exponent; /**< Unit exponent (refer to HID specifications for details). */
149 } HID_Unit_t;
150
151 /** Type define for the Usage attributes of a report item. */
152 typedef struct
153 {
154 uint16_t Page; /**< Usage page of the report item. */
155 uint16_t Usage; /**< Usage of the report item. */
156 HID_MinMax_t MinMax; /**< Usage minimum and maximum of the report item. */
157 } HID_Usage_t;
158
159 /** Type define for a COLLECTION object. Contains the collection attributes and a reference to the
160 * parent collection if any.
161 */
162 typedef struct CollectionPath
163 {
164 uint8_t Type; /**< Collection type (for example "Generic Desktop"). */
165 HID_Usage_t Usage; /**< Collection usage. */
166 struct CollectionPath* Parent; /**< Reference to parent collection, or NULL if root collection. */
167 } HID_CollectionPath_t;
168
169 /** Type define for all the data attributes of a report item, except flags. */
170 typedef struct
171 {
172 uint8_t BitSize; /**< Size in bits of the report item's data. */
173
174 HID_Usage_t Usage; /**< Usage of the report item. */
175 HID_Unit_t Unit; /**< Unit type and exponent of the report item. */
176 HID_MinMax_t Logical; /**< Logical minimum and maximum of the report item. */
177 HID_MinMax_t Physical; /**< Physical minimum and maximum of the report item. */
178 } HID_ReportItem_Attributes_t;
179
180 /** Type define for a report item (IN, OUT or FEATURE) attributes and other details. */
181 typedef struct
182 {
183 uint16_t BitOffset; /**< Bit offset in the IN, OUT or FEATURE report of the item. */
184 uint8_t ItemType; /**< Report item type, a value in HID_Types_t. */
185 uint16_t ItemFlags; /**< Item data flags, such as constant/variable, etc. */
186 uint8_t ReportID; /**< Report ID this item belongs to, or 0x00 if device has only one report */
187 HID_CollectionPath_t* CollectionPath; /**< Collection path of the item. */
188
189 HID_ReportItem_Attributes_t Attributes; /**< Report item attributes. */
190
191 uint32_t Value; /**< Current value of the report item. */
192 } HID_ReportItem_t;
193
194 /** Type define for a complete processed HID report, including all report item data and collections. */
195 typedef struct
196 {
197 uint8_t TotalReportItems; /**< Total number of report items stored in the
198 * ReportItems array. */
199
200 HID_ReportItem_t ReportItems[HID_MAX_REPORTITEMS]; /**< Report items array, including
201 * all IN, OUT and FEATURE items. */
202
203 HID_CollectionPath_t CollectionPaths[HID_MAX_COLLECTIONS]; /**< All collection items, referenced
204 * by the report items. */
205 } HID_ReportInfo_t;
206
207 /* Function Prototypes: */
208 /** Function to process a given HID report returned from an attached device, and store it into a given
209 * HID_ReportInfo_t structure.
210 *
211 * \param ReportData Buffer containing the device's HID report table
212 * \param ReportSize Size in bytes of the HID report table
213 * \param ParserData Pointer to a HID_ReportInfo_t instance for the parser output
214 *
215 * \return A value in the HID_Parse_ErrorCodes_t enum
216 */
217 uint8_t ProcessHIDReport(const uint8_t* ReportData, uint16_t ReportSize, HID_ReportInfo_t* const ParserData)
218 ATTR_NON_NULL_PTR_ARG(1, 3);
219
220 /** Extracts the given report item's value out of the given HID report and places it into the Value
221 * member of the report item's HID_ReportItem_t structure.
222 *
223 * \param ReportData Buffer containing an IN or FEATURE report from an attached device
224 * \param ReportItem Pointer to the report item of interest in a HID_ReportInfo_t ReportItem array
225 *
226 * \returns Boolean true if the item to retrieve was located in the given report, false otherwise
227 */
228 bool GetReportItemInfo(const uint8_t* ReportData, HID_ReportItem_t* const ReportItem)
229 ATTR_NON_NULL_PTR_ARG(1, 2);
230
231 /** Retrieves the given report item's value out of the Value member of the report item's
232 * HID_ReportItem_t structure and places it into the correct position in the HID report
233 * buffer. The report buffer is assumed to have the appropriate bits cleared before calling
234 * this function (i.e., the buffer should be explicitly cleared before report values are added).
235 *
236 * If the device has multiple HID reports, the report ID is set to the report ID of the given item.
237 *
238 * \param ReportData Buffer holding the current OUT report data
239 * \param ReportItem Pointer to the report item of interest in a HID_ReportInfo_t ReportItem array
240 */
241 void SetReportItemInfo(uint8_t* ReportData, const HID_ReportItem_t* ReportItem)
242 ATTR_NON_NULL_PTR_ARG(1, 2);
243
244 /* Private Interface - For use in library only: */
245 #if !defined(__DOXYGEN__)
246 /* Type Defines: */
247 typedef struct
248 {
249 HID_ReportItem_Attributes_t Attributes;
250 uint8_t ReportCount;
251 uint8_t ReportID;
252 } HID_StateTable_t;
253 #endif
254
255 /* Disable C linkage for C++ Compilers: */
256 #if defined(__cplusplus)
257 }
258 #endif
259
260 #endif
261
262 /** @} */
USB isp AVR programmer