X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/eee252603be67c539f9986cde76454f756e55d95..d6a528f9a03fe338e30d93f306e0482612e02e3e:/LUFA/Drivers/USB/Core/StdDescriptors.h diff --git a/LUFA/Drivers/USB/Core/StdDescriptors.h b/LUFA/Drivers/USB/Core/StdDescriptors.h index 1ea4546ab..20cc44f72 100644 --- a/LUFA/Drivers/USB/Core/StdDescriptors.h +++ b/LUFA/Drivers/USB/Core/StdDescriptors.h @@ -1,13 +1,13 @@ /* LUFA Library - Copyright (C) Dean Camera, 2012. + Copyright (C) Dean Camera, 2018. dean [at] fourwalledcubicle [dot] com www.lufa-lib.org */ /* - Copyright 2012 Dean Camera (dean [at] fourwalledcubicle [dot] com) + Copyright 2018 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 @@ -85,17 +85,34 @@ */ #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. + /** Convenience macro to easily create \ref USB_Descriptor_String_t instances from a wide character string. + * + * \note This macro is for little-endian systems only. + * + * \param[in] String String to initialize a USB String Descriptor structure with. + */ + #define USB_STRING_DESCRIPTOR(String) { .Header = {.Size = sizeof(USB_Descriptor_Header_t) + (sizeof(String) - 2), .Type = DTYPE_String}, .UnicodeString = String } + + /** Convenience macro to easily create \ref USB_Descriptor_String_t instances from an array of characters. + * + * \param[in] ... Characters to initialize a USB String Descriptor structure with. + */ + #define USB_STRING_DESCRIPTOR_ARRAY(...) { .Header = {.Size = sizeof(USB_Descriptor_Header_t) + sizeof((uint16_t){__VA_ARGS__}), .Type = DTYPE_String}, .UnicodeString = {__VA_ARGS__} } + + /** Macro to encode a given major/minor/revision version number 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. + * \param[in] Major Major version number to encode. + * \param[in] Minor Minor version number to encode. + * \param[in] Revision Revision version number to encode. */ - #define VERSION_BCD(x) CPU_TO_LE16((VERSION_TENS(x) << 12) | (VERSION_ONES(x) << 8) | \ - (VERSION_TENTHS(x) << 4) | (VERSION_HUNDREDTHS(x) << 0) ) + #define VERSION_BCD(Major, Minor, Revision) \ + CPU_TO_LE16( ((Major & 0xFF) << 8) | \ + ((Minor & 0x0F) << 4) | \ + (Revision & 0x0F) ) /** 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. @@ -104,14 +121,17 @@ /** \name USB Configuration Descriptor Attribute Masks */ //@{ - /** Mask for the reserved bit in the Configuration Descriptor's \c ConfigAttributes field, which must be set on all - * devices for historical purposes. + /** Mask for the reserved bit in the Configuration Descriptor's \c ConfigAttributes field, which must be always + * set on all USB devices for historical purposes. */ #define USB_CONFIG_ATTR_RESERVED 0x80 /** Can be masked with other configuration descriptor attributes for a \ref USB_Descriptor_Configuration_Header_t * descriptor's \c ConfigAttributes value to indicate that the specified configuration can draw its power - * from the device's own power source. + * from the device's own power source, instead of drawing it from the USB host. + * + * Note that the host will probe this dynamically - the device should report its current power state via the + * \ref USB_Device_CurrentlySelfPowered global variable. */ #define USB_CONFIG_ATTR_SELFPOWERED 0x40 @@ -119,6 +139,10 @@ * 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. + * + * If set, the host will dynamically enable and disable remote wakeup support, indicated via the + * \ref USB_Device_RemoteWakeupEnabled global variable. To initiate a remote wakeup of the host (when allowed) + * see \ref USB_Device_RemoteWakeupEnabled(). */ #define USB_CONFIG_ATTR_REMOTEWAKEUP 0x20 //@} @@ -275,7 +299,10 @@ { USB_Descriptor_Header_t Header; /**< Descriptor header, including type and size. */ - uint16_t USBSpecification; /**< BCD of the supported USB specification. */ + uint16_t USBSpecification; /**< BCD of the supported USB specification. + * + * \see \ref VERSION_BCD() utility macro. + */ uint8_t Class; /**< USB device class. */ uint8_t SubClass; /**< USB device subclass. */ uint8_t Protocol; /**< USB device protocol. */ @@ -284,8 +311,10 @@ uint16_t VendorID; /**< Vendor ID for the USB product. */ uint16_t ProductID; /**< Unique product ID for the USB product. */ - uint16_t ReleaseNumber; /**< Product release (version) number. */ - + uint16_t ReleaseNumber; /**< Product release (version) number. + * + * \see \ref VERSION_BCD() utility macro. + */ uint8_t ManufacturerStrIndex; /**< String index for the manufacturer's name. The * host will request this string via a separate * control request for the string descriptor. @@ -301,12 +330,12 @@ * * \note On some microcontroller 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. + * To use this serial number, set this to \c USE_INTERNAL_SERIAL. + * On unsupported devices, this will evaluate to \ref NO_DESCRIPTOR + * and will cause the host to generate a pseudo-unique value for the + * device upon insertion. * - * \see ManufacturerStrIndex structure entry. + * \see \c ManufacturerStrIndex structure entry. */ uint8_t NumberOfConfigurations; /**< Total number of configurations supported by * the device. @@ -328,14 +357,20 @@ 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. */ + uint16_t bcdUSB; /**< BCD of the supported USB specification. + * + * \see \ref VERSION_BCD() utility macro. + */ 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. */ uint16_t idVendor; /**< Vendor ID for the USB product. */ uint16_t idProduct; /**< Unique product ID for the USB product. */ - uint16_t bcdDevice; /**< Product release (version) number. */ + uint16_t bcdDevice; /**< Product release (version) number. + * + * \see \ref VERSION_BCD() utility macro. + */ uint8_t iManufacturer; /**< String index for the manufacturer's name. The * host will request this string via a separate * control request for the string descriptor. @@ -351,12 +386,12 @@ * * \note On some microcontroller 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. + * To use this serial number, set this to \c USE_INTERNAL_SERIAL. + * On unsupported devices, this will evaluate to \ref NO_DESCRIPTOR + * and will cause the host to generate a pseudo-unique value for the + * device upon insertion. * - * \see ManufacturerStrIndex structure entry. + * \see \c ManufacturerStrIndex structure entry. */ uint8_t bNumConfigurations; /**< Total number of configurations supported by * the device. @@ -374,7 +409,10 @@ { USB_Descriptor_Header_t Header; /**< Descriptor header, including type and size. */ - uint16_t USBSpecification; /**< BCD of the supported USB specification. */ + uint16_t USBSpecification; /**< BCD of the supported USB specification. + * + * \see \ref VERSION_BCD() utility macro. + */ uint8_t Class; /**< USB device class. */ uint8_t SubClass; /**< USB device subclass. */ uint8_t Protocol; /**< USB device protocol. */ @@ -397,9 +435,12 @@ { 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. */ + * given by the specific class. + */ + uint16_t bcdUSB; /**< BCD of the supported USB specification. + * + * \see \ref VERSION_BCD() utility macro. + */ uint8_t bDeviceClass; /**< USB device class. */ uint8_t bDeviceSubClass; /**< USB device subclass. */ uint8_t bDeviceProtocol; /**< USB device protocol. */ @@ -454,8 +495,8 @@ { 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. - */ + * given by the specific class. + */ uint16_t wTotalLength; /**< Size of the configuration descriptor header, * and all sub descriptors inside the configuration. */ @@ -719,14 +760,6 @@ */ } ATTR_PACKED USB_StdDescriptor_String_t; - /* Private Interface - For use in library only: */ - #if !defined(__DOXYGEN__) - /* Macros: */ - #define VERSION_TENS(x) (int)((int)(x) / 10) - #define VERSION_ONES(x) (int)((int)(x) % 10) - #define VERSION_TENTHS(x) (int)((x - (int)x) * 10) - #define VERSION_HUNDREDTHS(x) (int)((x * 100) - ((int)(x * 10) * 10)) - #endif /* Disable C linkage for C++ Compilers: */ #if defined(__cplusplus)