stddescriptors.h

userial is an Free project building an USB to I2C/SPI/GPIO bridge, using the Atmel AT90USB647 chip.

				uint8_t                 NumberOfConfigurations; /**< Total number of configurations supported by
				                                                 *   the device.
				                                                 */
				#else
				uint8_t                 bLength;
				uint8_t                 bDescriptorType;
				uint16_t                bcdUSB;
				uint8_t                 bDeviceClass;
				uint8_t                 bDeviceSubClass;
				uint8_t                 bDeviceProtocol;
				uint8_t                 bMaxPacketSize0;
				uint16_t                idVendor;
				uint16_t                idProduct;
				uint16_t                bcdDevice;
				uint8_t                 iManufacturer;
				uint8_t                 iProduct;
				uint8_t                 iSerialNumber;
				uint8_t                 bNumConfigurations;
				#endif
			} USB_Descriptor_Device_t;

			/** 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.
			 */
			typedef struct
			{
				#if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__)
				USB_Descriptor_Header_t Header; /**< Descriptor header, including type and size. */
			
				uint16_t                TotalConfigurationSize; /**< Size of the configuration descriptor header,
				                                                 *   and all sub descriptors inside the configuration.
				                                                 */
				uint8_t                 TotalInterfaces; /**< Total number of interfaces in the configuration. */

				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                 MaxPowerConsumption; /**< Maximum power consumption of the device while in the
				                                              *   current configuration, calculated by the USB_CONFIG_POWER_MA()
				                                              *   macro.
				                                              */
				#else
				uint8_t                 bLength;
				uint8_t                 bDescriptorType;
				uint16_t                wTotalLength;
				uint8_t                 bNumInterfaces;
				uint8_t                 bConfigurationValue;
				uint8_t                 iConfiguration;
				uint8_t                 bmAttributes;
				uint8_t                 bMaxPower;
				#endif
			} USB_Descriptor_Configuration_Header_t;

			/** 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.
			 */
			typedef struct
			{
				#if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__)
				USB_Descriptor_Header_t Header; /**< Descriptor header, including type and size. */

				uint8_t                 InterfaceNumber; /**< Index of the interface in the current configuration. */
				uint8_t                 AlternateSetting; /**< Alternate setting for the interface number. The same
				                                           *   interface number can have multiple alternate settings
				                                           *   with different endpoint configurations, which can be
				                                           *   selected by the host.
				                                           */
				uint8_t                 TotalEndpoints; /**< Total number of endpoints in the interface. */
				
				uint8_t                 Class; /**< Interface class ID. */
				uint8_t                 SubClass; /**< Interface subclass ID. */
				uint8_t                 Protocol; /**< Interface protocol ID. */

				uint8_t                 InterfaceStrIndex; /**< Index of the string descriptor describing the
				                                            *   interface.
				                                            */
				#else
				uint8_t                 bLength;
				uint8_t                 bDescriptorType;
				uint8_t                 bInterfaceNumber;
				uint8_t                 bAlternateSetting;
				uint8_t                 bNumEndpoints;
				uint8_t                 bInterfaceClass;
				uint8_t                 bInterfaceSubClass;
				uint8_t                 bInterfaceProtocol;
				uint8_t                 iInterface;
				#endif
			} USB_Descriptor_Interface_t;

			/** 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
			 *  <a>http://www.usb.org/developers/docs/InterfaceAssociationDescriptor_ecn.pdf</a>. 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.
			 */
			typedef struct
			{
				#if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__)
				USB_Descriptor_Header_t Header; /**< Descriptor header, including type and size. */
				
				uint8_t                 FirstInterfaceIndex; /**< Index of the first associated interface. */
				uint8_t                 TotalInterfaces; /** Total number of associated interfaces. */

				uint8_t                 Class; /**< Interface class ID. */
				uint8_t                 SubClass; /**< Interface subclass ID. */
				uint8_t                 Protocol; /**< Interface protocol ID. */

				uint8_t                 IADStrIndex; /**< Index of the string descriptor describing the
				                                      *   interface association.
				                                      */
				#else
				uint8_t                 bLength;
				uint8_t                 bDescriptorType;
				uint8_t                 bFirstInterface;
				uint8_t                 bInterfaceCount;
				uint8_t                 bFunctionClass;
				uint8_t                 bFunctionSubClass;
				uint8_t                 bFunctionProtocol;
				uint8_t                 iFunction;
				#endif
			} USB_Descriptor_Interface_Association_t;

			/** 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.
			*/
			typedef struct
			{
				#if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__)
				USB_Descriptor_Header_t Header; /**< Descriptor header, including type and size. */

				uint8_t                 EndpointAddress; /**< Logical address of the endpoint within the device
				                                          *   for the current configuration, including direction
				                                          *   mask.
				                                          */
				uint8_t                 Attributes; /**< Endpoint attributes, comprised of a mask of the
				                                     *   endpoint type (EP_TYPE_*) and attributes (ENDPOINT_ATTR_*)
				                                     *   masks.
				                                     */
				uint16_t                EndpointSize; /**< Size of the endpoint bank, in bytes. This indicates the
				                                       *   maximum packet size that the endpoint can receive at a time.
				                                       */
				
				uint8_t                 PollingIntervalMS; /**< Polling interval in milliseconds for the endpont
				                                            *   if it is an INTERRUPT or ISOCHRONOUS type.
				                                            */
				#else
				uint8_t                 bLength;
				uint8_t                 bDescriptorType;
				uint8_t                 bEndpointAddress;
				uint8_t                 bmAttributes;
				uint16_t                wMaxPacketSize;
				uint8_t                 bInterval;
				#endif
			} 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()
			 *  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.
			 */
			typedef struct
			{
				#if defined(USE_NONSTANDARD_DESCRIPTOR_NAMES) || defined(__DOXYGEN__)
				USB_Descriptor_Header_t Header; /**< Descriptor header, including type and size. */
				
				int16_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.
				                                          */
				#else
				uint8_t                 bLength;
				uint8_t                 bDescriptorType;
				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__)
		/* 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)))
	#endif
	
	/* Disable C linkage for C++ Compilers: */
		#if defined(__cplusplus)
			}
		#endif
		
#endif