HIDParser.h 15.6 KB
 Dean Camera committed Feb 23, 2009 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 /* LUFA Library Copyright (C) Dean Camera, 2009. dean [at] fourwalledcubicle [dot] com www.fourwalledcubicle.com */ /* Copyright 2009 Dean Camera (dean [at] fourwalledcubicle [dot] com) Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that the copyright notice and this 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 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 * * USB Human Interface Device (HID) Class report descriptor processing routines. This file allows for the easy * parsing of the complex HID report descriptor, which describes the data that the device transmits to the host. *  Dean Camera committed Apr 17, 2009 36 37 38 39 40  */ /** \ingroup Group_USB * @defgroup Group_HIDParser HID Report Parser *  Dean Camera committed Jul 14, 2009 41 42 43 44 45  * \section Sec_Dependencies Module Source Dependencies * The following files must be built with any user project that uses this module: * - LUFA/Drivers/USB/Class/Host/HIDParser.c * * \section Module Description  Dean Camera committed Apr 17, 2009 46 47 48  * Functions, macros, variables, enums and types related to the parsing of HID class device report descriptors. * * The processed HID report is presented back to the user application as a flat structure containing each report  Dean Camera committed Sep 02, 2009 49  * item's IN, OUT and FEATURE items along with each item's attributes.  Dean Camera committed Feb 23, 2009 50 51 52 53  * * This library portion also allows for easy setting and retrieval of data from a HID report, including devices * with multiple reports on the one HID interface. *  Dean Camera committed Apr 16, 2009 54 55  * @{ */  Dean Camera committed Feb 23, 2009 56 57 58 59 60 61 62 63 64 65  #ifndef __HIDPARSER_H__ #define __HIDPARSER_H__ /* Includes: */ #include #include #include "HIDReportData.h"  Dean Camera committed Jun 01, 2009 66  #include "../../../../Common/Common.h"  Dean Camera committed Feb 23, 2009 67 68 69 70 71 72 73 74 75 76  /* Enable C linkage for C++ Compilers: */ #if defined(__cplusplus) extern "C" { #endif /* Preprocessor checks and defines: */ #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  Dean Camera committed Aug 31, 2009 77  * this is set to 2 levels (allowing non-nested PUSH items) but this can be overridden by  Dean Camera committed Feb 23, 2009 78 79 80  * defining HID_STATETABLE_STACK_DEPTH to another value in the user project makefile, passing the * define to the compiler using the -D compiler switch. */  Dean Camera committed Aug 31, 2009 81  #define HID_STATETABLE_STACK_DEPTH 2  Dean Camera committed Feb 23, 2009 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105  #endif #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 * item with a count of 8) but this can be overridden by defining HID_USAGE_STACK_DEPTH to another * 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 * processed, but consumes more memory. By default this is set to 5 collections, but this can be * overridden by defining HID_MAX_COLLECTIONS to another value in the user project makefile, passing * the define to the compiler using the -D compiler switch. */ #define HID_MAX_COLLECTIONS 5 #endif #if !defined(HID_MAX_REPORTITEMS) || defined(__DOXYGEN__)  Dean Camera committed Sep 02, 2009 106 107 108 109  /** Constant indicating the maximum number of report items (IN, OUT or FEATURE) that can be processed * in the report item descriptor and stored in the user HID Report Info structure. A large value allows * for more report items to be stored, but consumes more memory. By default this is set to 20 items, * but this can be overridden by defining HID_MAX_REPORTITEMS to another value in the user project  Dean Camera committed Sep 09, 2009 110  * makefile, and passing the define to the compiler using the -D compiler switch.  Dean Camera committed Feb 23, 2009 111  */  Dean Camera committed Sep 02, 2009 112  #define HID_MAX_REPORTITEMS 20  Dean Camera committed Feb 23, 2009 113  #endif  Dean Camera committed Sep 09, 2009 114 115 116 117 118 119 120 121 122 123 124  #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 * to 5 items, but this can be overridden by defining HID_MAX_REPORT_IDS to another value in the user project * 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 5 #endif  Dean Camera committed Feb 23, 2009 125 126 127  /* Public Interface - May be used in end-application: */ /* Enums: */  Dean Camera committed Apr 22, 2009 128  /** Enum for indicating what type of report item an entry in a \ref HID_ReportInfo_t ReportItem array is */  Dean Camera committed Feb 23, 2009 129 130 131 132 133 134 135  enum HID_ReportItemTypes_t { REPORT_ITEM_TYPE_In = 0, /**< Indicates that the item is an IN report type. */ REPORT_ITEM_TYPE_Out = 1, /**< Indicates that the item is an OUT report type. */ REPORT_ITEM_TYPE_Feature = 2, /**< Indicates that the item is a FEATURE report type. */ };  Dean Camera committed Apr 22, 2009 136  /** Enum for the possible error codes in the return value of the \ref USB_ProcessHIDReport() function */  Dean Camera committed Feb 23, 2009 137 138 139  enum HID_Parse_ErrorCodes_t { HID_PARSE_Successful = 0, /**< Successful parse of the HID report descriptor, no error. */  Dean Camera committed Apr 22, 2009 140  HID_PARSE_HIDStackOverflow = 1, /**< More than \ref HID_STATETABLE_STACK_DEPTH nested PUSHes in the report. */  Dean Camera committed Feb 23, 2009 141  HID_PARSE_HIDStackUnderflow = 2, /**< A POP was found when the state table stack was empty. */  Dean Camera committed Apr 22, 2009 142  HID_PARSE_InsufficientReportItems = 3, /**< More than \ref HID_MAX_REPORTITEMS report items in the report. */  Dean Camera committed Aug 31, 2009 143  HID_PARSE_UnexpectedEndCollection = 4, /**< An END COLLECTION item found without matching COLLECTION item. */  Dean Camera committed Apr 22, 2009 144 145  HID_PARSE_InsufficientCollectionPaths = 5, /**< More than \ref HID_MAX_COLLECTIONS collections in the report. */ HID_PARSE_UsageStackOverflow = 6, /**< More than \ref HID_USAGE_STACK_DEPTH usages listed in a row. */  Dean Camera committed Sep 09, 2009 146  HID_PARSE_InsufficientReportIDItems = 7, /**< More than \ref HID_MAX_REPORT_IDS report IDs in the device. */  Dean Camera committed Feb 23, 2009 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176  }; /* Type Defines: */ /** Type define for an attribute with both minimum and maximum values (e.g. Logical Min/Max). */ typedef struct { uint32_t Minimum; /**< Minimum value for the attribute. */ uint32_t Maximum; /**< Maximum value for the attribute. */ } HID_MinMax_t; /** Type define for the Unit attributes of a report item. */ typedef struct { uint32_t Type; /**< Unit type (refer to HID specifications for details). */ uint8_t Exponent; /**< Unit exponent (refer to HID specifications for details). */ } HID_Unit_t; /** Type define for the Usage attributes of a report item. */ typedef struct { uint16_t Page; /**< Usage page of the report item. */ uint16_t Usage; /**< Usage of the report item. */ HID_MinMax_t MinMax; /**< Usage minimum and maximum of the report item. */ } HID_Usage_t; /** Type define for a COLLECTION object. Contains the collection attributes and a reference to the * parent collection if any. */ typedef struct CollectionPath {  Dean Camera committed Apr 22, 2009 177  uint8_t Type; /**< Collection type (e.g. "Generic Desktop"). */  Dean Camera committed Feb 23, 2009 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205  HID_Usage_t Usage; /**< Collection usage. */ struct CollectionPath* Parent; /**< Reference to parent collection, or NULL if root collection. */ } HID_CollectionPath_t; /** Type define for all the data attributes of a report item, except flags. */ typedef struct { uint8_t BitSize; /**< Size in bits of the report item's data. */ 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. */ } HID_ReportItem_Attributes_t; /** Type define for a report item (IN, OUT or FEATURE) attributes and other details. */ typedef struct { uint16_t BitOffset; /**< Bit offset in the IN, OUT or FEATURE report of the item. */ uint8_t ItemType; /**< Report item type, a value in HID_Types_t. */ uint16_t ItemFlags; /**< Item data flags, such as constant/variable, etc. */ 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. */ HID_ReportItem_Attributes_t Attributes; /**< Report item attributes. */ uint32_t Value; /**< Current value of the report item. */ } HID_ReportItem_t;  Dean Camera committed Sep 09, 2009 206 207 208 209 210 211 212 213 214  /** Type define for a report item size information structure */ typedef struct { uint8_t ReportID; /** Report ID of the report within the HID interface */ uint8_t BitsIn; /** Total number of IN data bits in the current report ID */ uint8_t BitsOut; /** Total number of OUT data bits in the current report ID */ uint8_t BitsFeature; /** Total number of FEATURE data bits in the current report ID */ } HID_ReportSizeInfo_t;  Dean Camera committed Feb 23, 2009 215 216 217 218 219  /** Type define for a complete processed HID report, including all report item data and collections. */ typedef struct { uint8_t TotalReportItems; /**< Total number of report items stored in the  Dean Camera committed Aug 11, 2009 220 221  * ReportItems array. */  Dean Camera committed Feb 23, 2009 222  HID_ReportItem_t ReportItems[HID_MAX_REPORTITEMS]; /**< Report items array, including  Dean Camera committed Aug 11, 2009 223 224  * all IN, OUT and FEATURE items. */  Dean Camera committed Feb 23, 2009 225  HID_CollectionPath_t CollectionPaths[HID_MAX_COLLECTIONS]; /**< All collection items, referenced  Dean Camera committed Aug 11, 2009 226 227  * by the report items. */  Dean Camera committed Sep 09, 2009 228 229 230 231 232  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 */ bool UsingReportIDs; /**< Indicates if the device has at least one REPORT ID * element in its HID report descriptor. */  Dean Camera committed Feb 23, 2009 233 234 235 236  } HID_ReportInfo_t; /* Function Prototypes: */ /** Function to process a given HID report returned from an attached device, and store it into a given  Dean Camera committed Apr 22, 2009 237  * \ref HID_ReportInfo_t structure.  Dean Camera committed Feb 23, 2009 238  *  Dean Camera committed Jun 28, 2009 239 240 241  * \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  Dean Camera committed Feb 23, 2009 242  *  Dean Camera committed Apr 22, 2009 243  * \return A value in the \ref HID_Parse_ErrorCodes_t enum  Dean Camera committed Feb 23, 2009 244  */  Dean Camera committed Apr 17, 2009 245 246  uint8_t USB_ProcessHIDReport(const uint8_t* ReportData, uint16_t ReportSize, HID_ReportInfo_t* const ParserData) ATTR_NON_NULL_PTR_ARG(1, 3);  Dean Camera committed Feb 23, 2009 247 248  /** Extracts the given report item's value out of the given HID report and places it into the Value  Dean Camera committed Apr 22, 2009 249  * member of the report item's \ref HID_ReportItem_t structure.  Dean Camera committed Feb 23, 2009 250  *  Dean Camera committed Jun 28, 2009 251 252  * \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  Dean Camera committed Feb 23, 2009 253 254 255  * * \returns Boolean true if the item to retrieve was located in the given report, false otherwise */  Dean Camera committed Apr 17, 2009 256 257  bool USB_GetHIDReportItemInfo(const uint8_t* ReportData, HID_ReportItem_t* const ReportItem) ATTR_NON_NULL_PTR_ARG(1, 2);  Dean Camera committed Feb 23, 2009 258   Dean Camera committed Apr 01, 2009 259  /** Retrieves the given report item's value out of the Value member of the report item's  Dean Camera committed Apr 22, 2009 260  * \ref HID_ReportItem_t structure and places it into the correct position in the HID report  Dean Camera committed Feb 23, 2009 261 262 263  * 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). *  Dean Camera committed Aug 11, 2009 264  * If the device has multiple HID reports, the first byte in the report is set to the report ID of the given item.  Dean Camera committed Feb 23, 2009 265  *  Dean Camera committed Aug 11, 2009 266  * \param[out] ReportData Buffer holding the current OUT or FEATURE report data  Dean Camera committed Jun 28, 2009 267  * \param[in] ReportItem Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array  Dean Camera committed Feb 23, 2009 268  */  Dean Camera committed Apr 17, 2009 269 270  void USB_SetHIDReportItemInfo(uint8_t* ReportData, const HID_ReportItem_t* ReportItem) ATTR_NON_NULL_PTR_ARG(1, 2);  Dean Camera committed Sep 02, 2009 271 272 273 274 275 276 277 278 279 280 281  /** Callback routine for the HID Report Parser. This callback must 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 * HID_ReportInfo_t structure. This can be used to filter only those items the application will be using, so that * no RAM is wasted storing the attributes for report items which will never be referenced by the application. * * \param CurrentItemAttributes Pointer to the current report item attributes for user checking * * \return Boolean true if the item should be stored into the HID_ReportInfo_t structure, false if it should be ignored */ bool CALLBACK_HIDParser_FilterHIDReportItem(HID_ReportItem_Attributes_t* CurrentItemAttributes);  Dean Camera committed Feb 23, 2009 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299  /* 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 /* Disable C linkage for C++ Compilers: */ #if defined(__cplusplus) } #endif #endif  Dean Camera committed Apr 16, 2009 300 301  /** @} */