X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/6a10d6b465be27db090d760dc0fbe722c94e4344..05fa6e0c43e542459000c7ebe0b10cbe24c7f5d9:/LUFA/Drivers/USB/HighLevel/StdDescriptors.h diff --git a/LUFA/Drivers/USB/HighLevel/StdDescriptors.h b/LUFA/Drivers/USB/HighLevel/StdDescriptors.h index d9075cc75..274b84fc4 100644 --- a/LUFA/Drivers/USB/HighLevel/StdDescriptors.h +++ b/LUFA/Drivers/USB/HighLevel/StdDescriptors.h @@ -28,10 +28,11 @@ this software. */ -/** \file +/** \ingroup Group_USB + * @defgroup Group_Descriptors USB Descriptors * * Standard USB device descriptor defines and retrieval routines, for USB devices. This module contains - * strucutures 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 @@ -42,8 +43,10 @@ * 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. + * + * @{ */ - + #ifndef __USBDESCRIPTORS_H__ #define __USBDESCRIPTORS_H__ @@ -52,7 +55,7 @@ #include #include "../../../Common/Common.h" - #include "../LowLevel/USBMode.h" + #include "USBMode.h" #include "Events.h" #if defined(USB_CAN_BE_DEVICE) @@ -71,14 +74,29 @@ * descriptor does not exist. */ #define NO_DESCRIPTOR 0 + + #if (!defined(NO_INTERNAL_SERIAL) && (defined(USB_SERIES_6_AVR) || defined(USB_SERIES_7_AVR))) || defined(__DOXYGEN__) + /** String descriptor index for the device's unique serial number string descriptor within the device. + * This unique serial number is used by the host to associate resources to the device (such as drivers or COM port + * number allocations) to a device regardless of the port it is plugged in to on the host. Some USB AVRs contain + * a unique serial number internally, and setting the device descriptors serial number string index to this value + * will cause it to use the internal serial number. + * + * On unsupported devices, this will evaluate to NO_DESCRIPTOR and so will force the host to create a pseduo-serial + * number for the device. + */ + #define USE_INTERNAL_SERIAL 0xDC + #else + #define USE_INTERNAL_SERIAL NO_DESCRIPTOR + #endif /** Macro to calculate the power value for the device descriptor, from a given number of milliamps. */ - #define USB_CONFIG_POWER_MA(x) (x >> 1) + #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. */ - #define USB_STRING_LEN(x) (sizeof(USB_Descriptor_Header_t) + (x << 1)) + #define USB_STRING_LEN(str) (sizeof(USB_Descriptor_Header_t) + (str << 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 @@ -87,104 +105,91 @@ #define VERSION_BCD(x) ((((VERSION_TENS(x) << 4) | VERSION_ONES(x)) << 8) | \ ((VERSION_TENTHS(x) << 4) | VERSION_HUNDREDTHS(x))) - /** String language ID for the English language. Should be used in USB_Descriptor_Language_t descriptors + /** 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 - /** Can be masked with an endpoint address for a USB_Descriptor_Endpoint_t endpoint descriptor's + /** 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 USB_Descriptor_Endpoint_t endpoint descriptor's + /** 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 - /** Can be masked with other configuration descriptor attributes for a USB_Descriptor_Configuration_Header_t + /** 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. */ - #define USB_CONFIG_ATTR_BUSPOWERED 0b10000000 + #define USB_CONFIG_ATTR_BUSPOWERED 0x80 - /** Can be masked with other configuration descriptor attributes for a USB_Descriptor_Configuration_Header_t + /** 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 device's own power source. */ - #define USB_CONFIG_ATTR_SELFPOWERED 0b11000000 + #define USB_CONFIG_ATTR_SELFPOWERED 0xC0 - /** Can be masked with other configuration descriptor attributes for a USB_Descriptor_Configuration_Header_t + /** 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 * remote wakeup feature of the USB standard, allowing a suspended USB device to wake up the host upon * request. */ - #define USB_CONFIG_ATTR_REMOTEWAKEUP 0b10100000 + #define USB_CONFIG_ATTR_REMOTEWAKEUP 0xA0 - /** Can be masked with other endpoint descriptor attributes for a USB_Descriptor_Endpoint_t descriptor's + /** 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. * * \see The USB specification for more details on the possible Endpoint attributes. */ - #define ENDPOINT_ATTR_NO_SYNC (0b00 << 2) + #define ENDPOINT_ATTR_NO_SYNC (0 << 2) - /** Can be masked with other endpoint descriptor attributes for a USB_Descriptor_Endpoint_t descriptor's + /** 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. * * \see The USB specification for more details on the possible Endpoint attributes. */ - #define ENDPOINT_ATTR_ASYNC (0b01 << 2) + #define ENDPOINT_ATTR_ASYNC (1 << 2) - /** Can be masked with other endpoint descriptor attributes for a USB_Descriptor_Endpoint_t descriptor's + /** 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. * * \see The USB specification for more details on the possible Endpoint attributes. */ - #define ENDPOINT_ATTR_ADAPTIVE (0b10 << 2) + #define ENDPOINT_ATTR_ADAPTIVE (2 << 2) - /** Can be masked with other endpoint descriptor attributes for a USB_Descriptor_Endpoint_t descriptor's + /** 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. * * \see The USB specification for more details on the possible Endpoint attributes. */ - #define ENDPOINT_ATTR_SYNC (0b11 << 2) + #define ENDPOINT_ATTR_SYNC (3 << 2) - /** Can be masked with other endpoint descriptor attributes for a USB_Descriptor_Endpoint_t descriptor's + /** 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. * * \see The USB specification for more details on the possible Endpoint usage attributes. */ - #define ENDPOINT_USAGE_DATA (0b00 << 4) + #define ENDPOINT_USAGE_DATA (0 << 4) - /** Can be masked with other endpoint descriptor attributes for a USB_Descriptor_Endpoint_t descriptor's + /** 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. * * \see The USB specification for more details on the possible Endpoint usage attributes. */ - #define ENDPOINT_USAGE_FEEDBACK (0b01 << 4) + #define ENDPOINT_USAGE_FEEDBACK (1 << 4) - /** Can be masked with other endpoint descriptor attributes for a USB_Descriptor_Endpoint_t descriptor's + /** 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. * * \see The USB specification for more details on the possible Endpoint usage attributes. */ - #define ENDPOINT_USAGE_IMPLICIT_FEEDBACK (0b10 << 4) + #define ENDPOINT_USAGE_IMPLICIT_FEEDBACK (2 << 4) - /** Gives a void pointer to the specified descriptor (of any type). */ - #define DESCRIPTOR_ADDRESS(Descriptor) ((void*)&Descriptor) - - /* Events: */ - #if defined(USB_CAN_BE_DEVICE) || defined(__DOXYGEN__) - /** This module raises the Device Error event while in device mode, if the USB_GetDescriptor() - * routine is not hooked in the user application to properly return descriptors to the library. - * - * \see Events.h for more information on this event. - */ - RAISES_EVENT(USB_DeviceError); - #endif - /* Enums: */ /** Enum for the possible standard descriptor types, as given in each descriptor's header. */ enum USB_DescriptorTypes_t @@ -203,16 +208,15 @@ /* Type Defines: */ /** Type define for all descriptor's header, indicating the descriptor's length and type. * - * \note The non-standard structure element names are documented here - see the StdDescriptors.h file - * documentation for more information on the two descriptor naming schemes. If the - * USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set, this structure contains elements with names - * identical to those listed in the USB standard. + * \note The non-standard structure element names are documented here. If the + * USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set, this structure contains elements + * with names identical to those listed in the USB standard. */ typedef struct { #if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__) uint8_t Size; /**< Size of the descriptor, in bytes. */ - uint8_t Type; /**< Type of the descriptor, either a value in 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. */ #else @@ -223,10 +227,9 @@ /** Type define for a standard device descriptor. * - * \note The non-standard structure element names are documented here - see the StdDescriptors.h file - * documentation for more information on the two descriptor naming schemes. If the - * USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set, this structure contains elements with names - * identical to those listed in the USB standard. + * \note The non-standard structure element names are documented here. If the + * USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set, this structure contains elements + * with names identical to those listed in the USB standard. */ typedef struct { @@ -245,17 +248,24 @@ uint16_t ReleaseNumber; /**< Product release (version) number. */ uint8_t ManufacturerStrIndex; /**< String index for the manufacturer's name. The - * host will request this string via a seperate + * host will request this string via a separate * control request for the string descriptor. * - * \note If no string supplied, use NO_DESCRIPTOR. + * \note If no string supplied, use \ref NO_DESCRIPTOR. */ uint8_t ProductStrIndex; /**< String index for the product name/details. * * \see ManufacturerStrIndex structure entry. */ uint8_t SerialNumStrIndex; /**< String index for the product's globally unique hexadecimal - * serial number, in uppercase Unicoded ASCII. + * 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. */ @@ -283,10 +293,9 @@ /** Type define for a standard configuration descriptor. * - * \note The non-standard structure element names are documented here - see the StdDescriptors.h file - * documentation for more information on the two descriptor naming schemes. If the - * USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set, this structure contains elements with names - * identical to those listed in the USB standard. + * \note The non-standard structure element names are documented here. If the + * USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set, this structure contains elements + * with names identical to those listed in the USB standard. */ typedef struct { @@ -306,7 +315,7 @@ */ uint8_t MaxPowerConsumption; /**< Maximum power consumption of the device while in the - * current configuration, calculated by the USB_CONFIG_POWER_MA() + * current configuration, calculated by the \ref USB_CONFIG_POWER_MA() * macro. */ #else @@ -323,10 +332,9 @@ /** Type define for a standard interface descriptor. * - * \note The non-standard structure element names are documented here - see the StdDescriptors.h file - * documentation for more information on the two descriptor naming schemes. If the - * USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set, this structure contains elements with names - * identical to those listed in the USB standard. + * \note The non-standard structure element names are documented here. If the + * USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set, this structure contains elements + * with names identical to those listed in the USB standard. */ typedef struct { @@ -361,18 +369,17 @@ #endif } USB_Descriptor_Interface_t; - /** Type define for a standard interface association descriptor. + /** Type define for a standard Interface Association descriptor. * - * This descriptor has been added as a suppliment 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 * http://www.usb.org/developers/docs/InterfaceAssociationDescriptor_ecn.pdf. 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. * - * \note The non-standard structure element names are documented here - see the StdDescriptors.h file - * documentation for more information on the two descriptor naming schemes. If the - * USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set, this structure contains elements with names - * identical to those listed in the USB standard. + * \note The non-standard structure element names are documented here. If the + * USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set, this structure contains elements + * with names identical to those listed in the USB standard. */ typedef struct { @@ -403,10 +410,9 @@ /** Type define for a standard endpoint descriptor. * - * \note The non-standard structure element names are documented here - see the StdDescriptors.h file - * documentation for more information on the two descriptor naming schemes. If the - * USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set, this structure contains elements with names - * identical to those listed in the USB standard. + * \note The non-standard structure element names are documented here. If the + * USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set, this structure contains elements + * with names identical to those listed in the USB standard. */ typedef struct { @@ -425,7 +431,7 @@ * maximum packet size that the endpoint can receive at a time. */ - uint8_t PollingIntervalMS; /**< Polling interval in milliseconds for the endpont + uint8_t PollingIntervalMS; /**< Polling interval in milliseconds for the endpoint * if it is an INTERRUPT or ISOCHRONOUS type. */ #else @@ -439,16 +445,15 @@ } USB_Descriptor_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 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. * * This structure should also be used for string index 0, which contains the supported language IDs for * the device as an array. * - * \note The non-standard structure element names are documented here - see the StdDescriptors.h file - * documentation for more information on the two descriptor naming schemes. If the - * USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set, this structure contains elements with names - * identical to those listed in the USB standard. + * \note The non-standard structure element names are documented here. If the + * USE_NONSTANDARD_DESCRIPTOR_NAMES token is not set, this structure contains elements + * with names identical to those listed in the USB standard. */ typedef struct { @@ -472,39 +477,6 @@ int16_t bString[]; #endif } USB_Descriptor_String_t; - - typedef struct - { - uint16_t Size; - void* Address; - } USB_Descriptor_Details_t; - - /* Function Prototypes: */ - /** Function to retrieve a given descriptor's size and memory location from the given descriptor type value, - * index and language ID. This function MUST be overridden in the user application (added with full, identical - * prototype and name except for the ATTR_WEAK attribute) so that the library can call it to retrieve descriptor - * data. - * - * \param wValue The type of the descriptor to retrieve in the upper byte, and the index in the - * lower byte (when more than one descriptor of the given type exists, such as the - * case of string descriptors). The type may be one of the standard types defined - * in the DescriptorTypes_t enum, or may be a class-specific descriptor type value. - * \param wIndex The language ID of the string to return if the wValue type indicates DTYPE_String, - * otherwise zero for standard descriptors, or as defined in a class-specific - * standards. - * \param DescriptorAddress Pointer to the descriptor in memory. This should be set by the routine to - * the location of the descriptor, found by the DESCRIPTOR_ADDRESS macro. - * - * \note By default, the library expects all descriptors to be located in flash memory via the PROGMEM attribute. - * If descriptors should be located in RAM or EEPROM instead (to speed up access in the case of RAM, or to - * allow the descriptors to be changed dynamically at runtime) either the USE_SRAM_DESCRIPTORS or the - * USE_EEPROM_DESCRIPTORS tokens may be defined in the project makefile and passed to the compiler by the -D - * switch. - * - * \return Size in bytes of the descriptor if it exists, zero or NO_DESCRIPTOR otherwise - */ - uint16_t USB_GetDescriptor(const uint16_t wValue, const uint8_t wIndex, void** const DescriptorAddress) - ATTR_WARN_UNUSED_RESULT ATTR_WEAK ATTR_NON_NULL_PTR_ARG(3); /* Private Interface - For use in library only: */ #if !defined(__DOXYGEN__) @@ -519,5 +491,7 @@ #if defined(__cplusplus) } #endif - + #endif + +/** @} */