| LUFA Library 140302 |

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Modules | Data Structures | Macros | Enumerations | Functions
HID Report Parser
USB Core - LUFA/Drivers/USB/USB.h

USB Human Interface Device (HID) Class report descriptor parser. More...

## Modules
| HID Report Descriptor Item Constants

## Data Structures
struct | HID_CollectionPath_t
| HID Parser Report Item Collection Path Structure. More...
struct | HID_MinMax_t
| HID Parser Report Item Min/Max Structure. More...
struct | HID_ReportInfo_t
| HID Parser State Structure. More...
struct | HID_ReportItem_Attributes_t
| HID Parser Report Item Attributes Structure. More...
struct | HID_ReportItem_t
| HID Parser Report Item Details Structure. More...
struct | HID_ReportSizeInfo_t
| HID Parser Report Size Structure. More...
struct | HID_Unit_t
| HID Parser Report Item Unit Structure. More...
struct | HID_Usage_t
| HID Parser Report Item Usage Structure. More...

## Macros
#define | HID_ALIGN_DATA(ReportItem, Type) ((Type)(ReportItem->Value << ((8 * sizeof(Type)) - ReportItem->Attributes.BitSize)))
#define | HID_MAX_COLLECTIONS 10
#define | HID_MAX_REPORT_IDS 10
#define | HID_MAX_REPORTITEMS 20
#define | HID_STATETABLE_STACK_DEPTH 2
#define | HID_USAGE_STACK_DEPTH 8

## Enumerations
enum | HID_Parse_ErrorCodes_t { HID_PARSE_Successful = 0, HID_PARSE_HIDStackOverflow = 1, HID_PARSE_HIDStackUnderflow = 2, HID_PARSE_InsufficientReportItems = 3, HID_PARSE_UnexpectedEndCollection = 4, HID_PARSE_InsufficientCollectionPaths = 5, HID_PARSE_UsageListOverflow = 6, HID_PARSE_InsufficientReportIDItems = 7, HID_PARSE_NoUnfilteredReportItems = 8 }

## Functions
bool | CALLBACK_HIDParser_FilterHIDReportItem (HID_ReportItem_t *const CurrentItem)
bool | USB_GetHIDReportItemInfo (const uint8_t *ReportData, HID_ReportItem_t *const ReportItem) ATTR_NON_NULL_PTR_ARG(1)
uint16_t | USB_GetHIDReportSize (HID_ReportInfo_t *const ParserData, const uint8_t ReportID, const uint8_t ReportType) ATTR_CONST ATTR_NON_NULL_PTR_ARG(1)
uint8_t | USB_ProcessHIDReport (const uint8_t *ReportData, uint16_t ReportSize, HID_ReportInfo_t *const ParserData) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3)
void | USB_SetHIDReportItemInfo (uint8_t *ReportData, HID_ReportItem_t *const ReportItem) ATTR_NON_NULL_PTR_ARG(1)

## Detailed Description

# Module Source Dependencies

The following files must be built with any user project that uses this module:

- LUFA/Drivers/USB/Class/Host/HIDParser.c (Makefile source module name: LUFA_SRC_USB)

# 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.

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 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.

## Macro Definition Documentation

#define HID_ALIGN_DATA | ( |  | ReportItem,
|  |  | Type
| ) |  | ((Type)(ReportItem->Value << ((8 * sizeof(Type)) - ReportItem->Attributes.BitSize)))

Returns the value a given HID report item (once its value has been fetched via USB_GetHIDReportItemInfo()) left-aligned to the given data type. This allows for signed data to be interpreted correctly, by shifting the data leftwards until the data's sign bit is in the correct position.

Parameters

  [in] | ReportItem | HID Report Item whose retrieved value is to be aligned.
  [in] | Type | Data type to align the HID report item's value to.

Returns
  Left-aligned data of the given report item's pre-retrieved value for the given datatype.

#define HID_MAX_COLLECTIONS 10

Constant indicating the maximum number of COLLECTION items (nested or unnested) that can be processed in the report item descriptor. A large value allows for more COLLECTION items to be processed, but consumes more memory. By default this is set to 10 collections, but this can be overridden by defining `HID_MAX_COLLECTIONS` to another value in the user project makefile, passing the define to the compiler using the -D compiler switch.

#define HID_MAX_REPORT_IDS 10

Constant indicating the maximum number of unique report IDs that can be processed in the report item descriptor for the report size information array in the user HID Report Info structure. A large value allows for more report ID report sizes to be stored, but consumes more memory. By default this is set to 10 items, but this can be overridden by defining `HID_MAX_REPORT_IDS` to another value in the user project makefile, and passing the define to the compiler using the -D compiler switch. Note that IN, OUT and FEATURE items sharing the same report ID consume only one size item in the array.

#define HID_MAX_REPORTITEMS 20

Constant indicating the maximum number of report items (IN, OUT or FEATURE) that can be processed in the report item descriptor and stored in the user HID Report Info structure. A large value allows for more report items to be stored, but consumes more memory. By default this is set to 20 items, but this can be overridden by defining `HID_MAX_REPORTITEMS` to another value in the user project makefile, and passing the define to the compiler using the -D compiler switch.

#define HID_STATETABLE_STACK_DEPTH 2

Constant indicating the maximum stack depth of the state table. A larger state table allows for more PUSH/POP report items to be nested, but consumes more memory. By default this is set to 2 levels (allowing non-nested PUSH items) but this can be overridden by defining `HID_STATETABLE_STACK_DEPTH` to another value in the user project makefile, passing the define to the compiler using the -D compiler switch.

#define HID_USAGE_STACK_DEPTH 8

Constant indicating the maximum stack depth of the usage table. A larger usage table allows for more USAGE items to be indicated sequentially for REPORT COUNT entries of more than one, but requires more stack space. By default this is set to 8 levels (allowing for a report item with a count of 8) but this can be overridden by defining `HID_USAGE_STACK_DEPTH` to another value in the user project makefile, passing the define to the compiler using the -D compiler switch.

## Enumeration Type Documentation

enum HID_Parse_ErrorCodes_t

Enum for the possible error codes in the return value of the USB_ProcessHIDReport() function.

Enumerator
HID_PARSE_Successful | Successful parse of the HID report descriptor, no error.
HID_PARSE_HIDStackOverflow | More than HID_STATETABLE_STACK_DEPTH nested PUSHes in the report.
HID_PARSE_HIDStackUnderflow | A POP was found when the state table stack was empty.
HID_PARSE_InsufficientReportItems | More than HID_MAX_REPORTITEMS report items in the report.
HID_PARSE_UnexpectedEndCollection | An END COLLECTION item found without matching COLLECTION item.
HID_PARSE_InsufficientCollectionPaths | More than HID_MAX_COLLECTIONS collections in the report.
HID_PARSE_UsageListOverflow | More than HID_USAGE_STACK_DEPTH usages listed in a row.
HID_PARSE_InsufficientReportIDItems | More than HID_MAX_REPORT_IDS report IDs in the device.
HID_PARSE_NoUnfilteredReportItems | All report items from the device were filtered by the filtering callback routine.

## Function Documentation

bool CALLBACK_HIDParser_FilterHIDReportItem | ( | HID_ReportItem_t *const | CurrentItem | ) |

Callback routine for the HID Report Parser. This callback must be implemented by the user code when the parser is used, to determine what report IN, OUT and FEATURE item's information is stored into the user 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.

Parameters

  [in] | CurrentItem | Pointer to the current report item for user checking.

Returns
  Boolean `true` if the item should be stored into the HID_ReportInfo_t structure, `false` if it should be ignored.

bool USB_GetHIDReportItemInfo | ( | const uint8_t * | ReportData,
|  | HID_ReportItem_t *const | ReportItem
| ) |  |

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 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 its `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.

Parameters

  [in] | ReportData | Buffer containing an IN or FEATURE report from an attached device.
  [in,out] | ReportItem | Pointer to the report item of interest in a HID_ReportInfo_t ReportItem array.

Returns
  Boolean `true` if the item to retrieve was located in the given report, `false` otherwise.

uint16_t USB_GetHIDReportSize | ( | HID_ReportInfo_t *const | ParserData,
|  | const uint8_t | ReportID,
|  | const uint8_t | ReportType
| ) |  |

Retrieves the size of a given HID report in bytes from its Report ID.

Parameters

  [in] | ParserData | Pointer to a HID_ReportInfo_t instance containing the parser output.
  [in] | ReportID | Report ID of the report whose size is to be determined.
  [in] | ReportType | Type of the report whose size is to be determined, a value from the HID_ReportItemTypes_t enum.

Returns
  Size of the report in bytes, or `0` if the report does not exist.

uint8_t USB_ProcessHIDReport | ( | const uint8_t * | ReportData,
|  | uint16_t | ReportSize,
|  | HID_ReportInfo_t *const | ParserData
| ) |  |

Function to process a given HID report returned from an attached device, and store it into a given HID_ReportInfo_t structure.

Parameters

  [in] | ReportData | Buffer containing the device's HID report table.
  [in] | ReportSize | Size in bytes of the HID report table.
  [out] | ParserData | Pointer to a HID_ReportInfo_t instance for the parser output.

Returns
  A value in the HID_Parse_ErrorCodes_t enum.

void USB_SetHIDReportItemInfo | ( | uint8_t * | ReportData,
|  | HID_ReportItem_t *const | ReportItem
| ) |  |

Retrieves the given report item's value out of the `Value` member of the report item's 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 its `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.

Parameters

  [out] | ReportData | Buffer holding the current OUT or FEATURE report data.
  [in] | ReportItem | Pointer to the report item of interest in a HID_ReportInfo_t ReportItem array.