projects / pub / USBasp.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Make XPLAINBridge serial bridge much more reliable for the reception of characters...
[pub/USBasp.git] / LUFA / Drivers / USB / Class / Host / HID.h
diff --git a/LUFA/Drivers/USB/Class/Host/HID.h b/LUFA/Drivers/USB/Class/Host/HID.h
index 1988e5d..70728d8 100644 (file)
--- a/LUFA/Drivers/USB/Class/Host/HID.h
+++ b/LUFA/Drivers/USB/Class/Host/HID.h
@@ -85,20 +85,20 @@
                        {
                                const struct
                                {
                        {
                                const struct
                                {
-                                       uint8_t  DataINPipeNumber; /**< Pipe number of the HID interface's IN data pipe */
-                                       bool     DataINPipeDoubleBank; /**< Indicates if the HID interface's IN data pipe should use double banking */
+                                       uint8_t  DataINPipeNumber; /**< Pipe number of the HID interface's IN data pipe. */
+                                       bool     DataINPipeDoubleBank; /**< Indicates if the HID interface's IN data pipe should use double banking. */
 
 
-                                       uint8_t  DataOUTPipeNumber; /**< Pipe number of the HID interface's OUT data pipe */
-                                       bool     DataOUTPipeDoubleBank; /**< Indicates if the HID interface's OUT data pipe should use double banking */
+                                       uint8_t  DataOUTPipeNumber; /**< Pipe number of the HID interface's OUT data pipe. */
+                                       bool     DataOUTPipeDoubleBank; /**< Indicates if the HID interface's OUT data pipe should use double banking. */
 
                                        uint8_t  HIDInterfaceProtocol; /**< HID interface protocol value to match against if a specific
                                                                        *   boot subclass protocol is required, either \ref HID_BOOT_MOUSE_PROTOCOL,
                                                                                                        *   \ref HID_BOOT_KEYBOARD_PROTOCOL or \ref HID_NON_BOOT_PROTOCOL if any
 
                                        uint8_t  HIDInterfaceProtocol; /**< HID interface protocol value to match against if a specific
                                                                        *   boot subclass protocol is required, either \ref HID_BOOT_MOUSE_PROTOCOL,
                                                                                                        *   \ref HID_BOOT_KEYBOARD_PROTOCOL or \ref HID_NON_BOOT_PROTOCOL if any
-                                                                                                       *   HID device should be enumerated by the interface
+                                                                                                       *   HID device should be enumerated by the interface.
                                                                        */
                                        #if !defined(HID_HOST_BOOT_PROTOCOL_ONLY)
                                        HID_ReportInfo_t* HIDParserData; /**< HID parser data to store the parsed HID report data, when boot protocol
                                                                        */
                                        #if !defined(HID_HOST_BOOT_PROTOCOL_ONLY)
                                        HID_ReportInfo_t* HIDParserData; /**< HID parser data to store the parsed HID report data, when boot protocol
-                                                                         *   is not used
+                                                                         *   is not used.
                                                                                                          *
                                                                          *  \note When the HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined,
                                                                          *        this method is unavailable.
                                                                                                          *
                                                                          *  \note When the HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined,
                                                                          *        this method is unavailable.
@@ -111,23 +111,23 @@
                                {
                                        bool IsActive; /**< Indicates if the current interface instance is connected to an attached device, valid
                                                        *   after \ref HID_Host_ConfigurePipes() is called and the Host state machine is in the
                                {
                                        bool IsActive; /**< Indicates if the current interface instance is connected to an attached device, valid
                                                        *   after \ref HID_Host_ConfigurePipes() is called and the Host state machine is in the
-                                                       *   Configured state
+                                                       *   Configured state.
                                                        */
                                                        */
-                                       uint8_t InterfaceNumber; /**< Interface index of the HID interface within the attached device */
+                                       uint8_t InterfaceNumber; /**< Interface index of the HID interface within the attached device. */
 
 
-                                       uint16_t DataINPipeSize; /**< Size in bytes of the HID interface's IN data pipe */
-                                       uint16_t DataOUTPipeSize;  /**< Size in bytes of the HID interface's OUT data pipe */
+                                       uint16_t DataINPipeSize; /**< Size in bytes of the HID interface's IN data pipe. */
+                                       uint16_t DataOUTPipeSize;  /**< Size in bytes of the HID interface's OUT data pipe. */
                                        
                                        bool SupportsBootProtocol; /**< Indicates if the current interface instance supports the HID Boot
                                        
                                        bool SupportsBootProtocol; /**< Indicates if the current interface instance supports the HID Boot
-                                                                   *   Protocol when enabled via \ref HID_Host_SetBootProtocol()
+                                                                   *   Protocol when enabled via \ref HID_Host_SetBootProtocol().
                                                                    */
                                        bool DeviceUsesOUTPipe; /**< Indicates if the current interface instance uses a separate OUT data pipe for
                                                                 *   OUT reports, or if OUT reports are sent via the control pipe instead.
                                                                 */
                                        bool UsingBootProtocol; /**< Indicates that the interface is currently initialized in Boot Protocol mode */
                                                                    */
                                        bool DeviceUsesOUTPipe; /**< Indicates if the current interface instance uses a separate OUT data pipe for
                                                                 *   OUT reports, or if OUT reports are sent via the control pipe instead.
                                                                 */
                                        bool UsingBootProtocol; /**< Indicates that the interface is currently initialized in Boot Protocol mode */
-                                       uint16_t HIDReportSize; /**< Size in bytes of the HID report descriptor in the device */
+                                       uint16_t HIDReportSize; /**< Size in bytes of the HID report descriptor in the device. */
                                        
                                        
-                                       uint8_t LargestReportSize; /**< Largest report the device will send, in bytes */
+                                       uint8_t LargestReportSize; /**< Largest report the device will send, in bytes. */
                                } State; /**< State data for the USB class interface within the device. All elements in this section
                                                  *   <b>may</b> be set to initial values, but may also be ignored to default to sane values when
                                                  *   the interface is enumerated.
                                } State; /**< State data for the USB class interface within the device. All elements in this section
                                                  *   <b>may</b> be set to initial values, but may also be ignored to default to sane values when
                                                  *   the interface is enumerated.
@@ -138,11 +138,11 @@
                        /** Enum for the possible error codes returned by the \ref HID_Host_ConfigurePipes() function. */
                        enum HIDHost_EnumerationFailure_ErrorCodes_t
                        {
                        /** Enum for the possible error codes returned by the \ref HID_Host_ConfigurePipes() function. */
                        enum HIDHost_EnumerationFailure_ErrorCodes_t
                        {
-                               HID_ENUMERROR_NoError                    = 0, /**< Configuration Descriptor was processed successfully */
-                               HID_ENUMERROR_InvalidConfigDescriptor    = 1, /**< The device returned an invalid Configuration Descriptor */
-                               HID_ENUMERROR_NoHIDInterfaceFound        = 2, /**< A compatible HID interface was not found in the device's Configuration Descriptor */
-                               HID_ENUMERROR_NoHIDDescriptorFound       = 3, /**< The HID descriptor was not found in the device's HID interface */
-                               HID_ENUMERROR_EndpointsNotFound          = 4, /**< Compatible HID endpoints were not found in the device's HID interface */
+                               HID_ENUMERROR_NoError                    = 0, /**< Configuration Descriptor was processed successfully. */
+                               HID_ENUMERROR_InvalidConfigDescriptor    = 1, /**< The device returned an invalid Configuration Descriptor. */
+                               HID_ENUMERROR_NoHIDInterfaceFound        = 2, /**< A compatible HID interface was not found in the device's Configuration Descriptor. */
+                               HID_ENUMERROR_NoHIDDescriptorFound       = 3, /**< The HID descriptor was not found in the device's HID interface. */
+                               HID_ENUMERROR_EndpointsNotFound          = 4, /**< Compatible HID endpoints were not found in the device's HID interface. */
                        };
        
                /* Function Prototypes: */
                        };
        
                /* Function Prototypes: */
@@ -155,11 +155,11 @@
                         *  \note Once the device pipes are configured, the HID device's reporting protocol <b>must</b> be set via a call
                         *        to either the \ref HID_Host_SetBootProtocol() or \ref HID_Host_SetReportProtocol() function.
                         *
                         *  \note Once the device pipes are configured, the HID device's reporting protocol <b>must</b> be set via a call
                         *        to either the \ref HID_Host_SetBootProtocol() or \ref HID_Host_SetReportProtocol() function.
                         *
-                        *  \param[in,out] HIDInterfaceInfo        Pointer to a structure containing a HID Class host configuration and state
-                        *  \param[in]     ConfigDescriptorSize    Length of the attached device's Configuration Descriptor
-                        *  \param[in]     DeviceConfigDescriptor  Pointer to a buffer containing the attached device's Configuration Descriptor
+                        *  \param[in,out] HIDInterfaceInfo        Pointer to a structure containing a HID Class host configuration and state.
+                        *  \param[in]     ConfigDescriptorSize    Length of the attached device's Configuration Descriptor.
+                        *  \param[in]     DeviceConfigDescriptor  Pointer to a buffer containing the attached device's Configuration Descriptor.
                         *
                         *
-                        *  \return A value from the \ref HIDHost_EnumerationFailure_ErrorCodes_t enum
+                        *  \return A value from the \ref HIDHost_EnumerationFailure_ErrorCodes_t enum.
                         */
                        uint8_t HID_Host_ConfigurePipes(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo, uint16_t ConfigDescriptorSize,
                                                        void* DeviceConfigDescriptor) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);
                         */
                        uint8_t HID_Host_ConfigurePipes(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo, uint16_t ConfigDescriptorSize,
                                                        void* DeviceConfigDescriptor) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);
@@ -167,17 +167,16 @@
 
                        /** Receives a HID IN report from the attached HID device, when a report has been received on the HID IN Data pipe.
                         *  
 
                        /** Receives a HID IN report from the attached HID device, when a report has been received on the HID IN Data pipe.
                         *  
-                        *  \note This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the
-                        *        call will fail.
-                        *        \n\n
+                        *  \pre This function must only be called when the Host state machine is in the \ref HOST_STATE_Configured state or the
+                        *       call will fail.
                         *
                         *  \note The destination buffer should be large enough to accommodate the largest report that the attached device
                         *        can generate.
                         *
                         *
                         *  \note The destination buffer should be large enough to accommodate the largest report that the attached device
                         *        can generate.
                         *
-                        *  \param[in,out] HIDInterfaceInfo  Pointer to a structure containing a HID Class host configuration and state
-                        *  \param[in]     Buffer            Buffer to store the received report into
+                        *  \param[in,out] HIDInterfaceInfo  Pointer to a structure containing a HID Class host configuration and state.
+                        *  \param[in]     Buffer            Buffer to store the received report into.
                         *
                         *
-                        *  \return An error code from the \ref Pipe_Stream_RW_ErrorCodes_t enum
+                        *  \return An error code from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
                         */
                        uint8_t HID_Host_ReceiveReport(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo, void* Buffer)
                                                       ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
                         */
                        uint8_t HID_Host_ReceiveReport(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo, void* Buffer)
                                                       ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
@@ -185,17 +184,16 @@
                        #if !defined(HID_HOST_BOOT_PROTOCOL_ONLY)
                        /** Receives a HID IN report from the attached device, by the report ID.
                         *
                        #if !defined(HID_HOST_BOOT_PROTOCOL_ONLY)
                        /** Receives a HID IN report from the attached device, by the report ID.
                         *
-                        *  \note This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the
-                        *        call will fail.
-                        *        \n\n
+                        *  \pre This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the
+                        *       call will fail.
                         *
                         *  \note When the HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, this method is unavailable.
                         *
                         *
                         *  \note When the HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, this method is unavailable.
                         *
-                        *  \param[in,out] HIDInterfaceInfo  Pointer to a structure containing a HID Class host configuration and state
-                        *  \param[in]     ReportID          Report ID of the received report if ControlRequest is false, set by the to the Report ID to fetch
-                        *  \param[in]     Buffer            Buffer to store the received report into
+                        *  \param[in,out] HIDInterfaceInfo  Pointer to a structure containing a HID Class host configuration and state.
+                        *  \param[in]     ReportID          Report ID of the received report if ControlRequest is false, set by the to the Report ID to fetch.
+                        *  \param[in]     Buffer            Buffer to store the received report into.
                         *
                         *
-                        *  \return A value from the \ref USB_Host_SendControlErrorCodes_t enum
+                        *  \return A value from the \ref USB_Host_SendControlErrorCodes_t enum.
                         */
                        uint8_t HID_Host_ReceiveReportByID(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo, const uint8_t ReportID,
                                                           void* Buffer) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);
                         */
                        uint8_t HID_Host_ReceiveReportByID(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo, const uint8_t ReportID,
                                                           void* Buffer) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(3);
@@ -204,21 +202,20 @@
                        /** Sends an OUT or FEATURE report to the currently attached HID device, using the device's OUT pipe if available,
                         *  or the device's Control pipe if not.
                         *
                        /** Sends an OUT or FEATURE report to the currently attached HID device, using the device's OUT pipe if available,
                         *  or the device's Control pipe if not.
                         *
-                        *  \note This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the
-                        *        call will fail.
-                        *        \n\n
+                        *  \pre This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the
+                        *       call will fail.
                         *
                         *  \note When the HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, the ReportID parameter is removed
                         *        from the parameter list of this function.
                         *
                         *
                         *  \note When the HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, the ReportID parameter is removed
                         *        from the parameter list of this function.
                         *
-                        *  \param[in,out] HIDInterfaceInfo  Pointer to a structure containing a HID Class host configuration and state
-                        *  \param[in]     ReportID          Report ID of the report to send to the device, or 0 if the device does not use report IDs
-                        *  \param[in]     ReportType        Type of report to issue to the device, either \ref REPORT_ITEM_TYPE_Out or \ref REPORT_ITEM_TYPE_Feature
-                        *  \param[in]     Buffer            Buffer containing the report to send to the attached device
-                        *  \param[in]     ReportSize        Report size in bytes to send to the attached device
+                        *  \param[in,out] HIDInterfaceInfo  Pointer to a structure containing a HID Class host configuration and state.
+                        *  \param[in]     ReportID          Report ID of the report to send to the device, or 0 if the device does not use report IDs.
+                        *  \param[in]     ReportType        Type of report to issue to the device, either \ref REPORT_ITEM_TYPE_Out or \ref REPORT_ITEM_TYPE_Feature.
+                        *  \param[in]     Buffer            Buffer containing the report to send to the attached device.
+                        *  \param[in]     ReportSize        Report size in bytes to send to the attached device.
                         *
                         *  \return An error code from the \ref USB_Host_SendControlErrorCodes_t enum if the DeviceUsesOUTPipe flag is set in
                         *
                         *  \return An error code from the \ref USB_Host_SendControlErrorCodes_t enum if the DeviceUsesOUTPipe flag is set in
-                        *          the interface's state structure, a value from the \ref Pipe_Stream_RW_ErrorCodes_t enum otherwise
+                        *          the interface's state structure, a value from the \ref Pipe_Stream_RW_ErrorCodes_t enum otherwise.
                         */
                        uint8_t HID_Host_SendReportByID(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo,
                        #if !defined(HID_HOST_BOOT_PROTOCOL_ONLY)
                         */
                        uint8_t HID_Host_SendReportByID(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo,
                        #if !defined(HID_HOST_BOOT_PROTOCOL_ONLY)
@@ -233,12 +230,12 @@
 
                        /** Determines if a HID IN report has been received from the attached device on the data IN pipe.
                         *
 
                        /** Determines if a HID IN report has been received from the attached device on the data IN pipe.
                         *
-                        *  \note This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the
-                        *        call will fail.
+                        *  \pre This function must only be called when the Host state machine is in the HOST_STATE_Configured state or the
+                        *       call will fail.
                         *
                         *
-                        *  \param[in,out] HIDInterfaceInfo  Pointer to a structure containing a HID Class host configuration and state
+                        *  \param[in,out] HIDInterfaceInfo  Pointer to a structure containing a HID Class host configuration and state.
                         *
                         *
-                        *  \return Boolean true if a report has been received, false otherwise
+                        *  \return Boolean true if a report has been received, false otherwise.
                         */
                        bool HID_Host_IsReportReceived(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
                        
                         */
                        bool HID_Host_IsReportReceived(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
                        
@@ -247,10 +244,10 @@
                         *  \note When the HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, this method must still be called
                         *        to explicitly place the attached device into boot protocol mode before use.
                         *
                         *  \note When the HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, this method must still be called
                         *        to explicitly place the attached device into boot protocol mode before use.
                         *
-                        *  \param[in,out] HIDInterfaceInfo  Pointer to a structure containing a HID Class host configuration and state
+                        *  \param[in,out] HIDInterfaceInfo  Pointer to a structure containing a HID Class host configuration and state.
                         *
                         *  \return \ref HID_ERROR_LOGICAL if the device does not support Boot Protocol mode, a value from the
                         *
                         *  \return \ref HID_ERROR_LOGICAL if the device does not support Boot Protocol mode, a value from the
-                        *          \ref USB_Host_SendControlErrorCodes_t enum otherwise
+                        *          \ref USB_Host_SendControlErrorCodes_t enum otherwise.
                         */
                        uint8_t HID_Host_SetBootProtocol(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
 
                         */
                        uint8_t HID_Host_SetBootProtocol(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
 
@@ -264,12 +261,12 @@
                         *
                         *  \note When the HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, this method is unavailable.
                         *
                         *
                         *  \note When the HID_HOST_BOOT_PROTOCOL_ONLY compile time token is defined, this method is unavailable.
                         *
-                        *  \param[in,out] HIDInterfaceInfo  Pointer to a structure containing a HID Class host configuration and state
+                        *  \param[in,out] HIDInterfaceInfo  Pointer to a structure containing a HID Class host configuration and state.
                         *
                         *  \return A value from the \ref USB_Host_SendControlErrorCodes_t enum if an error occurs while retrieving the HID
                         *          Report descriptor or the setting of the Report protocol, \ref HID_ERROR_LOGICAL if the HID interface does
                         *          not have a valid \ref HID_ReportInfo_t structure set in its configuration, a mask of \ref HID_ERROR_LOGICAL
                         *
                         *  \return A value from the \ref USB_Host_SendControlErrorCodes_t enum if an error occurs while retrieving the HID
                         *          Report descriptor or the setting of the Report protocol, \ref HID_ERROR_LOGICAL if the HID interface does
                         *          not have a valid \ref HID_ReportInfo_t structure set in its configuration, a mask of \ref HID_ERROR_LOGICAL
-                        *          and a value from the \ref HID_Parse_ErrorCodes_t otherwise
+                        *          and a value from the \ref HID_Parse_ErrorCodes_t otherwise.
                         */
                        uint8_t HID_Host_SetReportProtocol(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
                        #endif
                         */
                        uint8_t HID_Host_SetReportProtocol(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo) ATTR_NON_NULL_PTR_ARG(1);
                        #endif
@@ -279,7 +276,7 @@
                         *  the interface. This should be called frequently in the main program loop, before the master USB management task
                         *  \ref USB_USBTask().
                         *
                         *  the interface. This should be called frequently in the main program loop, before the master USB management task
                         *  \ref USB_USBTask().
                         *
-                        *  \param[in,out] HIDInterfaceInfo  Pointer to a structure containing a HID Class host configuration and state
+                        *  \param[in,out] HIDInterfaceInfo  Pointer to a structure containing a HID Class host configuration and state.
                         */
                        static inline void HID_Host_USBTask(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo);
                        static inline void HID_Host_USBTask(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo)
                         */
                        static inline void HID_Host_USBTask(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo);
                        static inline void HID_Host_USBTask(USB_ClassInfo_HID_Host_t* const HIDInterfaceInfo)
USB isp AVR programmer