X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/d38fa49cb6cb3804c9bb17601688a62ba466b535..05fa6e0c43e542459000c7ebe0b10cbe24c7f5d9:/LUFA/Drivers/USB/HighLevel/StdDescriptors.h diff --git a/LUFA/Drivers/USB/HighLevel/StdDescriptors.h b/LUFA/Drivers/USB/HighLevel/StdDescriptors.h index 431080b72..274b84fc4 100644 --- a/LUFA/Drivers/USB/HighLevel/StdDescriptors.h +++ b/LUFA/Drivers/USB/HighLevel/StdDescriptors.h @@ -74,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 @@ -90,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 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 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 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 (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 (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 (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 (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 (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 (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 (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 @@ -206,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 @@ -226,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 { @@ -251,7 +251,7 @@ * 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. * @@ -260,6 +260,13 @@ 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 + * 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. */ @@ -286,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 { @@ -309,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 @@ -326,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 { @@ -364,7 +369,7 @@ #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 supplement to the USB2.0 standard, in the ECN located at * http://www.usb.org/developers/docs/InterfaceAssociationDescriptor_ecn.pdf. It allows compound @@ -372,10 +377,9 @@ * 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 { @@ -406,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 { @@ -442,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 { @@ -476,33 +478,6 @@ #endif } USB_Descriptor_String_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_RAM_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__) /* Macros: */