X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/28a1ee29a1a200c8e8c76355a9036a7456425bc3..0da99447d3e88e83f9977501bee56af5c7aa56c0:/LUFA/Drivers/USB/Core/StdDescriptors.h diff --git a/LUFA/Drivers/USB/Core/StdDescriptors.h b/LUFA/Drivers/USB/Core/StdDescriptors.h index d2a9bee0e..031e01d28 100644 --- a/LUFA/Drivers/USB/Core/StdDescriptors.h +++ b/LUFA/Drivers/USB/Core/StdDescriptors.h @@ -1,13 +1,13 @@ /* LUFA Library - Copyright (C) Dean Camera, 2011. + Copyright (C) Dean Camera, 2012. dean [at] fourwalledcubicle [dot] com www.lufa-lib.org */ /* - Copyright 2011 Dean Camera (dean [at] fourwalledcubicle [dot] com) + Copyright 2012 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 @@ -54,10 +54,6 @@ #include "USBMode.h" #include "Events.h" - #if defined(USB_CAN_BE_DEVICE) - #include "Device.h" - #endif - /* Enable C linkage for C++ Compilers: */ #if defined(__cplusplus) extern "C" { @@ -76,118 +72,112 @@ */ #define NO_DESCRIPTOR 0 - /** Macro to calculate the power value for the configuration descriptor, from a given number of milliamperes. */ + /** Macro to calculate the power value for the configuration descriptor, from a given number of milliamperes. + * + * \param[in] mA Maximum number of milliamps the device consumes when the given configuration is selected. + */ #define USB_CONFIG_POWER_MA(mA) ((mA) >> 1) /** Macro to calculate the Unicode length of a string with a given number of Unicode characters. * 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(str) (sizeof(USB_Descriptor_Header_t) + ((str) << 1)) + #define USB_STRING_LEN(UnicodeChars) (sizeof(USB_Descriptor_Header_t) + ((UnicodeChars) << 1)) /** Macro to encode a given four digit floating point version number (e.g. 01.23) into Binary Coded * Decimal format for descriptor 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] x Version number to encode as a 16-bit little-endian number, as a floating point number. */ - #define VERSION_BCD(x) ((((VERSION_TENS(x) << 4) | VERSION_ONES(x)) << 8) | \ - ((VERSION_TENTHS(x) << 4) | VERSION_HUNDREDTHS(x))) + #define VERSION_BCD(x) CPU_TO_LE16((VERSION_TENS(x) << 12) | (VERSION_ONES(x) << 8) | \ + (VERSION_TENTHS(x) << 4) | (VERSION_HUNDREDTHS(x) << 0) ) /** String language ID for the English language. Should be used in \ref USB_Descriptor_String_t descriptors * to indicate that the English language is supported by the device in its string descriptors. */ #define LANGUAGE_ID_ENG 0x0409 - /** \name Endpoint Address Direction Masks */ - //@{ - /** Can be masked with an endpoint address for a \ref USB_Descriptor_Endpoint_t endpoint descriptor's - * EndpointAddress value to indicate to the host that the endpoint is of the IN direction (i.e, from - * device to host). - */ - #define ENDPOINT_DESCRIPTOR_DIR_IN 0x80 - - /** Can be masked with an endpoint address for a \ref USB_Descriptor_Endpoint_t endpoint descriptor's - * EndpointAddress value to indicate to the host that the endpoint is of the OUT direction (i.e, from - * host to device). - */ - #define ENDPOINT_DESCRIPTOR_DIR_OUT 0x00 - //@} - /** \name USB Configuration Descriptor Attribute Masks */ //@{ - /** Can be masked with other configuration descriptor attributes for a \ref USB_Descriptor_Configuration_Header_t - * descriptor's ConfigAttributes value to indicate that the specified configuration can draw its power - * from the host's VBUS line. + /** Mask for the reserved bit in the Configuration Descriptor's \c ConfigAttributes field, which must be set on all + * devices for historical purposes. */ - #define USB_CONFIG_ATTR_BUSPOWERED 0x80 + #define USB_CONFIG_ATTR_RESERVED 0x80 /** Can be masked with other configuration descriptor attributes for a \ref USB_Descriptor_Configuration_Header_t - * descriptor's ConfigAttributes value to indicate that the specified configuration can draw its power + * descriptor's \c ConfigAttributes value to indicate that the specified configuration can draw its power * from the device's own power source. */ #define USB_CONFIG_ATTR_SELFPOWERED 0x40 /** Can be masked with other configuration descriptor attributes for a \ref USB_Descriptor_Configuration_Header_t - * descriptor's ConfigAttributes value to indicate that the specified configuration supports the + * 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. */ #define USB_CONFIG_ATTR_REMOTEWAKEUP 0x20 //@} - + /** \name Endpoint Descriptor Attribute Masks */ //@{ /** Can be masked with other endpoint descriptor attributes for a \ref USB_Descriptor_Endpoint_t descriptor's - * Attributes value to indicate that the specified endpoint is not synchronized. + * \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) /** Can be masked with other endpoint descriptor attributes for a \ref USB_Descriptor_Endpoint_t descriptor's - * Attributes value to indicate that the specified endpoint is asynchronous. + * \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) /** Can be masked with other endpoint descriptor attributes for a \ref USB_Descriptor_Endpoint_t descriptor's - * Attributes value to indicate that the specified endpoint is adaptive. + * \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) /** Can be masked with other endpoint descriptor attributes for a \ref USB_Descriptor_Endpoint_t descriptor's - * Attributes value to indicate that the specified endpoint is synchronized. + * \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) //@} - + /** \name Endpoint Descriptor Usage Masks */ //@{ /** Can be masked with other endpoint descriptor attributes for a \ref USB_Descriptor_Endpoint_t descriptor's - * Attributes value to indicate that the specified endpoint is used for data transfers. + * \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) /** Can be masked with other endpoint descriptor attributes for a \ref USB_Descriptor_Endpoint_t descriptor's - * Attributes value to indicate that the specified endpoint is used for feedback. + * \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) /** Can be masked with other endpoint descriptor attributes for a \ref USB_Descriptor_Endpoint_t descriptor's - * Attributes value to indicate that the specified endpoint is used for implicit feedback. + * \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) //@} - + /* Enums: */ /** Enum for the possible standard descriptor types, as given in each descriptor's header. */ enum USB_DescriptorTypes_t @@ -244,6 +234,8 @@ * 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 { @@ -251,7 +243,7 @@ uint8_t Type; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a value * given by the specific class. */ - } USB_Descriptor_Header_t; + } ATTR_PACKED USB_Descriptor_Header_t; /** \brief Standard USB Descriptor Header (USB-IF naming conventions). * @@ -259,6 +251,8 @@ * 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 { @@ -266,7 +260,7 @@ 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; + } ATTR_PACKED USB_StdDescriptor_Header_t; /** \brief Standard USB Device Descriptor (LUFA naming conventions). * @@ -274,6 +268,8 @@ * 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 { @@ -303,7 +299,7 @@ uint8_t SerialNumStrIndex; /**< 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 + * \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 USE_INTERNAL_SERIAL. * On unsupported devices, this will evaluate to 0 and will cause @@ -315,7 +311,7 @@ uint8_t NumberOfConfigurations; /**< Total number of configurations supported by * the device. */ - } USB_Descriptor_Device_t; + } ATTR_PACKED USB_Descriptor_Device_t; /** \brief Standard USB Device Descriptor (USB-IF naming conventions). * @@ -323,6 +319,8 @@ * 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 { @@ -351,7 +349,7 @@ 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 + * \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 USE_INTERNAL_SERIAL. * On unsupported devices, this will evaluate to 0 and will cause @@ -363,7 +361,54 @@ uint8_t bNumConfigurations; /**< Total number of configurations supported by * the device. */ - } USB_StdDescriptor_Device_t; + } ATTR_PACKED USB_StdDescriptor_Device_t; + + /** \brief Standard USB Device Qualifier Descriptor (LUFA naming conventions). + * + * 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; /**< Descriptor header, including type and size. */ + + uint16_t USBSpecification; /**< BCD of the supported USB specification. */ + uint8_t Class; /**< USB device class. */ + uint8_t SubClass; /**< USB device subclass. */ + uint8_t Protocol; /**< USB device protocol. */ + + uint8_t Endpoint0Size; /**< Size of the control (address 0) endpoint's bank in bytes. */ + uint8_t NumberOfConfigurations; /**< Total number of configurations supported by + * the device. + */ + uint8_t Reserved; /**< Reserved for future use, must be 0. */ + } ATTR_PACKED USB_Descriptor_DeviceQualifier_t; + + /** \brief Standard USB Device Qualifier Descriptor (USB-IF naming conventions). + * + * 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; /**< 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. */ + uint8_t bNumConfigurations; /**< Total number of configurations supported by + * the device. + */ + uint8_t bReserved; /**< Reserved for future use, must be 0. */ + } ATTR_PACKED USB_StdDescriptor_DeviceQualifier_t; /** \brief Standard USB Configuration Descriptor (LUFA naming conventions). * @@ -371,6 +416,8 @@ * 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 { @@ -384,15 +431,15 @@ uint8_t ConfigurationNumber; /**< Configuration index of the current configuration. */ uint8_t ConfigurationStrIndex; /**< Index of a string descriptor describing the configuration. */ - uint8_t ConfigAttributes; /**< Configuration attributes, comprised of a mask of zero or - * more USB_CONFIG_ATTR_* masks. + uint8_t ConfigAttributes; /**< Configuration attributes, comprised of a mask of \c USB_CONFIG_ATTR_* masks. + * On all devices, this should include USB_CONFIG_ATTR_RESERVED at a minimum. */ uint8_t MaxPowerConsumption; /**< Maximum power consumption of the device while in the * current configuration, calculated by the \ref USB_CONFIG_POWER_MA() * macro. */ - } USB_Descriptor_Configuration_Header_t; + } ATTR_PACKED USB_Descriptor_Configuration_Header_t; /** \brief Standard USB Configuration Descriptor (USB-IF naming conventions). * @@ -400,6 +447,8 @@ * 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 { @@ -413,14 +462,14 @@ 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 bmAttributes; /**< Configuration attributes, comprised of a mask of \c USB_CONFIG_ATTR_* masks. + * On all devices, this should include USB_CONFIG_ATTR_RESERVED at a minimum. */ 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; + } ATTR_PACKED USB_StdDescriptor_Configuration_Header_t; /** \brief Standard USB Interface Descriptor (LUFA naming conventions). * @@ -428,6 +477,8 @@ * 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 { @@ -446,7 +497,7 @@ uint8_t Protocol; /**< Interface protocol ID. */ uint8_t InterfaceStrIndex; /**< Index of the string descriptor describing the interface. */ - } USB_Descriptor_Interface_t; + } ATTR_PACKED USB_Descriptor_Interface_t; /** \brief Standard USB Interface Descriptor (USB-IF naming conventions). * @@ -454,6 +505,8 @@ * 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 { @@ -474,7 +527,7 @@ uint8_t iInterface; /**< Index of the string descriptor describing the * interface. */ - } USB_StdDescriptor_Interface_t; + } ATTR_PACKED USB_StdDescriptor_Interface_t; /** \brief Standard USB Interface Association Descriptor (LUFA naming conventions). * @@ -488,6 +541,8 @@ * 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 { @@ -503,7 +558,7 @@ uint8_t IADStrIndex; /**< Index of the string descriptor describing the * interface association. */ - } USB_Descriptor_Interface_Association_t; + } ATTR_PACKED USB_Descriptor_Interface_Association_t; /** \brief Standard USB Interface Association Descriptor (USB-IF naming conventions). * @@ -518,6 +573,8 @@ * * \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 { @@ -533,7 +590,7 @@ uint8_t iFunction; /**< Index of the string descriptor describing the * interface association. */ - } USB_StdDescriptor_Interface_Association_t; + } ATTR_PACKED USB_StdDescriptor_Interface_Association_t; /** \brief Standard USB Endpoint Descriptor (LUFA naming conventions). * @@ -541,6 +598,8 @@ * 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 { @@ -558,7 +617,7 @@ uint8_t PollingIntervalMS; /**< Polling interval in milliseconds for the endpoint if it is an INTERRUPT * or ISOCHRONOUS type. */ - } USB_Descriptor_Endpoint_t; + } ATTR_PACKED USB_Descriptor_Endpoint_t; /** \brief Standard USB Endpoint Descriptor (USB-IF naming conventions). * @@ -567,6 +626,8 @@ * * \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 { @@ -586,7 +647,7 @@ uint8_t bInterval; /**< Polling interval in milliseconds for the endpoint if it is an INTERRUPT or * ISOCHRONOUS type. */ - } USB_StdDescriptor_Endpoint_t; + } ATTR_PACKED USB_StdDescriptor_Endpoint_t; /** \brief Standard USB String Descriptor (LUFA naming conventions). * @@ -600,23 +661,30 @@ * 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; /**< Descriptor header, including type and size. */ - wchar_t UnicodeString[]; /**< 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_Descriptor_String_t; + #if (((ARCH == ARCH_AVR8) || (ARCH == ARCH_XMEGA)) && !defined(__DOXYGEN__)) + wchar_t UnicodeString[]; + #else + uint16_t UnicodeString[]; /**< 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 on little endian devices with + * UTF-16-LE \c wchar_t encoding. + */ + #endif + } ATTR_PACKED USB_Descriptor_String_t; /** \brief Standard USB String Descriptor (USB-IF naming conventions). * @@ -631,6 +699,8 @@ * * \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 { @@ -638,24 +708,24 @@ 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; + uint16_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. + */ + } ATTR_PACKED USB_StdDescriptor_String_t; /* Private Interface - For use in library only: */ #if !defined(__DOXYGEN__) /* Macros: */ - #define VERSION_TENS(x) (int)((x) / 10) - #define VERSION_ONES(x) (int)((x) - (10 * VERSION_TENS(x))) - #define VERSION_TENTHS(x) (int)(((x) - (int)(x)) * 10) - #define VERSION_HUNDREDTHS(x) (int)((((x) - (int)(x)) * 100) - (10 * VERSION_TENTHS(x))) + #define VERSION_TENS(x) (int)((int)(x) / 10) + #define VERSION_ONES(x) (int)((int)(x) % 10) + #define VERSION_TENTHS(x) (int)(((x * 1) - ((int)(x * 1))) * 10) + #define VERSION_HUNDREDTHS(x) (int)(((x * 10) - ((int)(x * 10))) * 10) #endif /* Disable C linkage for C++ Compilers: */