path: root/include/arch/rm46l8lp/halcogen/usblib.h

/* 
* Copyright (C) 2009-2018 Texas Instruments Incorporated - www.ti.com 
* 
* 
*  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 following disclaimer.
*
*    Redistributions in binary form must reproduce the above copyright
*    notice, this list of conditions and the following disclaimer in the 
*    documentation and/or other materials provided with the   
*    distribution.
*
*    Neither the name of Texas Instruments Incorporated nor the names of
*    its contributors may be used to endorse or promote products derived
*    from this software without specific prior written permission.
*
*  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
*  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
*  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
*  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
*  OWNER OR CONTRIBUTORS 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       usblib.h
 *
 *  @brief      Main header file for the USB Library.
 * 
 */

#ifndef __USBLIB_H__
#define __USBLIB_H__

/******************************************************************************
 *
 * If building with a C++ compiler, make all of the definitions in this header
 * have a C binding.
 *
 *****************************************************************************/
#ifdef __cplusplus
extern "C"
{
#endif



/* standard device requests -- USB_SetupDataPacket::bRequest */
#define USB_REQUEST_GETSTATUS           (0u)
#define USB_REQUEST_CLEARFEATURE        (1u)
#define USB_REQUEST_SETFEATURE          (3u)
#define USB_REQUEST_SETADDRESS          (5u)
#define USB_REQUEST_GETDESCRIPTOR       (6u)
#define USB_REQUEST_SETDESCRIPTOR       (7u)
#define USB_REQUEST_GETCONFIGURATION    (8u)
#define USB_REQUEST_SETCONFIGURATION    (9u)
#define USB_REQUEST_GETINTERFACE        (10u)
#define USB_REQUEST_SETINTERFACE        (11u)
#define USB_REQUEST_SYNCHFRAME          (12u)


/** ***************************************************************************
 *
 * This is the maximum number of endpoints supported by the usblib.
 *
 *****************************************************************************/
#define USBLIB_NUM_EP           16u   /* Number of supported endpoints. */

/******************************************************************************
 *
 * The following macro allows compiler-independent syntax to be used to
 * define packed structures.  A typical structure definition using these
 * macros will look similar to the following example:
 *
 *   #ifdef ewarm
 *   #pragma pack(1)
 *   #endif
 *
 *   typedef struct _PackedStructName
 *   {
 *      uint32 ulFirstField;
 *      char cCharMember;
 *      uint16 usShort;
 *   }
 *   PACKED tPackedStructName;
 *
 *   #ifdef ewarm
 *   #pragma pack()
 *   #endif
 *
 * The conditional blocks related to ewarm include the #pragma pack() lines
 * only if the IAR Embedded Workbench compiler is being used.  Unfortunately,
 * it is not possible to emit a #pragma from within a macro definition so this
 * must be done explicitly.
 *
 *****************************************************************************/
#if defined(ccs) ||             \
    defined(codered) ||         \
    defined(gcc) ||             \
    defined(rvmdk) ||           \
    defined(__ARMCC_VERSION) || \
    defined(sourcerygxx)
#define PACKED __attribute__ ((packed))
#elif defined(ewarm) || defined(__IAR_SYSTEMS_ICC__)
#define PACKED
#elif (__TMS470__)
#define PACKED __attribute__ ((packed))
#else
#error Unrecognized COMPILER!
#endif

/******************************************************************************
 *
 * Assorted language IDs from the document "USB_LANGIDs.pdf" provided by the
 * USB Implementers' Forum (Version 1.0).
 *
 *****************************************************************************/
#define USB_LANG_CHINESE_PRC    0x0804u      /**< Chinese (PRC) */
#define USB_LANG_CHINESE_TAIWAN 0x0404u      /**< Chinese (Taiwan) */
#define USB_LANG_EN_US          0x0409u      /**< English (United States) */
#define USB_LANG_EN_UK          0x0809u      /**< English (United Kingdom) */
#define USB_LANG_EN_AUS         0x0C09u      /**< English (Australia) */
#define USB_LANG_EN_CA          0x1009u      /**< English (Canada) */
#define USB_LANG_EN_NZ          0x1409u      /**< English (New Zealand) */
#define USB_LANG_FRENCH         0x040Cu      /**< French (Standard) */
#define USB_LANG_GERMAN         0x0407u      /**< German (Standard) */
#define USB_LANG_HINDI          0x0439u      /**< Hindi */
#define USB_LANG_ITALIAN        0x0410u      /**< Italian (Standard) */
#define USB_LANG_JAPANESE       0x0411u      /**< Japanese */
#define USB_LANG_KOREAN         0x0412u      /**< Korean */
#define USB_LANG_ES_TRAD        0x040Au      /**< Spanish (Traditional) */
#define USB_LANG_ES_MODERN      0x0C0Au      /**< Spanish (Modern) */
#define USB_LANG_SWAHILI        0x0441u      /**< Swahili (Kenya) */
#define USB_LANG_URDU_IN        0x0820u      /**< Urdu (India) */
#define USB_LANG_URDU_PK        0x0420u      /**< Urdu (Pakistan) */
/** ***************************************************************************
 *
 *  @ingroup usbchap9_src
 *  @{
 *
 *****************************************************************************/

/******************************************************************************
 *
 * Note:
 *
 * Structure definitions which are derived directly from the USB specification
 * use field names from the specification.  Since a somewhat different version
 * of Hungarian prefix notation is used from the Stellaris standard, beware of
 * making assumptions about field sizes based on the field prefix when using
 * these structures.  Of particular note is the difference in the meaning of
 * the 'i' prefix.  In USB structures, this indicates a single byte index
 * whereas in Stellaris code, this is a 32 bit integer.
 *
 *****************************************************************************/

/******************************************************************************
 *
 * All structures defined in this section of the header require byte packing of
 * fields.  This is usually accomplished using the PACKED macro but, for IAR
 * Embedded Workbench, this requires a pragma.
 *
 *****************************************************************************/
#if defined(ewarm) || defined(__IAR_SYSTEMS_ICC__)
#pragma pack(1)
#endif

/******************************************************************************
 *
 * Definitions related to standard USB device requests (sections 9.3 & 9.4)
 *
 *****************************************************************************/

/** ***************************************************************************
 *
 *  @brief  The standard USB request header as defined in section 9.3 of the 
 *          USB 2.0 specification.
 *
 *****************************************************************************/
typedef struct
{
    /**
     *  @brief  Determines the type and direction of the request.
     */
    uint8 bmRequestType;

    /**
     *  @brief  Identifies the specific request being made.
     */
    uint8 bRequest;

    /**
     *  @brief  Word-sized field that varies according to the request.
     */
    uint16 wValue;

    /**
     *  @brief  Word-sized field that varies according to the request; typically used
     *          to pass an index or offset.
     */
    uint16 wIndex;

    /**
     *  @brief  The number of bytes to transfer if there is a data stage to the
     *          request.
     */
    uint16 wLength;

}
PACKED tUSBRequest;

/******************************************************************************
 *
 * The following defines are used with the bmRequestType member of tUSBRequest.
 *
 * Request types have 3 bit fields:
 * 4:0 - Is the recipient type.
 * 6:5 - Is the request type.
 * 7 - Is the direction of the request.
 *
 *****************************************************************************/
#define USB_RTYPE_DIR_IN        0x80u
#define USB_RTYPE_DIR_OUT       0x00u

#define USB_RTYPE_TYPE_M        0x60u
#define USB_RTYPE_VENDOR        0x40u
#define USB_RTYPE_CLASS         0x20u
#define USB_RTYPE_STANDARD      0x00u

#define USB_RTYPE_RECIPIENT_M   0x1fu
#define USB_RTYPE_OTHER         0x03u
#define USB_RTYPE_ENDPOINT      0x02u
#define USB_RTYPE_INTERFACE     0x01u
#define USB_RTYPE_DEVICE        0x00u

/******************************************************************************
 *
 * Standard USB requests IDs used in the bRequest field of tUSBRequest.
 *
 *****************************************************************************/
#define USBREQ_GET_STATUS       0x00u
#define USBREQ_CLEAR_FEATURE    0x01u
#define USBREQ_SET_FEATURE      0x03u
#define USBREQ_SET_ADDRESS      0x05u
#define USBREQ_GET_DESCRIPTOR   0x06u
#define USBREQ_SET_DESCRIPTOR   0x07u
#define USBREQ_GET_CONFIG       0x08u
#define USBREQ_SET_CONFIG       0x09u
#define USBREQ_GET_INTERFACE    0x0au
#define USBREQ_SET_INTERFACE    0x0bu
#define USBREQ_SYNC_FRAME       0x0cu

#define USBREQ_COUNT            (USBREQ_SYNC_FRAME + 1u)

/******************************************************************************
 *
 * Data returned from a USBREQ_GET_STATUS request to a device.
 *
 *****************************************************************************/
#define USB_STATUS_SELF_PWR     0x0001u  /**< Currently self powered. */
#define USB_STATUS_BUS_PWR      0x0000u  /**< Currently bus-powered. */
#define USB_STATUS_PWR_M        0x0001u  /**< Mask for power mode. */
#define USB_STATUS_REMOTE_WAKE  0x0002u  /**< Remote wake-up is currently 
                                             enabled. */

/******************************************************************************
 *
 * Feature Selectors (tUSBRequest.wValue) passed on USBREQ_CLEAR_FEATURE and
 * USBREQ_SET_FEATURE.
 *
 *****************************************************************************/
#define USB_FEATURE_EP_HALT     0x0000u  /**< Endpoint halt feature. */
#define USB_FEATURE_REMOTE_WAKE 0x0001u  /**< Remote wake feature, device only. */
#define USB_FEATURE_TEST_MODE   0x0002u  /**< Test mode */

/******************************************************************************
 *
 * Endpoint Selectors (tUSBRequest.wIndex) passed on USBREQ_CLEAR_FEATURE,
 * USBREQ_SET_FEATURE and USBREQ_GET_STATUS.
 *
 *****************************************************************************/
#define USB_REQ_EP_NUM_M   0x007Fu
#define USB_REQ_EP_DIR_M   0x0080u
#define USB_REQ_EP_DIR_IN  0x0080u
#define USB_REQ_EP_DIR_OUT 0x0000u

/******************************************************************************
 *
 * Standard USB descriptor types.  These values are passed in the upper bytes
 * of tUSBRequest.wValue on USBREQ_GET_DESCRIPTOR and also appear in the
 * bDescriptorType field of standard USB descriptors.
 *
 *****************************************************************************/
#define USB_DTYPE_DEVICE        1u
#define USB_DTYPE_CONFIGURATION 2u
#define USB_DTYPE_STRING        3u
#define USB_DTYPE_INTERFACE     4u
#define USB_DTYPE_ENDPOINT      5u
#define USB_DTYPE_DEVICE_QUAL   6u
#define USB_DTYPE_OSPEED_CONF   7u
#define USB_DTYPE_INTERFACE_PWR 8u
#define USB_DTYPE_OTG           9u
#define USB_DTYPE_INTERFACE_ASC 11u
#define USB_DTYPE_CS_INTERFACE  36u

/******************************************************************************
 *
 * Definitions related to USB descriptors (sections 9.5 & 9.6)
 *
 *****************************************************************************/

/** ***************************************************************************
 *
 *  @brief      This structure describes a generic descriptor header.  These 
 *              fields are to be found at the beginning of all valid USB 
 *              descriptors.
 *
 *****************************************************************************/
typedef struct
{
    /**
     *  @brief  The length of this descriptor (including this length byte) expressed
     *          in bytes.
     */
    uint8 bLength;

    /**
     *  @brief  The type identifier of the descriptor whose information follows.
     *          For standard descriptors, this field could contain, for example,
     *          USB_DTYPE_DEVICE to identify a device descriptor or
	 *          USB_DTYPE_ENDPOINT to identify an endpoint descriptor.
     */
    uint8 bDescriptorType;
}
PACKED tDescriptorHeader;

/** ***************************************************************************
 *
 *  @brief This structure describes the USB device descriptor as defined in USB
 *         2.0 specification section 9.6.1.
 *
 *****************************************************************************/
typedef struct
{
    /**
     *  @brief  The length of this descriptor in bytes.  All device descriptors
	 *          are 18 bytes long.
     */
    uint8 bLength;

    /**
     *  @brief  The type of the descriptor.  For a device descriptor, this will
     *          be USB_DTYPE_DEVICE (1).
     */
    uint8 bDescriptorType;

    /**
     *  @brief  The USB Specification Release Number in BCD format.  
	 *          For USB 2.0, this will be 0x0200.
     */
    uint16 bcdUSB;

    /**
     *  @brief  The device class code.
     */
    uint8 bDeviceClass;

    /**
     *  @brief  The device subclass code.  This value qualifies the value 
	 *          found in the bDeviceClass field.
     */
    uint8 bDeviceSubClass;

    /**
     *  @brief  The device protocol code.  This value is qualified by the 
	 *          values of bDeviceClass and bDeviceSubClass.
     */
    uint8 bDeviceProtocol;

    /**
     *  @brief  The maximum packet size for endpoint zero.  Valid values 
	 *          are 8, 16, 32 and 64.
     */
    uint8 bMaxPacketSize0;

    /**
     *  @brief  The device Vendor ID (VID) as assigned by the USB-IF.
     */
    uint16 idVendor;

    /**
     *  @brief  The device Product ID (PID) as assigned by the manufacturer.
     */
    uint16 idProduct;

    /**
     *  @brief  The device release number in BCD format.
     */
    uint16 bcdDevice;

    /**
     *  @brief  The index of a string descriptor describing the manufacturer.
     */
    uint8 iManufacturer;

    /**
     *  @brief  The index of a string descriptor describing the product.
     */
    uint8 iProduct;

    /**
     *  @brief  The index of a string descriptor describing the device's serial
     *          number.
     */
    uint8 iSerialNumber;

    /**
     *  @brief  The number of possible configurations offered by the device.
	 *          This field indicates the number of distinct configuration 
	 *          descriptors that the device offers.
     */
    uint8 bNumConfigurations;
}
PACKED tDeviceDescriptor;

/******************************************************************************
 *
 * USB Device Class codes used in the tDeviceDescriptor.bDeviceClass field.
 * Definitions for the bDeviceSubClass and bDeviceProtocol fields are device
 * specific and can be found in the appropriate device class header files.
 *
 *****************************************************************************/
#define USB_CLASS_DEVICE        0x00u
#define USB_CLASS_AUDIO         0x01u
#define USB_CLASS_CDC           0x02u
#define USB_CLASS_HID           0x03u
#define USB_CLASS_PHYSICAL      0x05u
#define USB_CLASS_IMAGE         0x06u
#define USB_CLASS_PRINTER       0x07u
#define USB_CLASS_MASS_STORAGE  0x08u
#define USB_CLASS_HUB           0x09u
#define USB_CLASS_CDC_DATA      0x0au
#define USB_CLASS_SMART_CARD    0x0bu
#define USB_CLASS_SECURITY      0x0du
#define USB_CLASS_VIDEO         0x0eu
#define USB_CLASS_HEALTHCARE    0x0fu
#define USB_CLASS_DIAG_DEVICE   0xdcu
#define USB_CLASS_WIRELESS      0xe0u
#define USB_CLASS_MISC          0xefu
#define USB_CLASS_APP_SPECIFIC  0xfeu
#define USB_CLASS_VEND_SPECIFIC 0xffu
#define USB_CLASS_EVENTS        0xffffffffU

/******************************************************************************
 *
 * Generic values for undefined subclass and protocol.
 *
 *****************************************************************************/
#define USB_SUBCLASS_UNDEFINED  0x00u
#define USB_PROTOCOL_UNDEFINED  0x00u

/******************************************************************************
 *
 * The following are the miscellaneous subclass values.
 *
 *****************************************************************************/
#define USB_MISC_SUBCLASS_SYNC      0x01u
#define USB_MISC_SUBCLASS_COMMON    0x02u

/******************************************************************************
 *
 * These following are miscellaneous protocol values.
 *
 *****************************************************************************/
#define USB_MISC_PROTOCOL_IAD   0x01u

/** ***************************************************************************
 *
 *  @brief  This structure describes the USB device qualifier descriptor as 
 *          defined in the USB 2.0 specification, section 9.6.2.
 *
 *****************************************************************************/
typedef struct
{
    /**
     *  @brief  The length of this descriptor in bytes.  All device qualifier
     *          descriptors are 10 bytes long.
     */
    uint8 bLength;

    /**
     *  @brief  The type of the descriptor.  For a device descriptor, this will
     *          be USB_DTYPE_DEVICE_QUAL (6).
     */
    uint8 bDescriptorType;

    /**
     *  @brief  The USB Specification Release Number in BCD format.  
	 *          For USB 2.0, this will be 0x0200.
     */
    uint16 bcdUSB;

    /**
     *  @brief  The device class code.
     */
    uint8 bDeviceClass;

    /**
     *  @brief  The device subclass code.  This value qualifies the value 
	 *          found in the bDeviceClass field.
     */
    uint8 bDeviceSubClass;

    /**
     *  @brief  The device protocol code.  This value is qualified by the 
	 *          values of bDeviceClass and bDeviceSubClass.
     */
    uint8 bDeviceProtocol;

    /**
     *  @brief  The maximum packet size for endpoint zero when operating at
     *          a speed other than high speed.
     */
    uint8 bMaxPacketSize0;

    /**
     *  @brief  The number of other-speed configurations supported.
     */
    uint8 bNumConfigurations;

    /**
     *  @brief  Reserved for future use.  Must be set to zero.
     */
    uint8 bReserved;
}
PACKED tDeviceQualifierDescriptor;

/** ***************************************************************************
 *
 *  This structure describes the USB configuration descriptor as defined in
 *  USB 2.0 specification section 9.6.3.  This structure also applies to the
 *  USB other speed configuration descriptor defined in section 9.6.4.
 *
 *****************************************************************************/
typedef struct
{
    /**
     *  @brief  The length of this descriptor in bytes.  All configuration 
	 *          descriptors are 9 bytes long.
     */
    uint8 bLength;

    /**
     *  @brief  The type of the descriptor.  For a configuration descriptor, 
	 *          this will be USB_DTYPE_CONFIGURATION (2).
     */
    uint8 bDescriptorType;

    /**
     *  @brief  The total length of data returned for this configuration.  
	 *          This includes the combined length of all descriptors 
	 *          (configuration, interface, endpoint and class- or 
	 *           vendor-specific) returned for this configuration.
     */
    uint16 wTotalLength;

    /**
     *  @brief  The number of interface supported by this configuration.
     */
    uint8 bNumInterfaces;

    /**
     *  @brief  The value used as an argument to the SetConfiguration standard
     *          request to select this configuration.
     */
    uint8 bConfigurationValue;

    /**
     *  @brief  The index of a string descriptor describing this configuration.
     */
    uint8 iConfiguration;

    /**
     *  @brief  Attributes of this configuration.
     */
    uint8 bmAttributes;

    /**
     *  @brief  The maximum power consumption of the USB device from the bus 
	 *          in this configuration when the device is fully operational.  
	 *          This is expressed in units of 2mA so, for example, 
	 *          100 represents 200mA.
     */
    uint8 bMaxPower;
}
PACKED tConfigDescriptor;

/******************************************************************************
 *
 * Flags used in constructing the value assigned to the field
 * tConfigDescriptor.bmAttributes.  Note that bit 7 is reserved and must be set
 * to 1.
 *
 *****************************************************************************/
#define USB_CONF_ATTR_PWR_M     0xC0u

#define USB_CONF_ATTR_SELF_PWR  0xC0u
#define USB_CONF_ATTR_BUS_PWR   0x80u
#define USB_CONF_ATTR_RWAKE     0xA0u

/** ***************************************************************************
 *
 *  This structure describes the USB interface descriptor as defined in USB
 *  2.0 specification section 9.6.5.
 *
 *****************************************************************************/
typedef struct
{
    /**
     *  @brief  The length of this descriptor in bytes.  All interface 
	 *          descriptors are 9 bytes long.
     */
    uint8 bLength;

    /**
     *  @brief  The type of the descriptor.  For an interface descriptor, this
	 *          will be USB_DTYPE_INTERFACE (4).
     */
    uint8 bDescriptorType;

    /**
     *  @brief  The number of this interface.  This is a zero based index into
	 *          the array of concurrent interfaces supported by this 
	 *          configuration.
     */
    uint8 bInterfaceNumber;

    /**
     *  @brief  The value used to select this alternate setting for the 
	 *          interface defined in bInterfaceNumber.
     */
    uint8 bAlternateSetting;

    /**
     *  @brief  The number of endpoints used by this interface (excluding 
	 *          endpoint zero).
     */
    uint8 bNumEndpoints;

    /**
     *  @brief  The interface class code as assigned by the USB-IF.
     */
    uint8 bInterfaceClass;

    /**
     *  @brief  The interface subclass code as assigned by the USB-IF.
     */
    uint8 bInterfaceSubClass;

    /**
     *  @brief  The interface protocol code as assigned by the USB-IF.
     */
    uint8 bInterfaceProtocol;

    /**
     *  @brief  The index of a string descriptor describing this interface.
     */
    uint8 iInterface;
}
PACKED tInterfaceDescriptor;

/** ***************************************************************************
 *
 *  This structure describes the USB endpoint descriptor as defined in USB
 *  2.0 specification section 9.6.6.
 *
 *****************************************************************************/
typedef struct
{
    /**
     *  @brief  The length of this descriptor in bytes.  All endpoint 
	 *          descriptors are 7 bytes long.
     */
    uint8 bLength;

    /**
     *  @brief  The type of the descriptor.  For an endpoint descriptor, this 
	 *          will be USB_DTYPE_ENDPOINT (5).
     */
    uint8 bDescriptorType;

    /**
     *  @brief  The address of the endpoint.  This field contains the endpoint
	 *          number ORed with flag USB_EP_DESC_OUT or USB_EP_DESC_IN to 
	 *          indicate the endpoint direction.
     */
    uint8 bEndpointAddress;

    /**
     *  @brief  The endpoint transfer type, USB_EP_ATTR_CONTROL, 
	 *          USB_EP_ATTR_ISOC, USB_EP_ATTR_BULK or USB_EP_ATTR_INT and, 
	 *          if isochronous, additional flags indicating usage type and 
	 *          synchronization method.
     */
    uint8 bmAttributes;

    /**
     *  @brief  The maximum packet size this endpoint is capable of sending or
     *          receiving when this configuration is selected.  For high speed
     *          isochronous or interrupt endpoints, bits 11 and 12 are used to
     *          pass additional information.
     */
    uint16 wMaxPacketSize;

    /**
     *  @brief  The polling interval for data transfers expressed in frames or
     *          micro frames depending upon the operating speed.
     */
    uint8 bInterval;
}
PACKED tEndpointDescriptor;

/******************************************************************************
 *
 * Flags used in constructing the value assigned to the field
 * tEndpointDescriptor.bEndpointAddress.
 *
 *****************************************************************************/
#define USB_EP_DESC_OUT                 0x00u
#define USB_EP_DESC_IN                  0x80u
#define USB_EP_DESC_NUM_M               0x0fu

/******************************************************************************
 *
 * Mask used to extract the maximum packet size (in bytes) from the
 * wMaxPacketSize field of the endpoint descriptor.
 *
 *****************************************************************************/
#define USB_EP_MAX_PACKET_COUNT_M       0x07FFu

/******************************************************************************
 *
 * Endpoint attributes used in tEndpointDescriptor.bmAttributes.
 *
 *****************************************************************************/
#define USB_EP_ATTR_CONTROL             0x00u
#define USB_EP_ATTR_ISOC                0x01u
#define USB_EP_ATTR_BULK                0x02u
#define USB_EP_ATTR_INT                 0x03u
#define USB_EP_ATTR_TYPE_M              0x03u

#define USB_EP_ATTR_ISOC_M              0x0cu
#define USB_EP_ATTR_ISOC_NOSYNC         0x00u
#define USB_EP_ATTR_ISOC_ASYNC          0x04u
#define USB_EP_ATTR_ISOC_ADAPT          0x08u
#define USB_EP_ATTR_ISOC_SYNC           0x0cu
#define USB_EP_ATTR_USAGE_M             0x30u
#define USB_EP_ATTR_USAGE_DATA          0x00u
#define USB_EP_ATTR_USAGE_FEEDBACK      0x10u
#define USB_EP_ATTR_USAGE_IMPFEEDBACK   0x20u

/** ***************************************************************************
 *
 *  @brief  This structure describes the USB string descriptor for index 0 as 
 *          defined in USB 2.0 specification section 9.6.7.  Note that the 
 *          number of language IDs is variable and can be determined by 
 *          examining bLength.  The number of language IDs present in the 
 *          descriptor is given by ((bLength - 2) / 2).
 *
 *****************************************************************************/
typedef struct
{
    /**
     *  @brief  The length of this descriptor in bytes.  This value will vary
     *          depending upon the number of language codes provided in the 
	 *          descriptor.
     */
    uint8 bLength;

    /**
     *  @brief  The type of the descriptor.  For a string descriptor, this will
     *          be USB_DTYPE_STRING (3).
     */
    uint8 bDescriptorType;

    /**
     *  @brief  The language code (LANGID) for the first supported language.  
	 *          Note that this descriptor may support multiple languages, in 
	 *          which case, the number of elements in the wLANGID array will 
	 *          increase and bLength will be updated accordingly.
     */
    uint16 wLANGID[1];
}
PACKED tString0Descriptor;

/** ***************************************************************************
 *
 *  @brief  This structure describes the USB string descriptor for all string 
 *          indexes other than 0 as defined in USB 2.0 specification 
 *          section 9.6.7.
 *
 *****************************************************************************/
typedef struct
{
    /**
     *  @brief  The length of this descriptor in bytes.  This value will be 
	 *          2 greater than the number of bytes comprising the UNICODE 
	 *          string that the descriptor contains.
     */
    uint8 bLength;

    /**
     *  @brief  The type of the descriptor.  For a string descriptor, this will
     *          be USB_DTYPE_STRING (3).
     */
    uint8 bDescriptorType;

    /**
     *  @brief  The first byte of the UNICODE string.  This string is not NULL
     *          terminated.  Its length (in bytes) can be computed by 
	 *          subtracting 2 from the value in the bLength field.
     */
    uint8 bString;
}
PACKED tStringDescriptor;

/** ***************************************************************************
 *
 *  Write a 2 byte uint16 value to a USB descriptor block.
 *
 *  @param usValue is the two byte uint16 that is to be written to
 *  the descriptor.
 * 
 *  This helper macro is used in descriptor definitions to write two-byte
 *  values.  Since the configuration descriptor contains all interface and
 *  endpoint descriptors in a contiguous block of memory, these descriptors are
 *  typically defined using an array of bytes rather than as packed structures.
 * 
 *  @return Not a function.
 *
 *****************************************************************************/
#define USBShort(usValue)       (uint8_t)((uint16_t)(usValue) & (uint16_t)0x00ffU), (uint8_t)((uint16_t)(usValue) >> 8U)

/** ***************************************************************************
 *
 *  Write a 3 byte uint32 value to a USB descriptor block.
 * 
 *  @param ulValue is the three byte unsigned value that is to be written to the
 *  descriptor.
 * 
 *  This helper macro is used in descriptor definitions to write three-byte
 *  values.  Since the configuration descriptor contains all interface and
 *  endpoint descriptors in a contiguous block of memory, these descriptors are
 *  typically defined using an array of bytes rather than as packed structures.
 * 
 *  @return Not a function.
 *
 *****************************************************************************/
#define USB3Byte(ulValue)       (ulValue & 0xff),              \
                                ((ulValue >> 8) & 0xff),       \
                                ((ulValue >> 16) & 0xff)

/** ***************************************************************************
 *
 *  Write a 4 byte uint32 value to a USB descriptor block.
 * 
 *  @param ulValue is the four byte uint32 that is to be written to the
 *  descriptor.
 * 
 *  This helper macro is used in descriptor definitions to write four-byte
 *  values.  Since the configuration descriptor contains all interface and
 *  endpoint descriptors in a contiguous block of memory, these descriptors are
 *  typically defined using an array of bytes rather than as packed structures.
 * 
 *  @return Not a function.
 *
 *****************************************************************************/
#define USBLong(ulValue)        (ulValue & 0xff),              \
                                ((ulValue >> 8) & 0xff),       \
                                ((ulValue >> 16) & 0xff),      \
                                ((ulValue >> 24) & 0xff)

/** ***************************************************************************
 *
 *  Traverse to the next USB descriptor in a block.
 * 
 *  @param ptr points to the first byte of a descriptor in a block of
 *  USB descriptors.
 * 
 *  This macro aids in traversing lists of descriptors by returning a pointer
 *  to the next descriptor in the list given a pointer to the current one.
 * 
 *  @return Returns a pointer to the next descriptor in the block following
 *  @e ptr.
 * 
 *****************************************************************************/
#define NEXT_USB_DESCRIPTOR(ptr)                         \
        (tDescriptorHeader *)(((uint8 *)(ptr)) + \
                              (ptr)->bLength)

/******************************************************************************
 *
 * Return to default packing when using the IAR Embedded Workbench compiler.
 *
 *****************************************************************************/
#if defined(ewarm) || defined(__IAR_SYSTEMS_ICC__)
#pragma pack()
#endif

/** ***************************************************************************
 *
 *  Close the usbchap9_src Doxygen group.
 *  @}
 *
 *****************************************************************************/

/** ***************************************************************************
 *
 *  @ingroup device_api
 *  @{
 *
 *****************************************************************************/

/** ***************************************************************************
 *
 *  @brief  Function prototype for any standard USB request.
 *
 *****************************************************************************/
typedef void (* tStdRequest)(void * pvInstance, tUSBRequest * pUSBRequest);

/** ***************************************************************************
 *
 *  @brief  Data callback for receiving data from an endpoint.
 *
 *****************************************************************************/
typedef void (* tInfoCallback)(void * pvInstance, uint32 ulInfo);

/** ***************************************************************************
 *
 *  @brief  Callback made to indicate that an interface alternate setting 
 *          change has occurred.
 *
 *****************************************************************************/
typedef void (* tInterfaceCallback)(void * pvInstance,
                                    uint8  ucInterfaceNum,
                                    uint8  ucAlternateSetting);

/** ***************************************************************************
 *
 *  @brief  Generic interrupt handler callbacks.
 *
 *****************************************************************************/
typedef void (* tUSBIntHandler)(void * pvInstance);

/** ***************************************************************************
 *
 *  @brief  Interrupt handler callbacks that have status information.
 *
 *****************************************************************************/
typedef void (* tUSBEPIntHandler)(void * pvInstance,
                                  uint32 ulStatus);

/** ***************************************************************************
 *
 *  @brief  Generic handler callbacks that are used when the callers needs to 
 *          call into an instance of class.
 *
 *****************************************************************************/
typedef void (* tUSBDeviceHandler)(void * pvInstance,
                                   uint32 ulRequest,
                                   void * pvRequestData);

/** ***************************************************************************
 *
 *  @brief  USB event handler functions used during enumeration and operation 
 *          of the device stack.
 *
 *****************************************************************************/
typedef struct
{
    /**
     *  @brief  This callback is made whenever the USB host requests a 
	 *          non-standard descriptor from the device.
     */
    tStdRequest pfnGetDescriptor;

    /**
     *  @brief  This callback is made whenever the USB host makes a 
	 *          non-standard request.
     */
    tStdRequest pfnRequestHandler;

    /**
     *  @brief  This callback is made in response to a SetInterface request 
	 *          from the host.
     */
    tInterfaceCallback pfnInterfaceChange;

    /**
     *  @brief  This callback is made in response to a SetConfiguration 
	 *          request from the host.
     */
    tInfoCallback pfnConfigChange;

    /**
     *  @brief  This callback is made when data has been received following 
	 *          to a call to USBDCDRequestDataEP0.
     */
    tInfoCallback pfnDataReceived;

    /**
     *  @brief  This callback is made when data has been transmitted following
	 *          a call to USBDCDSendDataEP0.
     */
    tInfoCallback pfnDataSent;

    /**
     *  @brief  This callback is made when a USB reset is detected.
     */
    tUSBIntHandler pfnResetHandler;

    /**
     *  @brief  This callback is made when the bus has been inactive long 
	 *          enough to trigger a suspend condition.
     */
    tUSBIntHandler pfnSuspendHandler;

    /**
     *  @brief  This is called when resume signaling is detected.
     */
    tUSBIntHandler pfnResumeHandler;

    /**
     *  @brief  This callback is made when the device is disconnected from 
	 *          the USB bus.
     */
    tUSBIntHandler pfnDisconnectHandler;

    /**
     *  @brief  This callback is made to inform the device of activity on 
	 *          all endpoints other than endpoint zero.
     */
    tUSBEPIntHandler pfnEndpointHandler;

    /**
     *  @brief  This generic handler is provided to allow requests based on
	 *          a given instance to be passed into a device.  This is commonly
     *          used by a top level composite device that is using multiple 
	 *          instances of a class.
     */
    tUSBDeviceHandler pfnDeviceHandler;
}
tCustomHandlers;

/** ***************************************************************************
 *
 *  @brief  This structure defines how a given endpoint's FIFO is configured in
 *          relation to the maximum packet size for the endpoint as specified 
 *          in the endpoint descriptor.
 *
 *****************************************************************************/
typedef struct
{
    /**
     *  @brief  The multiplier to apply to an endpoint's maximum packet size 
	 *          when configuring the FIFO for that endpoint.  For example, 
	 *          setting this value to 2 will result in a 128 byte FIFO being 
	 *          configured if bDoubleBuffer is FALSE and the associated 
	 *          endpoint is set to use a 64 byte maximum packet size.
     */
    uint8 cMultiplier;

    /**
     *  @brief  This field indicates whether to configure an endpoint's FIFO 
	 *          to be double- or single-buffered.  If TRUE, a double-buffered 
	 *          FIFO is created and the amount of required FIFO storage is 
	 *          multiplied by two.
     */
    tBoolean bDoubleBuffer;

    /**
     *  @brief  This field defines endpoint mode flags which cannot be deduced
     *          from the configuration descriptor, namely any in the set 
	 *          USB_EP_AUTO_xxx or USB_EP_DMA_MODE_x.  USBDCDConfig adds these 
	 *          flags to the endpoint mode and direction determined from the 
	 *          config descriptor before it configures the endpoint using a 
	 *          call to USBDevEndpointConfigSet().
     */
    uint16 usEPFlags;
}
tFIFOEntry;

/** ***************************************************************************
 *
 *  @brief  This structure defines endpoint and FIFO configuration information 
 *          for all endpoints that the device wishes to use.  This information 
 *          cannot be determined by examining the USB configuration descriptor 
 *          and is provided to USBDCDConfig by the application to allow the USB
 *          controller endpoints to be correctly configured.
 *
 *****************************************************************************/
typedef struct
{
    /**
     *  @brief  An array containing one FIFO entry for each of the IN
     *          endpoints. Note that endpoint 0 is configured and managed by 
	 *          the USB device stack so is excluded from this array.  The 
	 *          index 0 entry of the array corresponds to endpoint 1, 
	 *          index 1 to endpoint 2, etc.
     */
    tFIFOEntry sIn[USBLIB_NUM_EP - 1];

    /**
     *  @brief  An array containing one FIFO entry for each of the OUT 
	 *          endpoints. Note that endpoint 0 is configured and managed by 
	 *          the USB device stack so is excluded from this array.  
	 *          The index 0 entry of the array corresponds to endpoint 1, 
	 *          index 1 to endpoint 2, etc.
     */
    tFIFOEntry sOut[USBLIB_NUM_EP - 1];
}
tFIFOConfig;

/** ***************************************************************************
 *
 *  @brief  This structure defines a contiguous block of data which contains a
 *          group of descriptors that form part of a configuration descriptor 
 *          for a device. It is assumed that a config section contains only 
 *          whole descriptors.  It is not valid to split a single descriptor 
 *          across multiple sections.
 *
 *****************************************************************************/
typedef struct
{
    /**
     *  @brief  The number of bytes of descriptor data pointed to by pucData.
     */
    uint8 ucSize;

    /**
     *  @brief  A pointer to a block of data containing an integral number of
     *          SB descriptors which form part of a larger configuration
	 *          descriptor.
     */
    const uint8 * pucData;
}
tConfigSection;

/** ***************************************************************************
 *
 *  @brief  This is the top level structure defining a USB device configuration
 *          descriptor.  A configuration descriptor contains a collection of 
 *          device-specific descriptors in addition to the basic config, 
 *          interface and endpoint descriptors.  To allow flexibility in 
 *          constructing the configuration, the descriptor is described in 
 *          terms of a list of data blocks.  The first block must contain the 
 *          configuration descriptor itself and the following blocks are 
 *          appended to this in order to produce the full descriptor sent to 
 *          the host in response to a GetDescriptor request for the 
 *          configuration descriptor.
 *
 *****************************************************************************/
typedef struct
{
    /**
     *  @brief  The number of sections comprising the full descriptor for this
     *          configuration.
     */
    uint8 ucNumSections;

    /**
     *  @brief  A pointer to an array of ucNumSections section pointers which 
	 *          must be concatenated to form the configuration descriptor.
     */
    const tConfigSection * const * psSections;
}
tConfigHeader;

/** ***************************************************************************
 *
 *  @brief  This structure is passed to the USB library on a call to USBDCDInit
 *          and provides the library with information about the device that the
 *          application is implementing.  It contains functions pointers for
 *          the various USB event handlers and pointers to each of the standard
 *          device descriptors.
 *
 *****************************************************************************/
typedef struct
{
    /**
     *  @brief  A pointer to a structure containing pointers to event handler 
	 *          functions provided by the client to support the operation of 
	 *          this device.
     */
    tCustomHandlers sCallbacks;

    /**
     *  @brief  A pointer to the device descriptor for this device.
     */
    const uint8 * pDeviceDescriptor;

    /**
     *  @brief  A pointer to an array of configuration descriptor pointers. 
	 *          Each entry in the array corresponds to one configuration that 
	 *          the device may be set to use by the USB host.  The number of 
	 *          entries in the array must match the bNumConfigurations value 
	 *          in the device descriptor array, pDeviceDescriptor.
     */
    const tConfigHeader * const * ppConfigDescriptors;

    /**
     *  @brief  A pointer to the string descriptor array for this device.  
	 *          This array must be arranged as follows:
     *
     *    - [0]   - Standard descriptor containing supported language codes.
     *    - [1]   - String 1 for the first language listed in descriptor 0.
     *    - [2]   - String 2 for the first language listed in descriptor 0.
     *    - ...
     *    - [n]   - String n for the first language listed in descriptor 0.
     *    - [n+1] - String 1 for the second language listed in descriptor 0.
     *    - ...
     *    - [2n]  - String n for the second language listed in descriptor 0.
     *    - [2n+1]- String 1 for the third language listed in descriptor 0.
     *    - ...
     *    - [3n]  - String n for the third language listed in descriptor 0.
     * 
     *  and so on.
     */
    const uint8 * const * ppStringDescriptors;

    /**
     *  @brief  The total number of descriptors provided in the ppStringDescriptors
     *          array.
     */
    uint32 ulNumStringDescriptors;

    /**
     *  @brief  A structure defining how the USB controller FIFO is to be 
	 *          partitioned between the various endpoints.  This member can be
     *          set to point to g_sUSBDefaultFIFOConfig if the default FIFO 
	 *          configuration is acceptable. This configuration sets each 
	 *          endpoint FIFO to be single buffered and sized to hold the 
	 *          maximum packet size for the endpoint.
     */
    const tFIFOConfig * psFIFOConfig;

    /**
     *  @brief  This value will be passed back to all call back functions so 
	 *          that they have access to individual instance data based on the 
	 *          this pointer.
     */
    void * pvInstance;
}
tDeviceInfo;

/** ***************************************************************************
 *
 * Close the Doxygen group.
 * @}
 *
 *****************************************************************************/

/** ***************************************************************************
 *
 * @ingroup general_usblib_api
 * @{
 *
 *****************************************************************************/

/******************************************************************************
 *
 * USB descriptor parsing functions found in usbdesc.c
 *
 *****************************************************************************/

/** ***************************************************************************
 *
 *  @brief  The USB_DESC_ANY label is used as a wild card in several of the 
 *          descriptor parsing APIs to determine whether or not particular 
 *          search criteria should be ignored.
 *
 *****************************************************************************/
#define USB_DESC_ANY 0xFFFFFFFFu

extern uint32 USBDescGetNum(tDescriptorHeader * psDesc,
                                   uint32 ulSize, uint32 ulType);
extern tDescriptorHeader * USBDescGet(tDescriptorHeader * psDesc,
                                     uint32 ulSize,
                                     uint32 ulType,
                                     uint32 ulIndex);
extern uint32
       USBDescGetNumAlternateInterfaces(tConfigDescriptor * psConfig,
                                        uint8 ucInterfaceNumber);
extern tInterfaceDescriptor * USBDescGetInterface(tConfigDescriptor * psConfig,
                                                 uint32 ulIndex,
                                                 uint32 ulAltCfg);
extern tEndpointDescriptor *
       USBDescGetInterfaceEndpoint(tInterfaceDescriptor * psInterface,
                                   uint32 ulIndex,
                                   uint32 ulSize);

/** ***************************************************************************
 *
 * The operating mode required by the USB library client.  This type is used
 * by applications which wish to be able to switch between host and device
 * modes by calling the USBStackModeSet() API.
 *
 *****************************************************************************/
typedef enum
{
    /**
     *  @brief  The application wishes to operate as a USB device.
     */
    USB_MODE_DEVICE = 0,

    /**
     *  @brief  The application wishes to operate as a USB host.
     */
    USB_MODE_HOST,

    /**
     *  @brief  The application wishes to operate as both a host and device 
	 *          using On-The-Go protocols to negotiate.
     */
    USB_MODE_OTG,

    /**
     *  @brief  A marker indicating that no USB mode has yet been set by the
     *          application.
     */
    USB_MODE_NONE
} tUSBMode;

/** ***************************************************************************
 *
 * A pointer to a USB mode callback function.  This function is called by the
 * USB library to indicate to the application which operating mode it should
 * use, host or device.
 *
 *****************************************************************************/
typedef void (* tUSBModeCallback)(uint32 ulIndex, tUSBMode eMode);

/** ***************************************************************************
 *
 * Mode selection and dual mode interrupt steering functions.
 *
 *****************************************************************************/
extern void USBStackModeSet(uint32 ulIndex, tUSBMode eUSBMode,
                            tUSBModeCallback pfnCallback);
extern void USBDualModeInit(uint32 ulIndex);
extern void USBDualModeTerm(uint32 ulIndex);
extern void USBOTGMain(uint32 ulMsTicks);
extern void USBOTGPollRate(uint32 ulIndex, uint32 ulPollRate);
extern void USBOTGModeInit(uint32 ulIndex, uint32 ulPollRate,
                           void * pHostData, uint32 ulHostDataSize);
extern void USBOTGModeTerm(uint32 ulIndex);
extern void USB0OTGModeIntHandler(void);
extern void USB0DualModeIntHandler(void);

/** ***************************************************************************
 *
 *  USB callback function.
 * 
 *  @param pvCBData is the callback pointer associated with the instance
 *   generating the callback.  This is a value provided by the client during
 *  initialization of the instance making the callback.
 *  @param ulEvent is the identifier of the asynchronous event which is being
 *  notified to the client.
 *  @param ulMsgParam is an event-specific parameter.
 *  @param pvMsgData is an event-specific data pointer.
 * 
 *  A function pointer provided to the USB layer by the application
 *  which will be called to notify it of all asynchronous events relating to
 *  data transmission or reception.  This callback is used by device class
 *  drivers and host pipe functions.
 * 
 *  @return Returns an event-dependent value.
 * 
 *****************************************************************************/
typedef uint32 (* tUSBCallback)(void * pvCBData, uint32 ulEvent,
                                       uint32 ulMsgParam,
                                       void * pvMsgData);

/** ***************************************************************************
 * 
 * Base identifiers for groups of USB events.  These are used by both the
 * device class drivers and host layer.
 *
 * USB_CLASS_EVENT_BASE is the lowest identifier that should be used for
 * a class-specific event.  Individual event bases are defined for each
 * of the supported device class drivers.  Events with IDs between
 * USB_EVENT_BASE and USB_CLASS_EVENT_BASE are reserved for stack use.
 *
 *****************************************************************************/
#define USB_EVENT_BASE          0x0000u
#define USB_CLASS_EVENT_BASE    0x8000u

/** ***************************************************************************
 *
 * Event base identifiers for the various device classes supported in host
 * and device modes.
 * The first 0x800 values of a range are reserved for the device specific
 * messages and the second 0x800 values of a range are used for the host
 * specific messages for a given class.
 *
 *****************************************************************************/
#define USBD_CDC_EVENT_BASE      (USB_CLASS_EVENT_BASE + 0u)
#define USBD_HID_EVENT_BASE      (USB_CLASS_EVENT_BASE + 0x1000u)
#define USBD_HID_KEYB_EVENT_BASE (USBD_HID_EVENT_BASE + 0x100u)
#define USBD_BULK_EVENT_BASE     (USB_CLASS_EVENT_BASE + 0x2000u)
#define USBD_MSC_EVENT_BASE      (USB_CLASS_EVENT_BASE + 0x3000u)
#define USBD_AUDIO_EVENT_BASE    (USB_CLASS_EVENT_BASE + 0x4000u)

#define USBH_CDC_EVENT_BASE   (USBD_CDC_EVENT_BASE  + 0x800u)
#define USBH_HID_EVENT_BASE   (USBD_HID_EVENT_BASE  + 0x800u)
#define USBH_BULK_EVENT_BASE  (USBD_BULK_EVENT_BASE + 0x800u)
#define USBH_MSC_EVENT_BASE   (USBD_MSC_EVENT_BASE  + 0x800u)
#define USBH_AUDIO_EVENT_BASE (USBD_AUDIO_EVENT_BASE  + 0x800u)

/** ***************************************************************************
 *
 * General events supported by device classes and host pipes.
 *
 *****************************************************************************/

/**
 *  @brief  The device is now attached to a USB host and ready to begin sending
 *          and receiving data (used by device classes only).
 */
#define USB_EVENT_CONNECTED (USB_EVENT_BASE + 0u)

/**
 *  @brief  The device has been disconnected from the USB host (used by device
 *          classes only).
 *
 * Note: Due to a hardware erratum in revision A of LM3S3748, this
 * event is not posted to self-powered USB devices when they are disconnected
 * from the USB host.
 */
#define USB_EVENT_DISCONNECTED (USB_EVENT_BASE + 1u)

/**
 *  @brief  Data has been received and is in the buffer provided.
 */
#define USB_EVENT_RX_AVAILABLE (USB_EVENT_BASE + 2u)

/**
 *  @brief  This event is sent by a lower layer to inquire about the amount of
 *          unprocessed data buffered in the layers above.  It is used in 
 *          cases where a low level driver needs to ensure that all preceding 
 *          data has been processed prior to performing some action or making 
 *          some notification. Clients receiving this event should return the 
 *          number of bytes of data that are unprocessed or 0 if no outstanding
 *          data remains.
 */
#define USB_EVENT_DATA_REMAINING (USB_EVENT_BASE + 3u)

/**
 *  @brief  This event is sent by a lower layer supporting DMA to request a 
 *          buffer in which the next received packet may be stored.  
 *          The \e ulMsgValue parameter indicates the maximum size of packet 
 *          that can be received in this channel and \e pvMsgData points to 
 *          storage which should be written with the returned buffer pointer.  
 *          The return value from the callback should be the size of the buffer
 *          allocated (which may be less than the maximum size passed in 
 *          \e ulMsgValue if the client knows that fewer bytes are expected
 *          to be received) or 0 if no buffer is being returned.
 */
#define USB_EVENT_REQUEST_BUFFER (USB_EVENT_BASE + 4u)

/**
 *  @brief  Data has been sent and acknowledged.  If this event is received via
 *          the USB buffer callback, the \e ulMsgValue parameter indicates the 
 *          number of bytes from the transmit buffer that have been successfully
 *          transmitted and acknowledged.
 */
#define USB_EVENT_TX_COMPLETE (USB_EVENT_BASE + 5u)

/**
 *  @brief  An error has been reported on the channel or pipe.  The 
 *          \e ulMsgValue parameter indicates the source(s) of the error and 
 *          is the logical OR combination of "USBERR_" flags defined below.
 */
#define USB_EVENT_ERROR (USB_EVENT_BASE + 6u)

/**
 *  @brief  The bus has entered suspend state.
 */
#define USB_EVENT_SUSPEND (USB_EVENT_BASE + 7u)

/**
 *  @brief  The bus has left suspend state.
 */
#define USB_EVENT_RESUME (USB_EVENT_BASE + 8u)

/**
 *  @brief  A scheduler event has occurred.
 */
#define USB_EVENT_SCHEDULER     (USB_EVENT_BASE + 9u)
/**
 *  @brief  A device or host has detected a stall condition.
 */
#define USB_EVENT_STALL         (USB_EVENT_BASE + 10u)

/**
 *  @brief  The host detected a power fault condition.
 */
#define USB_EVENT_POWER_FAULT   (USB_EVENT_BASE + 11u)

/**
 *  @brief  The controller has detected a A-Side cable and needs power applied.
 *          This is only generated on OTG parts if automatic power control is 
 *          disabled.
 */
#define USB_EVENT_POWER_ENABLE  (USB_EVENT_BASE + 12u)

/**
 *  @brief  The controller needs power removed,  This is only generated on OTG 
 *          parts if automatic power control is disabled.
 */
#define USB_EVENT_POWER_DISABLE (USB_EVENT_BASE + 13u)

/**
 *  @brief  Used with pfnDeviceHandler handler function is classes to indicate
 *          changes in the interface number by a class outside the class being
 *          accessed. Typically this is when composite device class is in use.
 *
 *  The \e pvInstance value should point to an instance of the device being
 *  accessed.
 *
 *  The \e ulRequest should be USB_EVENT_COMP_IFACE_CHANGE.
 *
 *  The \e pvRequestData should point to a two byte array where the first value
 *  is the old interface number and the second is the new interface number.
 */
#define USB_EVENT_COMP_IFACE_CHANGE (USB_EVENT_BASE + 14u)

/**
 *  @brief  Used with pfnDeviceHandler handler function is classes to indicate
 *          changes in endpoint number by a class outside the class being 
 *          accessed. Typically this is when composite device class is in use.
 * 
 *  The \e pvInstance value should point to an instance of the device being
 *  accessed.
 * 
 *  The \e ulRequest should be USB_EVENT_COMP_EP_CHANGE.
 * 
 *  The \e pvRequestData should point to a two byte array where the first value
 *  is the old endpoint number and the second is the new endpoint number.  The
 *  endpoint numbers should be exactly as USB specification defines them and
 *  bit 7 set indicates an IN endpoint and bit 7 clear indicates an OUT
 *  endpoint.
 */
#define USB_EVENT_COMP_EP_CHANGE    (USB_EVENT_BASE + 15u)

/**
 *  @brief  Used with pfnDeviceHandler handler function is classes to indicate 
 *          changes in string index number by a class outside the class being 
 *          accessed. Typically this is when composite device class is in use.
 *
 *  The \e pvInstance value should point to an instance of the device being
 *  accessed.
 * 
 *  The \e ulRequest should be USB_EVENT_COMP_STR_CHANGE.
 * 
 *  The \e pvRequestData should point to a two byte array where the first value
 *  is the old string index and the second is the new string index.
 */
#define USB_EVENT_COMP_STR_CHANGE    (USB_EVENT_BASE + 16u)

/**
 *  @brief  Used with pfnDeviceHandler handler function is classes to allow the
 *          device class to make final adjustments to the configuration 
 *          descriptor. This is only used when a device class is used in a 
 *           composite device class is in use.
 * 
 *  The \e pvInstance value should point to an instance of the device being
 *  accessed.
 * 
 *  The \e ulRequest should be USB_EVENT_COMP_CONFIG.
 * 
 *  The \e pvRequestData should point to the beginning of the configuration
 *  descriptor for the device instance.
 */
#define USB_EVENT_COMP_CONFIG        (USB_EVENT_BASE + 17u)

/** ***************************************************************************
 *
 * Error sources reported via USB_EVENT_ERROR.
 *
 *****************************************************************************/

/**
 *  @brief  The host received an invalid PID in a transaction.
 */
#define USBERR_HOST_IN_PID_ERROR   0x01000000u

/**
 *  @brief  The host did not receive a response from a device.
 */
#define USBERR_HOST_IN_NOT_COMP    0x00100000u

/**
 *  @brief  The host received a stall on an IN endpoint.
 */
#define USBERR_HOST_IN_STALL       0x00400000u

/**
 *  @brief  The host detected a CRC or bit-stuffing error (isochronous mode).
 */
#define USBERR_HOST_IN_DATA_ERROR  0x00080000u

/**
 *  @brief  The host received NAK on an IN endpoint for longer than the 
 *          specified timeout period (interrupt, bulk and control modes).
 */
#define USBERR_HOST_IN_NAK_TO      0x00080000u

/**
 *  @brief  The host failed to communicate with a device via an IN endpoint.
 */
#define USBERR_HOST_IN_ERROR       0x00040000u

/**
 *  @brief  The host receive FIFO is full.
 */
#define USBERR_HOST_IN_FIFO_FULL   0x00020000u  /* RX FIFO full */
/**
 *  @brief  The host received NAK on an OUT endpoint for longer than the 
 *          specified timeout period (bulk, interrupt and control modes).
 */
#define USBERR_HOST_OUT_NAK_TO     0x00000080u

/**
 *  @brief  The host did not receive a response from a device (isochronous mode).
 */
#define USBERR_HOST_OUT_NOT_COMP   0x00000080u

/**
 *  @brief  The host received a stall on an OUT endpoint.
 */
#define USBERR_HOST_OUT_STALL      0x00000020u

/**
 *  @brief  The host failed to communicate with a device via an OUT endpoint.
 */
#define USBERR_HOST_OUT_ERROR      0x00000004u

/**
 *  @brief  The host received NAK on endpoint 0 for longer than the configured
 *          timeout.
 */
#define USBERR_HOST_EP0_NAK_TO     0x00000080u

/**
 *  @brief  The host failed to communicate with a device via an endpoint zero.
 */
#define USBERR_HOST_EP0_ERROR      0x00000010u

/**
 *  @brief  The device detected a CRC error in received data.
 */
#define USBERR_DEV_RX_DATA_ERROR   0x00080000u

/**
 *  @brief  The device was unable to receive a packet from the host since the 
 *          receive FIFO is full.
 */
#define USBERR_DEV_RX_OVERRUN      0x00040000u

/**
 *  @brief  The device receive FIFO is full.
 */
#define USBERR_DEV_RX_FIFO_FULL    0x00020000u  /* RX FIFO full */

/** ***************************************************************************
 *
 * Close the general_usblib_api Doxygen group.
 * @}
 *
 *****************************************************************************/

/** ***************************************************************************
 *
 * @ingroup usblib_buffer_api
 * @{
 *
 *****************************************************************************/

/** ***************************************************************************
 *
 *  @brief  A function pointer type which describes either a class driver 
 *          packet read or packet write function (both have the same prototype)
 *          to the USB buffer object.
 *
 *****************************************************************************/
typedef uint32 (* tUSBPacketTransfer)(void * pvHandle,
                                             uint8 *  pcData,
                                             uint32   ulLength,
                                             tBoolean bLast);

/** ***************************************************************************
 *
 *  @brief  A function pointer type which describes either a class driver 
 *          transmit or receive packet available function (both have the same
 *          prototype) to the USB buffer object.
 *
 *****************************************************************************/
typedef uint32 (* tUSBPacketAvailable)(void * pvHandle);

/** ***************************************************************************
 *
 *  @brief  The number of bytes of workspace that each USB buffer object 
 *          requires. This workspace memory is provided to the buffer on 
 *          USBBufferInit() in the \e pvWorkspace field of the \e tUSBBuffer 
 *          structure.
 *
 *****************************************************************************/
#define USB_BUFFER_WORKSPACE_SIZE 16

/** ***************************************************************************
 *
 *  @brief  The structure used by the application to initialize a buffer object 
 *          that will provide buffered access to either a transmit or receive 
 *          channel.
 *
 *****************************************************************************/
typedef struct
{
    /**
     *  @brief  This field sets the mode of the buffer.  If TRUE, the buffer
     *          operates as a transmit buffer and supports calls to 
	 *          USBBufferWrite by the client.  If FALSE, the buffer operates 
	 *          as a receive buffer and supports calls to USBBufferRead.
     */
    tBoolean bTransmitBuffer;

    /**
     *  @brief  A pointer to the callback function which will be called to 
	 *          notify the application of all asynchronous events related to
	 *          the operation of the buffer.
     */
    tUSBCallback pfnCBack;

    /**
     *  @brief  A pointer that the buffer will pass back to the client in the
     *          first parameter of all callbacks related to this instance.
     */
    void * pvCBData;

    /**
     *  @brief  The function which should be called to transmit a packet of 
	 *          data in transmit mode or receive a packet in receive mode.
     */
    tUSBPacketTransfer pfnTransfer;

    /**
     *  @brief  The function which should be called to determine if the 
	 *          endpoint is ready to accept a new packet for transmission in 
	 *          transmit mode or to determine the size of the buffer required
	 *          to read a packet in receive mode.
     */
    tUSBPacketAvailable pfnAvailable;

    /**
     *  @brief  The handle to pass to the low level function pointers provided
     *          in the pfnTransfer and pfnAvailable members.  For USB device
     *          use, this is the psDevice parameter required by the relevant 
	 *          device class driver APIs.  For USB host use, this is the pipe 
	 *          identifier returned by USBHCDPipeAlloc.
     */
    void * pvHandle;

    /**
     *  @brief  A pointer to memory to be used as the ring buffer for this
     *          instance.
     */
    uint8 * pcBuffer;

    /**
     *  @brief  The size, in bytes, of the buffer pointed to by pcBuffer.
     */
    uint32 ulBufferSize;

    /**
     *  @brief  A pointer to USB_BUFFER_WORKSPACE_SIZE bytes of RAM that the 
	 *          buffer object can use for workspace.
     */
    void * pvWorkspace;
}
tUSBBuffer;

/** ***************************************************************************
 *
 *  @brief  The structure used for encapsulating all the items associated with
 *          a ring buffer.
 *
 *****************************************************************************/
typedef struct
{
    /**
     *  @brief  The ring buffer size.
     */
    uint32 ulSize;

    /**
     *  @brief  The ring buffer write index.
     */
    volatile uint32 ulWriteIndex;

    /**
     *  @brief  The ring buffer read index.
     */
    volatile uint32 ulReadIndex;

    /**
     *  @brief  The ring buffer.
     */
    uint8 * pucBuf;
}
tUSBRingBufObject;

/** ***************************************************************************
 *
 * USB buffer API function prototypes.
 *
 *****************************************************************************/
extern const tUSBBuffer * USBBufferInit(const tUSBBuffer * psBuffer);
extern void USBBufferInfoGet(const tUSBBuffer * psBuffer,
                             tUSBRingBufObject * psRingBuf);
extern void * USBBufferCallbackDataSet(tUSBBuffer * psBuffer, void * pvCBData);
extern uint32 USBBufferWrite(const tUSBBuffer * psBuffer,
                                    const uint8 * pucData,
                                    uint32 ulLength);
extern void USBBufferDataWritten(const tUSBBuffer * psBuffer,
                                 uint32 ulLength);
extern void USBBufferDataRemoved(const tUSBBuffer * psBuffer,
                                 uint32 ulLength);
extern void USBBufferFlush(const tUSBBuffer * psBuffer);
extern uint32 USBBufferRead(const tUSBBuffer * psBuffer,
                                   uint8 * pucData,
                                   uint32 ulLength);
extern uint32 USBBufferDataAvailable(const tUSBBuffer * psBuffer);
extern uint32 USBBufferSpaceAvailable(const tUSBBuffer * psBuffer);
extern uint32 USBBufferEventCallback(void * pvCBData,
                                            uint32 ulEvent,
                                            uint32 ulMsgValue,
                                            void * pvMsgData);
extern tBoolean USBRingBufFull(tUSBRingBufObject * ptUSBRingBuf);
extern tBoolean USBRingBufEmpty(tUSBRingBufObject * ptUSBRingBuf);
extern void USBRingBufFlush(tUSBRingBufObject * ptUSBRingBuf);
extern uint32 USBRingBufUsed(tUSBRingBufObject * ptUSBRingBuf);
extern uint32 USBRingBufFree(tUSBRingBufObject * ptUSBRingBuf);
extern uint32 USBRingBufContigUsed(tUSBRingBufObject * ptUSBRingBuf);
extern uint32 USBRingBufContigFree(tUSBRingBufObject * ptUSBRingBuf);
extern uint32 USBRingBufSize(tUSBRingBufObject * ptUSBRingBuf);
extern uint8 USBRingBufReadOne(tUSBRingBufObject * ptUSBRingBuf);
extern void USBRingBufRead(tUSBRingBufObject * ptUSBRingBuf,
                           uint8 * pucData, uint32 ulLength);
extern void USBRingBufWriteOne(tUSBRingBufObject * ptUSBRingBuf,
                               uint8 ucData);
extern void USBRingBufWrite(tUSBRingBufObject * ptUSBRingBuf,
                            const uint8 pucData[],
                            uint32 ulLength);
extern void USBRingBufAdvanceWrite(tUSBRingBufObject * ptUSBRingBuf,
                                   uint32 ulNumBytes);
extern void USBRingBufAdvanceRead(tUSBRingBufObject * ptUSBRingBuf,
                                  uint32 ulNumBytes);
extern void USBRingBufInit(tUSBRingBufObject * ptUSBRingBuf,
                           uint8 * pucBuf, uint32 ulSize);

/** ***************************************************************************
 *
 *  Close the Doxygen group.
 *  @}
 *
 *****************************************************************************/

/******************************************************************************
 *
 * Mark the end of the C bindings section for C++ compilers.
 *
 *****************************************************************************/
#ifdef __cplusplus
}
#endif

#endif /* __USBLIB_H__ */