Get rid of the redundant ATTR_NEVER_INLINE macro which translated to the same as...

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

diff --git a/LUFA/Drivers/USB/Class/Common/HIDParser.h b/LUFA/Drivers/USB/Class/Common/HIDParser.h
index e5b4f9b..f5454c3 100644 (file)
--- a/LUFA/Drivers/USB/Class/Common/HIDParser.h
+++ b/LUFA/Drivers/USB/Class/Common/HIDParser.h
@@ -1,13 +1,13 @@
 /*
              LUFA Library
 /*
              LUFA Library

-     Copyright (C) Dean Camera, 2011.
+     Copyright (C) Dean Camera, 2013.

 
   dean [at] fourwalledcubicle [dot] com
            www.lufa-lib.org
 */
 
 /*
 
   dean [at] fourwalledcubicle [dot] com
            www.lufa-lib.org
 */
 
 /*

-  Copyright 2011  Dean Camera (dean [at] fourwalledcubicle [dot] com)
+  Copyright 2013  Dean Camera (dean [at] fourwalledcubicle [dot] com)

 
   Permission to use, copy, modify, distribute, and sell this
   software and its documentation for any purpose is hereby granted
 
   Permission to use, copy, modify, distribute, and sell this
   software and its documentation for any purpose is hereby granted


@@ -18,7 +18,7 @@
   advertising or publicity pertaining to distribution of the
   software without specific, written prior permission.
 
   advertising or publicity pertaining to distribution of the
   software without specific, written prior permission.
 

-  The author disclaim all warranties with regard to this
+  The author disclaims 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
   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


@@ -37,20 +37,28 @@
  */
 
 /** \ingroup Group_USB
  */
 
 /** \ingroup Group_USB

- *  @defgroup Group_HIDParser HID Report Parser
+ *  \defgroup Group_HIDParser HID Report Parser
+ *  \brief USB Human Interface Device (HID) Class report descriptor parser.

  *
  *

- *  \section Sec_Dependencies Module Source Dependencies
+ *  \section Sec_HIDParser_Dependencies Module Source Dependencies

  *  The following files must be built with any user project that uses this module:
  *    - LUFA/Drivers/USB/Class/Host/HIDParser.c <i>(Makefile source module name: LUFA_SRC_USB)</i>
  *
  *  The following files must be built with any user project that uses this module:
  *    - LUFA/Drivers/USB/Class/Host/HIDParser.c <i>(Makefile source module name: LUFA_SRC_USB)</i>
  *

- *  \section Sec_ModDescription Module Description
- *  Functions, macros, variables, enums and types related to the parsing of HID class device report descriptors.
+ *  \section Sec_HIDParser_ModDescription Module Description
+ *  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.

  *
  *

- *  The processed HID report is presented back to the user application as a flat structure containing each report
- *  item's IN, OUT and FEATURE items along with each item's attributes.
+ *  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
+ *  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.

  *
  *

- *  This library portion also allows for easy setting and retrieval of data from a HID report, including devices
- *  with multiple reports on the one HID interface.
+ *  This module also contains routines for the processing of data in an actual HID report, using the parsed report
+ *  descriptor data as a guide for the encoding.

  *
  *  @{
  */
  *
  *  @{
  */


@@ -59,13 +67,10 @@
 #define __HIDPARSER_H__
 
        /* Includes: */
 #define __HIDPARSER_H__
 
        /* Includes: */

-               #include <string.h>
-               #include <stdbool.h>
+               #include "../../../../Common/Common.h"

 
                #include "HIDReportData.h"
 
                #include "HIDReportData.h"

-               #include "../Common/HID.h"
-
-               #include "../../../../Common/Common.h"
+               #include "HIDClassCommon.h"

 
        /* Enable C linkage for C++ Compilers: */
                #if defined(__cplusplus)
 
        /* Enable C linkage for C++ Compilers: */
                #if defined(__cplusplus)


@@ -159,8 +164,8 @@
                         */
                        typedef struct
                        {
                         */
                        typedef struct
                        {

-                               uint32_t                     Minimum; /**< Minimum value for the attribute. */
-                               uint32_t                     Maximum; /**< Maximum value for the attribute. */
+                               uint32_t Minimum; /**< Minimum value for the attribute. */
+                               uint32_t Maximum; /**< Maximum value for the attribute. */

                        } HID_MinMax_t;
 
                        /** \brief HID Parser Report Item Unit Structure.
                        } HID_MinMax_t;
 
                        /** \brief HID Parser Report Item Unit Structure.


@@ -169,8 +174,8 @@
                         */
                        typedef struct
                        {
                         */
                        typedef struct
                        {

-                               uint32_t                     Type;     /**< Unit type (refer to HID specifications for details). */
-                               uint8_t                      Exponent; /**< Unit exponent (refer to HID specifications for details). */
+                               uint32_t Type;     /**< Unit type (refer to HID specifications for details). */
+                               uint8_t  Exponent; /**< Unit exponent (refer to HID specifications for details). */

                        } HID_Unit_t;
 
                        /** \brief HID Parser Report Item Usage Structure.
                        } HID_Unit_t;
 
                        /** \brief HID Parser Report Item Usage Structure.


@@ -179,8 +184,8 @@
                         */
                        typedef struct
                        {
                         */
                        typedef struct
                        {

-                               uint16_t                     Page;   /**< Usage page of the report item. */
-                               uint16_t                     Usage;  /**< Usage of the report item. */
+                               uint16_t Page;  /**< Usage page of the report item. */
+                               uint16_t Usage; /**< Usage of the report item. */

                        } HID_Usage_t;
 
                        /** \brief HID Parser Report Item Collection Path Structure.
                        } HID_Usage_t;
 
                        /** \brief HID Parser Report Item Collection Path Structure.


@@ -188,11 +193,11 @@
                         *  Type define for a COLLECTION object. Contains the collection attributes and a reference to the
                         *  parent collection if any.
                         */
                         *  Type define for a COLLECTION object. Contains the collection attributes and a reference to the
                         *  parent collection if any.
                         */

-                       typedef struct CollectionPath
+                       typedef struct HID_CollectionPath

                        {
                        {

-                               uint8_t                      Type;   /**< Collection type (e.g. "Generic Desktop"). */
-                               HID_Usage_t                  Usage;  /**< Collection usage. */
-                               struct CollectionPath*       Parent; /**< Reference to parent collection, or \c NULL if root collection. */
+                               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. */

                        } HID_CollectionPath_t;
 
                        /** \brief HID Parser Report Item Attributes Structure.
                        } HID_CollectionPath_t;
 
                        /** \brief HID Parser Report Item Attributes Structure.


@@ -201,12 +206,12 @@
                         */
                        typedef struct
                        {
                         */
                        typedef struct
                        {

-                               uint8_t                      BitSize;  /**< Size in bits of the report item's data. */
+                               uint8_t      BitSize;  /**< Size in bits of the report item's data. */

 
 

-                               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. */
+                               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. */

                        } HID_ReportItem_Attributes_t;
 
                        /** \brief HID Parser Report Item Details Structure.
                        } HID_ReportItem_Attributes_t;
 
                        /** \brief HID Parser Report Item Details Structure.


@@ -215,18 +220,18 @@
                         */
                        typedef struct
                        {
                         */
                        typedef struct
                        {

-                               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, such as constant/variable, etc. */
-                               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. */
-
-                               HID_ReportItem_Attributes_t  Attributes;     /**< Report item attributes. */
-
-                               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. */
+                               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 \c 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. */
+
+                               HID_ReportItem_Attributes_t Attributes;     /**< Report item attributes. */
+
+                               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. */

                        } HID_ReportItem_t;
 
                        /** \brief HID Parser Report Size Structure.
                        } HID_ReportItem_t;
 
                        /** \brief HID Parser Report Size Structure.


@@ -235,10 +240,10 @@
                         */
                        typedef struct
                        {
                         */
                        typedef struct
                        {

-                               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.
-                                                                                                                                */
+                               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.
+                                                            */

                        } HID_ReportSizeInfo_t;
 
                        /** \brief HID Parser State Structure.
                        } HID_ReportSizeInfo_t;
 
                        /** \brief HID Parser State Structure.


@@ -247,21 +252,19 @@
                         */
                        typedef struct
                        {
                         */
                        typedef struct
                        {

-                               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.
-                                                                             */
+                               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.
+                                                                     */

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


@@ -281,8 +284,8 @@
                        /** 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.
                         *
                        /** 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.
                         *

-                        *  When called on a report with an item that exists in that report, this copies the report item's Value
-                        *  to it's PreviousValue element for easy checking to see if an item's value has changed before processing
+                        *  When called on a report with an item that exists in that report, this copies the report item's \c Value
+                        *  to its \c 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.
                         *
                         *  a report. If the given item does not exist in the report, the function does not modify the report item's
                         *  data.
                         *


@@ -292,14 +295,14 @@
                         *  \returns Boolean \c true if the item to retrieve was located in the given report, \c false otherwise.
                         */
                        bool USB_GetHIDReportItemInfo(const uint8_t* ReportData,
                         *  \returns Boolean \c true if the item to retrieve was located in the given report, \c false otherwise.
                         */
                        bool USB_GetHIDReportItemInfo(const uint8_t* ReportData,

-                                                     HID_ReportItem_t* const ReportItem) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
+                                                     HID_ReportItem_t* const ReportItem) ATTR_NON_NULL_PTR_ARG(1);

 
 

-                       /** Retrieves the given report item's value out of the Value member of the report item's
+                       /** Retrieves the given report item's value out of the \c 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).
                         *
                         *  \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
+                        *  When called, this copies the report item's \c Value element to its \c 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.
                         *  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.


@@ -308,16 +311,16 @@
                         *  \param[in]  ReportItem  Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array.
                         */
                        void USB_SetHIDReportItemInfo(uint8_t* ReportData,
                         *  \param[in]  ReportItem  Pointer to the report item of interest in a \ref HID_ReportInfo_t ReportItem array.
                         */
                        void USB_SetHIDReportItemInfo(uint8_t* ReportData,

-                                                     HID_ReportItem_t* const ReportItem) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
+                                                     HID_ReportItem_t* const ReportItem) ATTR_NON_NULL_PTR_ARG(1);

 
 

-                       /** Retrieves the size of a given HID report in bytes from it's Report ID.
+                       /** Retrieves the size of a given HID report in bytes from its Report ID.

                         *
                         *  \param[in] ParserData  Pointer to a \ref HID_ReportInfo_t instance containing the parser output.
                         *
                         *  \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.
-                        *  \param[in] ReportType  Type of the report whose size is to be determined, a valued from the
+                        *  \param[in] ReportID    Report ID of the report whose size is to be determined.
+                        *  \param[in] ReportType  Type of the report whose size is to be determined, a value from the

                         *                         \ref HID_ReportItemTypes_t enum.
                         *
                         *                         \ref HID_ReportItemTypes_t enum.
                         *

-                        *  \return Size of the report in bytes, or 0 if the report does not exist.
+                        *  \return Size of the report in bytes, or \c 0 if the report does not exist.

                         */
                        uint16_t USB_GetHIDReportSize(HID_ReportInfo_t* const ParserData,
                                                      const uint8_t ReportID,
                         */
                        uint16_t USB_GetHIDReportSize(HID_ReportInfo_t* const ParserData,
                                                      const uint8_t ReportID,


@@ -328,6 +331,10 @@
                         *  \ref HID_ReportInfo_t structure. This can be used to filter only those items the application will be using, so that
                         *  no RAM is wasted storing the attributes for report items which will never be referenced by the application.
                         *
                         *  \ref HID_ReportInfo_t structure. This can be used to filter only those items the application will be using, so that
                         *  no RAM is wasted storing the attributes for report items which will never be referenced by the application.
                         *

+                        *  Report item pointers passed to this callback function may be cached by the user application for later use
+                        *  when processing report items. This provides faster report processing in the user application than would
+                        *  a search of the entire parsed report item table for each received or sent report.
+                        *

                         *  \param[in] CurrentItem  Pointer to the current report item for user checking.
                         *
                         *  \return Boolean \c true if the item should be stored into the \ref HID_ReportInfo_t structure, \c false if
                         *  \param[in] CurrentItem  Pointer to the current report item for user checking.
                         *
                         *  \return Boolean \c true if the item should be stored into the \ref HID_ReportInfo_t structure, \c false if