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