USB_IsConnected is now cleared before the USB_Disconnect() event is fired in response...

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

diff --git a/LUFA/Drivers/USB/Class/ConfigDescriptor.h b/LUFA/Drivers/USB/Class/ConfigDescriptor.h
index d1f8927..5c2b6e2 100644 (file)
--- a/LUFA/Drivers/USB/Class/ConfigDescriptor.h
+++ b/LUFA/Drivers/USB/Class/ConfigDescriptor.h
@@ -35,6 +35,14 @@
  *  and other descriptor data can be extracted and used as needed.\r
  */\r
 \r
  *  and other descriptor data can be extracted and used as needed.\r
  */\r
 \r

+/** \ingroup Group_Descriptors\r
+ *  @defgroup Group_ConfigDescriptorParser Configuration Descriptor Parser\r
+ *\r
+ *  Functions, macros, variables, enums and types related to the parsing of Configuration Descriptors.\r
+ *\r
+ *  @{\r
+ */\r
+\r

 #ifndef __CONFIGDESCRIPTOR_H__\r
 #define __CONFIGDESCRIPTOR_H__\r
 \r
 #ifndef __CONFIGDESCRIPTOR_H__\r
 #define __CONFIGDESCRIPTOR_H__\r
 \r


@@ -42,6 +50,7 @@
                #include <avr/io.h>\r
                \r
                #include "../../../Common/Common.h"\r
                #include <avr/io.h>\r
                \r
                #include "../../../Common/Common.h"\r

+               #include "../HighLevel/USBMode.h"\r

                #include "../LowLevel/HostChapter9.h"\r
                #include "../HighLevel/StdDescriptors.h"\r
                \r
                #include "../LowLevel/HostChapter9.h"\r
                #include "../HighLevel/StdDescriptors.h"\r
                \r


@@ -50,8 +59,13 @@
                        extern "C" {\r
                #endif\r
 \r
                        extern "C" {\r
                #endif\r
 \r

-       /* Public Interface - May be used in end-application: */\r
+       /* Public Interface - May be used in end-application: */        \r

                /* Macros: */\r
                /* Macros: */\r

+                       /** Mask for determining the type of an endpoint from an endpoint descriptor. This should then be compared\r
+                        *  with the EP_TYPE_* masks to determine the exact type of the endpoint.\r
+                        */\r
+                       #define EP_TYPE_MASK                       0x03\r
+\r

                        /** Casts a pointer to a descriptor inside the configuration descriptor into a pointer to the given\r
                         *  descriptor type.\r
                         *\r
                        /** Casts a pointer to a descriptor inside the configuration descriptor into a pointer to the given\r
                         *  descriptor type.\r
                         *\r


@@ -82,7 +96,7 @@
 \r
                        /** Returns the descriptor's type, expressed as the 8-bit type value in the header of the descriptor.\r
                         *  This value's meaning depends on the descriptor's placement in the descriptor, but standard type\r
 \r
                        /** Returns the descriptor's type, expressed as the 8-bit type value in the header of the descriptor.\r
                         *  This value's meaning depends on the descriptor's placement in the descriptor, but standard type\r

-                        *  values can be accessed in the DescriptorTypes_t enum located in USB/HighLevel/StdDescriptors.h.\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
                         */\r
                        #if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__)\r
                                #define DESCRIPTOR_TYPE(DescriptorPtr)    DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).Type\r


@@ -96,18 +110,16 @@
                        #else\r
                                #define DESCRIPTOR_SIZE(DescriptorPtr)    DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).bLength\r
                        #endif\r
                        #else\r
                                #define DESCRIPTOR_SIZE(DescriptorPtr)    DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).bLength\r
                        #endif\r

-                       \r
-                       /** Creates a prototype for or begins a descriptor comparitor routine. Descriptor comparitor routines are \r
-                        *  small search routines which are passed a pointer to the current sub descriptor in the configuration\r
-                        *  descriptor, and which analyse the sub descriptor to determine whether or not it matches the routine's\r
-                        *  search parameters. Comparitor routines provide a powerful way to scan through the config descriptor\r
-                        *  for certain descriptors matching unique criteria.\r
+\r
+               /* Type Defines: */\r
+                       /** Type define for a Configuration Descriptor comparator function (function taking a pointer to an array\r
+                        *  of type void, returning a uint8_t value).\r

                         *\r
                         *\r

-                        *  Comparitor routines are passed in a single pointer named CurrentDescriptor, and should return a value\r
-                        *  of a member of the DSEARCH_Return_ErrorCodes_t enum.\r
+                        *  \see \ref USB_GetNextDescriptorComp function for more details\r

                         */\r
                         */\r

-                       #define DESCRIPTOR_COMPARATOR(name)           uint8_t DCOMP_##name (void* const CurrentDescriptor)\r
+                       typedef uint8_t (* const ConfigComparatorPtr_t)(void* const);\r

 \r
 \r

+               /* Function Prototypes: */\r

                        /** Searches for the next descriptor in the given configuration descriptor using a premade comparator\r
                         *  function. The routine updates the position and remaining configuration descriptor bytes values\r
                         *  automatically. If a comparator routine fails a search, the descriptor pointer is retreated back\r
                        /** Searches for the next descriptor in the given configuration descriptor using a premade comparator\r
                         *  function. The routine updates the position and remaining configuration descriptor bytes values\r
                         *  automatically. If a comparator routine fails a search, the descriptor pointer is retreated back\r


@@ -115,22 +127,28 @@
                         *  original search to fail. This behaviour allows for one comparator to be used immediately after another\r
                         *  has failed, starting the second search from the descriptor which failed the first.\r
                         *\r
                         *  original search to fail. This behaviour allows for one comparator to be used immediately after another\r
                         *  has failed, starting the second search from the descriptor which failed the first.\r
                         *\r

-                        *  \param DSize    Pointer to an int storing the remaining bytes in the configuration descriptor\r
-                        *  \param DPos     Pointer to the current position in the configuration descriptor\r
-                        *  \param DSearch  Name of the comparitor search function to use on the configuration descriptor\r
+                        *  Comparator functions should be standard functions which accept a pointer to the header of the current\r
+                        *  descriptor inside the configuration descriptor which is being compared, and should return a value from\r
+                        *  the \ref DSearch_Return_ErrorCodes_t enum as a uint8_t value.\r
+                        *\r
+                        *  \note This function is available in USB Host mode only.\r

                         *\r
                         *\r

-                        *  \return Value of one of the members of the DSEARCH_Comp_Return_ErrorCodes_t enum\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
+                        *\r
+                        *  \return Value of one of the members of the \ref DSearch_Comp_Return_ErrorCodes_t enum\r

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

-                        *  DESCRIPTOR_COMPARATOR(EndpointSearcher); // Comparator Prototype\r
+                        *  uint8_t EndpointSearcher(void* CurrentDescriptor); // Comparator Prototype\r

                         *\r
                         *\r

-                        *  DESCRIPTOR_COMPARATOR(EndpointSearcher)\r
+                        *  uint8_t EndpointSearcher(void* CurrentDescriptor)\r

                         *  {\r
                         *     if (DESCRIPTOR_TYPE(CurrentDescriptor) == DTYPE_Endpoint)\r
                         *  {\r
                         *     if (DESCRIPTOR_TYPE(CurrentDescriptor) == DTYPE_Endpoint)\r

-                        *         return Descriptor_Search_Found;\r
+                        *         return DESCRIPTOR_SEARCH_Found;\r

                         *     else\r
                         *     else\r

-                        *         return Descriptor_Search_NotFound;\r
+                        *         return DESCRIPTOR_SEARCH_NotFound;\r

                         *  }\r
                         *\r
                         *  //...\r
                         *  }\r
                         *\r
                         *  //...\r


@@ -142,24 +160,24 @@
                         *  }\r
                         *  \endcode\r
                         */\r
                         *  }\r
                         *  \endcode\r
                         */\r

-                       #define USB_Host_GetNextDescriptorComp(DSize, DPos, DSearch) \\r
-                                                                     USB_Host_GetNextDescriptorComp_P(DSize, DPos, DCOMP_##DSearch)\r
+                       uint8_t USB_GetNextDescriptorComp(uint16_t* BytesRem, uint8_t** CurrConfigLoc, ConfigComparatorPtr_t ComparatorRoutine);\r
+                       \r

                /* Enums: */\r
                /* Enums: */\r

-                       /** Enum for return values of a descriptor comparator made with DESCRIPTOR_COMPARATOR. */\r
-                       enum DSEARCH_Return_ErrorCodes_t\r
+                       /** Enum for return values of a descriptor comparator function. */\r
+                       enum DSearch_Return_ErrorCodes_t\r

                        {\r
                        {\r

-                               Descriptor_Search_Found                = 0, /**< Current descriptor matches comparator criteria. */\r
-                               Descriptor_Search_Fail                 = 1, /**< No further descriptor could possibly match criteria, fail the search. */\r
-                               Descriptor_Search_NotFound             = 2, /**< Current descriptor does not match comparator criteria. */\r
+                               DESCRIPTOR_SEARCH_Found                = 0, /**< Current descriptor matches comparator criteria. */\r
+                               DESCRIPTOR_SEARCH_Fail                 = 1, /**< No further descriptor could possibly match criteria, fail the search. */\r
+                               DESCRIPTOR_SEARCH_NotFound             = 2, /**< Current descriptor does not match comparator criteria. */\r

                        };\r
 \r
                        };\r
 \r

-                       /** Enum for return values of USB_Host_GetNextDescriptorComp() */\r
-                       enum DSEARCH_Comp_Return_ErrorCodes_t\r
+                       /** Enum for return values of \ref USB_GetNextDescriptorComp(). */\r
+                       enum DSearch_Comp_Return_ErrorCodes_t\r

                        {\r
                        {\r

-                               Descriptor_Search_Comp_Found           = 0, /**< Configuration descriptor now points to decriptor which matches\r
+                               DESCRIPTOR_SEARCH_COMP_Found           = 0, /**< Configuration descriptor now points to descriptor which matches\r

                                                                             *   search criteria of the given comparator function. */\r
                                                                             *   search criteria of the given comparator function. */\r

-                               Descriptor_Search_Comp_Fail            = 1, /**< Comparator function returned Descriptor_Search_Fail. */\r
-                               Descriptor_Search_Comp_EndOfDescriptor = 2, /**< End of configuration descriptor reached before match found. */\r
+                               DESCRIPTOR_SEARCH_COMP_Fail            = 1, /**< Comparator function returned Descriptor_Search_Fail. */\r
+                               DESCRIPTOR_SEARCH_COMP_EndOfDescriptor = 2, /**< End of configuration descriptor reached before match found. */\r

                        };\r
        \r
                /* Function Prototypes: */\r
                        };\r
        \r
                /* Function Prototypes: */\r


@@ -174,31 +192,8 @@
                         *                    of bytes indicated by ConfigSizePtr of the configuration descriptor will be loaded\r
                         *                    into the buffer\r
                         */\r
                         *                    of bytes indicated by ConfigSizePtr of the configuration descriptor will be loaded\r
                         *                    into the buffer\r
                         */\r

-                       uint8_t USB_Host_GetDeviceConfigDescriptor(uint16_t* const ConfigSizePtr, void* BufferPtr)\r
-                                                                  ATTR_NON_NULL_PTR_ARG(1);\r
-\r
-               /* Inline Functions: */\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
-                        */\r
-                       static inline void USB_Host_GetNextDescriptor(uint16_t* const BytesRem,\r
-                                                                     uint8_t** const CurrConfigLoc) \r
-                                                                                                                 ATTR_NON_NULL_PTR_ARG(1, 2);                                                                    \r
-                       static inline void USB_Host_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
-                               #else\r
-                               uint16_t CurrDescriptorSize = DESCRIPTOR_CAST(*CurrConfigLoc, USB_Descriptor_Header_t).bLength;                         \r
-                               #endif\r
-\r
-                               *CurrConfigLoc += CurrDescriptorSize;\r
-                               *BytesRem      -= CurrDescriptorSize;\r
-                       }\r
+                       uint8_t USB_GetDeviceConfigDescriptor(uint16_t* const ConfigSizePtr, void* BufferPtr)\r
+                                                             ATTR_NON_NULL_PTR_ARG(1);\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
                        /** Skips to the next sub-descriptor inside the configuration descriptor of the specified type value.\r
                         *  The bytes remaining value is automatically decremented.\r


@@ -207,10 +202,10 @@
                         * \param CurrConfigLoc  Pointer to the current descriptor inside the configuration descriptor\r
                         * \param Type  Descriptor type value to search for\r
                         */\r
                         * \param CurrConfigLoc  Pointer to the current descriptor inside the configuration descriptor\r
                         * \param Type  Descriptor type value to search for\r
                         */\r

-                       void USB_Host_GetNextDescriptorOfType(uint16_t* const BytesRem,\r
-                                                             uint8_t** const CurrConfigLoc,\r
-                                                             const uint8_t Type)\r
-                                                             ATTR_NON_NULL_PTR_ARG(1, 2);\r
+                       void USB_GetNextDescriptorOfType(uint16_t* const BytesRem,\r
+                                                        uint8_t** const CurrConfigLoc,\r
+                                                        const uint8_t Type)\r
+                                                        ATTR_NON_NULL_PTR_ARG(1, 2);\r

 \r
                        /** Skips to the next sub-descriptor inside the configuration descriptor of the specified type value,\r
                         *  which must come before a descriptor of the second given type value. If the BeforeType type\r
 \r
                        /** Skips to the next sub-descriptor inside the configuration descriptor of the specified type value,\r
                         *  which must come before a descriptor of the second given type value. If the BeforeType type\r


@@ -222,11 +217,11 @@
                         * \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
                         */\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
                         */\r

-                       void USB_Host_GetNextDescriptorOfTypeBefore(uint16_t* const BytesRem,\r
-                                                                   uint8_t** const CurrConfigLoc,\r
-                                                                   const uint8_t Type,\r
-                                                                   const uint8_t BeforeType)\r
-                                                                   ATTR_NON_NULL_PTR_ARG(1, 2);\r
+                       void USB_GetNextDescriptorOfTypeBefore(uint16_t* const BytesRem,\r
+                                                              uint8_t** const CurrConfigLoc,\r
+                                                              const uint8_t Type,\r
+                                                              const uint8_t BeforeType)\r
+                                                              ATTR_NON_NULL_PTR_ARG(1, 2);\r

 \r
                        /** Skips to the next sub-descriptor inside the configuration descriptor of the specified type value,\r
                         *  which must come after a descriptor of the second given type value. The bytes remaining value is\r
 \r
                        /** Skips to the next sub-descriptor inside the configuration descriptor of the specified type value,\r
                         *  which must come after a descriptor of the second given type value. The bytes remaining value is\r


@@ -237,22 +232,40 @@
                         * \param Type  Descriptor type value to search for\r
                         * \param AfterType  Descriptor type value which must be reached before the given Type descriptor\r
                         */\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
                         */\r

-                       void USB_Host_GetNextDescriptorOfTypeAfter(uint16_t* const BytesRem,\r
-                                                                  uint8_t** const CurrConfigLoc,\r
-                                                                  const uint8_t Type,\r
-                                                                  const uint8_t AfterType)\r
-                                                                  ATTR_NON_NULL_PTR_ARG(1, 2);\r
-                       \r
-       /* Private Interface - For use in library only: */\r
-       #if !defined(__DOXYGEN__)\r
-               /* Function Prototypes: */\r
-                       uint8_t USB_Host_GetNextDescriptorComp_P(uint16_t* BytesRem, uint8_t** CurrConfigLoc,\r
-                                                     uint8_t (* const ComparatorRoutine)(void* const));\r
-       #endif\r
+                       void USB_GetNextDescriptorOfTypeAfter(uint16_t* const BytesRem,\r
+                                                             uint8_t** const CurrConfigLoc,\r
+                                                             const uint8_t Type,\r
+                                                             const uint8_t AfterType)\r
+                                                             ATTR_NON_NULL_PTR_ARG(1, 2);\r
+\r
+               /* Inline Functions: */\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
+                        */\r
+                       static inline void USB_GetNextDescriptor(uint16_t* const BytesRem,\r
+                                                                uint8_t** const CurrConfigLoc) \r
+                                                                ATTR_NON_NULL_PTR_ARG(1, 2);                                                                     \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
+                               #else\r
+                               uint16_t CurrDescriptorSize = DESCRIPTOR_CAST(*CurrConfigLoc, USB_Descriptor_Header_t).bLength;                         \r
+                               #endif\r
+\r
+                               *CurrConfigLoc += CurrDescriptorSize;\r
+                               *BytesRem      -= CurrDescriptorSize;\r
+                       }\r

                        \r
        /* Disable C linkage for C++ Compilers: */\r
                #if defined(__cplusplus)\r
                        }\r
                #endif\r
                        \r
        /* Disable C linkage for C++ Compilers: */\r
                #if defined(__cplusplus)\r
                        }\r
                #endif\r

-               \r
+\r

 #endif\r
 #endif\r

+\r
+/** @} */\r