/* ---------------------------------------------------------------------------- | |
* ATMEL Microcontroller Software Support | |
* ---------------------------------------------------------------------------- | |
* Copyright (c) 2010, Atmel Corporation | |
* | |
* All rights reserved. | |
* | |
* Redistribution and use in source and binary forms, with or without | |
* modification, are permitted provided that the following conditions are met: | |
* | |
* - Redistributions of source code must retain the above copyright notice, | |
* this list of conditions and the disclaimer below. | |
* | |
* Atmel's name may not be used to endorse or promote products derived from | |
* this software without specific prior written permission. | |
* | |
* DISCLAIMER: THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR | |
* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF | |
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE | |
* DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT, | |
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, | |
* OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF | |
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING | |
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, | |
* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
* ---------------------------------------------------------------------------- | |
*/ | |
/** \file | |
* \section Purpose | |
* | |
* Definitions and methods for USB descriptor structures described by the | |
* USB specification. | |
* | |
* \section Usage | |
* | |
*/ | |
#ifndef _USBDESCRIPTORS_H_ | |
#define _USBDESCRIPTORS_H_ | |
/** \addtogroup usb_general | |
* @{ | |
* \addtogroup usb_descriptor USB Descriptors | |
* @{ | |
*/ | |
/*--------------------------------------------------------------------------- | |
* Headers | |
*---------------------------------------------------------------------------*/ | |
/* These headers were introduced in C99 by working group | |
* ISO/IEC JTC1/SC22/WG14. | |
*/ | |
#include <stdint.h> | |
/*--------------------------------------------------------------------------- | |
* Definitions | |
*---------------------------------------------------------------------------*/ | |
/*--------- Generic Descriptors --------*/ | |
/** \addtogroup usb_desc_type USB Descriptor types | |
* @{ | |
* This section lists the codes of the usb descriptor types | |
* - \ref USBGenericDescriptor_DEVICE | |
* - \ref USBGenericDescriptor_CONFIGURATION | |
* - \ref USBGenericDescriptor_STRING | |
* - \ref USBGenericDescriptor_INTERFACE | |
* - \ref USBGenericDescriptor_ENDPOINT | |
* - \ref USBGenericDescriptor_DEVICEQUALIFIER | |
* - \ref USBGenericDescriptor_OTHERSPEEDCONFIGURATION | |
* - \ref USBGenericDescriptor_INTERFACEPOWER | |
* - \ref USBGenericDescriptor_OTG | |
* - \ref USBGenericDescriptor_DEBUG | |
* - \ref USBGenericDescriptor_INTERFACEASSOCIATION | |
*/ | |
/** Device descriptor type. */ | |
#define USBGenericDescriptor_DEVICE 1 | |
/** Configuration descriptor type. */ | |
#define USBGenericDescriptor_CONFIGURATION 2 | |
/** String descriptor type. */ | |
#define USBGenericDescriptor_STRING 3 | |
/** Interface descriptor type. */ | |
#define USBGenericDescriptor_INTERFACE 4 | |
/** Endpoint descriptor type. */ | |
#define USBGenericDescriptor_ENDPOINT 5 | |
/** Device qualifier descriptor type. */ | |
#define USBGenericDescriptor_DEVICEQUALIFIER 6 | |
/** Other speed configuration descriptor type. */ | |
#define USBGenericDescriptor_OTHERSPEEDCONFIGURATION 7 | |
/** Interface power descriptor type. */ | |
#define USBGenericDescriptor_INTERFACEPOWER 8 | |
/** On-The-Go descriptor type. */ | |
#define USBGenericDescriptor_OTG 9 | |
/** Debug descriptor type. */ | |
#define USBGenericDescriptor_DEBUG 10 | |
/** Interface association descriptor type. */ | |
#define USBGenericDescriptor_INTERFACEASSOCIATION 11 | |
/** @}*/ | |
/*--------- Device Descriptors --------*/ | |
/** \addtogroup usb_release_number USB release numbers | |
* @{ | |
* This section lists the codes of USB release numbers. | |
* - \ref USBDeviceDescriptor_USB2_00 | |
*/ | |
/** The device supports USB 2.00. */ | |
#define USBDeviceDescriptor_USB2_00 0x0200 | |
/** @}*/ | |
/*--------- Configuration Descriptors --------*/ | |
/** \addtogroup usb_attributes USB Device Attributes | |
* @{ | |
* This section lists the codes of the usb attributes. | |
* - \ref USBConfigurationDescriptor_BUSPOWERED_NORWAKEUP | |
* - \ref USBConfigurationDescriptor_SELFPOWERED_NORWAKEUP | |
* - \ref USBConfigurationDescriptor_BUSPOWERED_RWAKEUP | |
* - \ref USBConfigurationDescriptor_SELFPOWERED_RWAKEUP | |
* - \ref USBConfigurationDescriptor_POWER | |
*/ | |
/** Device is bus-powered and not support remote wake-up. */ | |
#define USBConfigurationDescriptor_BUSPOWERED_NORWAKEUP 0x80 | |
/** Device is self-powered and not support remote wake-up. */ | |
#define USBConfigurationDescriptor_SELFPOWERED_NORWAKEUP 0xC0 | |
/** Device is bus-powered and supports remote wake-up. */ | |
#define USBConfigurationDescriptor_BUSPOWERED_RWAKEUP 0xA0 | |
/** Device is self-powered and supports remote wake-up. */ | |
#define USBConfigurationDescriptor_SELFPOWERED_RWAKEUP 0xE0 | |
/** Calculates the value of the power consumption field given the value in mA. | |
* \param power The power consumption value in mA | |
* \return The value that should be set to the field in descriptor | |
*/ | |
#define USBConfigurationDescriptor_POWER(power) (power / 2) | |
/** @}*/ | |
/*--------- Endpoint Descriptors --------*/ | |
/** \addtogroup usb_ep_define USB Endpoint definitions | |
* @{ | |
* This section lists definitions and macro for endpoint descriptors. | |
* - \ref usb_ep_dir USB Endpoint directions | |
* - \ref USBEndpointDescriptor_OUT | |
* - \ref USBEndpointDescriptor_IN | |
* | |
* - \ref usb_ep_type USB Endpoint types | |
* - \ref USBEndpointDescriptor_CONTROL | |
* - \ref USBEndpointDescriptor_ISOCHRONOUS | |
* - \ref USBEndpointDescriptor_BULK | |
* - \ref USBEndpointDescriptor_INTERRUPT | |
* | |
* - \ref usb_ep_size USB Endpoint maximun sizes | |
* - \ref USBEndpointDescriptor_MAXCTRLSIZE_FS | |
* - \ref USBEndpointDescriptor_MAXCTRLSIZE_HS | |
* - \ref USBEndpointDescriptor_MAXBULKSIZE_FS | |
* - \ref USBEndpointDescriptor_MAXBULKSIZE_HS | |
* - \ref USBEndpointDescriptor_MAXINTERRUPTSIZE_FS | |
* - \ref USBEndpointDescriptor_MAXINTERRUPTSIZE_HS | |
* - \ref USBEndpointDescriptor_MAXISOCHRONOUSSIZE_FS | |
* - \ref USBEndpointDescriptor_MAXISOCHRONOUSSIZE_HS | |
* | |
* - \ref usb_ep_addr USB Endpoint address define | |
* - \ref USBEndpointDescriptor_ADDRESS | |
*/ | |
/** \addtogroup usb_ep_dir USB Endpoint directions | |
* @{ | |
* This section lists definitions of USB endpoint directions. | |
* - USBEndpointDescriptor_OUT | |
* - USBEndpointDescriptor_IN | |
*/ | |
/** Endpoint receives data from the host. */ | |
#define USBEndpointDescriptor_OUT 0 | |
/** Endpoint sends data to the host. */ | |
#define USBEndpointDescriptor_IN 1 | |
/** @}*/ | |
/** \addtogroup usb_ep_type USB Endpoint types | |
* @{ | |
* This section lists definitions of USB endpoint types. | |
* - \ref USBEndpointDescriptor_CONTROL | |
* - \ref USBEndpointDescriptor_ISOCHRONOUS | |
* - \ref USBEndpointDescriptor_BULK | |
* - \ref USBEndpointDescriptor_INTERRUPT | |
*/ | |
/** Control endpoint type. */ | |
#define USBEndpointDescriptor_CONTROL 0 | |
/** Isochronous endpoint type. */ | |
#define USBEndpointDescriptor_ISOCHRONOUS 1 | |
/** Bulk endpoint type. */ | |
#define USBEndpointDescriptor_BULK 2 | |
/** Interrupt endpoint type. */ | |
#define USBEndpointDescriptor_INTERRUPT 3 | |
/** @}*/ | |
/** \addtogroup usb_ep_size USB Endpoint maximun sizes | |
* @{ | |
* This section lists definitions of USB endpoint maximun sizes. | |
* - \ref USBEndpointDescriptor_MAXCTRLSIZE_FS | |
* - \ref USBEndpointDescriptor_MAXCTRLSIZE_HS | |
* - \ref USBEndpointDescriptor_MAXBULKSIZE_FS | |
* - \ref USBEndpointDescriptor_MAXBULKSIZE_HS | |
* - \ref USBEndpointDescriptor_MAXINTERRUPTSIZE_FS | |
* - \ref USBEndpointDescriptor_MAXINTERRUPTSIZE_HS | |
* - \ref USBEndpointDescriptor_MAXISOCHRONOUSSIZE_FS | |
* - \ref USBEndpointDescriptor_MAXISOCHRONOUSSIZE_HS | |
*/ | |
/** Maximum size for a full-speed control endpoint. */ | |
#define USBEndpointDescriptor_MAXCTRLSIZE_FS 64 | |
/** Maximum size for a high-speed control endpoint. */ | |
#define USBEndpointDescriptor_MAXCTRLSIZE_HS 64 | |
/** Maximum size for a full-speed bulk endpoint. */ | |
#define USBEndpointDescriptor_MAXBULKSIZE_FS 64 | |
/** Maximum size for a high-speed bulk endpoint. */ | |
#define USBEndpointDescriptor_MAXBULKSIZE_HS 512 | |
/** Maximum size for a full-speed interrupt endpoint. */ | |
#define USBEndpointDescriptor_MAXINTERRUPTSIZE_FS 64 | |
/** Maximum size for a high-speed interrupt endpoint. */ | |
#define USBEndpointDescriptor_MAXINTERRUPTSIZE_HS 1024 | |
/** Maximum size for a full-speed isochronous endpoint. */ | |
#define USBEndpointDescriptor_MAXISOCHRONOUSSIZE_FS 1023 | |
/** Maximum size for a high-speed isochronous endpoint. */ | |
#define USBEndpointDescriptor_MAXISOCHRONOUSSIZE_HS 1024 | |
/** @}*/ | |
/** \addtogroup usb_ep_addr USB Endpoint address define | |
* @{ | |
* This section lists macro for USB endpoint address definition. | |
* - \ref USBEndpointDescriptor_ADDRESS | |
*/ | |
/** | |
* Calculates the address of an endpoint given its number and direction | |
* \param direction USB endpoint direction definition | |
* \param number USB endpoint number | |
* \return The value used to set the endpoint descriptor based on input number | |
* and direction | |
*/ | |
#define USBEndpointDescriptor_ADDRESS(direction, number) \ | |
(((direction & 0x01) << 7) | (number & 0xF)) | |
/** @}*/ | |
/** @}*/ | |
/*--------- Generic Descriptors --------*/ | |
/** \addtogroup usb_string_descriptor USB String Descriptor Definitions | |
* @{ | |
* This section lists the codes and macros for USB string descriptor definition. | |
* | |
* \par Language IDs | |
* - USBStringDescriptor_ENGLISH_US | |
* | |
* \par String Descriptor Length | |
* - USBStringDescriptor_LENGTH | |
* | |
* \par ASCII to UNICODE convertion | |
* - USBStringDescriptor_UNICODE | |
*/ | |
/** Language ID for US english. */ | |
#define USBStringDescriptor_ENGLISH_US 0x09, 0x04 | |
/** | |
* Calculates the length of a string descriptor given the number of ascii | |
* characters/language IDs in it. | |
* \param length The ascii format string length. | |
* \return The actual data length in bytes. | |
*/ | |
#define USBStringDescriptor_LENGTH(length) ((length) * 2 + 2) | |
/** | |
* Converts an ascii character to its unicode representation. | |
* \param ascii The ASCII character to convert | |
* \return A 2-byte-array for the UNICODE based on given ASCII | |
*/ | |
#define USBStringDescriptor_UNICODE(ascii) (ascii), 0 | |
/** @}*/ | |
/*--------------------------------------------------------------------------- | |
* Types | |
*---------------------------------------------------------------------------*/ | |
/* | |
* Function types | |
*/ | |
typedef uint32_t (*USBDescriptorParseFunction)(void *descriptor, void *parseArg); | |
/* | |
* Descriptor structs types | |
*/ | |
#pragma pack(1) | |
#if defined ( __CC_ARM ) /* Keil ¦ÌVision 4 */ | |
#elif defined ( __ICCARM__ ) /* IAR Ewarm */ | |
#define __attribute__(...) | |
#define __packed__ packed | |
#elif defined ( __GNUC__ ) /* GCC CS3 */ | |
#define __packed__ aligned(1) | |
#endif | |
/** | |
\typedef USBGenericDescriptor | |
\brief Holds the few fields shared by all USB descriptors. | |
*/ | |
typedef struct _USBGenericDescriptor { | |
/** Length of the descriptor in bytes. */ | |
uint8_t bLength; | |
/** Descriptor type. */ | |
uint8_t bDescriptorType; | |
} __attribute__ ((__packed__)) USBGenericDescriptor; /* GCC */ | |
/** | |
* \typedef USBDeviceDescriptor | |
* \brief USB standard device descriptor structure. | |
*/ | |
typedef struct _USBDeviceDescriptor { | |
/** Size of this descriptor in bytes. */ | |
uint8_t bLength; | |
/** Descriptor type (USBGenericDescriptor_DEVICE). */ | |
uint8_t bDescriptorType; | |
/** USB specification release number in BCD format. */ | |
uint16_t bcdUSB; | |
/** Device class code. */ | |
uint8_t bDeviceClass; | |
/** Device subclass code. */ | |
uint8_t bDeviceSubClass; | |
/** Device protocol code. */ | |
uint8_t bDeviceProtocol; | |
/** Maximum packet size of endpoint 0 (in bytes). */ | |
uint8_t bMaxPacketSize0; | |
/** Vendor ID. */ | |
uint16_t idVendor; | |
/** Product ID. */ | |
uint16_t idProduct; | |
/** Device release number in BCD format. */ | |
uint16_t bcdDevice; | |
/** Index of the manufacturer string descriptor. */ | |
uint8_t iManufacturer; | |
/** Index of the product string descriptor. */ | |
uint8_t iProduct; | |
/** Index of the serial number string descriptor. */ | |
uint8_t iSerialNumber; | |
/** Number of possible configurations for the device. */ | |
uint8_t bNumConfigurations; | |
} __attribute__ ((__packed__)) USBDeviceDescriptor; /* GCC */ | |
/** | |
* \typedef USBOtgDescriptor | |
* \brief USB On-The-Go descriptor struct. | |
*/ | |
typedef struct _USBOtgDescriptor { | |
/** Size of this descriptor in bytes. */ | |
uint8_t bLength; | |
/** Descriptor type (USBGenericDescriptor_OTG). */ | |
uint8_t bDescriptorType; | |
/** Attribute Fields D7?: Reserved D1: HNP support D0: SRP support */ | |
uint8_t bmAttributes; | |
} __attribute__ ((__packed__)) USBOtgDescriptor; /* GCC */ | |
/** | |
* \typedef USBDeviceQualifierDescriptor | |
* \brief Alternate device descriptor indicating the capabilities of the device | |
* in full-speed, if currently in high-speed; or in high-speed, if it is | |
* currently in full-speed. Only relevant for devices supporting the | |
* high-speed mode. | |
*/ | |
typedef struct _USBDeviceQualifierDescriptor { | |
/** Size of the descriptor in bytes. */ | |
uint8_t bLength; | |
/** Descriptor type (USBDESC_DEVICE_QUALIFIER or "USB device types"). */ | |
uint8_t bDescriptorType; | |
/** USB specification release number (in BCD format). */ | |
uint16_t bcdUSB; | |
/** Device class code. */ | |
uint8_t bDeviceClass; | |
/** Device subclass code. */ | |
uint8_t bDeviceSubClass; | |
/** Device protocol code. */ | |
uint8_t bDeviceProtocol; | |
/** Maximum packet size of endpoint 0. */ | |
uint8_t bMaxPacketSize0; | |
/** Number of possible configurations for the device. */ | |
uint8_t bNumConfigurations; | |
/** Reserved. */ | |
uint8_t bReserved; | |
} __attribute__ ((__packed__)) USBDeviceQualifierDescriptor; /* GCC */ | |
/** | |
* \typedef USBConfigurationDescriptor | |
* \brief USB standard configuration descriptor structure. | |
*/ | |
typedef struct _USBConfigurationDescriptor { | |
/** Size of the descriptor in bytes. */ | |
uint8_t bLength; | |
/** Descriptor type | |
(USBDESC_CONFIGURATION of \ref usb_desc_type USB Descriptor types). */ | |
uint8_t bDescriptorType; | |
/** Length of all descriptors returned along with this configuration | |
descriptor. */ | |
uint16_t wTotalLength; | |
/** Number of interfaces in this configuration. */ | |
uint8_t bNumInterfaces; | |
/** Value for selecting this configuration. */ | |
uint8_t bConfigurationValue; | |
/** Index of the configuration string descriptor. */ | |
uint8_t iConfiguration; | |
/** Configuration characteristics. */ | |
uint8_t bmAttributes; | |
/** Maximum power consumption of the device when in this configuration. */ | |
uint8_t bMaxPower; | |
} __attribute__ ((__packed__)) USBConfigurationDescriptor; /* GCC*/ | |
/** | |
* \typedef USBInterfaceAssociationDescriptor | |
* \brief | |
*/ | |
typedef struct _USBInterfaceAssociationDescriptor { | |
unsigned char bLength; | |
unsigned char bDescriptorType; | |
unsigned char bFirstInterface; | |
unsigned char bInterfaceCount; | |
unsigned char bFunctionClass; | |
unsigned char bFunctionSubClass; | |
unsigned char bFunctionProtocol; | |
unsigned char iFunction; | |
} __attribute__ ((__packed__)) USBInterfaceAssociationDescriptor; /* GCC*/ | |
/** | |
* \typedef USBInterfaceDescriptor | |
* \brief USB standard interface descriptor structure. | |
*/ | |
typedef struct _USBInterfaceDescriptor { | |
/** Size of the descriptor in bytes. */ | |
uint8_t bLength; | |
/** Descriptor type (USBGenericDescriptor_INTERFACE). */ | |
uint8_t bDescriptorType; | |
/** Number of the interface in its configuration. */ | |
uint8_t bInterfaceNumber; | |
/** Value to select this alternate interface setting. */ | |
uint8_t bAlternateSetting; | |
/** Number of endpoints used by the inteface (excluding endpoint 0). */ | |
uint8_t bNumEndpoints; | |
/** Interface class code. */ | |
uint8_t bInterfaceClass; | |
/** Interface subclass code. */ | |
uint8_t bInterfaceSubClass; | |
/** Interface protocol code. */ | |
uint8_t bInterfaceProtocol; | |
/** Index of the interface string descriptor. */ | |
uint8_t iInterface; | |
} __attribute__ ((__packed__)) USBInterfaceDescriptor; /* GCC */ | |
/** | |
* \typedef USBEndpointDescriptor | |
* \brief USB standard endpoint descriptor structure. | |
*/ | |
typedef struct _USBEndpointDescriptor { | |
/** Size of the descriptor in bytes. */ | |
uint8_t bLength; | |
/** Descriptor type (\ref USBGenericDescriptor_ENDPOINT). */ | |
uint8_t bDescriptorType; | |
/** Address and direction of the endpoint. */ | |
uint8_t bEndpointAddress; | |
/** Endpoint type and additional characteristics | |
(for isochronous endpoints). */ | |
uint8_t bmAttributes; | |
/** Maximum packet size (in bytes) of the endpoint. */ | |
uint16_t wMaxPacketSize; | |
/** Polling rate of the endpoint. */ | |
uint8_t bInterval; | |
} __attribute__ ((__packed__)) USBEndpointDescriptor; /* GCC*/ | |
#pragma pack() | |
/*--------------------------------------------------------------------------- | |
* Exported Functions | |
*---------------------------------------------------------------------------*/ | |
extern uint32_t USBGenericDescriptor_GetLength( | |
const USBGenericDescriptor *descriptor); | |
extern uint8_t USBGenericDescriptor_GetType( | |
const USBGenericDescriptor *descriptor); | |
extern USBGenericDescriptor *USBGenericDescriptor_GetNextDescriptor( | |
const USBGenericDescriptor *descriptor); | |
extern USBGenericDescriptor *USBGenericDescriptor_Parse( | |
const USBGenericDescriptor * descriptor, | |
uint32_t totalLength, | |
USBDescriptorParseFunction parseFunction, | |
void * parseArg); | |
extern uint32_t USBConfigurationDescriptor_GetTotalLength( | |
const USBConfigurationDescriptor *configuration); | |
extern uint8_t USBConfigurationDescriptor_GetNumInterfaces( | |
const USBConfigurationDescriptor *configuration); | |
extern uint8_t USBConfigurationDescriptor_IsSelfPowered( | |
const USBConfigurationDescriptor *configuration); | |
extern void USBConfigurationDescriptor_Parse( | |
const USBConfigurationDescriptor *configuration, | |
USBInterfaceDescriptor **interfaces, | |
USBEndpointDescriptor **endpoints, | |
USBGenericDescriptor **others); | |
extern uint8_t USBEndpointDescriptor_GetNumber( | |
const USBEndpointDescriptor *endpoint); | |
extern uint8_t USBEndpointDescriptor_GetDirection( | |
const USBEndpointDescriptor *endpoint); | |
extern uint8_t USBEndpointDescriptor_GetType( | |
const USBEndpointDescriptor *endpoint); | |
extern uint16_t USBEndpointDescriptor_GetMaxPacketSize( | |
const USBEndpointDescriptor *endpoint); | |
extern uint8_t USBEndpointDescriptor_GetInterval( | |
const USBEndpointDescriptor *endpoint); | |
/** @}*/ | |
/**@}*/ | |
#endif /* #ifndef _USBDESCRIPTORS_H_ */ | |