diff options
Diffstat (limited to 'LUFA/Drivers/USB')
-rw-r--r-- | LUFA/Drivers/USB/Class/Common/HID.h | 34 | ||||
-rw-r--r-- | LUFA/Drivers/USB/Class/Common/HIDParser.h | 107 | ||||
-rw-r--r-- | LUFA/Drivers/USB/Class/Device/CDC.h | 6 | ||||
-rw-r--r-- | LUFA/Drivers/USB/Class/Host/CDC.h | 9 |
4 files changed, 83 insertions, 73 deletions
diff --git a/LUFA/Drivers/USB/Class/Common/HID.h b/LUFA/Drivers/USB/Class/Common/HID.h index d28417ed5..485b9dbb0 100644 --- a/LUFA/Drivers/USB/Class/Common/HID.h +++ b/LUFA/Drivers/USB/Class/Common/HID.h @@ -343,11 +343,11 @@ * Where \c uintA_t is a type large enough to hold one bit per button, and \c intB_t is a type large enough to hold the * ranges of the signed \c MinAxisVal and \c MaxAxisVal values. * - * \param[in] MinAxisVal Minimum X/Y logical axis value - * \param[in] MaxAxisVal Maximum X/Y logical axis value - * \param[in] MinPhysicalVal Minimum X/Y physical axis value, for movement resolution calculations - * \param[in] MaxPhysicalVal Maximum X/Y physical axis value, for movement resolution calculations - * \param[in] Buttons Total number of buttons in the device + * \param[in] MinAxisVal Minimum X/Y logical axis value. + * \param[in] MaxAxisVal Maximum X/Y logical axis value. + * \param[in] MinPhysicalVal Minimum X/Y physical axis value, for movement resolution calculations. + * \param[in] MaxPhysicalVal Maximum X/Y physical axis value, for movement resolution calculations. + * \param[in] Buttons Total number of buttons in the device. */ #define HID_DESCRIPTOR_JOYSTICK(MinAxisVal, MaxAxisVal, MinPhysicalVal, MaxPhysicalVal, Buttons) \ HID_RI_USAGE_PAGE(8, 0x01), \ @@ -393,7 +393,7 @@ * \endcode * * \param[in] MaxKeys Number of simultaneous keys that can be reported at the one time (a value between 1 and - * (ENDPOINT_SIZE - 2) ) + * (ENDPOINT_SIZE - 2) ). */ #define HID_DESCRIPTOR_KEYBOARD(MaxKeys) \ HID_RI_USAGE_PAGE(8, 0x01), \ @@ -446,12 +446,12 @@ * Where \c intA_t is a type large enough to hold one bit per button, and \c intB_t is a type large enough to hold the * ranges of the signed \c MinAxisVal and \c MaxAxisVal values. * - * \param[in] MinAxisVal Minimum X/Y logical axis value - * \param[in] MaxAxisVal Maximum X/Y logical axis value - * \param[in] MinPhysicalVal Minimum X/Y physical axis value, for movement resolution calculations - * \param[in] MaxPhysicalVal Maximum X/Y physical axis value, for movement resolution calculations - * \param[in] Buttons Total number of buttons in the device - * \param[in] AbsoluteCoords Boolean true to use absolute X/Y coordinates (e.g. touchscreen) + * \param[in] MinAxisVal Minimum X/Y logical axis value. + * \param[in] MaxAxisVal Maximum X/Y logical axis value. + * \param[in] MinPhysicalVal Minimum X/Y physical axis value, for movement resolution calculations. + * \param[in] MaxPhysicalVal Maximum X/Y physical axis value, for movement resolution calculations. + * \param[in] Buttons Total number of buttons in the device. + * \param[in] AbsoluteCoords Boolean true to use absolute X/Y coordinates (e.g. touchscreen). */ #define HID_DESCRIPTOR_MOUSE(MinAxisVal, MaxAxisVal, MinPhysicalVal, MaxPhysicalVal, Buttons, AbsoluteCoords) \ HID_RI_USAGE_PAGE(8, 0x01), \ @@ -488,11 +488,11 @@ * used for transporting abitrary data between the USB host and device via HID reports. The resulting report should be * a uint8_t byte array of the specified length in both Device to Host (IN) and Host to Device (OUT) directions. * - * \param[in] VendorPageNum Vendor Defined HID Usage Page index, ranging from 0x00 to 0xFF - * \param[in] CollectionUsage Vendor Usage for the encompasing report IN and OUT collection, ranging from 0x00 to 0xFF - * \param[in] DataINUsage Vendor Usage for the IN report data, ranging from 0x00 to 0xFF - * \param[in] DataOUTUsage Vendor Usage for the OUT report data, ranging from 0x00 to 0xFF - * \param[in] NumBytes Length of the data IN and OUT reports + * \param[in] VendorPageNum Vendor Defined HID Usage Page index, ranging from 0x00 to 0xFF. + * \param[in] CollectionUsage Vendor Usage for the encompasing report IN and OUT collection, ranging from 0x00 to 0xFF. + * \param[in] DataINUsage Vendor Usage for the IN report data, ranging from 0x00 to 0xFF. + * \param[in] DataOUTUsage Vendor Usage for the OUT report data, ranging from 0x00 to 0xFF. + * \param[in] NumBytes Length of the data IN and OUT reports. */ #define HID_DESCRIPTOR_VENDOR(VendorPageNum, CollectionUsage, DataINUsage, DataOUTUsage, NumBytes) \ HID_RI_USAGE_PAGE(16, (0xFF00 | VendorPageNum)), \ diff --git a/LUFA/Drivers/USB/Class/Common/HIDParser.h b/LUFA/Drivers/USB/Class/Common/HIDParser.h index 8347f1dcf..c1689fad8 100644 --- a/LUFA/Drivers/USB/Class/Common/HIDParser.h +++ b/LUFA/Drivers/USB/Class/Common/HIDParser.h @@ -44,13 +44,20 @@ * - 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. + * 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 + * characterstics. 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 featureset. * - * 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 + * descritor data as a guide for the encoding. * * @{ */ @@ -159,8 +166,8 @@ */ 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. @@ -169,8 +176,8 @@ */ 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. @@ -179,8 +186,8 @@ */ 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. @@ -188,11 +195,11 @@ * 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. @@ -201,12 +208,12 @@ */ 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. @@ -215,18 +222,18 @@ */ 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, a mask of 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. */ + 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 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. @@ -235,10 +242,10 @@ */ 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. @@ -247,21 +254,19 @@ */ 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: */ diff --git a/LUFA/Drivers/USB/Class/Device/CDC.h b/LUFA/Drivers/USB/Class/Device/CDC.h index 62ee0433f..85ab16396 100644 --- a/LUFA/Drivers/USB/Class/Device/CDC.h +++ b/LUFA/Drivers/USB/Class/Device/CDC.h @@ -280,12 +280,12 @@ void CDC_Device_SendControlLineStateChange(USB_ClassInfo_CDC_Device_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1); /** Creates a standard character stream for the given CDC Device instance so that it can be used with all the regular - * functions in the avr-libc <stdio.h> library that accept a FILE stream as a destination (e.g. fprintf). The created + * functions in the avr-libc <stdio.h> library that accept a \c FILE stream as a destination (e.g. \c fprintf). The created * stream is bidirectional and can be used for both input and output functions. * * Reading data from this stream is non-blocking, i.e. in most instances, complete strings cannot be read in by a single * fetch, as the endpoint will not be ready at some point in the transmission, aborting the transfer. However, this may - * be used when the read data is processed byte-per-bye (via getc()) or when the user application will implement its own + * be used when the read data is processed byte-per-bye (via \c getc()) or when the user application will implement its own * line buffering. * * \note The created stream can be given as stdout if desired to direct the standard output from all <stdio.h> functions @@ -297,7 +297,7 @@ void CDC_Device_CreateStream(USB_ClassInfo_CDC_Device_t* const CDCInterfaceInfo, FILE* const Stream) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2); - /** Identical to CDC_Device_CreateStream(), except that reads are blocking until the calling stream function terminates + /** Identical to \ref CDC_Device_CreateStream(), except that reads are blocking until the calling stream function terminates * the transfer. While blocking, the USB and CDC service tasks are called repeatedly to maintain USB communications. * * \param[in,out] CDCInterfaceInfo Pointer to a structure containing a CDC Class configuration and state. diff --git a/LUFA/Drivers/USB/Class/Host/CDC.h b/LUFA/Drivers/USB/Class/Host/CDC.h index 9033cbfb9..3b84bb2d7 100644 --- a/LUFA/Drivers/USB/Class/Host/CDC.h +++ b/LUFA/Drivers/USB/Class/Host/CDC.h @@ -270,9 +270,14 @@ uint8_t CDC_Host_Flush(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1); /** Creates a standard character stream for the given CDC Device instance so that it can be used with all the regular - * functions in the avr-libc \c <stdio.h> library that accept a FILE stream as a destination (e.g. fprintf). The created + * functions in the avr-libc \c <stdio.h> library that accept a \c FILE stream as a destination (e.g. \c fprintf). The created * stream is bidirectional and can be used for both input and output functions. * + * Reading data from this stream is non-blocking, i.e. in most instances, complete strings cannot be read in by a single + * fetch, as the endpoint will not be ready at some point in the transmission, aborting the transfer. However, this may + * be used when the read data is processed byte-per-bye (via \c getc()) or when the user application will implement its own + * line buffering. + * * \note The created stream can be given as stdout if desired to direct the standard output from all \c <stdio.h> functions * to the given CDC interface. * @@ -282,7 +287,7 @@ void CDC_Host_CreateStream(USB_ClassInfo_CDC_Host_t* const CDCInterfaceInfo, FILE* const Stream); - /** Identical to CDC_Host_CreateStream(), except that reads are blocking until the calling stream function terminates + /** Identical to \ref CDC_Host_CreateStream(), except that reads are blocking until the calling stream function terminates * the transfer. While blocking, the USB and CDC service tasks are called repeatedly to maintain USB communications. * * \param[in,out] CDCInterfaceInfo Pointer to a structure containing a CDC Class configuration and state. |