Configuration Descriptor Parser
[USB Descriptors]


Defines

#define EP_TYPE_MASK   0x03
#define DESCRIPTOR_PCAST(DescriptorPtr, Type)   ((Type*)DescriptorPtr)
#define DESCRIPTOR_CAST(DescriptorPtr, Type)   (*DESCRIPTOR_PCAST(DescriptorPtr, Type))
#define DESCRIPTOR_TYPE(DescriptorPtr)   DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).Type
#define DESCRIPTOR_SIZE(DescriptorPtr)   DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).Size

Typedefs

typedef uint8_t(*const ConfigComparatorPtr_t )(void *const)

Enumerations

enum  DSearch_Return_ErrorCodes_t {
  DESCRIPTOR_SEARCH_Found = 0,
  DESCRIPTOR_SEARCH_Fail = 1,
  DESCRIPTOR_SEARCH_NotFound = 2
}
enum  DSearch_Comp_Return_ErrorCodes_t {
  DESCRIPTOR_SEARCH_COMP_Found = 0,
  DESCRIPTOR_SEARCH_COMP_Fail = 1,
  DESCRIPTOR_SEARCH_COMP_EndOfDescriptor = 2
}

Functions

uint8_t USB_GetNextDescriptorComp (uint16_t *BytesRem, uint8_t **CurrConfigLoc, ConfigComparatorPtr_t ComparatorRoutine)
uint8_t USB_GetDeviceConfigDescriptor (uint16_t *const ConfigSizePtr, void *BufferPtr) ATTR_NON_NULL_PTR_ARG(1)
void USB_GetNextDescriptorOfType (uint16_t *const BytesRem, uint8_t **const CurrConfigLoc, const uint8_t Type) ATTR_NON_NULL_PTR_ARG(1
void void USB_GetNextDescriptorOfTypeBefore (uint16_t *const BytesRem, uint8_t **const CurrConfigLoc, const uint8_t Type, const uint8_t BeforeType) ATTR_NON_NULL_PTR_ARG(1
void void void USB_GetNextDescriptorOfTypeAfter (uint16_t *const BytesRem, uint8_t **const CurrConfigLoc, const uint8_t Type, const uint8_t AfterType) ATTR_NON_NULL_PTR_ARG(1
void void void static void USB_GetNextDescriptor (uint16_t *const BytesRem, uint8_t **const CurrConfigLoc) ATTR_NON_NULL_PTR_ARG(1

Detailed Description

Functions, macros, variables, enums and types related to the parsing of Configuration Descriptors.

Define Documentation

#define DESCRIPTOR_CAST ( DescriptorPtr,
Type   )     (*DESCRIPTOR_PCAST(DescriptorPtr, Type))

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).

Usage Example:

  uint8_t* CurrDescriptor = &ConfigDescriptor[0]; // Pointing to the configuration header
  USB_Descriptor_Configuration_Header_t ConfigHeader = DESCRIPTOR_CAST(CurrDescriptor,
                                                       USB_Descriptor_Configuration_Header_t);

  // Can now access elements of the configuration header struct using the . operator

#define DESCRIPTOR_PCAST ( DescriptorPtr,
Type   )     ((Type*)DescriptorPtr)

Casts a pointer to a descriptor inside the configuration descriptor into a pointer to the given descriptor type.

Usage Example:

  uint8_t* CurrDescriptor = &ConfigDescriptor[0]; // Pointing to the configuration header
  USB_Descriptor_Configuration_Header_t* ConfigHeaderPtr = DESCRIPTOR_PCAST(CurrDescriptor,
                                                           USB_Descriptor_Configuration_Header_t);

  // Can now access elements of the configuration header struct using the -> indirection operator

#define DESCRIPTOR_SIZE ( DescriptorPtr   )     DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).Size

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

#define DESCRIPTOR_TYPE ( DescriptorPtr   )     DESCRIPTOR_CAST(DescriptorPtr, USB_Descriptor_Header_t).Type

Returns the descriptor's type, expressed as the 8-bit type value in the header of the descriptor. This value's meaning depends on the descriptor's placement in the descriptor, but standard type values can be accessed in the USB_DescriptorTypes_t enum.

#define EP_TYPE_MASK   0x03

Mask for determining the type of an endpoint from an endpoint descriptor. This should then be compared with the EP_TYPE_* masks to determine the exact type of the endpoint.


Typedef Documentation

typedef uint8_t(* const ConfigComparatorPtr_t)(void *const)

Type define for a Configuration Descriptor comparator function (function taking a pointer to an array of type void, returning a uint8_t value).

See also:
USB_GetNextDescriptorComp function for more details


Enumeration Type Documentation

Enum for return values of USB_GetNextDescriptorComp().

Enumerator:
DESCRIPTOR_SEARCH_COMP_Found  Configuration descriptor now points to descriptor which matches search criteria of the given comparator function.
DESCRIPTOR_SEARCH_COMP_Fail  Comparator function returned Descriptor_Search_Fail.
DESCRIPTOR_SEARCH_COMP_EndOfDescriptor  End of configuration descriptor reached before match found.

Enum for return values of a descriptor comparator function.

Enumerator:
DESCRIPTOR_SEARCH_Found  Current descriptor matches comparator criteria.
DESCRIPTOR_SEARCH_Fail  No further descriptor could possibly match criteria, fail the search.
DESCRIPTOR_SEARCH_NotFound  Current descriptor does not match comparator criteria.


Function Documentation

uint8_t USB_GetDeviceConfigDescriptor ( uint16_t *const   ConfigSizePtr,
void *  BufferPtr 
)

Retrieves the configuration descriptor data or size from an attached device via a standard request.

Parameters:
ConfigSizePtr Pointer to a uint16_t for either storing or retrieving the configuration descriptor size
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

void void void static void static void USB_GetNextDescriptor ( uint16_t *const   BytesRem,
uint8_t **const   CurrConfigLoc 
) [inline, static]

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.

Parameters:
BytesRem Pointer to the number of bytes remaining of the configuration descriptor
CurrConfigLoc Pointer to the current descriptor inside the configuration descriptor

uint8_t USB_GetNextDescriptorComp ( uint16_t *  BytesRem,
uint8_t **  CurrConfigLoc,
ConfigComparatorPtr_t  ComparatorRoutine 
)

Searches for the next descriptor in the given configuration descriptor using a premade comparator function. The routine updates the position and remaining configuration descriptor bytes values automatically. If a comparator routine fails a search, the descriptor pointer is retreated back so that the next descriptor search invocation will start from the descriptor which first caused the original search to fail. This behaviour allows for one comparator to be used immediately after another has failed, starting the second search from the descriptor which failed the first.

Comparator functions should be standard functions which accept a pointer to the header of the current descriptor inside the configuration descriptor which is being compared, and should return a value from the DSearch_Return_ErrorCodes_t enum as a uint8_t value.

Note:
This function is available in USB Host mode only.
Parameters:
BytesRem Pointer to an int storing the remaining bytes in the configuration descriptor
CurrConfigLoc Pointer to the current position in the configuration descriptor
ComparatorRoutine Name of the comparator search function to use on the configuration descriptor
Returns:
Value of one of the members of the DSearch_Comp_Return_ErrorCodes_t enum
Usage Example:
  uint8_t EndpointSearcher(void* CurrentDescriptor); // Comparator Prototype

  uint8_t EndpointSearcher(void* CurrentDescriptor)
  {
     if (DESCRIPTOR_TYPE(CurrentDescriptor) == DTYPE_Endpoint)
         return DESCRIPTOR_SEARCH_Found;
     else
         return DESCRIPTOR_SEARCH_NotFound;
  }

  //...
  // After retrieving configuration descriptor:
  if (USB_Host_GetNextDescriptorComp(&BytesRemaining, &ConfigDescriptorData, EndpointSearcher) ==
      Descriptor_Search_Comp_Found)
  {
      // Do something with the endpoint descriptor
  }

void USB_GetNextDescriptorOfType ( uint16_t *const   BytesRem,
uint8_t **const   CurrConfigLoc,
const uint8_t  Type 
)

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

Parameters:
BytesRem Pointer to the number of bytes remaining of the configuration descriptor
CurrConfigLoc Pointer to the current descriptor inside the configuration descriptor
Type Descriptor type value to search for

void void void USB_GetNextDescriptorOfTypeAfter ( uint16_t *const   BytesRem,
uint8_t **const   CurrConfigLoc,
const uint8_t  Type,
const uint8_t  AfterType 
)

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.

Parameters:
BytesRem Pointer to the number of bytes remaining of the configuration descriptor
CurrConfigLoc Pointer to the current descriptor inside the configuration descriptor
Type Descriptor type value to search for
AfterType Descriptor type value which must be reached before the given Type descriptor

void void USB_GetNextDescriptorOfTypeBefore ( uint16_t *const   BytesRem,
uint8_t **const   CurrConfigLoc,
const uint8_t  Type,
const uint8_t  BeforeType 
)

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.

Parameters:
BytesRem Pointer to the number of bytes remaining of the configuration descriptor
CurrConfigLoc Pointer to the current descriptor inside the configuration descriptor
Type Descriptor type value to search for
BeforeType Descriptor type value which must not be reached before the given Type descriptor


Generated on Fri Jun 5 16:30:20 2009 for LUFA Library by  doxygen 1.5.7.1