X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/b221e7d175e4b5ca463fdd6d05b8c3fc71bd7c40..fc31973daffea3506051ce51a5f79383ce0867d6:/LUFA/Drivers/USB/HighLevel/StdDescriptors.h diff --git a/LUFA/Drivers/USB/HighLevel/StdDescriptors.h b/LUFA/Drivers/USB/HighLevel/StdDescriptors.h index 0b56ab6d0..5f54561dc 100644 --- a/LUFA/Drivers/USB/HighLevel/StdDescriptors.h +++ b/LUFA/Drivers/USB/HighLevel/StdDescriptors.h @@ -1,21 +1,21 @@ /* LUFA Library - Copyright (C) Dean Camera, 2009. + Copyright (C) Dean Camera, 2010. dean [at] fourwalledcubicle [dot] com www.fourwalledcubicle.com */ /* - Copyright 2009 Dean Camera (dean [at] fourwalledcubicle [dot] com) - - Permission to use, copy, modify, and distribute this software - and its documentation for any purpose and without fee is hereby - granted, provided that the above copyright notice appear in all - copies and that both that the copyright notice and this - permission notice and warranty disclaimer appear in supporting - documentation, and that the name of the author not be used in - advertising or publicity pertaining to distribution of the + Copyright 2010 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 + without fee, provided that the above copyright notice appear in + all copies and that both that the copyright notice and this + permission notice and warranty disclaimer appear in supporting + documentation, and that the name of the author not be used in + advertising or publicity pertaining to distribution of the software without specific, written prior permission. The author disclaim all warranties with regard to this @@ -28,6 +28,15 @@ this software. */ +/** \file + * \brief USB standard descriptor definitions. + * + * This file contains structures and macros for the easy creation of standard USB descriptors in USB device projects. + * + * \note This file should not be included directly. It is automatically included as needed by the USB driver + * dispatch header located in LUFA/Drivers/USB/USB.h. + */ + /** \ingroup Group_USB * @defgroup Group_Descriptors USB Descriptors * @@ -43,6 +52,7 @@ /* Includes: */ #include #include + #include #include "../../../Common/Common.h" #include "USBMode.h" @@ -57,6 +67,11 @@ extern "C" { #endif + /* Preprocessor Checks: */ + #if !defined(__INCLUDE_FROM_USB_DRIVER) + #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead. + #endif + /* Public Interface - May be used in end-application: */ /* Macros: */ /** Indicates that a given descriptor does not exist in the device. This can be used inside descriptors @@ -72,7 +87,7 @@ * 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 + * On unsupported devices, this will evaluate to NO_DESCRIPTOR and so will force the host to create a pseudo-serial * number for the device. */ #define USE_INTERNAL_SERIAL 0xDC @@ -80,13 +95,13 @@ #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(mA) (mA >> 1) + /** Macro to calculate the power value for the configuration descriptor, from a given number of milliamps. */ + #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(str) (sizeof(USB_Descriptor_Header_t) + (str << 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 @@ -122,14 +137,14 @@ * 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 + #define USB_CONFIG_ATTR_SELFPOWERED 0x40 /** 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 + #define USB_CONFIG_ATTR_REMOTEWAKEUP 0x20 /** 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. @@ -196,7 +211,9 @@ }; /* Type Defines: */ - /** Type define for all descriptors standard header, indicating the descriptor's length and type. This structure + /** \brief Standard USB Descriptor Header (LUFA naming conventions). + * + * Type define for all descriptors' standard header, indicating the descriptor's length and type. This structure * uses LUFA-specific element names to make each element's purpose clearer. * * \see \ref USB_StdDescriptor_Header_t for the version of this define with standard element names @@ -209,7 +226,9 @@ */ } USB_Descriptor_Header_t; - /** Type define for all descriptors standard header, indicating the descriptor's length and type. This structure + /** \brief Standard USB Descriptor Header (USB-IF naming conventions). + * + * Type define for all descriptors' standard header, indicating the descriptor's length and type. This structure * uses the relevant standard's given element names to ensure compatibility with the standard. * * \see \ref USB_Descriptor_Header_t for the version of this define with non-standard LUFA specific element names @@ -222,7 +241,9 @@ */ } USB_StdDescriptor_Header_t; - /** Type define for a standard Device Descriptor. This structure uses LUFA-specific element names to make each + /** \brief Standard USB Device Descriptor (LUFA naming conventions). + * + * Type define for a standard Device Descriptor. This structure uses LUFA-specific element names to make each * element's purpose clearer. * * \see \ref USB_StdDescriptor_Device_t for the version of this define with standard element names @@ -269,7 +290,9 @@ */ } USB_Descriptor_Device_t; - /** Type define for a standard Device Descriptor. This structure uses the relevant standard's given element names + /** \brief Standard USB Device Descriptor (USB-IF naming conventions). + * + * Type define for a standard Device Descriptor. This structure uses the relevant standard's given element names * to ensure compatibility with the standard. * * \see \ref USB_Descriptor_Device_t for the version of this define with non-standard LUFA specific element names @@ -315,7 +338,9 @@ */ } USB_StdDescriptor_Device_t; - /** Type define for a standard Configuration Descriptor header. This structure uses LUFA-specific element names + /** \brief Standard USB Configuration Descriptor (LUFA naming conventions). + * + * Type define for a standard Configuration Descriptor header. This structure uses LUFA-specific element names * to make each element's purpose clearer. * * \see \ref USB_StdDescriptor_Configuration_Header_t for the version of this define with standard element names @@ -342,7 +367,9 @@ */ } USB_Descriptor_Configuration_Header_t; - /** Type define for a standard Configuration Descriptor header. This structure uses the relevant standard's given element names + /** \brief Standard USB Configuration Descriptor (USB-IF naming conventions). + * + * Type define for a standard Configuration Descriptor header. This structure uses the relevant standard's given element names * to ensure compatibility with the standard. * * \see \ref USB_Descriptor_Device_t for the version of this define with non-standard LUFA specific element names @@ -368,7 +395,9 @@ */ } USB_StdDescriptor_Configuration_Header_t; - /** Type define for a standard Interface Descriptor. This structure uses LUFA-specific element names + /** \brief Standard USB Interface Descriptor (LUFA naming conventions). + * + * Type define for a standard Interface Descriptor. This structure uses LUFA-specific element names * to make each element's purpose clearer. * * \see \ref USB_StdDescriptor_Interface_t for the version of this define with standard element names @@ -394,7 +423,9 @@ */ } USB_Descriptor_Interface_t; - /** Type define for a standard Interface Descriptor. This structure uses the relevant standard's given element names + /** \brief Standard USB Interface Descriptor (USB-IF naming conventions). + * + * Type define for a standard Interface Descriptor. This structure uses the relevant standard's given element names * to ensure compatibility with the standard. * * \see \ref USB_Descriptor_Interface_t for the version of this define with non-standard LUFA specific element names @@ -420,7 +451,9 @@ */ } USB_StdDescriptor_Interface_t; - /** Type define for a standard Interface Association Descriptor. This structure uses LUFA-specific element names + /** \brief Standard USB Interface Association Descriptor (LUFA naming conventions). + * + * Type define for a standard Interface Association Descriptor. This structure uses LUFA-specific element names * to make each element's purpose clearer. * * This descriptor has been added as a supplement to the USB2.0 standard, in the ECN located at @@ -447,7 +480,9 @@ */ } USB_Descriptor_Interface_Association_t; - /** Type define for a standard Interface Association Descriptor. This structure uses the relevant standard's given + /** \brief Standard USB Interface Association Descriptor (USB-IF naming conventions). + * + * Type define for a standard Interface Association Descriptor. This structure uses the relevant standard's given * element names to ensure compatibility with the standard. * * This descriptor has been added as a supplement to the USB2.0 standard, in the ECN located at @@ -475,7 +510,9 @@ */ } USB_StdDescriptor_Interface_Association_t; - /** Type define for a standard Endpoint Descriptor. This structure uses LUFA-specific element names + /** \brief Standard USB Endpoint Descriptor (LUFA naming conventions). + * + * Type define for a standard Endpoint Descriptor. This structure uses LUFA-specific element names * to make each element's purpose clearer. * * \see \ref USB_StdDescriptor_Endpoint_t for the version of this define with standard element names @@ -501,7 +538,9 @@ */ } USB_Descriptor_Endpoint_t; - /** Type define for a standard Endpoint Descriptor. This structure uses the relevant standard's given + /** \brief Standard USB Endpoint Descriptor (USB-IF naming conventions). + * + * Type define for a standard Endpoint Descriptor. This structure uses the relevant standard's given * element names to ensure compatibility with the standard. * * \see \ref USB_Descriptor_Endpoint_t for the version of this define with non-standard LUFA specific @@ -529,7 +568,9 @@ */ } USB_StdDescriptor_Endpoint_t; - /** Type define for a standard string descriptor. Unlike other standard descriptors, the length + /** \brief Standard USB String Descriptor (LUFA naming conventions). + * + * 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 \ref USB_STRING_LEN() * macro rather than by the size of the descriptor structure, as the length is not fixed. * @@ -544,20 +585,22 @@ { 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. - */ + wchar_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. + */ } USB_Descriptor_String_t; - /** Type define for a standard string descriptor. Unlike other standard descriptors, the length + /** \brief Standard USB String Descriptor (USB-IF naming conventions). + * + * 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 \ref USB_STRING_LEN() * macro rather than by the size of the descriptor structure, as the length is not fixed. * @@ -592,10 +635,10 @@ /* 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))) + #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: */