\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
#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 comparator routine. Descriptor comparator 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. Comparator 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
- * Comparator 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
- #define DESCRIPTOR_COMPARATOR(name) uint8_t DCOMP_##name (void* const CurrentDescriptor)\r
+ typedef uint8_t (* const ConfigComparatorPtr_t)(void* const);\r
\r
- /* Psuedo-Functions: */\r
- #if defined(__DOXYGEN__)\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
- * so that the next descriptor search invocation will start from the descriptor which first caused the\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
- * \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
- *\r
- * \return Value of one of the members of the DSearch_Comp_Return_ErrorCodes_t enum\r
- *\r
- * Usage Example:\r
- * \code\r
- * DESCRIPTOR_COMPARATOR(EndpointSearcher); // Comparator Prototype\r
- *\r
- * DESCRIPTOR_COMPARATOR(EndpointSearcher)\r
- * {\r
- * if (DESCRIPTOR_TYPE(CurrentDescriptor) == DTYPE_Endpoint)\r
- * return Descriptor_Search_Found;\r
- * else\r
- * return Descriptor_Search_NotFound;\r
- * }\r
- *\r
- * //...\r
- * // After retrieving configuration descriptor:\r
- * if (USB_Host_GetNextDescriptorComp(&BytesRemaining, &ConfigDescriptorData, EndpointSearcher) ==\r
- * Descriptor_Search_Comp_Found)\r
- * {\r
- * // Do something with the endpoint descriptor\r
- * }\r
- * \endcode\r
- */\r
- uint8_t USB_GetNextDescriptorComp(uint16_t* BytesRem, uint8_t** CurrConfigLoc, ComparatorPtr_t ComparatorRoutine);\r
- #else\r
- #define USB_GetNextDescriptorComp(DSize, DPos, DSearch) USB_GetNextDescriptorComp_P(DSize, DPos, DCOMP_##DSearch)\r
- #endif\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
+ * so that the next descriptor search invocation will start from the descriptor which first caused the\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
+ * 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
+ * \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
+ * uint8_t EndpointSearcher(void* CurrentDescriptor); // Comparator Prototype\r
+ *\r
+ * uint8_t EndpointSearcher(void* CurrentDescriptor)\r
+ * {\r
+ * if (DESCRIPTOR_TYPE(CurrentDescriptor) == DTYPE_Endpoint)\r
+ * return DESCRIPTOR_SEARCH_Found;\r
+ * else\r
+ * return DESCRIPTOR_SEARCH_NotFound;\r
+ * }\r
+ *\r
+ * //...\r
+ * // After retrieving configuration descriptor:\r
+ * if (USB_Host_GetNextDescriptorComp(&BytesRemaining, &ConfigDescriptorData, EndpointSearcher) ==\r
+ * Descriptor_Search_Comp_Found)\r
+ * {\r
+ * // Do something with the endpoint descriptor\r
+ * }\r
+ * \endcode\r
+ */\r
+ uint8_t USB_GetNextDescriptorComp(uint16_t* BytesRem, uint8_t** CurrConfigLoc, ConfigComparatorPtr_t ComparatorRoutine);\r
\r
/* Enums: */\r
- /** Enum for return values of a descriptor comparator made with DESCRIPTOR_COMPARATOR. */\r
+ /** Enum for return values of a descriptor comparator function. */\r
enum DSearch_Return_ErrorCodes_t\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
- /** Enum for return values of USB_GetNextDescriptorComp(). */\r
+ /** Enum for return values of \ref USB_GetNextDescriptorComp(). */\r
enum DSearch_Comp_Return_ErrorCodes_t\r
{\r
- Descriptor_Search_Comp_Found = 0, /**< Configuration descriptor now points to descriptor 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
- 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
*BytesRem -= CurrDescriptorSize;\r
}\r
\r
- /* Private Interface - For use in library only: */\r
- #if !defined(__DOXYGEN__)\r
- /* Type Defines: */\r
- typedef uint8_t (* const ComparatorPtr_t)(void* const);\r
-\r
- /* Function Prototypes: */\r
- uint8_t USB_GetNextDescriptorComp_P(uint16_t* BytesRem, uint8_t** CurrConfigLoc, ComparatorPtr_t ComparatorRoutine);\r
- #endif\r
- \r
/* Disable C linkage for C++ Compilers: */\r
#if defined(__cplusplus)\r
}\r
projects / pub / USBasp.git / blobdiff