Minor documentation enhancements.

[pub/USBasp.git] / LUFA / Drivers / USB / HighLevel / ConfigDescriptor.h

diff --git a/LUFA/Drivers/USB/HighLevel/ConfigDescriptor.h b/LUFA/Drivers/USB/HighLevel/ConfigDescriptor.h
index 87610c7..001653b 100644 (file)
--- a/LUFA/Drivers/USB/HighLevel/ConfigDescriptor.h
+++ b/LUFA/Drivers/USB/HighLevel/ConfigDescriptor.h
@@ -51,12 +51,12 @@
 #define __CONFIGDESCRIPTOR_H__
 
        /* Includes: */
 #define __CONFIGDESCRIPTOR_H__
 
        /* Includes: */

-               #include <avr/io.h>
+               #include <stdint.h>

                
                #include "../../../Common/Common.h"
                
                #include "../../../Common/Common.h"

-               #include "../HighLevel/USBMode.h"
-               #include "../LowLevel/HostChapter9.h"
-               #include "../HighLevel/StdDescriptors.h"
+               #include "HostStandardReq.h"
+               #include "USBMode.h"
+               #include "StdDescriptors.h"

                
        /* Enable C linkage for C++ Compilers: */
                #if defined(__cplusplus)
                
        /* Enable C linkage for C++ Compilers: */
                #if defined(__cplusplus)


@@ -116,7 +116,7 @@
                        /** Type define for a Configuration Descriptor comparator function (function taking a pointer to an array
                         *  of type void, returning a uint8_t value).
                         *
                        /** Type define for a Configuration Descriptor comparator function (function taking a pointer to an array
                         *  of type void, returning a uint8_t value).
                         *

-                        *  \see \ref USB_GetNextDescriptorComp function for more details
+                        *  \see \ref USB_GetNextDescriptorComp function for more details.

                         */
                        typedef uint8_t (* ConfigComparatorPtr_t)(void*);
                        
                         */
                        typedef uint8_t (* ConfigComparatorPtr_t)(void*);
                        


@@ -124,19 +124,19 @@
                        /** Enum for the possible return codes of the \ref USB_Host_GetDeviceConfigDescriptor() function. */
                        enum USB_Host_GetConfigDescriptor_ErrorCodes_t
                        {
                        /** Enum for the possible return codes of the \ref USB_Host_GetDeviceConfigDescriptor() function. */
                        enum USB_Host_GetConfigDescriptor_ErrorCodes_t
                        {

-                               HOST_GETCONFIG_Successful       = 0, /**< No error occurred while retrieving the configuration descriptor */
+                               HOST_GETCONFIG_Successful       = 0, /**< No error occurred while retrieving the configuration descriptor. */

                                HOST_GETCONFIG_DeviceDisconnect = 1, /**< The attached device was disconnected while retrieving the configuration
                                HOST_GETCONFIG_DeviceDisconnect = 1, /**< The attached device was disconnected while retrieving the configuration

-                                                                       * descriptor
+                                                                       * descriptor.

                                                                        */
                                                                        */

-                               HOST_GETCONFIG_PipeError        = 2, /**< An error occurred in the pipe while sending the request */
+                               HOST_GETCONFIG_PipeError        = 2, /**< An error occurred in the pipe while sending the request. */

                                HOST_GETCONFIG_SetupStalled     = 3, /**< The attached device stalled the request to retrieve the configuration
                                HOST_GETCONFIG_SetupStalled     = 3, /**< The attached device stalled the request to retrieve the configuration

-                                                                       * descriptor
+                                                                       * descriptor.

                                                                        */
                                                                        */

-                               HOST_GETCONFIG_SoftwareTimeOut  = 4, /**< The request or data transfer timed out */
+                               HOST_GETCONFIG_SoftwareTimeOut  = 4, /**< The request or data transfer timed out. */

                                HOST_GETCONFIG_BuffOverflow     = 5, /**< The device's configuration descriptor is too large to fit into the allocated
                                HOST_GETCONFIG_BuffOverflow     = 5, /**< The device's configuration descriptor is too large to fit into the allocated

-                                                                       * buffer
+                                                                       * buffer.

                                                                        */
                                                                        */

-                               HOST_GETCONFIG_InvalidData      = 6, /**< The device returned invalid configuration descriptor data */
+                               HOST_GETCONFIG_InvalidData      = 6, /**< The device returned invalid configuration descriptor data. */

                        };
                
                        /** Enum for return values of a descriptor comparator function. */
                        };
                
                        /** Enum for return values of a descriptor comparator function. */


@@ -161,12 +161,12 @@
                         *  including validity and size checking to prevent a buffer overflow.
                         *
                         *  \param[in]     ConfigNumber   Device configuration descriptor number to fetch from the device (usually set to 1 for
                         *  including validity and size checking to prevent a buffer overflow.
                         *
                         *  \param[in]     ConfigNumber   Device configuration descriptor number to fetch from the device (usually set to 1 for

-                        *                                single configuration devices)
-                        *  \param[in,out] ConfigSizePtr  Pointer to a uint16_t for storing the retrieved configuration descriptor size
+                        *                                single configuration devices).
+                        *  \param[in,out] ConfigSizePtr  Pointer to a uint16_t for storing the retrieved configuration descriptor size.

                         *  \param[out]    BufferPtr      Pointer to the buffer for storing the configuration descriptor data.
                         *  \param[out]    BufferPtr      Pointer to the buffer for storing the configuration descriptor data.

-                        *  \param[out]    BufferSize     Size of the allocated buffer where the configuration descriptor is to be stored
+                        *  \param[out]    BufferSize     Size of the allocated buffer where the configuration descriptor is to be stored.

                         *
                         *

-                        *  \return A value from the \ref USB_Host_GetConfigDescriptor_ErrorCodes_t enum
+                        *  \return A value from the \ref USB_Host_GetConfigDescriptor_ErrorCodes_t enum.

                         */
                        uint8_t USB_Host_GetDeviceConfigDescriptor(uint8_t ConfigNumber, uint16_t* const ConfigSizePtr, void* BufferPtr,
                                                                   uint16_t BufferSize) ATTR_NON_NULL_PTR_ARG(2) ATTR_NON_NULL_PTR_ARG(3);
                         */
                        uint8_t USB_Host_GetDeviceConfigDescriptor(uint8_t ConfigNumber, uint16_t* const ConfigSizePtr, void* BufferPtr,
                                                                   uint16_t BufferSize) ATTR_NON_NULL_PTR_ARG(2) ATTR_NON_NULL_PTR_ARG(3);


@@ -174,9 +174,9 @@
                        /** Skips to the next sub-descriptor inside the configuration descriptor of the specified type value.
                         *  The bytes remaining value is automatically decremented.
                         *
                        /** Skips to the next sub-descriptor inside the configuration descriptor of the specified type value.
                         *  The bytes remaining value is automatically decremented.
                         *

-                        * \param[in,out] BytesRem       Pointer to the number of bytes remaining of the configuration descriptor
-                        * \param[in,out] CurrConfigLoc  Pointer to the current descriptor inside the configuration descriptor
-                        * \param[in]     Type           Descriptor type value to search for
+                        * \param[in,out] BytesRem       Pointer to the number of bytes remaining of the configuration descriptor.
+                        * \param[in,out] CurrConfigLoc  Pointer to the current descriptor inside the configuration descriptor.
+                        * \param[in]     Type           Descriptor type value to search for.

                         */
                        void USB_GetNextDescriptorOfType(uint16_t* const BytesRem,
                                                         void** const CurrConfigLoc,
                         */
                        void USB_GetNextDescriptorOfType(uint16_t* const BytesRem,
                                                         void** const CurrConfigLoc,


@@ -188,10 +188,10 @@
                         *  descriptor is reached first, the number of bytes remaining to process is set to zero and the
                         *  function exits. The bytes remaining value is automatically decremented.
                         *
                         *  descriptor is reached first, the number of bytes remaining to process is set to zero and the
                         *  function exits. The bytes remaining value is automatically decremented.
                         *

-                        * \param[in,out] BytesRem       Pointer to the number of bytes remaining of the configuration descriptor
-                        * \param[in,out] CurrConfigLoc  Pointer to the current descriptor inside the configuration descriptor
-                        * \param[in]     Type           Descriptor type value to search for
-                        * \param[in]     BeforeType     Descriptor type value which must not be reached before the given Type descriptor
+                        * \param[in,out] BytesRem       Pointer to the number of bytes remaining of the configuration descriptor.
+                        * \param[in,out] CurrConfigLoc  Pointer to the current descriptor inside the configuration descriptor.
+                        * \param[in]     Type           Descriptor type value to search for.
+                        * \param[in]     BeforeType     Descriptor type value which must not be reached before the given Type descriptor.

                         */
                        void USB_GetNextDescriptorOfTypeBefore(uint16_t* const BytesRem,
                                                               void** const CurrConfigLoc,
                         */
                        void USB_GetNextDescriptorOfTypeBefore(uint16_t* const BytesRem,
                                                               void** const CurrConfigLoc,


@@ -203,10 +203,10 @@
                         *  which must come after a descriptor of the second given type value. The bytes remaining value is
                         *  automatically decremented.
                         *
                         *  which must come after a descriptor of the second given type value. The bytes remaining value is
                         *  automatically decremented.
                         *

-                        * \param[in,out] BytesRem       Pointer to the number of bytes remaining of the configuration descriptor
-                        * \param[in,out] CurrConfigLoc  Pointer to the current descriptor inside the configuration descriptor
-                        * \param[in]     Type           Descriptor type value to search for
-                        * \param[in]     AfterType      Descriptor type value which must be reached before the given Type descriptor
+                        * \param[in,out] BytesRem       Pointer to the number of bytes remaining of the configuration descriptor.
+                        * \param[in,out] CurrConfigLoc  Pointer to the current descriptor inside the configuration descriptor.
+                        * \param[in]     Type           Descriptor type value to search for.
+                        * \param[in]     AfterType      Descriptor type value which must be reached before the given Type descriptor.

                         */
                        void USB_GetNextDescriptorOfTypeAfter(uint16_t* const BytesRem,
                                                              void** const CurrConfigLoc,
                         */
                        void USB_GetNextDescriptorOfTypeAfter(uint16_t* const BytesRem,
                                                              void** const CurrConfigLoc,


@@ -214,7 +214,7 @@
                                                              const uint8_t AfterType)
                                                              ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
 
                                                              const uint8_t AfterType)
                                                              ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);
 

-                       /** Searches for the next descriptor in the given configuration descriptor using a premade comparator
+                       /** Searches for the next descriptor in the given configuration descriptor using a pre-made comparator

                         *  function. The routine updates the position and remaining configuration descriptor bytes values
                         *  automatically. If a comparator routine fails a search, the descriptor pointer is retreated back
                         *  so that the next descriptor search invocation will start from the descriptor which first caused the
                         *  function. The routine updates the position and remaining configuration descriptor bytes values
                         *  automatically. If a comparator routine fails a search, the descriptor pointer is retreated back
                         *  so that the next descriptor search invocation will start from the descriptor which first caused the


@@ -227,11 +227,11 @@
                         *
                         *  \note This function is available in USB Host mode only.
                         *
                         *
                         *  \note This function is available in USB Host mode only.
                         *

-                        *  \param[in,out] BytesRem           Pointer to an int storing the remaining bytes in the configuration descriptor
-                        *  \param[in,out] CurrConfigLoc      Pointer to the current position in the configuration descriptor
-                        *  \param[in]     ComparatorRoutine  Name of the comparator search function to use on the configuration descriptor
+                        *  \param[in,out] BytesRem           Pointer to an int storing the remaining bytes in the configuration descriptor.
+                        *  \param[in,out] CurrConfigLoc      Pointer to the current position in the configuration descriptor.
+                        *  \param[in]     ComparatorRoutine  Name of the comparator search function to use on the configuration descriptor.

                         *
                         *

-                        *  \return Value of one of the members of the \ref DSearch_Comp_Return_ErrorCodes_t enum
+                        *  \return Value of one of the members of the \ref DSearch_Comp_Return_ErrorCodes_t enum.

                         *
                         *  Usage Example:
                         *  \code
                         *
                         *  Usage Example:
                         *  \code


@@ -254,35 +254,26 @@
                         *  }
                         *  \endcode
                         */
                         *  }
                         *  \endcode
                         */

-                       uint8_t USB_GetNextDescriptorComp(uint16_t* BytesRem, void** const CurrConfigLoc, ConfigComparatorPtr_t const ComparatorRoutine);
+                       uint8_t USB_GetNextDescriptorComp(uint16_t* const BytesRem,
+                                                         void** const CurrConfigLoc,
+                                                         ConfigComparatorPtr_t const ComparatorRoutine);

 
                /* Inline Functions: */
 
                /* Inline Functions: */

-                       #if !defined(__DOXYGEN__)
-                       static inline void USB_GetNextDescriptorST(uint16_t* const BytesRem, uint8_t** CurrConfigLoc)
-                       {
-                               uint16_t CurrDescriptorSize = DESCRIPTOR_CAST(*CurrConfigLoc, USB_Descriptor_Header_t).Size;
-                               
-                               *CurrConfigLoc += CurrDescriptorSize;
-                               *BytesRem      -= CurrDescriptorSize;
-                       }                       
-                       #endif
-               

                        /** Skips over the current sub-descriptor inside the configuration descriptor, so that the pointer then
                            points to the next sub-descriptor. The bytes remaining value is automatically decremented.
                         *
                        /** Skips over the current sub-descriptor inside the configuration descriptor, so that the pointer then
                            points to the next sub-descriptor. The bytes remaining value is automatically decremented.
                         *

-                        * \param[in,out] BytesRem       Pointer to the number of bytes remaining of the configuration descriptor
-                        * \param[in,out] CurrConfigLoc  Pointer to the current descriptor inside the configuration descriptor
+                        * \param[in,out] BytesRem       Pointer to the number of bytes remaining of the configuration descriptor.
+                        * \param[in,out] CurrConfigLoc  Pointer to the current descriptor inside the configuration descriptor.

                         */
                         */

-                       static inline void USB_GetNextDescriptor(uint16_t* const BytesRem, void** CurrConfigLoc) 
-                                                                ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);                                                                       
-                       static inline void USB_GetNextDescriptor(uint16_t* const BytesRem, void** CurrConfigLoc)
+                       static inline void USB_GetNextDescriptor(uint16_t* const BytesRem,
+                                                                void** CurrConfigLoc) ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2);                                                                         
+                       static inline void USB_GetNextDescriptor(uint16_t* const BytesRem,
+                                                                void** CurrConfigLoc)

                        {
                        {

-                               /* Horrible workaround for a bug in GCC - in some circumstances, the code generated for the strongly-typed
-                                * (uint8_t**) cast to avoid void pointer arithmetic (which is not allowed in C++) causes incorrect code to
-                                * be generated. Performing the cast and using a secondary inline routine show here seems to avoid the
-                                * problem.
-                                */
-                               USB_GetNextDescriptorST(BytesRem, (uint8_t**)CurrConfigLoc);
+                               uint16_t CurrDescriptorSize = DESCRIPTOR_CAST(*CurrConfigLoc, USB_Descriptor_Header_t).Size;
+                               
+                               *CurrConfigLoc  = ((uint8_t*)*CurrConfigLoc) + CurrDescriptorSize;
+                               *BytesRem      -= CurrDescriptorSize;

                        }
                
        /* Disable C linkage for C++ Compilers: */
                        }
                
        /* Disable C linkage for C++ Compilers: */