/*
LUFA Library
- Copyright (C) Dean Camera, 2013.
+ Copyright (C) Dean Camera, 2018.
dean [at] fourwalledcubicle [dot] com
www.lufa-lib.org
*/
/*
- Copyright 2013 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
*/
#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.
/** \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
* 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
//@}
{
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. */
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.
*
* \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.
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.
*
* \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.
{
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. */
{
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. */
{
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.
*/
*/
} 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)
projects / pub / USBasp.git / blobdiff