/* ----------------------------------------------------------------------------
 *         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
 */
#ifdef __ICCARM__          /* IAR */
#pragma pack(1)            /* IAR */
#define __attribute__(...) /* IAR */
#endif                     /* IAR */

/**
 \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*/


#ifdef __ICCARM__          /* IAR */
#pragma pack()             /* IAR */
#endif                     /* IAR */

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

