X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/9cec85bfd92a77a97e7d12625897de2682dfacd7..05fa6e0c43e542459000c7ebe0b10cbe24c7f5d9:/LUFA/Drivers/USB/HighLevel/StdDescriptors.h diff --git a/LUFA/Drivers/USB/HighLevel/StdDescriptors.h b/LUFA/Drivers/USB/HighLevel/StdDescriptors.h index caa0fb046..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 @@ -175,19 +190,6 @@ */ #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 \ref 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,10 +208,9 @@ /* 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 { @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -448,10 +451,9 @@ * 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 \ref 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 \ref 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 \ref 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: */