USBDescriptors.h

Go to the documentation of this file.

/* ---------------------------------------------------------------------------- */
/*                  Atmel Microcontroller Software Support                      */
/*                       SAM Software Package License                           */
/* ---------------------------------------------------------------------------- */
/* Copyright (c) 2015, Atmel Corporation                                        */
/*                                                                              */
/* All rights reserved.                                                         */
/*                                                                              */
/* Redistribution and use in source and binary forms, with or without           */
/* modification, are permitted provided that the following condition is 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.                           */
/* ---------------------------------------------------------------------------- */

#ifndef _USBDESCRIPTORS_H_
#define _USBDESCRIPTORS_H_

/*---------------------------------------------------------------------------
 *      Headers
 *---------------------------------------------------------------------------*/

/* These headers were introduced in C99 by working group
 * ISO/IEC JTC1/SC22/WG14.
 */
#include <stdint.h>

/*---------------------------------------------------------------------------
 *      Definitions
 *---------------------------------------------------------------------------*/

/*--------- Generic Descriptors --------*/

#define USBGenericDescriptor_DEVICE                     1

#define USBGenericDescriptor_CONFIGURATION              2

#define USBGenericDescriptor_STRING                     3

#define USBGenericDescriptor_INTERFACE                  4

#define USBGenericDescriptor_ENDPOINT                   5

#define USBGenericDescriptor_DEVICEQUALIFIER            6

#define USBGenericDescriptor_OTHERSPEEDCONFIGURATION    7

#define USBGenericDescriptor_INTERFACEPOWER             8

#define USBGenericDescriptor_OTG                        9

#define USBGenericDescriptor_DEBUG                      10

#define USBGenericDescriptor_INTERFACEASSOCIATION       11

#define USB_DT_BOS                                      0x0F

#define USBGenericDescriptor_DEVICE_CAPABILITY          0x10

#define  USB_EP_TYPE_MASK       0x03
#define  USB_EP_ADDR_MASK     0x0f

#define  USB_EP_DIR_IN        0x80

#define  USB_EP_DIR_OUT       0x00

#define  USB_REQ_DIR_OUT         (0<<7) 
#define  USB_REQ_DIR_IN          (1<<7) 
#define  USB_REQ_DIR_MASK        (1<<7) 


#define  USB_REQ_TYPE_STANDARD   (0<<5) 
#define  USB_REQ_TYPE_CLASS      (1<<5) 
#define  USB_REQ_TYPE_VENDOR     (2<<5) 
#define  USB_REQ_TYPE_MASK       (3<<5) 


#define  USB_REQ_RECIP_DEVICE    (0<<0) 
#define  USB_REQ_RECIP_INTERFACE (1<<0) 
#define  USB_REQ_RECIP_ENDPOINT  (2<<0) 
#define  USB_REQ_RECIP_OTHER     (3<<0) 
#define  USB_REQ_RECIP_MASK      (0x1F) 


enum usb_reqid {
        USB_REQ_GET_STATUS = 0,
        USB_REQ_CLEAR_FEATURE = 1,
        USB_REQ_SET_FEATURE = 3,
        USB_REQ_SET_ADDRESS = 5,
        USB_REQ_GET_DESCRIPTOR = 6,
        USB_REQ_SET_DESCRIPTOR = 7,
        USB_REQ_GET_CONFIGURATION = 8,
        USB_REQ_SET_CONFIGURATION = 9,
        USB_REQ_GET_INTERFACE = 10,
        USB_REQ_SET_INTERFACE = 11,
        USB_REQ_SYNCH_FRAME = 12,
};

enum usb_capability_type {
        USB_DC_USB20_EXTENSION = 0x02,
};

enum usb_capability_extension_attr {
        USB_DC_EXT_LPM  = 0x00000002,
        USB_DC_EXT_BESL = 0x00000004,
        USB_DC_EXT_BESL_BASELINE_VALID = 0x00000008,
        USB_DC_EXT_BESL_DEEP_VALID = 0x00000010,
};
#define USB_DC_EXT_BESL_DEEP_OFFSET       8
#define USB_DC_EXT_BESL_DEEP(besl)        ((besl & 0xF) << USB_DC_EXT_BESL_DEEP_OFFSET)
#define USB_DC_EXT_BESL_BASELINE_OFFSET   12
#define USB_DC_EXT_BESL_BASELINE(besl)    ((besl & 0xF) << USB_DC_EXT_BESL_BASELINE_OFFSET)

#define BESL_125_US   0
#define BESL_150_US   1
#define BESL_200_US   2
#define BESL_300_US   3
#define BESL_400_US   4
#define BESL_500_US   5
#define BESL_1000_US  6
#define BESL_2000_US  7
#define BESL_3000_US  8
#define BESL_4000_US  9
#define BESL_5000_US  10
#define BESL_6000_US  11
#define BESL_7000_US  12
#define BESL_8000_US  13
#define BESL_9000_US  14
#define BESL_10000_US 15

#define  USB_LPM_ATTRIBUT_BLINKSTATE_MASK      (0xF << 0)
#define  USB_LPM_ATTRIBUT_BESL_MASK            (0xF << 4)
#define  USB_LPM_ATTRIBUT_REMOTEWAKE_MASK      (1 << 8)
#define  USB_LPM_ATTRIBUT_BLINKSTATE(value)    ((value & 0xF) << 0)
#define  USB_LPM_ATTRIBUT_BESL(value)          ((value & 0xF) << 4)
#define  USB_LPM_ATTRIBUT_REMOTEWAKE(value)    ((value & 1) << 8)
#define  USB_LPM_ATTRIBUT_BLINKSTATE_L1        USB_LPM_ATTRIBUT_BLINKSTATE(1)


/******** END usb protocol */
/*--------- Device Descriptors --------*/

#define USBDeviceDescriptor_USB2_00         0x0200

#define USBDeviceDescriptor_USB2_01         0x0201

/*--------- Configuration Descriptors --------*/

#define USBConfigurationDescriptor_BUSPOWERED_NORWAKEUP  0x80

#define USBConfigurationDescriptor_SELFPOWERED_NORWAKEUP 0xC0

#define USBConfigurationDescriptor_BUSPOWERED_RWAKEUP    0xA0

#define USBConfigurationDescriptor_SELFPOWERED_RWAKEUP   0xE0

#define USBConfigurationDescriptor_REMOTE_WAKEUP        0x20

#define USBConfigurationDescriptor_POWER(power)     (power / 2)

#define USB_HOST_POWER_MAX  500

enum usb_interface_status {
        USB_IFACE_STATUS_RESERVED = 0
};

enum usb_endpoint_status {
        USB_EP_STATUS_HALTED = 1,
};

enum usb_endpoint_feature {
        USB_EP_FEATURE_HALT = 0,
};

enum usb_device_feature {
        USB_DEV_FEATURE_REMOTE_WAKEUP = 1, 
        USB_DEV_FEATURE_TEST_MODE = 2,     
        USB_DEV_FEATURE_OTG_B_HNP_ENABLE = 3,
        USB_DEV_FEATURE_OTG_A_HNP_SUPPORT = 4,
        USB_DEV_FEATURE_OTG_A_ALT_HNP_SUPPORT = 5
};

/*--------- Endpoint Descriptors --------*/

#define USBEndpointDescriptor_OUT           0

#define USBEndpointDescriptor_IN            1

#define  USB_EP_DIR_IN        0x80

#define  USB_EP_DIR_OUT       0x00

#define USBEndpointDescriptor_CONTROL       0

#define USBEndpointDescriptor_ISOCHRONOUS   1

#define USBEndpointDescriptor_BULK          2

#define USBEndpointDescriptor_INTERRUPT     3
   
  
#define USBEndpointDescriptor_Asynchronous_ISOCHRONOUS          (1<<2)
#define USBEndpointDescriptor_Adaptive_ISOCHRONOUS              (2<<2)
#define USBEndpointDescriptor_Synchronous_ISOCHRONOUS           (3<<2)
   
#define USBEndpointDescriptor_Feedback_ISOCHRONOUS              (1<<2)
#define USBEndpointDescriptor_Explicit_Feedback_ISOCHRONOUS     (2<<2) 

#define USBEndpointDescriptor_MAXCTRLSIZE_FS                64

#define USBEndpointDescriptor_MAXCTRLSIZE_HS                64

#define USBEndpointDescriptor_MAXBULKSIZE_FS                64

#define USBEndpointDescriptor_MAXBULKSIZE_HS                512

#define USBEndpointDescriptor_MAXINTERRUPTSIZE_FS           64

#define USBEndpointDescriptor_MAXINTERRUPTSIZE_HS           1024

#define USBEndpointDescriptor_MAXISOCHRONOUSSIZE_FS         1023

#define USBEndpointDescriptor_MAXISOCHRONOUSSIZE_HS         1024

#define USBEndpointDescriptor_ADDRESS(direction, number) \
    (((direction & 0x01) << 7) | (number & 0xF))

/*--------- Generic Descriptors --------*/

#define USBStringDescriptor_ENGLISH_US          0x09, 0x04

#define USBStringDescriptor_LENGTH(length)      ((length) * 2 + 2)

#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 struct _USBGenericDescriptor {

    uint8_t bLength;
    uint8_t bDescriptorType;

} __attribute__ ((__packed__)) USBGenericDescriptor; /* GCC */

typedef struct _USBDeviceDescriptor {

   uint8_t bLength;
   uint8_t bDescriptorType;
   uint16_t bcdUSB;
   uint8_t bDeviceClass;
   uint8_t bDeviceSubClass;
   uint8_t bDeviceProtocol;
   uint8_t bMaxPacketSize0;
   uint16_t idVendor;
   uint16_t idProduct;
   uint16_t bcdDevice;
   uint8_t iManufacturer;
   uint8_t iProduct;
   uint8_t iSerialNumber;
   uint8_t bNumConfigurations;

} __attribute__ ((__packed__)) USBDeviceDescriptor; /* GCC */

typedef struct _USBOtgDescriptor {

   uint8_t bLength;
   uint8_t bDescriptorType;
   uint8_t bmAttributes;

} __attribute__ ((__packed__)) USBOtgDescriptor; /* GCC */

typedef struct _USBDeviceQualifierDescriptor {

   uint8_t bLength;
   uint8_t bDescriptorType;
   uint16_t bcdUSB;
   uint8_t bDeviceClass;
   uint8_t bDeviceSubClass;
   uint8_t bDeviceProtocol;
   uint8_t bMaxPacketSize0;
   uint8_t bNumConfigurations;
   uint8_t bReserved;

} __attribute__ ((__packed__)) USBDeviceQualifierDescriptor; /* GCC */

typedef struct _USBConfigurationDescriptor {

   uint8_t bLength;
   uint8_t bDescriptorType;
   uint16_t wTotalLength;
   uint8_t bNumInterfaces;
   uint8_t bConfigurationValue;
   uint8_t iConfiguration;
   uint8_t bmAttributes;
   uint8_t bMaxPower;

} __attribute__ ((__packed__)) USBConfigurationDescriptor; /* GCC*/

typedef struct _USBDeviceBOSDescriptor{
        uint8_t     bLength;
        uint8_t     bDescriptorType;
        uint16_t    wTotalLength;
        uint8_t     bNumDeviceCaps;
} __attribute__ ((__packed__)) USBDeviceBOSDescriptor;


typedef struct _USBDeviceCapabilities{
        uint8_t bLength;
        uint8_t bDescriptorType;
        uint8_t bDevCapabilityType;
        uint32_t  bmAttributes;
} __attribute__ ((__packed__))  USBDeviceCapabilities;

typedef struct _USB_DeviceLPMDescriptor{
        USBDeviceBOSDescriptor bos;
        USBDeviceCapabilities capa_ext;
}__attribute__ ((__packed__))  USB_DeviceLPMDescriptor;

typedef struct _USBInterfaceAssociationDescriptor {

   uint8_t bLength;
   uint8_t bDescriptorType;
   uint8_t bFirstInterface;
   uint8_t bInterfaceCount;
   uint8_t bFunctionClass;
   uint8_t bFunctionSubClass;
   uint8_t bFunctionProtocol;
   uint8_t iFunction;
} __attribute__ ((__packed__)) USBInterfaceAssociationDescriptor; /* GCC*/

typedef struct _USBInterfaceDescriptor {

   uint8_t bLength;
   uint8_t bDescriptorType;
   uint8_t bInterfaceNumber;
   uint8_t bAlternateSetting;
   uint8_t bNumEndpoints;
   uint8_t bInterfaceClass;
   uint8_t bInterfaceSubClass;
   uint8_t bInterfaceProtocol;
   uint8_t iInterface;

} __attribute__ ((__packed__)) USBInterfaceDescriptor; /* GCC */

typedef struct _USBEndpointDescriptor {

   uint8_t bLength;
   uint8_t bDescriptorType;
   uint8_t bEndpointAddress;
   uint8_t bmAttributes;
   uint16_t wMaxPacketSize;
   uint8_t bInterval;

} __attribute__ ((__packed__)) USBEndpointDescriptor; /* GCC*/


typedef struct {
        uint8_t bLength;
        uint8_t bDescriptorType;
}__attribute__ ((__packed__)) USBStringDescriptor;

typedef struct {
        USBStringDescriptor desc;
        uint16_t string[1];
} __attribute__ ((__packed__))USBStringLangIdDescriptor;


#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_ */