/**************************************************************************** * include/nuttx/usb/hid_parser.h * * Copyright (C) 2011 Gregory Nutt. All rights reserved. * * Adapted from the LUFA Library: * * Copyright 2011 Dean Camera (dean [at] fourwalledcubicle [dot] com) * dean [at] fourwalledcubicle [dot] com, www.lufa-lib.org * * Permission to use, copy, modify, distribute, and sell this * software and its documentation for any purpose is hereby granted * without fee, provided that the above copyright notice appear in * all copies and that both that the copyright notice and this * permission notice and warranty disclaimer appear in supporting * documentation, and that the name of the author not be used in * advertising or publicity pertaining to distribution of the * software without specific, written prior permission. * * The author disclaim 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 * whatsoever resulting from loss of use, data or profits, whether * in an action of contract, negligence or other tortious action, * arising out of or in connection with the use or performance of * this software. * ****************************************************************************/ #ifndef __INCLUDE_NUTTX_USB_HID_PARSER_H #define __INCLUDE_NUTTX_USB_HID_PARSER_H /**************************************************************************** * Included Files ****************************************************************************/ #include #include /**************************************************************************** * Pre-processor Definitions ****************************************************************************/ /* Configuration ************************************************************/ /* HID_STATETABLE_STACK_DEPTH * 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 in the Nuttx config file. * * HID_USAGE_STACK_DEPTH * 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 * in the Nuttx config file. * * HID_MAX_COLLECTIONS * 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 in the Nuttx config file. * * 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 in the Nuttx config file. * * 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 in the Nuttx config file. Note that IN, OUT and FEATURE * items sharing the same report ID consume only one size item in the array. */ #ifndef HID_STATETABLE_STACK_DEPTH # define HID_STATETABLE_STACK_DEPTH 2 #endif #ifndef HID_USAGE_STACK_DEPTH # define HID_USAGE_STACK_DEPTH 8 #endif #ifndef HID_MAX_COLLECTIONS # define HID_MAX_COLLECTIONS 10 #endif #ifndef HID_MAX_REPORTITEMS # define HID_MAX_REPORTITEMS 20 #endif #ifndef HID_MAX_REPORT_IDS # define HID_MAX_REPORT_IDS 10 #endif /**************************************************************************** * Public Types ****************************************************************************/ /* HID Parser Report Item Min/Max Structure. Type define for an attribute * with both minimum and maximum values (e.g. Logical Min/Max). */ struct hid_range_s { uint32_t min; /* Minimum value for the attribute. */ uint32_t max; /* Maximum value for the attribute. */ }; /* HID Parser Report Item Unit Structure. Type define for the Unit attributes * of a report item. */ struct hid_unit_t { uint32_t type; /* Unit type (refer to HID specifications for details). */ uint8_t exponent; /* Unit exponent (refer to HID specifications for details). */ }; /* HID Parser Report Item Usage Structure. Type define for the Usage * attributes of a report item. */ struct hid_usage_t { uint16_t page; /* Usage page of the report item. */ uint16_t usage; /* Usage of the report item. */ }; /* HID Parser Report Item Collection Path Structure. Type define for a * COLLECTION object. Contains the collection attributes and a reference to * the parent collection if any. */ struct hid_collectionpath_s { uint8_t type; /* Collection type (e.g. "Generic Desktop"). */ struct hid_usage_t usage; /* Collection usage. */ struct hid_collectionpath_s *parent; /* Reference to parent collection, or NULL if root collection. */ }; /* HID Parser Report Item Attributes Structure. Type define for all the data * attributes of a report item, except flags. */ struct hid_rptitem_attributes_s { uint8_t bitsize; /* Size in bits of the report item's data. */ struct hid_usage_t usage; /* Usage of the report item. */ struct hid_unit_t unit; /* Unit type and exponent of the report item. */ struct hid_range_s logical; /* Logical minimum and maximum of the report item. */ struct hid_range_s physical; /* Physical minimum and maximum of the report item. */ }; /* HID Parser Report Item Details Structure. Type define for a report item * (IN, OUT or FEATURE) layout attributes and other details. */ struct hid_rptitem_s { uint16_t bitoffset; /* Bit offset in the IN, OUT or FEATURE report of the item. */ uint8_t type; /* Report item type, a value in HID_ReportItemTypes_t. */ uint16_t flags; /* Item data flags, a mask of HID_IOF_* constants. */ uint8_t id; /* Report ID this item belongs to, or 0x00 if device has only one report */ struct hid_collectionpath_s *collectionpath; /* Collection path of the item. */ struct hid_rptitem_attributes_s attrib; /* Report item attributes. */ uint32_t value; /* Current value of the report item */ uint32_t previous; /* Previous value of the report item. */ }; /* HID Parser Report Size Structure. Type define for a report item size * information structure, to retain the size of a device's reports by ID. */ struct hid_rptsizeinfo_s { uint8_t id; /* Report ID of the report within the HID interface. */ uint16_t size[3]; /* Number of bits in each report type for the given Report ID */ }; /* HID Parser State Structure. Type define for a complete processed HID * report, including all report item data and collections. */ struct hid_rptinfo_s { /* nitems is the number of report items stored in the report items array (rptitems[]). */ uint8_t nitems; struct hid_rptitem_s items[HID_MAX_REPORTITEMS]; /* All collection items, referenced by the report items. */ struct hid_collectionpath_s collectionpaths[HID_MAX_COLLECTIONS]; uint8_t nreports; /* Number of reports within the HID interface */ struct hid_rptsizeinfo_s rptsize[HID_MAX_REPORT_IDS]; /* Report sizes for each report in the interface */ uint16_t maxrptsize; /* Largest report that the attached device will generate, in bits */ bool haverptid; /* Device has at least one REPORT ID in its HID report. */ }; /* 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 * struct hid_rptinfo_s 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. * * Input Parameters: * item Pointer to the current report item for user checking. * * Returned value: * Boolean true if the item should be stored into the struct hid_rptinfo_s * structure, false if it should be ignored. */ typedef bool (*hid_rptfilter_t)(FAR struct hid_rptitem_s *item); /**************************************************************************** * Public Function Protoypes ****************************************************************************/ #undef EXTERN #if defined(__cplusplus) # define EXTERN extern "C" extern "C" { #else # define EXTERN extern #endif /**************************************************************************** * Name: hid_parsereport * * Description: * Function to process a given HID report returned from an attached device, * and store it into a given struct hid_rptinfo_s structure. * * Input Parameters: * report Buffer containing the device's HID report table. * rptlen Size in bytes of the HID report table. * filter Callback function to decide if an item should be retained * rptinfo Pointer to a struct hid_rptinfo_s instance for the parser output. * * Returned Value: * Zero on success, otherwise a negated errno value. ****************************************************************************/ EXTERN int hid_parsereport(FAR const uint8_t *report, int rptlen, hid_rptfilter_t filter, FAR struct hid_rptinfo_s *rptinfo); /**************************************************************************** * Name: hid_getitem * * Description: * 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 struct hid_rptitem_s * structure. * * When called on a report with an item that exists in that report, this * copies the report item's Value to it's previous 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. * * Input Parameters * report Buffer containing an IN or FEATURE report from an attached * device. * item Pointer to the report item of interest in a struct hid_rptinfo_s * item array. * * Returned Value: * Zero on success, otherwise a negated errno value. * ****************************************************************************/ EXTERN int hid_getitem(FAR const uint8_t *report, FAR struct hid_rptitem_s *item); /**************************************************************************** * Name: hid_putitem * * Desription: * Retrieves the given report item's value out of the value member of the * report item's struct hid_rptitem_s 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 * previous 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. * * Input Parameters: * report Buffer holding the current OUT or FEATURE report data. * item Pointer to the report item of interest in a struct hid_rptinfo_s * item array. * ****************************************************************************/ #if 0 /* Not needed by host */ EXTERN void hid_putitem(FAR uint8_t *report, FAR struct hid_rptitem_s *item); #endif /**************************************************************************** * Name: hid_reportsize * * Description: * Retrieves the size of a given HID report in bytes from it's Report ID. * * InputParameters: * rptinfo Pointer to a struct hid_rptinfo_s instance containing the parser output. * id Report ID of the report whose size is to be retrieved. * rpttype Type of the report whose size is to be determined, a valued from the * HID_ReportItemTypes_t enum. * * Size of the report in bytes, or 0 if the report does not exist. * ****************************************************************************/ EXTERN size_t hid_reportsize(FAR struct hid_rptinfo_s *rptinfo, uint8_t id, uint8_t rpttype); #undef EXTERN #if defined(__cplusplus) } #endif #endif /* __INCLUDE_NUTTX_USB_HID_PARSER_H */