-/*\r
- LUFA Library\r
- Copyright (C) Dean Camera, 2009.\r
- \r
- dean [at] fourwalledcubicle [dot] com\r
- www.fourwalledcubicle.com\r
-*/\r
-\r
-/*\r
- Copyright 2009 Dean Camera (dean [at] fourwalledcubicle [dot] com)\r
-\r
- Permission to use, copy, modify, and distribute this software\r
- and its documentation for any purpose and without fee is hereby\r
- granted, provided that the above copyright notice appear in all\r
- copies and that both that the copyright notice and this\r
- permission notice and warranty disclaimer appear in supporting\r
- documentation, and that the name of the author not be used in\r
- advertising or publicity pertaining to distribution of the\r
- software without specific, written prior permission.\r
-\r
- The author disclaim all warranties with regard to this\r
- software, including all implied warranties of merchantability\r
- and fitness. In no event shall the author be liable for any\r
- special, indirect or consequential damages or any damages\r
- whatsoever resulting from loss of use, data or profits, whether\r
- in an action of contract, negligence or other tortious action,\r
- arising out of or in connection with the use or performance of\r
- this software.\r
-*/\r
-\r
-/** \file\r
- *\r
- * Configuration descriptor parser API. This section of the library gives a friendly API which can be used in\r
- * host applications to easily parse an attached device's configuration descriptor so that endpoint, interface\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
- /* Includes: */\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
- /* Enable C linkage for C++ Compilers: */\r
- #if defined(__cplusplus)\r
- extern "C" {\r
- #endif\r
-\r
- /* Public Interface - May be used in end-application: */ \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
- * Usage Example:\r
- * \code\r
- * uint8_t* CurrDescriptor = &ConfigDescriptor[0]; // Pointing to the configuration header\r
- * USB_Descriptor_Configuration_Header_t* ConfigHeaderPtr = DESCRIPTOR_PCAST(CurrDescriptor,\r
- * USB_Descriptor_Configuration_Header_t);\r
- *\r
- * // Can now access elements of the configuration header struct using the -> indirection operator\r
- * \endcode\r
- */\r
- #define DESCRIPTOR_PCAST(DescriptorPtr, Type) ((Type*)DescriptorPtr)\r
-\r
- /** Casts a pointer to a descriptor inside the configuration descriptor into the given descriptor\r
- * type (as an actual struct instance rather than a pointer to a struct).\r
- *\r
- * Usage Example:\r
- * \code\r
- * uint8_t* CurrDescriptor = &ConfigDescriptor[0]; // Pointing to the configuration header\r
- * USB_Descriptor_Configuration_Header_t ConfigHeader = DESCRIPTOR_CAST(CurrDescriptor,\r
- * USB_Descriptor_Configuration_Header_t);\r
- *\r
- * // Can now access elements of the configuration header struct using the . operator\r
- * \endcode\r
- */\r
- #define DESCRIPTOR_CAST(DescriptorPtr, Type) (*DESCRIPTOR_PCAST(DescriptorPtr, 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 \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
- \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
-\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
- * \see \ref USB_GetNextDescriptorComp function for more details\r
- */\r
- typedef uint8_t (* const ConfigComparatorPtr_t)(void* const);\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
- * 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 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
- };\r
-\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
- * 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
- };\r
- \r
- /* Function Prototypes: */\r
- /** Retrieves the configuration descriptor data or size from an attached device via a standard request.\r
- *\r
- * \param ConfigSizePtr Pointer to a uint16_t for either storing or retrieving the configuration\r
- * descriptor size\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
- */\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
- * \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
- */\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
- * 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
- */\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
- * 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
- */\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
-#endif\r
-\r
-/** @} */\r
projects / pub / lufa.git / blobdiff