Re-add Webserver uIP application polling, apply patch to uIP by Andrew Ruder to fix...

[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 8d3fbf2..53601ec 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


@@ -62,6 +62,7 @@
                #include <stdbool.h>\r
 \r
                #include "HIDReportData.h"\r
                #include <stdbool.h>\r
 \r
                #include "HIDReportData.h"\r

+               #include "../Common/HID.h"\r

 \r
                #include "../../../../Common/Common.h"\r
 \r
 \r
                #include "../../../../Common/Common.h"\r
 \r


@@ -70,7 +71,7 @@
                        extern "C" {\r
                #endif\r
 \r
                        extern "C" {\r
                #endif\r
 \r

-       /* Preprocessor checks and defines: */\r
+       /* Macros: */\r

                #if !defined(HID_STATETABLE_STACK_DEPTH) || defined(__DOXYGEN__)\r
                        /** Constant indicating the maximum stack depth of the state table. A larger state table\r
                         *  allows for more PUSH/POP report items to be nested, but consumes more memory. By default\r
                #if !defined(HID_STATETABLE_STACK_DEPTH) || defined(__DOXYGEN__)\r
                        /** Constant indicating the maximum stack depth of the state table. A larger state table\r
                         *  allows for more PUSH/POP report items to be nested, but consumes more memory. By default\r


@@ -99,7 +100,7 @@
                         *  overridden by defining HID_MAX_COLLECTIONS to another value in the user project makefile, passing\r
                         *  the define to the compiler using the -D compiler switch.\r
                         */\r
                         *  overridden by defining HID_MAX_COLLECTIONS to another value in the user project makefile, passing\r
                         *  the define to the compiler using the -D compiler switch.\r
                         */\r

-                       #define HID_MAX_COLLECTIONS           5\r
+                       #define HID_MAX_COLLECTIONS           10\r

                #endif\r
                \r
                #if !defined(HID_MAX_REPORTITEMS) || defined(__DOXYGEN__)\r
                #endif\r
                \r
                #if !defined(HID_MAX_REPORTITEMS) || defined(__DOXYGEN__)\r


@@ -107,21 +108,35 @@
                         *  in the report item descriptor and stored in the user HID Report Info structure. A large value allows\r
                         *  for more report items to be stored, but consumes more memory. By default this is set to 20 items, \r
                         *  but this can be overridden by defining HID_MAX_REPORTITEMS to another value in the user project\r
                         *  in the report item descriptor and stored in the user HID Report Info structure. A large value allows\r
                         *  for more report items to be stored, but consumes more memory. By default this is set to 20 items, \r
                         *  but this can be overridden by defining HID_MAX_REPORTITEMS to another value in the user project\r

-                        *  makefile, passing the define to the compiler using the -D compiler switch.\r
+                        *  makefile, and passing the define to the compiler using the -D compiler switch.\r

                         */\r
                        #define HID_MAX_REPORTITEMS           20\r
                #endif\r
                         */\r
                        #define HID_MAX_REPORTITEMS           20\r
                #endif\r

+               \r
+               #if !defined(HID_MAX_REPORT_IDS) || defined(__DOXYGEN__)\r
+                       /** Constant indicating the maximum number of unique report IDs that can be processed in the report item\r
+                        *  descriptor for the report size information array in the user HID Report Info structure. A large value\r
+                        *  allows for more report ID report sizes to be stored, but consumes more memory. By default this is set\r
+                        *  to 5 items, but this can be overridden by defining HID_MAX_REPORT_IDS to another value in the user project\r
+                        *  makefile, and passing the define to the compiler using the -D compiler switch. Note that IN, OUT and FEATURE\r
+                        *  items sharing the same report ID consume only one size item in the array.\r
+                        */\r
+                       #define HID_MAX_REPORT_IDS            10\r
+               #endif\r
+\r
+               /** Returns the value a given HID report item (once its value has been fetched via \ref USB_GetHIDReportItemInfo())\r
+                *  left-aligned to the given data type. This allows for signed data to be interpreted correctly, by shifting the data\r
+                *  leftwards until the data's sign bit is in the correct position.\r
+                *\r
+                *  \param[in] reportitem  HID Report Item whose retrieved value is to be aligned\r
+                *  \param[in] type  Data type to align the HID report item's value to\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

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

-               /* Enums: */\r
-                       /** Enum for indicating what type of report item an entry in a \ref HID_ReportInfo_t ReportItem array is */\r
-                       enum HID_ReportItemTypes_t\r
-                       {\r
-                               REPORT_ITEM_TYPE_In                   = 0, /**< Indicates that the item is an IN report type. */\r
-                               REPORT_ITEM_TYPE_Out                  = 1, /**< Indicates that the item is an OUT report type. */\r
-                               REPORT_ITEM_TYPE_Feature              = 2, /**< Indicates that the item is a FEATURE report type. */\r
-                       };\r
-                       \r
+               /* Enums: */                    \r

                        /** Enum for the possible error codes in the return value of the \ref USB_ProcessHIDReport() function */\r
                        enum HID_Parse_ErrorCodes_t\r
                        {\r
                        /** Enum for the possible error codes in the return value of the \ref USB_ProcessHIDReport() function */\r
                        enum HID_Parse_ErrorCodes_t\r
                        {\r


@@ -131,7 +146,9 @@
                                HID_PARSE_InsufficientReportItems     = 3, /**< More than \ref HID_MAX_REPORTITEMS report items in the report. */\r
                                HID_PARSE_UnexpectedEndCollection     = 4, /**< An END COLLECTION item found without matching COLLECTION item. */\r
                                HID_PARSE_InsufficientCollectionPaths = 5, /**< More than \ref HID_MAX_COLLECTIONS collections in the report. */\r
                                HID_PARSE_InsufficientReportItems     = 3, /**< More than \ref HID_MAX_REPORTITEMS report items in the report. */\r
                                HID_PARSE_UnexpectedEndCollection     = 4, /**< An END COLLECTION item found without matching COLLECTION item. */\r
                                HID_PARSE_InsufficientCollectionPaths = 5, /**< More than \ref HID_MAX_COLLECTIONS collections in the report. */\r

-                               HID_PARSE_UsageStackOverflow          = 6, /**< More than \ref HID_USAGE_STACK_DEPTH usages listed in a row. */\r
+                               HID_PARSE_UsageListOverflow           = 6, /**< More than \ref HID_USAGE_STACK_DEPTH usages listed in a row. */\r
+                               HID_PARSE_InsufficientReportIDItems   = 7, /**< More than \ref HID_MAX_REPORT_IDS report IDs in the device. */\r
+                               HID_PARSE_NoUnfilteredReportItems     = 8, /**< All report items from the device were filtered by the filtering callback routine. */\r

                        };\r
                \r
                /* Type Defines: */             \r
                        };\r
                \r
                /* Type Defines: */             \r


@@ -154,7 +171,6 @@
                        {\r
                                uint16_t                     Page;   /**< Usage page of the report item. */\r
                                uint16_t                     Usage;  /**< Usage of the report item. */\r
                        {\r
                                uint16_t                     Page;   /**< Usage page of the report item. */\r
                                uint16_t                     Usage;  /**< Usage of the report item. */\r

-                               HID_MinMax_t                 MinMax; /**< Usage minimum and maximum 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
                        } HID_Usage_t;\r
 \r
                        /** Type define for a COLLECTION object. Contains the collection attributes and a reference to the\r


@@ -182,15 +198,27 @@
                        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
                        } HID_ReportItem_t;\r

+                       \r
+                       /** Type define for a report item size information structure */\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
+                                                                                *  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
                        typedef struct\r
 \r
                        /** Type define for a complete processed HID report, including all report item data and collections. */\r
                        typedef struct\r


@@ -204,9 +232,12 @@
                                HID_CollectionPath_t         CollectionPaths[HID_MAX_COLLECTIONS]; /**< All collection items, referenced\r
                                                                                                    *   by the report items.\r
                                                                                                    */\r
                                HID_CollectionPath_t         CollectionPaths[HID_MAX_COLLECTIONS]; /**< All collection items, referenced\r
                                                                                                    *   by the report items.\r
                                                                                                    */\r

-                               bool                         UsingMultipleReports; /**< Indicates if the device has at least one REPORT ID\r
-                                                                                   *   element in its HID report descriptor.\r
-                                                                                   */\r
+                               uint8_t                      TotalDeviceReports; /**< Number of reports within the HID interface */\r
+                               HID_ReportSizeInfo_t         ReportIDSizes[HID_MAX_REPORT_IDS]; /**< Report sizes for each report in the interface */\r
+                               uint16_t                     LargestReportSizeBits; /**< Largest report that the attached device will generate, in bits */\r
+                               bool                         UsingReportIDs; /**< Indicates if the device has at least one REPORT ID\r
+                                                                             *   element in its HID report descriptor.\r
+                                                                             */\r

                        } HID_ReportInfo_t;\r
                        \r
                /* Function Prototypes: */\r
                        } HID_ReportInfo_t;\r
                        \r
                /* Function Prototypes: */\r


@@ -220,42 +251,60 @@
                         *  \return A value in the \ref HID_Parse_ErrorCodes_t enum\r
                         */\r
                        uint8_t USB_ProcessHIDReport(const uint8_t* ReportData, uint16_t ReportSize, HID_ReportInfo_t* const ParserData)\r
                         *  \return A value in the \ref HID_Parse_ErrorCodes_t enum\r
                         */\r
                        uint8_t USB_ProcessHIDReport(const uint8_t* ReportData, uint16_t ReportSize, HID_ReportInfo_t* const ParserData)\r

-                                                    ATTR_NON_NULL_PTR_ARG(1, 3);\r
+                                                    ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);\r

 \r
                        /** Extracts the given report item's value out of the given HID report and places it into the Value\r
                         *  member of the report item's \ref HID_ReportItem_t structure.\r
                         *\r
 \r
                        /** Extracts the given report item's value out of the given HID report and places it into the Value\r
                         *  member of the report item's \ref HID_ReportItem_t structure.\r
                         *\r

+                        *  When called, this copies the report item's Value element to it's PreviousValue element for easy\r
+                        *  checking to see if an item's value has changed before processing a report.\r
+                        *\r

                         *  \param[in] ReportData  Buffer containing an IN or FEATURE report from an attached device\r
                         *  \param[in,out] ReportItem  Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array\r
                         *\r
                         *  \returns Boolean true if the item to retrieve was located in the given report, false otherwise\r
                         */\r
                        bool USB_GetHIDReportItemInfo(const uint8_t* ReportData, HID_ReportItem_t* const ReportItem)\r
                         *  \param[in] ReportData  Buffer containing an IN or FEATURE report from an attached device\r
                         *  \param[in,out] ReportItem  Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array\r
                         *\r
                         *  \returns Boolean true if the item to retrieve was located in the given report, false otherwise\r
                         */\r
                        bool USB_GetHIDReportItemInfo(const uint8_t* ReportData, HID_ReportItem_t* const ReportItem)\r

-                                                     ATTR_NON_NULL_PTR_ARG(1, 2);\r
+                                                     ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);\r

 \r
                        /** Retrieves the given report item's value out of the Value member of the report item's\r
                         *  \ref HID_ReportItem_t structure and places it into the correct position in the HID report\r
                         *  buffer. The report buffer is assumed to have the appropriate bits cleared before calling\r
                         *  this function (i.e., the buffer should be explicitly cleared before report values are added).\r
                         *\r
 \r
                        /** Retrieves the given report item's value out of the Value member of the report item's\r
                         *  \ref HID_ReportItem_t structure and places it into the correct position in the HID report\r
                         *  buffer. The report buffer is assumed to have the appropriate bits cleared before calling\r
                         *  this function (i.e., the buffer should be explicitly cleared before report values are added).\r
                         *\r

+                        *  When called, this copies the report item's Value element to it's PreviousValue element for easy\r
+                        *  checking to see if an item's value has changed before sending a report.\r
+                        *\r

                         *  If the device has multiple HID reports, the first byte in the report is set to the report ID of the given item.\r
                         *\r
                         *  \param[out] ReportData  Buffer holding the current OUT or FEATURE report data\r
                         *  \param[in] ReportItem  Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array\r
                         */\r
                         *  If the device has multiple HID reports, the first byte in the report is set to the report ID of the given item.\r
                         *\r
                         *  \param[out] ReportData  Buffer holding the current OUT or FEATURE report data\r
                         *  \param[in] ReportItem  Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array\r
                         */\r

-                       void USB_SetHIDReportItemInfo(uint8_t* ReportData, const HID_ReportItem_t* ReportItem)\r
-                                                     ATTR_NON_NULL_PTR_ARG(1, 2);\r
+                       void USB_SetHIDReportItemInfo(uint8_t* ReportData, HID_ReportItem_t* const ReportItem)\r
+                                                     ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);\r

                                                                                  \r
                                                                                  \r

+                       /** Retrieves the size of a given HID report in bytes from it's Report ID.\r
+                        *\r
+                        *  \param[in] ParserData  Pointer to a \ref HID_ReportInfo_t instance containing the parser output\r
+                        *  \param[in] ReportID  Report ID of the report whose size is to be retrieved\r
+                        *  \param[in] ReportType  Type of the report whose size is to be determined, a valued from the\r
+                        *                         \ref HID_ReportItemTypes_t enum\r
+                        *\r
+                        *  \return Size of the report in bytes, or 0 if the report does not exist\r
+                        */\r
+                       uint16_t USB_GetHIDReportSize(HID_ReportInfo_t* const ParserData, const uint8_t ReportID,\r
+                                                     const uint8_t ReportType) ATTR_CONST ATTR_NON_NULL_PTR_ARG(1);\r
+\r

                        /** Callback routine for the HID Report Parser. This callback <b>must</b> be implemented by the user code when\r
                         *  the parser is used, to determine what report IN, OUT and FEATURE item's information is stored into the user\r
                         *  HID_ReportInfo_t structure. This can be used to filter only those items the application will be using, so that\r
                         *  no RAM is wasted storing the attributes for report items which will never be referenced by the application.\r
                         *\r
                        /** Callback routine for the HID Report Parser. This callback <b>must</b> be implemented by the user code when\r
                         *  the parser is used, to determine what report IN, OUT and FEATURE item's information is stored into the user\r
                         *  HID_ReportInfo_t structure. This can be used to filter only those items the application will be using, so that\r
                         *  no RAM is wasted storing the attributes for report items which will never be referenced by the application.\r
                         *\r

-                        *  \param CurrentItemAttributes  Pointer to the current report item attributes for user checking\r
+                        *  \param[in] CurrentItem  Pointer to the current report item for user checking\r

                         *\r
                         *  \return Boolean true if the item should be stored into the HID_ReportInfo_t structure, false if it should be ignored\r
                         */\r
                         *\r
                         *  \return Boolean true if the item should be stored into the HID_ReportInfo_t structure, false if it should be ignored\r
                         */\r

-                       bool CALLBACK_HIDParser_FilterHIDReportItem(HID_ReportItem_Attributes_t* CurrentItemAttributes);\r
+                       bool CALLBACK_HIDParser_FilterHIDReportItem(HID_ReportItem_t* CurrentItem);\r

 \r
        /* Private Interface - For use in library only: */\r
        #if !defined(__DOXYGEN__)\r
 \r
        /* Private Interface - For use in library only: */\r
        #if !defined(__DOXYGEN__)\r