Revert changed CDC_Device_Flush() prototype accidentially changed in the last commit.

[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 17b6378..be24deb 100644 (file)
--- a/LUFA/Drivers/USB/HighLevel/ConfigDescriptor.h
+++ b/LUFA/Drivers/USB/HighLevel/ConfigDescriptor.h
@@ -98,18 +98,10 @@
                         *  This value's meaning depends on the descriptor's placement in the descriptor, but standard type\r
                         *  values can be accessed in the \ref USB_DescriptorTypes_t enum.\r
                         */\r
                         *  This value's meaning depends on the descriptor's placement in the descriptor, but standard type\r
                         *  values can be accessed in the \ref USB_DescriptorTypes_t enum.\r
                         */\r

-                       #if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__)\r
-                               #define DESCRIPTOR_TYPE(DescriptorPtr)    DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).Type\r
-                       #else\r
-                               #define DESCRIPTOR_TYPE(DescriptorPtr)    DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).bDescriptorType                       \r
-                       #endif\r
+                       #define DESCRIPTOR_TYPE(DescriptorPtr)    DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).Type\r

                        \r
                        /** Returns the descriptor's size, expressed as the 8-bit value indicating the number of bytes. */\r
                        \r
                        /** Returns the descriptor's size, expressed as the 8-bit value indicating the number of bytes. */\r

-                       #if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__)\r
-                               #define DESCRIPTOR_SIZE(DescriptorPtr)    DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).Size\r
-                       #else\r
-                               #define DESCRIPTOR_SIZE(DescriptorPtr)    DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).bLength\r
-                       #endif\r
+                       #define DESCRIPTOR_SIZE(DescriptorPtr)    DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).Size\r

 \r
                /* Type Defines: */\r
                        /** Type define for a Configuration Descriptor comparator function (function taking a pointer to an array\r
 \r
                /* Type Defines: */\r
                        /** Type define for a Configuration Descriptor comparator function (function taking a pointer to an array\r


@@ -133,9 +125,9 @@
                         *\r
                         *  \note This function is available in USB Host mode only.\r
                         *\r
                         *\r
                         *  \note This function is available in USB Host mode only.\r
                         *\r

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

                         *\r
                         *  \return Value of one of the members of the \ref DSearch_Comp_Return_ErrorCodes_t enum\r
                         *\r
                         *\r
                         *  \return Value of one of the members of the \ref DSearch_Comp_Return_ErrorCodes_t enum\r
                         *\r


@@ -153,7 +145,7 @@
                         *\r
                         *  //...\r
                         *  // After retrieving configuration descriptor:\r
                         *\r
                         *  //...\r
                         *  // After retrieving configuration descriptor:\r

-                        *  if (USB_Host_GetNextDescriptorComp(&BytesRemaining, &ConfigDescriptorData, EndpointSearcher) ==\r
+                        *  if (USB_Host_GetNextDescriptorComp(&BytesRemaining, &CurrentConfigLoc, EndpointSearcher) ==\r

                         *      Descriptor_Search_Comp_Found)\r
                         *  {\r
                         *      // Do something with the endpoint descriptor\r
                         *      Descriptor_Search_Comp_Found)\r
                         *  {\r
                         *      // Do something with the endpoint descriptor\r


@@ -163,6 +155,23 @@
                        uint8_t USB_GetNextDescriptorComp(uint16_t* BytesRem, uint8_t** CurrConfigLoc, ConfigComparatorPtr_t ComparatorRoutine);\r
                        \r
                /* Enums: */\r
                        uint8_t USB_GetNextDescriptorComp(uint16_t* BytesRem, uint8_t** CurrConfigLoc, ConfigComparatorPtr_t ComparatorRoutine);\r
                        \r
                /* Enums: */\r

+                       enum USB_Host_GetConfigDescriptor_ErrorCodes_t\r
+                       {\r
+                               HOST_GETCONFIG_Successful       = 0, /**< No error occurred while retrieving the configuration descriptor */\r
+                               HOST_GETCONFIG_DeviceDisconnect = 1, /**< The attached device was disconnected while retrieving the configuration\r
+                                                                       * descriptor\r
+                                                                       */\r
+                               HOST_GETCONFIG_PipeError        = 2, /**< An error occurred in the pipe while sending the request */\r
+                               HOST_GETCONFIG_SetupStalled     = 3, /**< The attached device stalled the request to retrieve the configuration\r
+                                                                       * descriptor\r
+                                                                       */\r
+                               HOST_GETCONFIG_SoftwareTimeOut  = 4, /**< The request or data transfer timed out */\r
+                               HOST_GETCONFIG_BuffOverflow     = 5, /**< The device's configuration descriptor is too large to fit into the allocated\r
+                                                                       * buffer\r
+                                                                       */\r
+                               HOST_GETCONFIG_InvalidData      = 6, /**< The device returned invalid configuration descriptor data */\r
+                       };\r
+               \r

                        /** Enum for return values of a descriptor comparator function. */\r
                        enum DSearch_Return_ErrorCodes_t\r
                        {\r
                        /** Enum for return values of a descriptor comparator function. */\r
                        enum DSearch_Return_ErrorCodes_t\r
                        {\r


@@ -181,29 +190,26 @@
                        };\r
        \r
                /* Function Prototypes: */\r
                        };\r
        \r
                /* Function Prototypes: */\r

-                       /** Retrieves the configuration descriptor data or size from an attached device via a standard request.\r
-                        *\r
-                        *  \param ConfigNumber  Device configuration descriptor number to fetch from the device (usually set to 1 for\r
-                        *                       single configuration devices)\r
+                       /** Retrieves the configuration descriptor data from an attached device via a standard request into a buffer,\r
+                        *  including validity and size checking to prevent a buffer overflow.\r

                         *\r
                         *\r

-                        *  \param ConfigSizePtr  Pointer to a uint16_t for either storing or retrieving the configuration\r
-                        *         descriptor size\r
+                        *  \param[in] ConfigNumber  Device configuration descriptor number to fetch from the device (usually set to 1 for\r
+                        *                           single configuration devices)\r
+                        *  \param[in,out] ConfigSizePtr  Pointer to a uint16_t for storing the retrieved configuration descriptor size\r
+                        *  \param[out] BufferPtr  Pointer to the buffer for storing the configuration descriptor data.\r
+                        *  \param[out] BufferSize  Size of the allocated buffer where the configuration descriptor is to be stored\r

                         *\r
                         *\r

-                        *  \param BufferPtr  Pointer to the buffer for storing the configuration descriptor data. If this is\r
-                        *                    NULL, the size of the configuration descriptor will be retrieved instead and\r
-                        *                    placed in the variable pointed to by ConfigSizePtr. If this is non-NULL, the number\r
-                        *                    of bytes indicated by ConfigSizePtr of the configuration descriptor will be loaded\r
-                        *                    into the buffer\r
+                        *  \return A value from the \ref USB_Host_GetConfigDescriptor_ErrorCodes_t enum\r

                         */\r
                         */\r

-                       uint8_t USB_GetDeviceConfigDescriptor(uint8_t ConfigNumber, uint16_t* const ConfigSizePtr, void* BufferPtr)\r
-                                                             ATTR_NON_NULL_PTR_ARG(2);\r
+                       uint8_t USB_GetDeviceConfigDescriptor(uint8_t ConfigNumber, uint16_t* const ConfigSizePtr, void* BufferPtr,\r
+                                                             uint16_t BufferSize) ATTR_NON_NULL_PTR_ARG(2, 3);\r

 \r
                        /** Skips to the next sub-descriptor inside the configuration descriptor of the specified type value.\r
                         *  The bytes remaining value is automatically decremented.\r
                         *\r
 \r
                        /** Skips to the next sub-descriptor inside the configuration descriptor of the specified type value.\r
                         *  The bytes remaining value is automatically decremented.\r
                         *\r

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

                         */\r
                        void USB_GetNextDescriptorOfType(uint16_t* const BytesRem,\r
                                                         uint8_t** const CurrConfigLoc,\r
                         */\r
                        void USB_GetNextDescriptorOfType(uint16_t* const BytesRem,\r
                                                         uint8_t** const CurrConfigLoc,\r


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

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

                         */\r
                        void USB_GetNextDescriptorOfTypeBefore(uint16_t* const BytesRem,\r
                                                               uint8_t** const CurrConfigLoc,\r
                         */\r
                        void USB_GetNextDescriptorOfTypeBefore(uint16_t* const BytesRem,\r
                                                               uint8_t** const CurrConfigLoc,\r


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

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

                         */\r
                        void USB_GetNextDescriptorOfTypeAfter(uint16_t* const BytesRem,\r
                                                              uint8_t** const CurrConfigLoc,\r
                         */\r
                        void USB_GetNextDescriptorOfTypeAfter(uint16_t* const BytesRem,\r
                                                              uint8_t** const CurrConfigLoc,\r


@@ -245,8 +251,8 @@
                        /** Skips over the current sub-descriptor inside the configuration descriptor, so that the pointer then\r
                            points to the next sub-descriptor. The bytes remaining value is automatically decremented.\r
                         *\r
                        /** Skips over the current sub-descriptor inside the configuration descriptor, so that the pointer then\r
                            points to the next sub-descriptor. The bytes remaining value is automatically decremented.\r
                         *\r

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

                         */\r
                        static inline void USB_GetNextDescriptor(uint16_t* const BytesRem,\r
                                                                 uint8_t** const CurrConfigLoc) \r
                         */\r
                        static inline void USB_GetNextDescriptor(uint16_t* const BytesRem,\r
                                                                 uint8_t** const CurrConfigLoc) \r


@@ -254,11 +260,7 @@
                        static inline void USB_GetNextDescriptor(uint16_t* const BytesRem,\r
                                                                 uint8_t** const CurrConfigLoc)\r
                        {\r
                        static inline void USB_GetNextDescriptor(uint16_t* const BytesRem,\r
                                                                 uint8_t** const CurrConfigLoc)\r
                        {\r

-                               #if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES)\r

                                uint16_t CurrDescriptorSize = DESCRIPTOR_CAST(*CurrConfigLoc, USB_Descriptor_Header_t).Size;\r
                                uint16_t CurrDescriptorSize = DESCRIPTOR_CAST(*CurrConfigLoc, USB_Descriptor_Header_t).Size;\r

-                               #else\r
-                               uint16_t CurrDescriptorSize = DESCRIPTOR_CAST(*CurrConfigLoc, USB_Descriptor_Header_t).bLength;                         \r
-                               #endif\r

 \r
                                *CurrConfigLoc += CurrDescriptorSize;\r
                                *BytesRem      -= CurrDescriptorSize;\r
 \r
                                *CurrConfigLoc += CurrDescriptorSize;\r
                                *BytesRem      -= CurrDescriptorSize;\r