HID Report Parser
[USB - LUFA/Drivers/USB/USB.h]

Data Structures

struct  HID_MinMax_t
 HID Parser Report Item Min/Max Structure. More...
struct  HID_Unit_t
 HID Parser Report Item Unit Structure. More...
struct  HID_Usage_t
 HID Parser Report Item Usage Structure. More...
struct  HID_CollectionPath_t
 HID Parser Report Item Collection Path 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_ReportInfo_t
 HID Parser State Structure. More...

Modules

 Input/Output/Feature Masks

Defines

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

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

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)
bool USB_GetHIDReportItemInfo (const uint8_t *ReportData, HID_ReportItem_t *const ReportItem) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2)
void USB_SetHIDReportItemInfo (uint8_t *ReportData, HID_ReportItem_t *const ReportItem) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2)
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)
bool CALLBACK_HIDParser_FilterHIDReportItem (HID_ReportItem_t *CurrentItem)

Detailed Description

Module Source Dependencies

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

Description

Functions, macros, variables, enums and types related to the parsing of HID class device report descriptors.

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.

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.


Define 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-retrived 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 5 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 5 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 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 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.

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, this copies the report item's Value element to it's PreviousValue element for easy checking to see if an item's value has changed before processing a report.

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 it's 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 retrieved
[in] ReportType Type of the report whose size is to be determined, a valued 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 it's 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
Generated by  doxygen 1.6.3