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


Data Structures

struct  HID_MinMax_t
struct  HID_Unit_t
struct  HID_Usage_t
struct  CollectionPath
struct  HID_ReportItem_Attributes_t
struct  HID_ReportItem_t
struct  HID_ReportInfo_t

Modules

 Input/Output/Feature Masks

Defines

#define HID_STATETABLE_STACK_DEPTH   3
#define HID_USAGE_STACK_DEPTH   8
#define HID_MAX_COLLECTIONS   5
#define HID_MAX_REPORTITEMS   30

Typedefs

typedef struct CollectionPath HID_CollectionPath_t

Enumerations

enum  HID_ReportItemTypes_t {
  REPORT_ITEM_TYPE_In = 0,
  REPORT_ITEM_TYPE_Out = 1,
  REPORT_ITEM_TYPE_Feature = 2
}
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_UsageStackOverflow = 6
}

Functions

uint8_t USB_ProcessHIDReport (const uint8_t *ReportData, uint16_t ReportSize, HID_ReportInfo_t *const ParserData) ATTR_NON_NULL_PTR_ARG(1
uint8_t bool USB_GetHIDReportItemInfo (const uint8_t *ReportData, HID_ReportItem_t *const ReportItem) ATTR_NON_NULL_PTR_ARG(1
uint8_t bool void USB_SetHIDReportItemInfo (uint8_t *ReportData, const HID_ReportItem_t *ReportItem) ATTR_NON_NULL_PTR_ARG(1

Detailed 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 (if desired) 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.

By default, FEATURE reports and IN/OUT reports with constant data are ignored in the HID report when processed to save on memory. This can be overridden by defining the HID_ENABLE_FEATURE_PROCESSING or HID_INCLUDE_CONSTANT_DATA_ITEMS tokens in the user project makefile, passing them to the compiler via the -D switch.


Define Documentation

#define HID_MAX_COLLECTIONS   5

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_REPORTITEMS   30

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

#define HID_STATETABLE_STACK_DEPTH   3

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 3 levels (allowing for two PUSHes to be nested) 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.


Typedef Documentation

Type define for a COLLECTION object. Contains the collection attributes and a reference to the parent collection if any.


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  END COLLECTION found without matching COLLECTION item.
HID_PARSE_InsufficientCollectionPaths  More than HID_MAX_COLLECTIONS collections in the report.
HID_PARSE_UsageStackOverflow  More than HID_USAGE_STACK_DEPTH usages listed in a row.

Enum for indicating what type of report item an entry in a HID_ReportInfo_t ReportItem array is

Enumerator:
REPORT_ITEM_TYPE_In  Indicates that the item is an IN report type.
REPORT_ITEM_TYPE_Out  Indicates that the item is an OUT report type.
REPORT_ITEM_TYPE_Feature  Indicates that the item is a FEATURE report type.


Function Documentation

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

Parameters:
ReportData Buffer containing an IN or FEATURE report from an attached device
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

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:
ReportData Buffer containing the device's HID report table
ReportSize Size in bytes of the HID report table
ParserData Pointer to a HID_ReportInfo_t instance for the parser output
Returns:
A value in the HID_Parse_ErrorCodes_t enum

uint8_t bool void USB_SetHIDReportItemInfo ( uint8_t *  ReportData,
const HID_ReportItem_t 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).

If the device has multiple HID reports, the report ID is set to the report ID of the given item.

Parameters:
ReportData Buffer holding the current OUT report data
ReportItem Pointer to the report item of interest in a HID_ReportInfo_t ReportItem array


Generated on Fri Jun 5 16:30:20 2009 for LUFA Library by  doxygen 1.5.7.1