/*
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
#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" {
*/
#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
* 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 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).
*
* 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 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).
*
* 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
{
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).
*
* 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 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).
*
* 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
{
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).
*
* 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 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).
*
* 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
{
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).
*
* 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 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).
*
* 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
{
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).
*
*
* \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 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).
*
* 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
{
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).
*
*
* \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 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).
*
* 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).
*
*
* \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 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: */
projects / pub / USBasp.git / blobdiff