HIDParser.h 18.4 KB
 Dean Camera committed May 08, 2010 1 2 /* LUFA Library  Dean Camera committed Jan 01, 2011 3  Copyright (C) Dean Camera, 2011.  4   Dean Camera committed May 08, 2010 5  dean [at] fourwalledcubicle [dot] com  Dean Camera committed Oct 28, 2010 6  www.lufa-lib.org  Dean Camera committed May 08, 2010 7 8 9 */ /*  Dean Camera committed Jan 01, 2011 10  Copyright 2011 Dean Camera (dean [at] fourwalledcubicle [dot] com)  Dean Camera committed May 08, 2010 11   12  Permission to use, copy, modify, distribute, and sell this  Dean Camera committed May 08, 2010 13  software and its documentation for any purpose is hereby granted  14  without fee, provided that the above copyright notice appear in  Dean Camera committed May 08, 2010 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  Dean Camera committed May 08, 2010 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   Dean Camera committed May 08, 2010 39 /** \ingroup Group_USB  Dean Camera committed Feb 19, 2011 40  * \defgroup Group_HIDParser HID Report Parser  Dean Camera committed Feb 20, 2011 41  * \brief USB Human Interface Device (HID) Class report descriptor parser.  Dean Camera committed May 08, 2010 42 43 44  * * \section Sec_Dependencies Module Source Dependencies * The following files must be built with any user project that uses this module:  Dean Camera committed Jul 19, 2010 45  * - LUFA/Drivers/USB/Class/Host/HIDParser.c (Makefile source module name: LUFA_SRC_USB)  Dean Camera committed May 08, 2010 46  *  Dean Camera committed Dec 26, 2010 47  * \section Sec_ModDescription Module Description  Dean Camera committed Jan 30, 2011 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.  Dean Camera committed May 08, 2010 52  *  Dean Camera committed Jan 30, 2011 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  Dean Camera committed Jun 01, 2011 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.  Dean Camera committed May 08, 2010 59  *  Dean Camera committed Jan 30, 2011 60  * This module also contains routines for the processing of data in an actual HID report, using the parsed report  Dean Camera committed Jun 01, 2011 61  * descriptor data as a guide for the encoding.  Dean Camera committed May 08, 2010 62 63 64 65 66 67 68 69  * * @{ */ #ifndef __HIDPARSER_H__ #define __HIDPARSER_H__ /* Includes: */  Dean Camera committed Feb 19, 2011 70  #include "../../../../Common/Common.h"  Dean Camera committed May 08, 2010 71 72 73  #include "HIDReportData.h" #include "../Common/HID.h"  Dean Camera committed Feb 19, 2011 74   Dean Camera committed May 08, 2010 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  Dean Camera committed Jan 08, 2011 85  * defining \c HID_STATETABLE_STACK_DEPTH to another value in the user project makefile, passing the  Dean Camera committed May 08, 2010 86 87 88 89  * define to the compiler using the -D compiler switch. */ #define HID_STATETABLE_STACK_DEPTH 2 #endif  90   Dean Camera committed May 08, 2010 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  Dean Camera committed Jan 08, 2011 95  * item with a count of 8) but this can be overridden by defining \c HID_USAGE_STACK_DEPTH to another  Dean Camera committed May 08, 2010 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  Dean Camera committed Jun 15, 2010 105  * processed, but consumes more memory. By default this is set to 10 collections, but this can be  Dean Camera committed Jan 08, 2011 106  * overridden by defining \c HID_MAX_COLLECTIONS to another value in the user project makefile, passing  Dean Camera committed May 08, 2010 107 108 109 110  * the define to the compiler using the -D compiler switch. */ #define HID_MAX_COLLECTIONS 10 #endif  111   Dean Camera committed May 08, 2010 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  Dean Camera committed May 08, 2010 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,  Dean Camera committed Jan 08, 2011 116  * but this can be overridden by defining \c HID_MAX_REPORTITEMS to another value in the user project  Dean Camera committed May 08, 2010 117 118 119 120  * makefile, and passing the define to the compiler using the -D compiler switch. */ #define HID_MAX_REPORTITEMS 20 #endif  121   Dean Camera committed May 08, 2010 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  Dean Camera committed Jan 08, 2011 126  * to 10 items, but this can be overridden by defining \c HID_MAX_REPORT_IDS to another value in the user project  Dean Camera committed May 08, 2010 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. *  Dean Camera committed Jun 17, 2010 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.  Dean Camera committed May 08, 2010 139  *  Dean Camera committed Jun 17, 2010 140  * \return Left-aligned data of the given report item's pre-retrieved value for the given datatype.  Dean Camera committed May 08, 2010 141  */  Dean Camera committed Jun 17, 2010 142  #define HID_ALIGN_DATA(ReportItem, Type) ((Type)(ReportItem->Value << ((8 * sizeof(Type)) - ReportItem->Attributes.BitSize)))  Dean Camera committed May 08, 2010 143 144  /* Public Interface - May be used in end-application: */  145  /* Enums: */  Dean Camera committed Jun 03, 2010 146  /** Enum for the possible error codes in the return value of the \ref USB_ProcessHIDReport() function. */  Dean Camera committed May 08, 2010 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. */  Dean Camera committed May 08, 2010 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: */  Dean Camera committed May 08, 2010 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 {  Dean Camera committed Jan 30, 2011 167 168  uint32_t Minimum; /**< Minimum value for the attribute. */ uint32_t Maximum; /**< Maximum value for the attribute. */  Dean Camera committed May 08, 2010 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 {  Dean Camera committed Jan 30, 2011 177 178  uint32_t Type; /**< Unit type (refer to HID specifications for details). */ uint8_t Exponent; /**< Unit exponent (refer to HID specifications for details). */  Dean Camera committed May 08, 2010 179  } HID_Unit_t;  180   Dean Camera committed May 08, 2010 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 {  Dean Camera committed Jan 30, 2011 187 188  uint16_t Page; /**< Usage page of the report item. */ uint16_t Usage; /**< Usage of the report item. */  Dean Camera committed May 08, 2010 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. */  Dean Camera committed Jan 30, 2011 196  typedef struct HID_CollectionPath  Dean Camera committed May 08, 2010 197  {  Dean Camera committed Jan 30, 2011 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. */  Dean Camera committed May 08, 2010 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 {  Dean Camera committed Jan 30, 2011 209  uint8_t BitSize; /**< Size in bits of the report item's data. */  210   Dean Camera committed Jan 30, 2011 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. */  Dean Camera committed May 08, 2010 215  } HID_ReportItem_Attributes_t;  216   Dean Camera committed May 08, 2010 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 {  Dean Camera committed Jan 30, 2011 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. */  Dean Camera committed May 08, 2010 228   Dean Camera committed Jan 30, 2011 229  HID_ReportItem_Attributes_t Attributes; /**< Report item attributes. */  230   Dean Camera committed Jan 30, 2011 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. */  Dean Camera committed May 08, 2010 235  } HID_ReportItem_t;  236   Dean Camera committed May 08, 2010 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 {  Dean Camera committed Jan 30, 2011 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. */  Dean Camera committed May 08, 2010 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 {  Dean Camera committed Jan 30, 2011 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. */  Dean Camera committed May 08, 2010 268  } HID_ReportInfo_t;  269   Dean Camera committed May 08, 2010 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. *  Dean Camera committed Jun 17, 2010 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.  Dean Camera committed May 08, 2010 277  *  Dean Camera committed Jun 17, 2010 278  * \return A value in the \ref HID_Parse_ErrorCodes_t enum.  Dean Camera committed May 08, 2010 279  */  Dean Camera committed Jul 21, 2010 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);  Dean Camera committed May 08, 2010 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  Dean Camera committed Aug 10, 2010 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.  Dean Camera committed May 08, 2010 291  *  Dean Camera committed Jun 17, 2010 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.  Dean Camera committed May 08, 2010 294  *  Dean Camera committed Jan 08, 2011 295  * \returns Boolean \c true if the item to retrieve was located in the given report, \c false otherwise.  Dean Camera committed May 08, 2010 296  */  Dean Camera committed Jul 21, 2010 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);  Dean Camera committed May 08, 2010 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. *  Dean Camera committed Jun 17, 2010 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.  Dean Camera committed May 08, 2010 312  */  Dean Camera committed Jul 21, 2010 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);  Dean Camera committed May 08, 2010 316 317  /** Retrieves the size of a given HID report in bytes from it's Report ID. *  Dean Camera committed Jun 17, 2010 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.  Dean Camera committed May 08, 2010 320  * \param[in] ReportType Type of the report whose size is to be determined, a valued from the  Dean Camera committed Jun 17, 2010 321  * \ref HID_ReportItemTypes_t enum.  Dean Camera committed May 08, 2010 322  *  Dean Camera committed Jun 17, 2010 323  * \return Size of the report in bytes, or 0 if the report does not exist.  Dean Camera committed May 08, 2010 324  */  Dean Camera committed Jul 21, 2010 325 326  uint16_t USB_GetHIDReportSize(HID_ReportInfo_t* const ParserData, const uint8_t ReportID,  Dean Camera committed May 08, 2010 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 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  Dean Camera committed Jan 08, 2011 331  * \ref HID_ReportInfo_t structure. This can be used to filter only those items the application will be using, so that  Dean Camera committed May 08, 2010 332 333  * no RAM is wasted storing the attributes for report items which will never be referenced by the application. *  Dean Camera committed Jun 17, 2010 334  * \param[in] CurrentItem Pointer to the current report item for user checking.  Dean Camera committed May 08, 2010 335  *  Dean Camera committed Jan 08, 2011 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.  Dean Camera committed May 08, 2010 338  */  339  bool CALLBACK_HIDParser_FilterHIDReportItem(HID_ReportItem_t* const CurrentItem);  Dean Camera committed May 08, 2010 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   Dean Camera committed May 08, 2010 352 353 354 355 356 357 358 359  /* Disable C linkage for C++ Compilers: */ #if defined(__cplusplus) } #endif #endif /** @} */  360