@ -34,16 +34,6 @@
* Standard USB device descriptor defines and retrieval routines , for USB devices . This module contains
* Standard USB device descriptor defines and retrieval routines , for USB devices . This module contains
* structures and macros for the easy creation of standard USB descriptors in USB device projects .
* structures and macros for the easy creation of standard USB descriptors in USB device projects .
*
*
* All standard descriptors have their elements named in an identical manner to the official USB specification ,
* however slightly more verbose alternate ( non - standard ) names are also supplied if the macro
* USE_NONSTANDARD_DESCRIPTOR_NAMES is defined in the user project makefile and passed to the compiler at
* compilation time using the - D option .
*
* The non - standard names are documented here - if USE_NONSTANDARD_DESCRIPTOR_NAMES is not defined , then all
* descriptors will contain elements named identically to the official USB specification . The alternately
* named descriptor elements are placed in the same order inside the descriptor structures as their officially
* named counterparts , thus they can be correlated easily with the official USB specification .
*
* @ {
* @ {
*/
*/
@ -206,34 +196,39 @@
} ;
} ;
/* Type Defines: */
/* Type Defines: */
/** Type define for all descriptor's header, indicating the descriptor's length and type.
/** Type define for all descriptors standard header, indicating the descriptor's length and type. This structure
* uses LUFA - specific element names to make each element ' s purpose clearer .
*
*
* \ note The non - standard structure element names are documented here . If the
* \ see \ ref USB_StdDescriptor_Header_t for the version of this define with standard element names
* USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set , this structure contains elements
* with names identical to those listed in the USB standard .
*/
*/
typedef struct
typedef struct
{
{
# if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__)
uint8_t Size ; /**< Size of the descriptor, in bytes. */
uint8_t Size ; /**< Size of the descriptor, in bytes. */
uint8_t Type ; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value
uint8_t Type ; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value
* given by the specific class .
* given by the specific class .
*/
*/
# else
uint8_t bLength ;
uint8_t bDescriptorType ;
# endif
} USB_Descriptor_Header_t ;
} USB_Descriptor_Header_t ;
/** Type define for a standard device descriptor.
/** Type define for all descriptors standard header, indicating the descriptor's length and type. This structure
* uses the relevant standard ' s given element names to ensure compatibility with the standard .
*
*
* \ note The non - standard structure element names are documented here . If the
* \ see \ ref USB_Descriptor_Header_t for the version of this define with non - standard LUFA specific element names
* USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set , this structure contains elements
*/
* with names identical to those listed in the USB standard .
typedef struct
{
uint8_t bLength ; /**< Size of the descriptor, in bytes. */
uint8_t bDescriptorType ; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value
* given by the specific class .
*/
} USB_StdDescriptor_Header_t ;
/** Type define for a standard Device Descriptor. This structure uses LUFA-specific element names to make each
* element ' s purpose clearer .
*
* \ see \ ref USB_StdDescriptor_Device_t for the version of this define with standard element names
*/
*/
typedef struct
typedef struct
{
{
# if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__)
USB_Descriptor_Header_t Header ; /**< Descriptor header, including type and size. */
USB_Descriptor_Header_t Header ; /**< Descriptor header, including type and size. */
uint16_t USBSpecification ; /**< BCD of the supported USB specification. */
uint16_t USBSpecification ; /**< BCD of the supported USB specification. */
@ -269,37 +264,64 @@
*
*
* \ see ManufacturerStrIndex structure entry .
* \ see ManufacturerStrIndex structure entry .
*/
*/
uint8_t NumberOfConfigurations ; /**< Total number of configurations supported by
uint8_t NumberOfConfigurations ; /**< Total number of configurations supported by
* the device .
* the device .
*/
*/
# else
uint8_t bLength ;
uint8_t bDescriptorType ;
uint16_t bcdUSB ;
uint8_t bDeviceClass ;
uint8_t bDeviceSubClass ;
uint8_t bDeviceProtocol ;
uint8_t bMaxPacketSize0 ;
uint16_t idVendor ;
uint16_t idProduct ;
uint16_t bcdDevice ;
uint8_t iManufacturer ;
uint8_t iProduct ;
uint8_t iSerialNumber ;
uint8_t bNumConfigurations ;
# endif
} USB_Descriptor_Device_t ;
} USB_Descriptor_Device_t ;
/** Type define for a standard configuration descriptor.
/** Type define for a standard Device Descriptor. This structure uses the relevant standard's given element names
* to ensure compatibility with the standard .
*
* \ see \ ref USB_Descriptor_Device_t for the version of this define with non - standard LUFA specific element names
*/
typedef struct
{
uint8_t bLength ; /**< Size of the descriptor, in bytes. */
uint8_t bDescriptorType ; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value
* given by the specific class .
*/
uint16_t bcdUSB ; /**< BCD of the supported USB specification. */
uint8_t bDeviceClass ; /**< USB device class. */
uint8_t bDeviceSubClass ; /**< USB device subclass. */
uint8_t bDeviceProtocol ; /**< USB device protocol. */
uint8_t bMaxPacketSize0 ; /**< Size of the control (address 0) endpoint's bank in bytes. */
uint16_t idVendor ; /**< Vendor ID for the USB product. */
uint16_t idProduct ; /**< Unique product ID for the USB product. */
uint16_t bcdDevice ; /**< Product release (version) number. */
uint8_t iManufacturer ; /**< String index for the manufacturer's name. The
* host will request this string via a separate
* control request for the string descriptor .
*
* \ note If no string supplied , use \ ref NO_DESCRIPTOR .
*/
uint8_t iProduct ; /**< String index for the product name/details.
*
* \ see ManufacturerStrIndex structure entry .
*/
uint8_t iSerialNumber ; /**< String index for the product's globally unique hexadecimal
* serial number , in uppercase Unicode ASCII .
*
* \ note On some AVR models , there is an embedded serial number
* in the chip which can be used for the device serial number .
* To use this serial number , set this to USE_INTERNAL_SERIAL .
* On unsupported devices , this will evaluate to 0 and will cause
* the host to generate a pseudo - unique value for the device upon
* insertion .
*
* \ see ManufacturerStrIndex structure entry .
*/
uint8_t bNumConfigurations ; /**< Total number of configurations supported by
* the device .
*/
} USB_StdDescriptor_Device_t ;
/** Type define for a standard Configuration Descriptor header. This structure uses LUFA-specific element names
* to make each element ' s purpose clearer .
*
*
* \ note The non - standard structure element names are documented here . If the
* \ see \ ref USB_StdDescriptor_Configuration_Header_t for the version of this define with standard element names
* USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set , this structure contains elements
* with names identical to those listed in the USB standard .
*/
*/
typedef struct
typedef struct
{
{
# if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__)
USB_Descriptor_Header_t Header ; /**< Descriptor header, including type and size. */
USB_Descriptor_Header_t Header ; /**< Descriptor header, including type and size. */
uint16_t TotalConfigurationSize ; /**< Size of the configuration descriptor header,
uint16_t TotalConfigurationSize ; /**< Size of the configuration descriptor header,
@ -318,27 +340,41 @@
* current configuration , calculated by the \ ref USB_CONFIG_POWER_MA ( )
* current configuration , calculated by the \ ref USB_CONFIG_POWER_MA ( )
* macro .
* macro .
*/
*/
# else
uint8_t bLength ;
uint8_t bDescriptorType ;
uint16_t wTotalLength ;
uint8_t bNumInterfaces ;
uint8_t bConfigurationValue ;
uint8_t iConfiguration ;
uint8_t bmAttributes ;
uint8_t bMaxPower ;
# endif
} USB_Descriptor_Configuration_Header_t ;
} USB_Descriptor_Configuration_Header_t ;
/** Type define for a standard interface descriptor.
/** Type define for a standard Configuration Descriptor header. This structure uses the relevant standard's given element names
* to ensure compatibility with the standard .
*
* \ see \ ref USB_Descriptor_Device_t for the version of this define with non - standard LUFA specific element names
*/
typedef struct
{
uint8_t bLength ; /**< Size of the descriptor, in bytes. */
uint8_t bDescriptorType ; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value
* given by the specific class .
*/
uint16_t wTotalLength ; /**< Size of the configuration descriptor header,
* and all sub descriptors inside the configuration .
*/
uint8_t bNumInterfaces ; /**< Total number of interfaces in the configuration. */
uint8_t bConfigurationValue ; /**< Configuration index of the current configuration. */
uint8_t iConfiguration ; /**< Index of a string descriptor describing the configuration. */
uint8_t bmAttributes ; /**< Configuration attributes, comprised of a mask of zero or
* more USB_CONFIG_ATTR_ * masks .
*/
uint8_t bMaxPower ; /**< Maximum power consumption of the device while in the
* current configuration , calculated by the \ ref USB_CONFIG_POWER_MA ( )
* macro .
*/
} USB_StdDescriptor_Configuration_Header_t ;
/** Type define for a standard Interface Descriptor. This structure uses LUFA-specific element names
* to make each element ' s purpose clearer .
*
*
* \ note The non - standard structure element names are documented here . If the
* \ see \ ref USB_StdDescriptor_Interface_t for the version of this define with standard element names
* USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set , this structure contains elements
* with names identical to those listed in the USB standard .
*/
*/
typedef struct
typedef struct
{
{
# if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__)
USB_Descriptor_Header_t Header ; /**< Descriptor header, including type and size. */
USB_Descriptor_Header_t Header ; /**< Descriptor header, including type and size. */
uint8_t InterfaceNumber ; /**< Index of the interface in the current configuration. */
uint8_t InterfaceNumber ; /**< Index of the interface in the current configuration. */
@ -356,20 +392,36 @@
uint8_t InterfaceStrIndex ; /**< Index of the string descriptor describing the
uint8_t InterfaceStrIndex ; /**< Index of the string descriptor describing the
* interface .
* interface .
*/
*/
# else
uint8_t bLength ;
uint8_t bDescriptorType ;
uint8_t bInterfaceNumber ;
uint8_t bAlternateSetting ;
uint8_t bNumEndpoints ;
uint8_t bInterfaceClass ;
uint8_t bInterfaceSubClass ;
uint8_t bInterfaceProtocol ;
uint8_t iInterface ;
# endif
} USB_Descriptor_Interface_t ;
} USB_Descriptor_Interface_t ;
/** Type define for a standard Interface Association descriptor.
/** Type define for a standard Interface Descriptor. This structure uses the relevant standard's given element names
* to ensure compatibility with the standard .
*
* \ see \ ref USB_Descriptor_Interface_t for the version of this define with non - standard LUFA specific element names
*/
typedef struct
{
uint8_t bLength ; /**< Size of the descriptor, in bytes. */
uint8_t bDescriptorType ; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value
* given by the specific class .
*/
uint8_t bInterfaceNumber ; /**< Index of the interface in the current configuration. */
uint8_t bAlternateSetting ; /**< Alternate setting for the interface number. The same
* interface number can have multiple alternate settings
* with different endpoint configurations , which can be
* selected by the host .
*/
uint8_t bNumEndpoints ; /**< Total number of endpoints in the interface. */
uint8_t bInterfaceClass ; /**< Interface class ID. */
uint8_t bInterfaceSubClass ; /**< Interface subclass ID. */
uint8_t bInterfaceProtocol ; /**< Interface protocol ID. */
uint8_t iInterface ; /**< Index of the string descriptor describing the
* interface .
*/
} USB_StdDescriptor_Interface_t ;
/** Type define for a standard Interface Association Descriptor. This structure uses LUFA-specific element names
* to make each element ' s purpose clearer .
*
*
* This descriptor has been added as a supplement to the USB2 .0 standard , in the ECN located at
* This descriptor has been added as a supplement to the USB2 .0 standard , in the ECN located at
* < a > http : //www.usb.org/developers/docs/InterfaceAssociationDescriptor_ecn.pdf</a>. It allows compound
* < a > http : //www.usb.org/developers/docs/InterfaceAssociationDescriptor_ecn.pdf</a>. It allows compound
@ -377,13 +429,10 @@
* together at the point of enumeration , loading one generic driver for all the interfaces in the single
* together at the point of enumeration , loading one generic driver for all the interfaces in the single
* function . Read the ECN for more information .
* function . Read the ECN for more information .
*
*
* \ note The non - standard structure element names are documented here . If the
* \ see \ ref USB_StdDescriptor_Interface_Association_t for the version of this define with standard element names
* USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set , this structure contains elements
* with names identical to those listed in the USB standard .
*/
*/
typedef struct
typedef struct
{
{
# if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__)
USB_Descriptor_Header_t Header ; /**< Descriptor header, including type and size. */
USB_Descriptor_Header_t Header ; /**< Descriptor header, including type and size. */
uint8_t FirstInterfaceIndex ; /**< Index of the first associated interface. */
uint8_t FirstInterfaceIndex ; /**< Index of the first associated interface. */
@ -396,27 +445,43 @@
uint8_t IADStrIndex ; /**< Index of the string descriptor describing the
uint8_t IADStrIndex ; /**< Index of the string descriptor describing the
* interface association .
* interface association .
*/
*/
# else
uint8_t bLength ;
uint8_t bDescriptorType ;
uint8_t bFirstInterface ;
uint8_t bInterfaceCount ;
uint8_t bFunctionClass ;
uint8_t bFunctionSubClass ;
uint8_t bFunctionProtocol ;
uint8_t iFunction ;
# endif
} USB_Descriptor_Interface_Association_t ;
} USB_Descriptor_Interface_Association_t ;
/** Type define for a standard endpoint descriptor.
/** Type define for a standard Interface Association Descriptor. This structure uses the relevant standard's given
* element names to ensure compatibility with the standard .
*
* This descriptor has been added as a supplement to the USB2 .0 standard , in the ECN located at
* < a > http : //www.usb.org/developers/docs/InterfaceAssociationDescriptor_ecn.pdf</a>. It allows compound
* devices with multiple interfaces related to the same function to have the multiple interfaces bound
* together at the point of enumeration , loading one generic driver for all the interfaces in the single
* function . Read the ECN for more information .
*
* \ see \ ref USB_Descriptor_Interface_Association_t for the version of this define with non - standard LUFA specific
* element names
*/
typedef struct
{
uint8_t bLength ; /**< Size of the descriptor, in bytes. */
uint8_t bDescriptorType ; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value
* given by the specific class .
*/
uint8_t bFirstInterface ; /**< Index of the first associated interface. */
uint8_t bInterfaceCount ; /** Total number of associated interfaces. */
uint8_t bFunctionClass ; /**< Interface class ID. */
uint8_t bFunctionSubClass ; /**< Interface subclass ID. */
uint8_t bFunctionProtocol ; /**< Interface protocol ID. */
uint8_t iFunction ; /**< Index of the string descriptor describing the
* interface association .
*/
} USB_StdDescriptor_Interface_Association_t ;
/** Type define for a standard Endpoint Descriptor. This structure uses LUFA-specific element names
* to make each element ' s purpose clearer .
*
*
* \ note The non - standard structure element names are documented here . If the
* \ see \ ref USB_StdDescriptor_Endpoint_t for the version of this define with standard element names
* USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set , this structure contains elements
* with names identical to those listed in the USB standard .
*/
*/
typedef struct
typedef struct
{
{
# if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__)
USB_Descriptor_Header_t Header ; /**< Descriptor header, including type and size. */
USB_Descriptor_Header_t Header ; /**< Descriptor header, including type and size. */
uint8_t EndpointAddress ; /**< Logical address of the endpoint within the device
uint8_t EndpointAddress ; /**< Logical address of the endpoint within the device
@ -434,16 +499,36 @@
uint8_t PollingIntervalMS ; /**< Polling interval in milliseconds for the endpoint
uint8_t PollingIntervalMS ; /**< Polling interval in milliseconds for the endpoint
* if it is an INTERRUPT or ISOCHRONOUS type .
* if it is an INTERRUPT or ISOCHRONOUS type .
*/
*/
# else
uint8_t bLength ;
uint8_t bDescriptorType ;
uint8_t bEndpointAddress ;
uint8_t bmAttributes ;
uint16_t wMaxPacketSize ;
uint8_t bInterval ;
# endif
} USB_Descriptor_Endpoint_t ;
} USB_Descriptor_Endpoint_t ;
/** Type define for a standard Endpoint Descriptor. This structure uses the relevant standard's given
* element names to ensure compatibility with the standard .
*
* \ see \ ref USB_Descriptor_Endpoint_t for the version of this define with non - standard LUFA specific
* element names
*/
typedef struct
{
uint8_t bLength ; /**< Size of the descriptor, in bytes. */
uint8_t bDescriptorType ; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value
* given by the specific class .
*/
uint8_t bEndpointAddress ; /**< Logical address of the endpoint within the device
* for the current configuration , including direction
* mask .
*/
uint8_t bmAttributes ; /**< Endpoint attributes, comprised of a mask of the
* endpoint type ( EP_TYPE_ * ) and attributes ( ENDPOINT_ATTR_ * )
* masks .
*/
uint16_t wMaxPacketSize ; /**< Size of the endpoint bank, in bytes. This indicates the
* maximum packet size that the endpoint can receive at a time .
*/
uint8_t bInterval ; /**< Polling interval in milliseconds for the endpoint
* if it is an INTERRUPT or ISOCHRONOUS type .
*/
} USB_StdDescriptor_Endpoint_t ;
/** Type define for a standard string descriptor. Unlike other standard descriptors, the length
/** Type define for a standard string descriptor. Unlike other standard descriptors, the length
* of the descriptor for placement in the descriptor header must be determined by the \ ref USB_STRING_LEN ( )
* of the descriptor for placement in the descriptor header must be determined by the \ ref USB_STRING_LEN ( )
* macro rather than by the size of the descriptor structure , as the length is not fixed .
* macro rather than by the size of the descriptor structure , as the length is not fixed .
@ -451,13 +536,12 @@
* This structure should also be used for string index 0 , which contains the supported language IDs for
* This structure should also be used for string index 0 , which contains the supported language IDs for
* the device as an array .
* the device as an array .
*
*
* \ note The non - standard structure element names are documented here . If the
* This structure uses LUFA - specific element names to make each element ' s purpose clearer .
* USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set , this structure contains elements
*
* with names identical to those listed in the USB standard .
* \ see \ ref USB_StdDescriptor_String_t for the version of this define with standard element names
*/
*/
typedef struct
typedef struct
{
{
# if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__)
USB_Descriptor_Header_t Header ; /**< Descriptor header, including type and size. */
USB_Descriptor_Header_t Header ; /**< Descriptor header, including type and size. */
int16_t UnicodeString [ ] ; /**< String data, as unicode characters (alternatively,
int16_t UnicodeString [ ] ; /**< String data, as unicode characters (alternatively,
@ -471,13 +555,40 @@
* Unicode strings , and may be used instead of an explicit
* Unicode strings , and may be used instead of an explicit
* array of ASCII characters .
* array of ASCII characters .
*/
*/
# else
uint8_t bLength ;
uint8_t bDescriptorType ;
int16_t bString [ ] ;
# endif
} USB_Descriptor_String_t ;
} USB_Descriptor_String_t ;
/** Type define for a standard string descriptor. Unlike other standard descriptors, the length
* of the descriptor for placement in the descriptor header must be determined by the \ ref USB_STRING_LEN ( )
* macro rather than by the size of the descriptor structure , as the length is not fixed .
*
* This structure should also be used for string index 0 , which contains the supported language IDs for
* the device as an array .
*
* This structure uses the relevant standard ' s given element names to ensure compatibility with the standard .
*
* \ see \ ref USB_Descriptor_String_t for the version of this define with with non - standard LUFA specific
* element names
*/
typedef struct
{
uint8_t bLength ; /**< Size of the descriptor, in bytes. */
uint8_t bDescriptorType ; /**< Type of the descriptor, either a value in
* \ ref USB_DescriptorTypes_t or a value
* given by the specific class .
*/
int16_t bString [ ] ; /**< String data, as unicode characters (alternatively,
* string language IDs ) . If normal ASCII characters are
* to be used , they must be added as an array of characters
* rather than a normal C string so that they are widened to
* Unicode size .
*
* Under GCC , strings prefixed with the " L " character ( before
* the opening string quotation mark ) are considered to be
* Unicode strings , and may be used instead of an explicit
* array of ASCII characters .
*/
} USB_StdDescriptor_String_t ;
/* Private Interface - For use in library only: */
/* Private Interface - For use in library only: */
# if !defined(__DOXYGEN__)
# if !defined(__DOXYGEN__)
/* Macros: */
/* Macros: */
Dean Camera
15 years ago