X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/5f57785404e671f136f8c7e325922076d16fee30..3d4d8e7f628f9dc9981242f69b097333faa9940d:/LUFA/Drivers/USB/HighLevel/StdDescriptors.h diff --git a/LUFA/Drivers/USB/HighLevel/StdDescriptors.h b/LUFA/Drivers/USB/HighLevel/StdDescriptors.h index 1798365c5..7b8f4d7dc 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, 2010. - + Copyright (C) Dean Camera, 2011. + dean [at] fourwalledcubicle [dot] com - www.fourwalledcubicle.com + www.lufa-lib.org */ /* - Copyright 2010 Dean Camera (dean [at] fourwalledcubicle [dot] com) + Copyright 2011 Dean Camera (dean [at] fourwalledcubicle [dot] com) - Permission to use, copy, modify, distribute, and sell this + 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 + 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 + 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 @@ -38,26 +38,27 @@ */ /** \ingroup Group_USB - * @defgroup Group_Descriptors USB Descriptors + * \defgroup Group_Descriptors USB Descriptors * * Standard USB device descriptor defines and retrieval routines, for USB devices. This module contains * structures and macros for the easy creation of standard USB descriptors in USB device projects. * * @{ */ - + #ifndef __USBDESCRIPTORS_H__ #define __USBDESCRIPTORS_H__ /* Includes: */ #include #include + #include #include #include "../../../Common/Common.h" #include "USBMode.h" #include "Events.h" - + #if defined(USB_CAN_BE_DEVICE) #include "../LowLevel/Device.h" #endif @@ -71,7 +72,7 @@ #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 @@ -97,15 +98,15 @@ #else #define USE_INTERNAL_SERIAL NO_DESCRIPTOR #endif - - /** Macro to calculate the power value for the configuration descriptor, from a given number of milliamps. */ + + /** Macro to calculate the power value for the configuration descriptor, from a given number of milliamperes. */ #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)) - + /** 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. @@ -118,6 +119,8 @@ */ #define LANGUAGE_ID_ENG 0x0409 + /** \name Endpoint Address Direction Masks */ + //@{ /** Can be masked with an endpoint address for a \ref USB_Descriptor_Endpoint_t endpoint descriptor's * EndpointAddress value to indicate to the host that the endpoint is of the IN direction (i.e, from * device to host). @@ -128,8 +131,11 @@ * EndpointAddress value to indicate to the host that the endpoint is of the OUT direction (i.e, from * host to device). */ - #define ENDPOINT_DESCRIPTOR_DIR_OUT 0x00 + #define ENDPOINT_DESCRIPTOR_DIR_OUT 0x00 + //@} + /** \name USB Configuration Descriptor Attribute Masks */ + //@{ /** 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 can draw its power * from the host's VBUS line. @@ -148,7 +154,10 @@ * request. */ #define USB_CONFIG_ATTR_REMOTEWAKEUP 0x20 - + //@} + + /** \name Endpoint Descriptor Attribute Masks */ + //@{ /** 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. * @@ -176,7 +185,10 @@ * \see The USB specification for more details on the possible Endpoint attributes. */ #define ENDPOINT_ATTR_SYNC (3 << 2) + //@} + /** \name Endpoint Descriptor Usage Masks */ + //@{ /** 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 used for data transfers. * @@ -197,20 +209,55 @@ * \see The USB specification for more details on the possible Endpoint usage attributes. */ #define ENDPOINT_USAGE_IMPLICIT_FEEDBACK (2 << 4) - + //@} + /* Enums: */ /** Enum for the possible standard descriptor types, as given in each descriptor's header. */ enum USB_DescriptorTypes_t { - DTYPE_Device = 0x01, /**< Indicates that the descriptor is a device descriptor. */ - DTYPE_Configuration = 0x02, /**< Indicates that the descriptor is a configuration descriptor. */ - DTYPE_String = 0x03, /**< Indicates that the descriptor is a string descriptor. */ - DTYPE_Interface = 0x04, /**< Indicates that the descriptor is an interface descriptor. */ - DTYPE_Endpoint = 0x05, /**< Indicates that the descriptor is an endpoint descriptor. */ - DTYPE_DeviceQualifier = 0x06, /**< Indicates that the descriptor is a device qualifier descriptor. */ - DTYPE_Other = 0x07, /**< Indicates that the descriptor is of other type. */ - DTYPE_InterfacePower = 0x08, /**< Indicates that the descriptor is an interface power descriptor. */ - DTYPE_InterfaceAssociation = 0x0B, /**< Indicates that the descriptor is an interface association descriptor. */ + DTYPE_Device = 0x01, /**< Indicates that the descriptor is a device descriptor. */ + DTYPE_Configuration = 0x02, /**< Indicates that the descriptor is a configuration descriptor. */ + DTYPE_String = 0x03, /**< Indicates that the descriptor is a string descriptor. */ + DTYPE_Interface = 0x04, /**< Indicates that the descriptor is an interface descriptor. */ + DTYPE_Endpoint = 0x05, /**< Indicates that the descriptor is an endpoint descriptor. */ + DTYPE_DeviceQualifier = 0x06, /**< Indicates that the descriptor is a device qualifier descriptor. */ + DTYPE_Other = 0x07, /**< Indicates that the descriptor is of other type. */ + DTYPE_InterfacePower = 0x08, /**< Indicates that the descriptor is an interface power descriptor. */ + DTYPE_InterfaceAssociation = 0x0B, /**< Indicates that the descriptor is an interface association descriptor. */ + DTYPE_CSInterface = 0x24, /**< Indicates that the descriptor is a class specific interface descriptor. */ + DTYPE_CSEndpoint = 0x25, /**< Indicates that the descriptor is a class specific endpoint descriptor. */ + }; + + /** Enum for possible Class, Subclass and Protocol values of device and interface descriptors. */ + enum USB_Descriptor_ClassSubclassProtocol_t + { + USB_CSCP_NoDeviceClass = 0x00, /**< Descriptor Class value indicating that the device does not belong + * to a particular class at the device level. + */ + USB_CSCP_NoDeviceSubclass = 0x00, /**< Descriptor Subclass value indicating that the device does not belong + * to a particular subclass at the device level. + */ + USB_CSCP_NoDeviceProtocol = 0x00, /**< Descriptor Protocol value indicating that the device does not belong + * to a particular protocol at the device level. + */ + USB_CSCP_VendorSpecificClass = 0xFF, /**< Descriptor Class value indicating that the device/interface belongs + * to a vendor specific class. + */ + USB_CSCP_VendorSpecificSubclass = 0xFF, /**< Descriptor Subclass value indicating that the device/interface belongs + * to a vendor specific subclass. + */ + USB_CSCP_VendorSpecificProtocol = 0xFF, /**< Descriptor Protocol value indicating that the device/interface belongs + * to a vendor specific protocol. + */ + USB_CSCP_IADDeviceClass = 0xEF, /**< Descriptor Class value indicating that the device belongs to the + * Interface Association Descriptor class. + */ + USB_CSCP_IADDeviceSubclass = 0x02, /**< Descriptor Subclass value indicating that the device belongs to the + * Interface Association Descriptor subclass. + */ + USB_CSCP_IADDeviceProtocol = 0x01, /**< Descriptor Protocol value indicating that the device belongs to the + * Interface Association Descriptor protocol. + */ }; /* Type Defines: */ @@ -219,7 +266,7 @@ * 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. + * \see \ref USB_StdDescriptor_Header_t for the version of this type with standard element names. */ typedef struct { @@ -228,13 +275,13 @@ * given by the specific class. */ } USB_Descriptor_Header_t; - + /** \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. + * \see \ref USB_Descriptor_Header_t for the version of this type with non-standard LUFA specific element names. */ typedef struct { @@ -243,13 +290,13 @@ * given by the specific class. */ } USB_StdDescriptor_Header_t; - + /** \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. + * \see \ref USB_StdDescriptor_Device_t for the version of this type with standard element names. */ typedef struct { @@ -259,13 +306,13 @@ uint8_t Class; /**< USB device class. */ uint8_t SubClass; /**< USB device subclass. */ uint8_t Protocol; /**< USB device protocol. */ - + uint8_t Endpoint0Size; /**< Size of the control (address 0) endpoint's bank in bytes. */ - + 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. */ - + 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. @@ -298,7 +345,7 @@ * 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. + * \see \ref USB_Descriptor_Device_t for the version of this type with non-standard LUFA specific element names. */ typedef struct { @@ -346,12 +393,12 @@ * 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. + * \see \ref USB_StdDescriptor_Configuration_Header_t for the version of this type with standard element names. */ typedef struct { 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. */ @@ -359,23 +406,23 @@ 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 \ref USB_CONFIG_POWER_MA() * macro. */ } USB_Descriptor_Configuration_Header_t; - + /** \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. + * \see \ref USB_Descriptor_Device_t for the version of this type with non-standard LUFA specific element names. */ typedef struct { @@ -403,7 +450,7 @@ * 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. + * \see \ref USB_StdDescriptor_Interface_t for the version of this type with standard element names. */ typedef struct { @@ -416,20 +463,20 @@ * 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. */ } USB_Descriptor_Interface_t; - + /** \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. + * \see \ref USB_Descriptor_Interface_t for the version of this type with non-standard LUFA specific element names. */ typedef struct { @@ -458,17 +505,17 @@ * 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 - * http://www.usb.org/developers/docs/InterfaceAssociationDescriptor_ecn.pdf. It allows compound + * http://www.usb.org/developers/docs/InterfaceAssociationDescriptor_ecn.pdf. It allows composite * 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. * - * \see \ref USB_StdDescriptor_Interface_Association_t for the version of this define with standard element names. + * \see \ref USB_StdDescriptor_Interface_Association_t for the version of this type with standard element names. */ typedef struct { 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. */ @@ -480,19 +527,19 @@ * interface association. */ } USB_Descriptor_Interface_Association_t; - + /** \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 - * http://www.usb.org/developers/docs/InterfaceAssociationDescriptor_ecn.pdf. It allows compound + * http://www.usb.org/developers/docs/InterfaceAssociationDescriptor_ecn.pdf. It allows composite * 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. * - * \see \ref USB_Descriptor_Interface_Association_t for the version of this define with non-standard LUFA specific + * \see \ref USB_Descriptor_Interface_Association_t for the version of this type with non-standard LUFA specific * element names. */ typedef struct @@ -516,7 +563,7 @@ * 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. + * \see \ref USB_StdDescriptor_Endpoint_t for the version of this type with standard element names. */ typedef struct { @@ -535,13 +582,13 @@ * or ISOCHRONOUS type. */ } USB_Descriptor_Endpoint_t; - + /** \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 + * \see \ref USB_Descriptor_Endpoint_t for the version of this type with non-standard LUFA specific * element names. */ typedef struct @@ -550,10 +597,10 @@ uint8_t bDescriptorType; /**< Type of the descriptor, either a value in \ref USB_DescriptorTypes_t or a * value given by the specific class. */ - uint8_t bEndpointAddress; /**< Logical address of the endpoint within the device for the current + uint8_t bEndpointAddress; /**< Logical address of the endpoint within the device for the current * configuration, including direction mask. */ - uint8_t bmAttributes; /**< Endpoint attributes, comprised of a mask of the endpoint type (EP_TYPE_*) + uint8_t bmAttributes; /**< Endpoint attributes, comprised of a mask of the endpoint type (EP_TYPE_*) * and attributes (ENDPOINT_ATTR_*) masks. */ uint16_t wMaxPacketSize; /**< Size of the endpoint bank, in bytes. This indicates the maximum packet size @@ -575,12 +622,12 @@ * * This structure uses LUFA-specific element names to make each element's purpose clearer. * - * \see \ref USB_StdDescriptor_String_t for the version of this define with standard element names. + * \see \ref USB_StdDescriptor_String_t for the version of this type with standard element names. */ typedef struct { USB_Descriptor_Header_t Header; /**< Descriptor header, including type and size. */ - + 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 @@ -605,7 +652,7 @@ * * This structure uses the relevant standard's given element names to ensure compatibility with the standard. * - * \see \ref USB_Descriptor_String_t for the version of this define with with non-standard LUFA specific + * \see \ref USB_Descriptor_String_t for the version of this type with with non-standard LUFA specific * element names. */ typedef struct @@ -633,12 +680,13 @@ #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 /** @} */ +