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