X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/dfa547164a1f9aefe202041e61075852f6e47191..d11ed10c5314c44dc01c06954d1d73d4894cbff8:/LUFA/Drivers/USB/HighLevel/ConfigDescriptor.h?ds=sidebyside diff --git a/LUFA/Drivers/USB/HighLevel/ConfigDescriptor.h b/LUFA/Drivers/USB/HighLevel/ConfigDescriptor.h index 17b6378e9..df5109d20 100644 --- a/LUFA/Drivers/USB/HighLevel/ConfigDescriptor.h +++ b/LUFA/Drivers/USB/HighLevel/ConfigDescriptor.h @@ -1,21 +1,21 @@ /* LUFA Library - Copyright (C) Dean Camera, 2009. + Copyright (C) Dean Camera, 2010. dean [at] fourwalledcubicle [dot] com www.fourwalledcubicle.com */ /* - Copyright 2009 Dean Camera (dean [at] fourwalledcubicle [dot] com) + Copyright 2010 Dean Camera (dean [at] fourwalledcubicle [dot] com) - Permission to use, copy, modify, and distribute this software - and its documentation for any purpose and without fee is hereby - granted, provided that the above copyright notice appear in all - copies and that both that the copyright notice and this - permission notice and warranty disclaimer appear in supporting - documentation, and that the name of the author not be used in - advertising or publicity pertaining to distribution of the + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that the copyright notice and this + permission notice and warranty disclaimer appear in supporting + documentation, and that the name of the author not be used in + advertising or publicity pertaining to distribution of the software without specific, written prior permission. The author disclaim all warranties with regard to this @@ -78,7 +78,7 @@ * // Can now access elements of the configuration header struct using the -> indirection operator * \endcode */ - #define DESCRIPTOR_PCAST(DescriptorPtr, Type) ((Type*)DescriptorPtr) + #define DESCRIPTOR_PCAST(DescriptorPtr, Type) ((Type*)(DescriptorPtr)) /** Casts a pointer to a descriptor inside the configuration descriptor into the given descriptor * type (as an actual struct instance rather than a pointer to a struct). @@ -98,18 +98,10 @@ * This value's meaning depends on the descriptor's placement in the descriptor, but standard type * values can be accessed in the \ref USB_DescriptorTypes_t enum. */ - #if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__) - #define DESCRIPTOR_TYPE(DescriptorPtr) DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).Type - #else - #define DESCRIPTOR_TYPE(DescriptorPtr) DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).bDescriptorType - #endif + #define DESCRIPTOR_TYPE(DescriptorPtr) DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).Type /** Returns the descriptor's size, expressed as the 8-bit value indicating the number of bytes. */ - #if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__) - #define DESCRIPTOR_SIZE(DescriptorPtr) DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).Size - #else - #define DESCRIPTOR_SIZE(DescriptorPtr) DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).bLength - #endif + #define DESCRIPTOR_SIZE(DescriptorPtr) DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).Size /* Type Defines: */ /** Type define for a Configuration Descriptor comparator function (function taking a pointer to an array @@ -117,7 +109,7 @@ * * \see \ref USB_GetNextDescriptorComp function for more details */ - typedef uint8_t (* const ConfigComparatorPtr_t)(void* const); + typedef uint8_t (* const ConfigComparatorPtr_t)(void*); /* Function Prototypes: */ /** Searches for the next descriptor in the given configuration descriptor using a premade comparator @@ -133,9 +125,9 @@ * * \note This function is available in USB Host mode only. * - * \param BytesRem Pointer to an int storing the remaining bytes in the configuration descriptor - * \param CurrConfigLoc Pointer to the current position in the configuration descriptor - * \param 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 * @@ -153,16 +145,34 @@ * * //... * // After retrieving configuration descriptor: - * if (USB_Host_GetNextDescriptorComp(&BytesRemaining, &ConfigDescriptorData, EndpointSearcher) == + * if (USB_Host_GetNextDescriptorComp(&BytesRemaining, &CurrentConfigLoc, EndpointSearcher) == * Descriptor_Search_Comp_Found) * { * // Do something with the endpoint descriptor * } * \endcode */ - uint8_t USB_GetNextDescriptorComp(uint16_t* BytesRem, uint8_t** CurrConfigLoc, ConfigComparatorPtr_t ComparatorRoutine); + uint8_t USB_GetNextDescriptorComp(uint16_t* BytesRem, void** CurrConfigLoc, ConfigComparatorPtr_t ComparatorRoutine); /* Enums: */ + /** 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_DeviceDisconnect = 1, /**< The attached device was disconnected while retrieving the configuration + * descriptor + */ + 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 + * descriptor + */ + 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 + * buffer + */ + HOST_GETCONFIG_InvalidData = 6, /**< The device returned invalid configuration descriptor data */ + }; + /** Enum for return values of a descriptor comparator function. */ enum DSearch_Return_ErrorCodes_t { @@ -181,84 +191,77 @@ }; /* Function Prototypes: */ - /** Retrieves the configuration descriptor data or size from an attached device via a standard request. - * - * \param ConfigNumber Device configuration descriptor number to fetch from the device (usually set to 1 for - * single configuration devices) + /** Retrieves the configuration descriptor data from an attached device via a standard request into a buffer, + * including validity and size checking to prevent a buffer overflow. * - * \param ConfigSizePtr Pointer to a uint16_t for either storing or retrieving the configuration - * descriptor size + * \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 + * \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 BufferPtr Pointer to the buffer for storing the configuration descriptor data. If this is - * NULL, the size of the configuration descriptor will be retrieved instead and - * placed in the variable pointed to by ConfigSizePtr. If this is non-NULL, the number - * of bytes indicated by ConfigSizePtr of the configuration descriptor will be loaded - * into the buffer + * \return A value from the \ref USB_Host_GetConfigDescriptor_ErrorCodes_t enum */ - uint8_t USB_GetDeviceConfigDescriptor(uint8_t ConfigNumber, uint16_t* const ConfigSizePtr, void* BufferPtr) - ATTR_NON_NULL_PTR_ARG(2); + 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); /** Skips to the next sub-descriptor inside the configuration descriptor of the specified type value. * The bytes remaining value is automatically decremented. * - * \param BytesRem Pointer to the number of bytes remaining of the configuration descriptor - * \param CurrConfigLoc Pointer to the current descriptor inside the configuration descriptor - * \param 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, - uint8_t** const CurrConfigLoc, + void** const CurrConfigLoc, const uint8_t Type) - ATTR_NON_NULL_PTR_ARG(1, 2); + ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2); /** Skips to the next sub-descriptor inside the configuration descriptor of the specified type value, * which must come before a descriptor of the second given type value. If the BeforeType type * 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 BytesRem Pointer to the number of bytes remaining of the configuration descriptor - * \param CurrConfigLoc Pointer to the current descriptor inside the configuration descriptor - * \param Type Descriptor type value to search for - * \param 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, - uint8_t** const CurrConfigLoc, + void** const CurrConfigLoc, const uint8_t Type, const uint8_t BeforeType) - ATTR_NON_NULL_PTR_ARG(1, 2); + ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2); /** Skips to the next sub-descriptor inside the configuration descriptor of the specified type value, * which must come after a descriptor of the second given type value. The bytes remaining value is * automatically decremented. * - * \param BytesRem Pointer to the number of bytes remaining of the configuration descriptor - * \param CurrConfigLoc Pointer to the current descriptor inside the configuration descriptor - * \param Type Descriptor type value to search for - * \param 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, - uint8_t** const CurrConfigLoc, + void** const CurrConfigLoc, const uint8_t Type, const uint8_t AfterType) - ATTR_NON_NULL_PTR_ARG(1, 2); + ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2); /* Inline Functions: */ /** 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 BytesRem Pointer to the number of bytes remaining of the configuration descriptor - * \param 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, - uint8_t** const CurrConfigLoc) - ATTR_NON_NULL_PTR_ARG(1, 2); + void** const CurrConfigLoc) + ATTR_NON_NULL_PTR_ARG(1) ATTR_NON_NULL_PTR_ARG(2); static inline void USB_GetNextDescriptor(uint16_t* const BytesRem, - uint8_t** const CurrConfigLoc) + void** const CurrConfigLoc) { - #if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) uint16_t CurrDescriptorSize = DESCRIPTOR_CAST(*CurrConfigLoc, USB_Descriptor_Header_t).Size; - #else - uint16_t CurrDescriptorSize = DESCRIPTOR_CAST(*CurrConfigLoc, USB_Descriptor_Header_t).bLength; - #endif *CurrConfigLoc += CurrDescriptorSize; *BytesRem -= CurrDescriptorSize;