Fixed incorrect comparison in the descriptor callback routine of the TeensyHID bootlo...

[pub/USBasp.git] / LUFA / Drivers / USB / Class / Host / HIDParser.h

diff --git a/LUFA/Drivers/USB/Class/Host/HIDParser.h b/LUFA/Drivers/USB/Class/Host/HIDParser.h
index 16cfc23..13f68a0 100644 (file)
--- a/LUFA/Drivers/USB/Class/Host/HIDParser.h
+++ b/LUFA/Drivers/USB/Class/Host/HIDParser.h
@@ -1,21 +1,21 @@
 /*\r
              LUFA Library\r
 /*\r
              LUFA Library\r

-     Copyright (C) Dean Camera, 2009.\r
+     Copyright (C) Dean Camera, 2010.\r

               \r
   dean [at] fourwalledcubicle [dot] com\r
       www.fourwalledcubicle.com\r
 */\r
 \r
 /*\r
               \r
   dean [at] fourwalledcubicle [dot] com\r
       www.fourwalledcubicle.com\r
 */\r
 \r
 /*\r

-  Copyright 2009  Dean Camera (dean [at] fourwalledcubicle [dot] com)\r
+  Copyright 2010  Dean Camera (dean [at] fourwalledcubicle [dot] com)\r

 \r
 \r

-  Permission to use, copy, modify, and distribute this software\r
-  and its documentation for any purpose and without fee is hereby\r
-  granted, provided that the above copyright notice appear in all\r
-  copies and that both that the copyright notice and this\r
-  permission notice and warranty disclaimer appear in supporting\r
-  documentation, and that the name of the author not be used in\r
-  advertising or publicity pertaining to distribution of the\r
+  Permission to use, copy, modify, distribute, and sell this \r
+  software and its documentation for any purpose is hereby granted\r
+  without fee, provided that the above copyright notice appear in \r
+  all copies and that both that the copyright notice and this\r
+  permission notice and warranty disclaimer appear in supporting \r
+  documentation, and that the name of the author not be used in \r
+  advertising or publicity pertaining to distribution of the \r

   software without specific, written prior permission.\r
 \r
   The author disclaim all warranties with regard to this\r
   software without specific, written prior permission.\r
 \r
   The author disclaim all warranties with regard to this\r


@@ -29,10 +29,11 @@
 */\r
 \r
 /** \file\r
 */\r
 \r
 /** \file\r

+ *  \brief USB Human Interface Device (HID) Class report descriptor parser.\r

  *\r
  *\r

- *  USB Human Interface Device (HID) Class report descriptor processing routines. This file allows for the easy\r
- *  parsing of the complex HID report descriptor, which describes the data that the device transmits to the host.\r
- *\r
+ *  This file allows for the easy parsing of complex HID report descriptors, which describes the data that\r
+ *  a HID device transmits to the host. It also provides an easy API for extracting and processing the data\r
+ *  elements inside a HID report sent from an attached HID device.\r

  */\r
  \r
 /** \ingroup Group_USB\r
  */\r
  \r
 /** \ingroup Group_USB\r


@@ -57,6 +58,10 @@
 #ifndef __HIDPARSER_H__\r
 #define __HIDPARSER_H__\r
 \r
 #ifndef __HIDPARSER_H__\r
 #define __HIDPARSER_H__\r
 \r

+       /* Macros: */\r
+               #define __INCLUDE_FROM_USB_DRIVER\r
+               #define __INCLUDE_FROM_HID_DRIVER\r
+\r

        /* Includes: */\r
                #include <string.h>\r
                #include <stdbool.h>\r
        /* Includes: */\r
                #include <string.h>\r
                #include <stdbool.h>\r


@@ -133,7 +138,7 @@
                 *\r
                 *  \return Left-aligned data of the given report item's pre-retrived value for the given datatype\r
                 */\r
                 *\r
                 *  \return Left-aligned data of the given report item's pre-retrived value for the given datatype\r
                 */\r

-               #define HID_ALIGN_DATA(reportitem, type) ((type)(reportitem->Value << (sizeof(type) - reportitem->Attributes.BitSize)))\r
+               #define HID_ALIGN_DATA(reportitem, type) ((type)(reportitem->Value << ((8 * sizeof(type)) - reportitem->Attributes.BitSize)))\r

 \r
        /* Public Interface - May be used in end-application: */\r
                /* Enums: */                    \r
 \r
        /* Public Interface - May be used in end-application: */\r
                /* Enums: */                    \r


@@ -152,28 +157,39 @@
                        };\r
                \r
                /* Type Defines: */             \r
                        };\r
                \r
                /* Type Defines: */             \r

-                       /** Type define for an attribute with both minimum and maximum values (e.g. Logical Min/Max). */\r
+                       /** \brief HID Parser Report Item Min/Max Structure.\r
+                        *\r
+                        *  Type define for an attribute with both minimum and maximum values (e.g. Logical Min/Max).\r
+                        */\r

                        typedef struct\r
                        {\r
                                uint32_t                     Minimum; /**< Minimum value for the attribute. */\r
                                uint32_t                     Maximum; /**< Maximum value for the attribute. */\r
                        } HID_MinMax_t;\r
 \r
                        typedef struct\r
                        {\r
                                uint32_t                     Minimum; /**< Minimum value for the attribute. */\r
                                uint32_t                     Maximum; /**< Maximum value for the attribute. */\r
                        } HID_MinMax_t;\r
 \r

-                       /** Type define for the Unit attributes of a report item. */\r
+                       /** \brief HID Parser Report Item Unit Structure.\r
+                        *\r
+                        *  Type define for the Unit attributes of a report item.\r
+                        */\r

                        typedef struct\r
                        {\r
                                uint32_t                     Type;     /**< Unit type (refer to HID specifications for details). */\r
                                uint8_t                      Exponent; /**< Unit exponent (refer to HID specifications for details). */\r
                        } HID_Unit_t;\r
                        \r
                        typedef struct\r
                        {\r
                                uint32_t                     Type;     /**< Unit type (refer to HID specifications for details). */\r
                                uint8_t                      Exponent; /**< Unit exponent (refer to HID specifications for details). */\r
                        } HID_Unit_t;\r
                        \r

-                       /** Type define for the Usage attributes of a report item. */\r
+                       /** \brief HID Parser Report Item Usage Structure.\r
+                        *\r
+                        *  Type define for the Usage attributes of a report item.\r
+                        */\r

                        typedef struct\r
                        {\r
                                uint16_t                     Page;   /**< Usage page of the report item. */\r
                                uint16_t                     Usage;  /**< Usage of the report item. */\r
                        } HID_Usage_t;\r
 \r
                        typedef struct\r
                        {\r
                                uint16_t                     Page;   /**< Usage page of the report item. */\r
                                uint16_t                     Usage;  /**< Usage of the report item. */\r
                        } HID_Usage_t;\r
 \r

-                       /** Type define for a COLLECTION object. Contains the collection attributes and a reference to the\r
+                       /** \brief HID Parser Report Item Collection Path Structure.\r
+                        *\r
+                        *  Type define for a COLLECTION object. Contains the collection attributes and a reference to the\r

                         *  parent collection if any.\r
                         */\r
                        typedef struct CollectionPath\r
                         *  parent collection if any.\r
                         */\r
                        typedef struct CollectionPath\r


@@ -183,7 +199,10 @@
                                struct CollectionPath*       Parent; /**< Reference to parent collection, or NULL if root collection. */\r
                        } HID_CollectionPath_t;\r
 \r
                                struct CollectionPath*       Parent; /**< Reference to parent collection, or NULL if root collection. */\r
                        } HID_CollectionPath_t;\r
 \r

-                       /** Type define for all the data attributes of a report item, except flags. */\r
+                       /** \brief HID Parser Report Item Attributes Structure.\r
+                        *\r
+                        *  Type define for all the data attributes of a report item, except flags.\r
+                        */\r

                        typedef struct\r
                        {\r
                                uint8_t                      BitSize;  /**< Size in bits of the report item's data. */\r
                        typedef struct\r
                        {\r
                                uint8_t                      BitSize;  /**< Size in bits of the report item's data. */\r


@@ -194,31 +213,42 @@
                                HID_MinMax_t                 Physical; /**< Physical minimum and maximum of the report item. */\r
                        } HID_ReportItem_Attributes_t;\r
                        \r
                                HID_MinMax_t                 Physical; /**< Physical minimum and maximum of the report item. */\r
                        } HID_ReportItem_Attributes_t;\r
                        \r

-                       /** Type define for a report item (IN, OUT or FEATURE) attributes and other details. */\r
+                       /** \brief HID Parser Report Item Details Structure.\r
+                        *\r
+                        *  Type define for a report item (IN, OUT or FEATURE) layout attributes and other details.\r
+                        */\r

                        typedef struct\r
                        {\r
                                uint16_t                     BitOffset;      /**< Bit offset in the IN, OUT or FEATURE report of the item. */\r
                        typedef struct\r
                        {\r
                                uint16_t                     BitOffset;      /**< Bit offset in the IN, OUT or FEATURE report of the item. */\r

-                               uint8_t                      ItemType;       /**< Report item type, a value in HID_Types_t. */\r
+                               uint8_t                      ItemType;       /**< Report item type, a value in HID_ReportItemTypes_t. */\r

                                uint16_t                     ItemFlags;      /**< Item data flags, such as constant/variable, etc. */\r
                                uint8_t                      ReportID;       /**< Report ID this item belongs to, or 0x00 if device has only one report */\r
                                HID_CollectionPath_t*        CollectionPath; /**< Collection path of the item. */\r
 \r
                                HID_ReportItem_Attributes_t  Attributes;     /**< Report item attributes. */\r
                                                        \r
                                uint16_t                     ItemFlags;      /**< Item data flags, such as constant/variable, etc. */\r
                                uint8_t                      ReportID;       /**< Report ID this item belongs to, or 0x00 if device has only one report */\r
                                HID_CollectionPath_t*        CollectionPath; /**< Collection path of the item. */\r
 \r
                                HID_ReportItem_Attributes_t  Attributes;     /**< Report item attributes. */\r
                                                        \r

-                               uint32_t                     Value;          /**< Current value of the report item. */\r
+                               uint32_t                     Value;          /**< Current value of the report item - use \ref HID_ALIGN_DATA() when processing\r
+                                                                             *   a retrieved value so that it is aligned to a specific type.\r
+                                                                             */\r

                                uint32_t                     PreviousValue;  /**< Previous value of the report item. */ \r
                        } HID_ReportItem_t;\r
                        \r
                                uint32_t                     PreviousValue;  /**< Previous value of the report item. */ \r
                        } HID_ReportItem_t;\r
                        \r

-                       /** Type define for a report item size information structure */\r
+                       /** \brief HID Parser Report Size Structure.\r
+                        *\r
+                        *  Type define for a report item size information structure, to retain the size of a device's reports by ID.\r
+                        */\r

                        typedef struct\r
                        {\r
                                uint8_t                      ReportID; /** Report ID of the report within the HID interface */\r
                        typedef struct\r
                        {\r
                                uint8_t                      ReportID; /** Report ID of the report within the HID interface */\r

-                               uint8_t                      ReportSizeBits[3]; /** Total number of bits in each report type for the given Report ID,\r
+                               uint16_t                     ReportSizeBits[3]; /** Total number of bits in each report type for the given Report ID,\r

                                                                                 *  indexed by the \ref HID_ReportItemTypes_t enum\r
                                                                                                                                 */\r
                        } HID_ReportSizeInfo_t;\r
 \r
                                                                                 *  indexed by the \ref HID_ReportItemTypes_t enum\r
                                                                                                                                 */\r
                        } HID_ReportSizeInfo_t;\r
 \r

-                       /** Type define for a complete processed HID report, including all report item data and collections. */\r
+                       /** \brief HID Parser State Structure.\r
+                        *\r
+                        *  Type define for a complete processed HID report, including all report item data and collections.\r
+                        */\r

                        typedef struct\r
                        {\r
                                uint8_t                      TotalReportItems; /**< Total number of report items stored in the\r
                        typedef struct\r
                        {\r
                                uint8_t                      TotalReportItems; /**< Total number of report items stored in the\r