LUFA Library
Copyright (C) Dean Camera, 2020.
dean [at] fourwalledcubicle [dot] com
www.lufa-lib.org
*/
Copyright 2020 Dean Camera (dean [at] fourwalledcubicle [dot] com)
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 disclaims all warranties with regard to this
software, including all implied warranties of merchantability
and fitness. In no event shall the author be liable for any
special, indirect or consequential damages or any damages
whatsoever resulting from loss of use, data or profits, whether
in an action of contract, negligence or other tortious action,
arising out of or in connection with the use or performance of
this software.
*/
* \brief Common standard USB Descriptor definitions for all architectures.
* \copydetails Group_StdDescriptors
*
* \note This file should not be included directly. It is automatically included as needed by the USB driver
* dispatch header located in LUFA/Drivers/USB/USB.h.
*/
* \defgroup Group_StdDescriptors USB Descriptors
* \brief Standard USB Descriptor definitions.
*
* 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.
*
* @{
*/
#ifndef __USBDESCRIPTORS_H__
#define __USBDESCRIPTORS_H__
#define ATTR_PACKED __packed
#define CPU_TO_LE16(x) (x)
#if defined(__cplusplus)
extern "C" {
#endif
* for string descriptor indexes, or may be use as a return value for GetDescriptor when the specified
* descriptor does not exist.
*/
#define NO_DESCRIPTOR 0
*
* \param[in] mA Maximum number of milliamps the device consumes when the given configuration is selected.
*/
#define USB_CONFIG_POWER_MA(mA) ((mA) >> 1)
* Should be used in string descriptor's headers for giving the string descriptor's byte length.
*
* \param[in] UnicodeChars Number of Unicode characters in the string text.
*/
#define USB_STRING_LEN(UnicodeChars) (sizeof(USB_Descriptor_Header_t) + ((UnicodeChars) << 1))
*
* \note This macro is for little-endian systems only.
*
* \param[in] String String to initialize a USB String Descriptor structure with.
*/
#define USB_STRING_DESCRIPTOR(String) { .Header = {.Size = sizeof(USB_Descriptor_Header_t) + (sizeof(String) - 2), .Type = DTYPE_String}, .UnicodeString = String }
*
* \param[in] ... Characters to initialize a USB String Descriptor structure with.
*/
#define USB_STRING_DESCRIPTOR_ARRAY(...) { .Header = {.Size = sizeof(USB_Descriptor_Header_t) + sizeof((uint16_t[]){__VA_ARGS__}), .Type = DTYPE_String}, .UnicodeString = {__VA_ARGS__} }
* fields requiring BCD encoding, such as the USB version number in the standard device descriptor.
*
* \note This value is automatically converted into Little Endian, suitable for direct use inside device
* descriptors on all architectures without endianness conversion macros.
*
* \param[in] Major Major version number to encode.
* \param[in] Minor Minor version number to encode.
* \param[in] Revision Revision version number to encode.
*/
#define VERSION_BCD(Major, Minor, Revision) \
CPU_TO_LE16( ((Major & 0xFF) << 8) | \
((Minor & 0x0F) << 4) | \
(Revision & 0x0F) )
* to indicate that the English language is supported by the device in its string descriptors.
*/
#define LANGUAGE_ID_ENG 0x0409
* set on all USB devices for historical purposes.
*/
#define USB_CONFIG_ATTR_RESERVED 0x80
* descriptor's \c ConfigAttributes value to indicate that the specified configuration can draw its power
* from the device's own power source, instead of drawing it from the USB host.
*
* Note that the host will probe this dynamically - the device should report its current power state via the
* \ref USB_Device_CurrentlySelfPowered global variable.
*/
#define USB_CONFIG_ATTR_SELFPOWERED 0x40
* descriptor's \c ConfigAttributes value to indicate that the specified configuration supports the
* remote wakeup feature of the USB standard, allowing a suspended USB device to wake up the host upon
* request.
*
* If set, the host will dynamically enable and disable remote wakeup support, indicated via the
* \ref USB_Device_RemoteWakeupEnabled global variable. To initiate a remote wakeup of the host (when allowed)
* see \ref USB_Device_RemoteWakeupEnabled().
*/
#define USB_CONFIG_ATTR_REMOTEWAKEUP 0x20
* \c Attributes value to indicate that the specified endpoint is not synchronized.
*
* \see The USB specification for more details on the possible Endpoint attributes.
*/
#define ENDPOINT_ATTR_NO_SYNC (0 << 2)
* \c Attributes value to indicate that the specified endpoint is asynchronous.
*
* \see The USB specification for more details on the possible Endpoint attributes.
*/
#define ENDPOINT_ATTR_ASYNC (1 << 2)
* \c Attributes value to indicate that the specified endpoint is adaptive.
*
* \see The USB specification for more details on the possible Endpoint attributes.
*/
#define ENDPOINT_ATTR_ADAPTIVE (2 << 2)
* \c Attributes value to indicate that the specified endpoint is synchronized.
*
* \see The USB specification for more details on the possible Endpoint attributes.
*/
#define ENDPOINT_ATTR_SYNC (3 << 2)
* \c Attributes value to indicate that the specified endpoint is used for data transfers.
*
* \see The USB specification for more details on the possible Endpoint usage attributes.
*/
#define ENDPOINT_USAGE_DATA (0 << 4)
* \c Attributes value to indicate that the specified endpoint is used for feedback.
*
* \see The USB specification for more details on the possible Endpoint usage attributes.
*/
#define ENDPOINT_USAGE_FEEDBACK (1 << 4)
* \c Attributes value to indicate that the specified endpoint is used for implicit feedback.
*
* \see The USB specification for more details on the possible Endpoint usage attributes.
*/
#define ENDPOINT_USAGE_IMPLICIT_FEEDBACK (2 << 4)
enum USB_DescriptorTypes_t
{
DTYPE_Device = 0x01,
DTYPE_Configuration = 0x02,
DTYPE_String = 0x03,
DTYPE_Interface = 0x04,
DTYPE_Endpoint = 0x05,
DTYPE_DeviceQualifier = 0x06,
DTYPE_Other = 0x07,
DTYPE_InterfacePower = 0x08,
DTYPE_InterfaceAssociation = 0x0B,
};
enum USB_Descriptor_ClassSubclassProtocol_t
{
USB_CSCP_NoDeviceClass = 0x00,
* to a particular class at the device level.
*/
USB_CSCP_NoDeviceSubclass = 0x00,
* to a particular subclass at the device level.
*/
USB_CSCP_NoDeviceProtocol = 0x00,
* to a particular protocol at the device level.
*/
USB_CSCP_VendorSpecificClass = 0xFF,
* to a vendor specific class.
*/
USB_CSCP_VendorSpecificSubclass = 0xFF,
* to a vendor specific subclass.
*/
USB_CSCP_VendorSpecificProtocol = 0xFF,
* to a vendor specific protocol.
*/
USB_CSCP_IADDeviceClass = 0xEF,
* Interface Association Descriptor class.
*/
USB_CSCP_IADDeviceSubclass = 0x02,
* Interface Association Descriptor subclass.
*/
USB_CSCP_IADDeviceProtocol = 0x01,
* Interface Association Descriptor protocol.
*/
};
*
* 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.
*
* \see \ref USB_StdDescriptor_Header_t for the version of this type with standard element names.
*
* \note Regardless of CPU architecture, these values should be stored as little endian.
*/
typedef struct
{
uint8_t Size;
uint8_t Type;
* given by the specific class.
*/
} ATTR_PACKED USB_Descriptor_Header_t;
*
* 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.
*
* \see \ref USB_Descriptor_Header_t for the version of this type with non-standard LUFA specific element names.
*
* \note Regardless of CPU architecture, these values should be stored as little endian.
*/
typedef struct
{
uint8_t bLength;
uint8_t bDescriptorType;
* given by the specific class.
*/
} ATTR_PACKED 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 type with standard element names.
*
* \note Regardless of CPU architecture, these values should be stored as little endian.
*/
typedef struct
{
USB_Descriptor_Header_t Header;
uint16_t USBSpecification;
*
* \see \ref VERSION_BCD() utility macro.
*/
uint8_t Class;
uint8_t SubClass;
uint8_t Protocol;
uint8_t Endpoint0Size;
uint16_t VendorID;
uint16_t ProductID;
uint16_t ReleaseNumber;
*
* \see \ref VERSION_BCD() utility macro.
*/
uint8_t ManufacturerStrIndex;
* 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 ProductStrIndex;
*
* \see ManufacturerStrIndex structure entry.
*/
uint8_t SerialNumStrIndex;
* serial number, in uppercase Unicode ASCII.
*
* \note On some microcontroller 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 \c USE_INTERNAL_SERIAL.
* On unsupported devices, this will evaluate to \ref NO_DESCRIPTOR
* and will cause the host to generate a pseudo-unique value for the
* device upon insertion.
*
* \see \c ManufacturerStrIndex structure entry.
*/
uint8_t NumberOfConfigurations;
* the device.
*/
} ATTR_PACKED USB_Descriptor_Device_t;
*
* 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 type with non-standard LUFA specific element names.
*
* \note Regardless of CPU architecture, these values should be stored as little endian.
*/
typedef struct
{
uint8_t bLength;
uint8_t bDescriptorType;
* given by the specific class.
*/
uint16_t bcdUSB;
*
* \see \ref VERSION_BCD() utility macro.
*/
uint8_t bDeviceClass;
uint8_t bDeviceSubClass;
uint8_t bDeviceProtocol;
uint8_t bMaxPacketSize0;
uint16_t idVendor;
uint16_t idProduct;
uint16_t bcdDevice;
*
* \see \ref VERSION_BCD() utility macro.
*/
uint8_t iManufacturer;
* 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;
*
* \see ManufacturerStrIndex structure entry.
*/
uint8_t iSerialNumber;
* serial number, in uppercase Unicode ASCII.
*
* \note On some microcontroller 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 \c USE_INTERNAL_SERIAL.
* On unsupported devices, this will evaluate to \ref NO_DESCRIPTOR
* and will cause the host to generate a pseudo-unique value for the
* device upon insertion.
*
* \see \c ManufacturerStrIndex structure entry.
*/
uint8_t bNumConfigurations;
* the device.
*/
} ATTR_PACKED USB_StdDescriptor_Device_t;
*
* Type define for a standard Device Qualifier Descriptor. This structure uses LUFA-specific element names
* to make each element's purpose clearer.
*
* \see \ref USB_StdDescriptor_DeviceQualifier_t for the version of this type with standard element names.
*/
typedef struct
{
USB_Descriptor_Header_t Header;
uint16_t USBSpecification;
*
* \see \ref VERSION_BCD() utility macro.
*/
uint8_t Class;
uint8_t SubClass;
uint8_t Protocol;
uint8_t Endpoint0Size;
uint8_t NumberOfConfigurations;
* the device.
*/
uint8_t Reserved;
} ATTR_PACKED USB_Descriptor_DeviceQualifier_t;
*
* Type define for a standard Device Qualifier Descriptor. This structure uses the relevant standard's given element names
* to ensure compatibility with the standard.
*
* \see \ref USB_Descriptor_DeviceQualifier_t for the version of this type with non-standard LUFA specific element names.
*/
typedef struct
{
uint8_t bLength;
uint8_t bDescriptorType;
* given by the specific class.
*/
uint16_t bcdUSB;
*
* \see \ref VERSION_BCD() utility macro.
*/
uint8_t bDeviceClass;
uint8_t bDeviceSubClass;
uint8_t bDeviceProtocol;
uint8_t bMaxPacketSize0;
uint8_t bNumConfigurations;
* the device.
*/
uint8_t bReserved;
} ATTR_PACKED USB_StdDescriptor_DeviceQualifier_t;
*
* Type define for a standard Configuration Descriptor header. This structure uses LUFA-specific element names
* to make each element's purpose clearer.
*
* \see \ref USB_StdDescriptor_Configuration_Header_t for the version of this type with standard element names.
*
* \note Regardless of CPU architecture, these values should be stored as little endian.
*/
typedef struct
{
USB_Descriptor_Header_t Header;
uint16_t TotalConfigurationSize;
* and all sub descriptors inside the configuration.
*/
uint8_t TotalInterfaces;
uint8_t ConfigurationNumber;
uint8_t ConfigurationStrIndex;
uint8_t ConfigAttributes;
* On all devices, this should include USB_CONFIG_ATTR_RESERVED at a minimum.
*/
uint8_t MaxPowerConsumption;
* current configuration, calculated by the \ref USB_CONFIG_POWER_MA()
* macro.
*/
} ATTR_PACKED USB_Descriptor_Configuration_Header_t;
*
* 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 type with non-standard LUFA specific element names.
*
* \note Regardless of CPU architecture, these values should be stored as little endian.
*/
typedef struct
{
uint8_t bLength;
uint8_t bDescriptorType;
* given by the specific class.
*/
uint16_t wTotalLength;
* and all sub descriptors inside the configuration.
*/
uint8_t bNumInterfaces;
uint8_t bConfigurationValue;
uint8_t iConfiguration;
uint8_t bmAttributes;
* On all devices, this should include USB_CONFIG_ATTR_RESERVED at a minimum.
*/
uint8_t bMaxPower;
* current configuration, calculated by the \ref USB_CONFIG_POWER_MA()
* macro.
*/
} ATTR_PACKED 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.
*
* \see \ref USB_StdDescriptor_Interface_t for the version of this type with standard element names.
*
* \note Regardless of CPU architecture, these values should be stored as little endian.
*/
typedef struct
{
USB_Descriptor_Header_t Header;
uint8_t InterfaceNumber;
uint8_t AlternateSetting;
* interface number can have multiple alternate settings
* with different endpoint configurations, which can be
* selected by the host.
*/
uint8_t TotalEndpoints;
uint8_t Class;
uint8_t SubClass;
uint8_t Protocol;
uint8_t InterfaceStrIndex;
} ATTR_PACKED USB_Descriptor_Interface_t;
*
* 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 type with non-standard LUFA specific element names.
*
* \note Regardless of CPU architecture, these values should be stored as little endian.
*/
typedef struct
{
uint8_t bLength;
uint8_t bDescriptorType;
* given by the specific class.
*/
uint8_t bInterfaceNumber;
uint8_t bAlternateSetting;
* interface number can have multiple alternate settings
* with different endpoint configurations, which can be
* selected by the host.
*/
uint8_t bNumEndpoints;
uint8_t bInterfaceClass;
uint8_t bInterfaceSubClass;
uint8_t bInterfaceProtocol;
uint8_t iInterface;
* interface.
*/
} ATTR_PACKED 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
* <a>http://www.usb.org/developers/docs/InterfaceAssociationDescriptor_ecn.pdf</a>. It allows composite
* 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_StdDescriptor_Interface_Association_t for the version of this type with standard element names.
*
* \note Regardless of CPU architecture, these values should be stored as little endian.
*/
typedef struct
{
USB_Descriptor_Header_t Header;
uint8_t FirstInterfaceIndex;
uint8_t TotalInterfaces;
uint8_t Class;
uint8_t SubClass;
uint8_t Protocol;
uint8_t IADStrIndex;
* interface association.
*/
} ATTR_PACKED USB_Descriptor_Interface_Association_t;
*
* 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 composite
* 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 type with non-standard LUFA specific
* element names.
*
* \note Regardless of CPU architecture, these values should be stored as little endian.
*/
typedef struct
{
uint8_t bLength;
uint8_t bDescriptorType;
* given by the specific class.
*/
uint8_t bFirstInterface;
uint8_t bInterfaceCount;
uint8_t bFunctionClass;
uint8_t bFunctionSubClass;
uint8_t bFunctionProtocol;
uint8_t iFunction;
* interface association.
*/
} ATTR_PACKED 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.
*
* \see \ref USB_StdDescriptor_Endpoint_t for the version of this type with standard element names.
*
* \note Regardless of CPU architecture, these values should be stored as little endian.
*/
typedef struct
{
USB_Descriptor_Header_t Header;
uint8_t EndpointAddress;
* configuration, including direction mask.
*/
uint8_t Attributes;
* and attributes (ENDPOINT_ATTR_*) masks.
*/
uint16_t EndpointSize;
* size that the endpoint can receive at a time.
*/
uint8_t PollingIntervalMS;
* or ISOCHRONOUS type.
*/
} ATTR_PACKED 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 type with non-standard LUFA specific
* element names.
*
* \note Regardless of CPU architecture, these values should be stored as little endian.
*/
typedef struct
{
uint8_t bLength;
uint8_t bDescriptorType;
* value given by the specific class.
*/
uint8_t bEndpointAddress;
* configuration, including direction mask.
*/
uint8_t bmAttributes;
* and attributes (ENDPOINT_ATTR_*) masks.
*/
uint16_t wMaxPacketSize;
* that the endpoint can receive at a time.
*/
uint8_t bInterval;
* ISOCHRONOUS type.
*/
} ATTR_PACKED USB_StdDescriptor_Endpoint_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 LUFA-specific element names to make each element's purpose clearer.
*
* \see \ref USB_StdDescriptor_String_t for the version of this type with standard element names.
*
* \note Regardless of CPU architecture, these values should be stored as little endian.
*/
typedef struct
{
USB_Descriptor_Header_t Header;
#if (((ARCH == ARCH_AVR8) || (ARCH == ARCH_XMEGA)) && !defined(__DOXYGEN__))
wchar_t UnicodeString[];
#else
uint16_t UnicodeString[];
* 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 on little endian devices with
* UTF-16-LE \c wchar_t encoding.
*/
#endif
} ATTR_PACKED 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 type with with non-standard LUFA specific
* element names.
*
* \note Regardless of CPU architecture, these values should be stored as little endian.
*/
typedef struct
{
uint8_t bLength;
uint8_t bDescriptorType;
* or a value given by the specific class.
*/
uint16_t bString[];
* 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.
*/
} ATTR_PACKED USB_StdDescriptor_String_t;
#if defined(__cplusplus)
}
#endif
#endif