ConfigDescriptor.h File Reference

#include <avr/io.h>
#include "../../../Common/Common.h"
#include "../LowLevel/HostChapter9.h"
#include "../HighLevel/StdDescriptors.h"

Defines

#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
#define DESCRIPTOR_COMPARATOR(name)   uint8_t DCOMP_##name (void* const CurrentDescriptor)
#define USB_Host_GetNextDescriptorComp(DSize, DPos, DSearch)   USB_Host_GetNextDescriptorComp_P(DSize, DPos, DCOMP_##DSearch)

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_Host_GetDeviceConfigDescriptor (uint16_t *const ConfigSizePtr, void *BufferPtr) ATTR_NON_NULL_PTR_ARG(1)
static void USB_Host_GetNextDescriptor (uint16_t *const BytesRem, uint8_t **const CurrConfigLoc) ATTR_NON_NULL_PTR_ARG(1
void USB_Host_GetNextDescriptorOfType (uint16_t *const BytesRem, uint8_t **const CurrConfigLoc, const uint8_t Type) ATTR_NON_NULL_PTR_ARG(1
void void USB_Host_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_Host_GetNextDescriptorOfTypeAfter (uint16_t *const BytesRem, uint8_t **const CurrConfigLoc, const uint8_t Type, const uint8_t AfterType) ATTR_NON_NULL_PTR_ARG(1

Detailed Description

Configuration descriptor parser API. This section of the library gives a friendly API which can be used in host applications to easily parse an attached device's configuration descriptor so that endpoint, interface and other descriptor data can be extracted and used as needed.

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_COMPARATOR ( name   )     uint8_t DCOMP_##name (void* const CurrentDescriptor)

Creates a prototype for or begins a descriptor comparitor routine. Descriptor comparitor routines are small search routines which are passed a pointer to the current sub descriptor in the configuration descriptor, and which analyse the sub descriptor to determine whether or not it matches the routine's search parameters. Comparitor routines provide a powerful way to scan through the config descriptor for certain descriptors matching unique criteria.

Comparitor routines are passed in a single pointer named CurrentDescriptor, and should return a value of a member of the DSEARCH_Return_ErrorCodes_t enum.

#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 DescriptorTypes_t enum located in USB/HighLevel/StdDescriptors.h.

#define USB_Host_GetNextDescriptorComp ( DSize,
DPos,
DSearch   )     USB_Host_GetNextDescriptorComp_P(DSize, DPos, DCOMP_##DSearch)

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.

Parameters:
DSize Pointer to an int storing the remaining bytes in the configuration descriptor
DPos Pointer to the current position in the configuration descriptor
DSearch Name of the comparitor 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:
  DESCRIPTOR_COMPARATOR(EndpointSearcher); // Comparator Prototype

  DESCRIPTOR_COMPARATOR(EndpointSearcher)
  {
     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
  }


Enumeration Type Documentation

Enum for return values of USB_Host_GetNextDescriptorComp()

Enumerator:
Descriptor_Search_Comp_Found  Configuration descriptor now points to decriptor 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 made with DESCRIPTOR_COMPARATOR.

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_Host_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

static void static void USB_Host_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

void USB_Host_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_Host_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_Host_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 Wed Dec 17 16:18:45 2008 for LUFA Library by  doxygen 1.5.7.1