usblib.h

Go to the documentation of this file.

//*****************************************************************************
//
// usblib.h - Main header file for the USB Library.
//
// Copyright (c) 2008-2017 Texas Instruments Incorporated.  All rights reserved.
// Software License Agreement
//
// Texas Instruments (TI) is supplying this software for use solely and
// exclusively on TI's microcontroller products. The software is owned by
// TI and/or its suppliers, and is protected under applicable copyright
// laws. You may not combine this software with "viral" open-source
// software in order to form a larger program.
//
// THIS SOFTWARE IS PROVIDED "AS IS" AND WITH ALL FAULTS.
// NO WARRANTIES, WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT
// NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. TI SHALL NOT, UNDER ANY
// CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
// DAMAGES, FOR ANY REASON WHATSOEVER.
//
//*****************************************************************************

#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

#include <stdint.h>
#include <stdbool.h>

//*****************************************************************************
//
// This is the maximum number of devices we can support when in host mode and
// using a hub.  By default, we support up to 4 devices (plus 1 internally for
// the hub itself).
//
//*****************************************************************************
#ifndef MAX_USB_DEVICES
#define MAX_USB_DEVICES         5
#endif

//*****************************************************************************
//
// This is the maximum number of endpoints supported by the usblib.
//
//*****************************************************************************
#ifndef USBLIB_NUM_EP
#define USBLIB_NUM_EP           8       // Number of supported endpoints.
#endif

//*****************************************************************************
//
// 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 __ICCARM__
//   #pragma pack(1)
//   #endif
//
//   typedef struct _PackedStructName
//   {
//      uint32_t ui32FirstField;
//      int8_t i8CharMember;
//      uint16_t ui16Short;
//   }
//   PACKED tPackedStructName;
//
//   #ifdef __ICCARM__
//   #pragma pack()
//   #endif
//
// The conditional blocks related to __ICCARM__ 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(__TI_ARM__) ||                                                    \
    defined(codered) ||                                                       \
    defined(__GNUC__) ||                                                      \
    defined(__CC_ARM) ||                                                      \
    defined(__ARMCC_VERSION) ||                                               \
    defined(sourcerygxx)
#define PACKED __attribute__ ((packed))
#elif defined(__ICCARM__)
#define 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    0x0804      // Chinese (PRC)
#define USB_LANG_CHINESE_TAIWAN 0x0404      // Chinese (Taiwan)
#define USB_LANG_EN_US          0x0409      // English (United States)
#define USB_LANG_EN_UK          0x0809      // English (United Kingdom)
#define USB_LANG_EN_AUS         0x0C09      // English (Australia)
#define USB_LANG_EN_CA          0x1009      // English (Canada)
#define USB_LANG_EN_NZ          0x1409      // English (New Zealand)
#define USB_LANG_FRENCH         0x040C      // French (Standard)
#define USB_LANG_GERMAN         0x0407      // German (Standard)
#define USB_LANG_HINDI          0x0439      // Hindi
#define USB_LANG_ITALIAN        0x0410      // Italian (Standard)
#define USB_LANG_JAPANESE       0x0411      // Japanese
#define USB_LANG_KOREAN         0x0412      // Korean
#define USB_LANG_ES_TRAD        0x040A      // Spanish (Traditional)
#define USB_LANG_ES_MODERN      0x0C0A      // Spanish (Modern)
#define USB_LANG_SWAHILI        0x0441      // Swahili (Kenya)
#define USB_LANG_URDU_IN        0x0820      // Urdu (India)
#define USB_LANG_URDU_PK        0x0420      // Urdu (Pakistan)

//*****************************************************************************
//
//
//*****************************************************************************

//*****************************************************************************
//
// 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 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 other code, this is an integer or enumeration variable.
//
//*****************************************************************************

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

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

//*****************************************************************************
//
//
//*****************************************************************************
typedef struct
{
    //
    //
    uint8_t bmRequestType;

    //
    //
    uint8_t bRequest;

    //
    //
    uint16_t wValue;

    //
    //
    uint16_t wIndex;

    //
    //
    uint16_t 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        0x80
#define USB_RTYPE_DIR_OUT       0x00

#define USB_RTYPE_TYPE_M        0x60
#define USB_RTYPE_VENDOR        0x40
#define USB_RTYPE_CLASS         0x20
#define USB_RTYPE_STANDARD      0x00

#define USB_RTYPE_RECIPIENT_M   0x1f
#define USB_RTYPE_OTHER         0x03
#define USB_RTYPE_ENDPOINT      0x02
#define USB_RTYPE_INTERFACE     0x01
#define USB_RTYPE_DEVICE        0x00

//*****************************************************************************
//
// Standard USB requests IDs used in the bRequest field of tUSBRequest.
//
//*****************************************************************************
#define USBREQ_GET_STATUS       0x00
#define USBREQ_CLEAR_FEATURE    0x01
#define USBREQ_SET_FEATURE      0x03
#define USBREQ_SET_ADDRESS      0x05
#define USBREQ_GET_DESCRIPTOR   0x06
#define USBREQ_SET_DESCRIPTOR   0x07
#define USBREQ_GET_CONFIG       0x08
#define USBREQ_SET_CONFIG       0x09
#define USBREQ_GET_INTERFACE    0x0a
#define USBREQ_SET_INTERFACE    0x0b
#define USBREQ_SYNC_FRAME       0x0c

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

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

//*****************************************************************************
//
// Endpoint Selectors (tUSBRequest.wIndex) passed on USBREQ_CLEAR_FEATURE,
// USBREQ_SET_FEATURE and USBREQ_GET_STATUS.
//
//*****************************************************************************
#define USB_REQ_EP_NUM_M        0x007F
#define USB_REQ_EP_DIR_M        0x0080
#define USB_REQ_EP_DIR_IN       0x0080
#define USB_REQ_EP_DIR_OUT      0x0000

//*****************************************************************************
//
// 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        1
#define USB_DTYPE_CONFIGURATION 2
#define USB_DTYPE_STRING        3
#define USB_DTYPE_INTERFACE     4
#define USB_DTYPE_ENDPOINT      5
#define USB_DTYPE_DEVICE_QUAL   6
#define USB_DTYPE_OSPEED_CONF   7
#define USB_DTYPE_INTERFACE_PWR 8
#define USB_DTYPE_OTG           9
#define USB_DTYPE_INTERFACE_ASC 11
#define USB_DTYPE_CS_INTERFACE  36
#define USB_DTYPE_HUB           41

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

//*****************************************************************************
//
//
//*****************************************************************************
typedef struct
{
    //
    //
    uint8_t bLength;

    //
    //
    uint8_t bDescriptorType;
}
PACKED tDescriptorHeader;

//*****************************************************************************
//
//
//*****************************************************************************
typedef struct
{
    //
    //
    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;
}
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        0x00
#define USB_CLASS_AUDIO         0x01
#define USB_CLASS_CDC           0x02
#define USB_CLASS_HID           0x03
#define USB_CLASS_PHYSICAL      0x05
#define USB_CLASS_IMAGE         0x06
#define USB_CLASS_PRINTER       0x07
#define USB_CLASS_MASS_STORAGE  0x08
#define USB_CLASS_HUB           0x09
#define USB_CLASS_CDC_DATA      0x0a
#define USB_CLASS_SMART_CARD    0x0b
#define USB_CLASS_SECURITY      0x0d
#define USB_CLASS_VIDEO         0x0e
#define USB_CLASS_HEALTHCARE    0x0f
#define USB_CLASS_DIAG_DEVICE   0xdc
#define USB_CLASS_WIRELESS      0xe0
#define USB_CLASS_MISC          0xef
#define USB_CLASS_APP_SPECIFIC  0xfe
#define USB_CLASS_VEND_SPECIFIC 0xff
#define USB_CLASS_EVENTS        0xffffffff

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

//*****************************************************************************
//
// The following are the miscellaneous subclass values.
//
//*****************************************************************************
#define USB_MISC_SUBCLASS_SYNC  0x01
#define USB_MISC_SUBCLASS_COMMON                                              \
                                0x02

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

//*****************************************************************************
//
// These following are hub protocol values.
//
//*****************************************************************************
#define USB_HUB_PROTOCOL_FS     0x00
#define USB_HUB_PROTOCOL_SINGLE 0x01
#define USB_HUB_PROTOCOL_MULTI  0x02

//*****************************************************************************
//
//
//*****************************************************************************
typedef struct
{
    //
    //
    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;
}
PACKED tDeviceQualifierDescriptor;

//*****************************************************************************
//
//
//*****************************************************************************
typedef struct
{
    //
    //
    uint8_t bLength;

    //
    //
    uint8_t bDescriptorType;

    //
    //
    uint16_t wTotalLength;

    //
    //
    uint8_t bNumInterfaces;

    //
    //
    uint8_t bConfigurationValue;

    //
    //
    uint8_t iConfiguration;

    //
    //
    uint8_t bmAttributes;

    //
    //
    uint8_t 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     0xC0

#define USB_CONF_ATTR_SELF_PWR  0xC0
#define USB_CONF_ATTR_BUS_PWR   0x80
#define USB_CONF_ATTR_RWAKE     0xA0

//*****************************************************************************
//
//
//*****************************************************************************
typedef struct
{
    //
    //
    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;
}
PACKED tInterfaceDescriptor;

//*****************************************************************************
//
//
//*****************************************************************************
typedef struct
{
    //
    //
    uint8_t bLength;

    //
    //
    uint8_t bDescriptorType;

    //
    //
    uint8_t bEndpointAddress;

    //
    //
    uint8_t bmAttributes;

    //
    //
    uint16_t wMaxPacketSize;

    //
    //
    uint8_t bInterval;
}
PACKED tEndpointDescriptor;

//*****************************************************************************
//
// Flags used in constructing the value assigned to the field
// tEndpointDescriptor.bEndpointAddress.
//
//*****************************************************************************
#define USB_EP_DESC_OUT         0x00
#define USB_EP_DESC_IN          0x80
#define USB_EP_DESC_NUM_M       0x0f

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

//*****************************************************************************
//
// Endpoint attributes used in tEndpointDescriptor.bmAttributes.
//
//*****************************************************************************
#define USB_EP_ATTR_CONTROL     0x00
#define USB_EP_ATTR_ISOC        0x01
#define USB_EP_ATTR_BULK        0x02
#define USB_EP_ATTR_INT         0x03
#define USB_EP_ATTR_TYPE_M      0x03

#define USB_EP_ATTR_ISOC_M      0x0c
#define USB_EP_ATTR_ISOC_NOSYNC 0x00
#define USB_EP_ATTR_ISOC_ASYNC  0x04
#define USB_EP_ATTR_ISOC_ADAPT  0x08
#define USB_EP_ATTR_ISOC_SYNC   0x0c
#define USB_EP_ATTR_USAGE_M     0x30
#define USB_EP_ATTR_USAGE_DATA  0x00
#define USB_EP_ATTR_USAGE_FEEDBACK                                            \
                                0x10
#define USB_EP_ATTR_USAGE_IMPFEEDBACK                                         \
                                0x20

//*****************************************************************************
//
//
//*****************************************************************************
typedef struct
{
    //
    //
    uint8_t bLength;

    //
    //
    uint8_t bDescriptorType;

    //
    //
    uint16_t wLANGID[1];
}
PACKED tString0Descriptor;

//*****************************************************************************
//
//
//*****************************************************************************
typedef struct
{
    //
    //
    uint8_t bLength;

    //
    //
    uint8_t bDescriptorType;

    //
    //
    uint8_t bString;
}
PACKED tStringDescriptor;

//*****************************************************************************
//
//
//*****************************************************************************
#define USBShort(ui16Value)     (ui16Value & 0xff), (ui16Value >> 8)

//*****************************************************************************
//
//
//*****************************************************************************
#define USB3Byte(ui32Value)     (ui32Value & 0xff),                           \
                                ((ui32Value >> 8) & 0xff),                    \
                                ((ui32Value >> 16) & 0xff)

//*****************************************************************************
//
//
//*****************************************************************************
#define USBLong(ui32Value)      (ui32Value & 0xff),                           \
                                ((ui32Value >> 8) & 0xff),                    \
                                ((ui32Value >> 16) & 0xff),                   \
                                ((ui32Value >> 24) & 0xff)

//*****************************************************************************
//
//*****************************************************************************
#define NEXT_USB_DESCRIPTOR(ptr)                                              \
                                (tDescriptorHeader *)(((uint8_t *)(ptr)) +    \
                                                      *((uint8_t *)(ptr)))

//*****************************************************************************
//
// Return to default packing when using the IAR Embedded Workbench compiler.
//
//*****************************************************************************
#ifdef __ICCARM__
#pragma pack()
#endif

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

//*****************************************************************************
//
//
//*****************************************************************************

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

//*****************************************************************************
//
// Data callback for receiving data from an endpoint.
//
//*****************************************************************************
typedef void (* tInfoCallback)(void *pvInstance, uint32_t ui32Info);

//*****************************************************************************
//
// Callback made to indicate that an interface alternate setting change has
// occurred.
//
//*****************************************************************************
typedef void (* tInterfaceCallback)(void *pvInstance, uint8_t ui8InterfaceNum,
                                    uint8_t ui8AlternateSetting);

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

//*****************************************************************************
//
// Interrupt handler callbacks that have status information.
//
//*****************************************************************************
typedef void (* tUSBEPIntHandler)(void *pvInstance, uint32_t ui32Status);

//*****************************************************************************
//
//
//*****************************************************************************
typedef void (* tUSBDeviceHandler)(void *pvInstance, uint32_t ui32Request,
                                   void *pvRequestData);

//*****************************************************************************
//
//
//*****************************************************************************
typedef struct
{
    //
    //
    tStdRequest pfnGetDescriptor;

    //
    //
    tStdRequest pfnRequestHandler;

    //
    //
    tInterfaceCallback pfnInterfaceChange;

    //
    //
    tInfoCallback pfnConfigChange;

    //
    //
    tInfoCallback pfnDataReceived;

    //
    //
    tInfoCallback pfnDataSent;

    //
    //
    tUSBIntHandler pfnResetHandler;

    //
    //
    tUSBIntHandler pfnSuspendHandler;

    //
    //
    tUSBIntHandler pfnResumeHandler;

    //
    //
    tUSBIntHandler pfnDisconnectHandler;

    //
    //
    tUSBEPIntHandler pfnEndpointHandler;

    //
    //
    tUSBDeviceHandler pfnDeviceHandler;
}
tCustomHandlers;

//*****************************************************************************
//
//*****************************************************************************
typedef struct
{
    //
    //
    uint16_t ui16Size;

    //
    //
    const uint8_t *pui8Data;
}
tConfigSection;

//*****************************************************************************
//
//*****************************************************************************
typedef struct
{
    //
    //
    uint8_t ui8NumSections;

    //
    //
    const tConfigSection * const *psSections;
}
tConfigHeader;

//*****************************************************************************
//
// Close the Doxygen group.
//
//*****************************************************************************

//*****************************************************************************
//
//
//*****************************************************************************

//*****************************************************************************
//
// Predeclare of the DMA instance structure.
//
//*****************************************************************************
typedef struct tUSBDMAInstance tUSBDMAInstance;

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

//*****************************************************************************
//
//
//*****************************************************************************
#define USB_DESC_ANY 0xFFFFFFFF

extern uint32_t USBDescGetNum(tDescriptorHeader *psDesc, uint32_t ui32Size,
                              uint32_t ui32Type);
extern tDescriptorHeader *USBDescGet(tDescriptorHeader *psDesc,
                                     uint32_t ui32Size, uint32_t ui32Type,
                                     uint32_t ui32Index);
extern uint32_t
       USBDescGetNumAlternateInterfaces(tConfigDescriptor *psConfig,
                                        uint8_t ui8InterfaceNumber);
extern tInterfaceDescriptor *USBDescGetInterface(tConfigDescriptor *psConfig,
                                                 uint32_t ui32Index,
                                                 uint32_t ui32AltCfg);
extern tEndpointDescriptor *
       USBDescGetInterfaceEndpoint(tInterfaceDescriptor *psInterface,
                                   uint32_t ui32Index, uint32_t ui32Size);

//*****************************************************************************
//
//
//*****************************************************************************
typedef enum
{
    //
    //
    eUSBModeDevice = 0,

    //
    //
    eUSBModeHost,

    //
    //
    eUSBModeOTG,

    //
    //
    eUSBModeNone,

    //
    //
    eUSBModeForceHost,

    //
    //
    eUSBModeForceDevice,
}
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_t ui32Index, tUSBMode iMode);

//*****************************************************************************
//
//
//*****************************************************************************
typedef uint32_t (* tUSBCallback)(void *pvCBData, uint32_t ui32Event,
                                  uint32_t ui32MsgParam, void *pvMsgData);

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

//
//
#define USBERR_HOST_IN_PID_ERROR                                              \
                                0x01000000

//
//
#define USBERR_HOST_IN_NOT_COMP 0x00100000

//
//
#define USBERR_HOST_IN_STALL    0x00400000

//
//
#define USBERR_HOST_IN_DATA_ERROR                                             \
                                0x00080000

//
//
#define USBERR_HOST_IN_NAK_TO   0x00080000

//
//
#define USBERR_HOST_IN_ERROR    0x00040000

//
//
#define USBERR_HOST_IN_FIFO_FULL                                              \
                                0x00020000
//
//
#define USBERR_HOST_OUT_NAK_TO  0x00000080

//
//
#define USBERR_HOST_OUT_NOT_COMP                                              \
                                0x00000080

//
//
#define USBERR_HOST_OUT_STALL   0x00000020

//
//
#define USBERR_HOST_OUT_ERROR   0x00000004

//
//
#define USBERR_HOST_EP0_NAK_TO  0x00000080

//
//
#define USBERR_HOST_EP0_ERROR   0x00000010

//
//
#define USBERR_DEV_RX_DATA_ERROR                                              \
                                0x00080000

//
//
#define USBERR_DEV_RX_OVERRUN   0x00040000

//
//
#define USBERR_DEV_RX_FIFO_FULL 0x00020000

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

//*****************************************************************************
//
//
//*****************************************************************************

//*****************************************************************************
//
//
//*****************************************************************************
typedef struct
{
    //
    //
    uint32_t ui32Event;

    //
    //
    uint32_t ui32Instance;
}
tEventInfo;

//*****************************************************************************
//
// 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          0x0000
#define USB_CLASS_EVENT_BASE    0x8000

//*****************************************************************************
//
// 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 + 0)
#define USBD_HID_EVENT_BASE     (USB_CLASS_EVENT_BASE + 0x1000)
#define USBD_HID_KEYB_EVENT_BASE                                              \
                                (USBD_HID_EVENT_BASE + 0x100)
#define USBD_BULK_EVENT_BASE    (USB_CLASS_EVENT_BASE + 0x2000)
#define USBD_MSC_EVENT_BASE     (USB_CLASS_EVENT_BASE + 0x3000)
#define USBD_AUDIO_EVENT_BASE   (USB_CLASS_EVENT_BASE + 0x4000)
#define USBD_DFU_EVENT_BASE     (USB_CLASS_EVENT_BASE + 0x5000)

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

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

//
//
#define USB_EVENT_CONNECTED     (USB_EVENT_BASE + 0)

//
//
#define USB_EVENT_DISCONNECTED  (USB_EVENT_BASE + 1)

//
//
#define USB_EVENT_RX_AVAILABLE  (USB_EVENT_BASE + 2)

//
//
#define USB_EVENT_DATA_REMAINING                                              \
                                (USB_EVENT_BASE + 3)

//
//
#define USB_EVENT_REQUEST_BUFFER                                              \
                                (USB_EVENT_BASE + 4)

//
//
#define USB_EVENT_TX_COMPLETE   (USB_EVENT_BASE + 5)

//
//
#define USB_EVENT_ERROR         (USB_EVENT_BASE + 6)

//
//
#define USB_EVENT_SUSPEND       (USB_EVENT_BASE + 7)

//
//
#define USB_EVENT_RESUME        (USB_EVENT_BASE + 8)

//
//
#define USB_EVENT_SCHEDULER     (USB_EVENT_BASE + 9)
//
//
#define USB_EVENT_STALL         (USB_EVENT_BASE + 10)

//
//
#define USB_EVENT_POWER_FAULT   (USB_EVENT_BASE + 11)

//
//
#define USB_EVENT_POWER_ENABLE  (USB_EVENT_BASE + 12)

//
//
#define USB_EVENT_POWER_DISABLE (USB_EVENT_BASE + 13)

//
//
#define USB_EVENT_COMP_IFACE_CHANGE                                           \
                                (USB_EVENT_BASE + 14)

//
//
#define USB_EVENT_COMP_EP_CHANGE                                              \
                                (USB_EVENT_BASE + 15)

//
//
#define USB_EVENT_COMP_STR_CHANGE                                             \
                                (USB_EVENT_BASE + 16)

//
//
#define USB_EVENT_COMP_CONFIG   (USB_EVENT_BASE + 17)

//
//
#define USB_EVENT_UNKNOWN_CONNECTED                                           \
                                (USB_EVENT_BASE + 18)

//
//
#define USB_EVENT_SOF           (USB_EVENT_BASE + 19)

//
//
#define USB_EVENT_LPM_SLEEP     (USB_EVENT_BASE + 20)

//
//
#define USB_EVENT_LPM_RESUME    (USB_EVENT_BASE + 21)

//
//
#define USB_EVENT_LPM_ERROR     (USB_EVENT_BASE + 22)

//
//
#define USB_EVENT_CONFIG_CHANGE (USB_EVENT_BASE + 23)

//*****************************************************************************
//
// Close the usblib_events Doxygen group.
//
//*****************************************************************************
//*****************************************************************************
//
//
//*****************************************************************************

//*****************************************************************************
//
//
//*****************************************************************************
typedef uint32_t (* tUSBPacketTransfer)(void *pvHandle, uint8_t *pi8Data,
                                        uint32_t ui32Length, bool bLast);

//*****************************************************************************
//
//
//*****************************************************************************
typedef uint32_t (* tUSBPacketAvailable)(void *pvHandle);

//*****************************************************************************
//
// The defines used with the USBDCDFeatureSet() or USBHCDFeatureSet() calls.
//
//*****************************************************************************

//*****************************************************************************
//
//
//*****************************************************************************
#define USBLIB_FEATURE_LPM      0x00000001

//*****************************************************************************
//
// The defines used with the USBDCDFeatureSet() or USBHCDFeatureSet() calls
// for \b USBLIB_FEATURE_LPM feature requests.
//
//*****************************************************************************
#define USBLIB_FEATURE_LPM_RMT_WAKE                                           \
                                0x00000002
#define USBLIB_FEATURE_LPM_EN   0x00000001
#define USBLIB_FEATURE_LPM_DIS  0x00000000

//*****************************************************************************
//
//
//*****************************************************************************
#define USBLIB_FEATURE_CPUCLK   0x00000002

//*****************************************************************************
//
//
//*****************************************************************************
#define USBLIB_FEATURE_USBPLL   0x00000003

//*****************************************************************************
//
//*****************************************************************************
#define USBLIB_FEATURE_USBULPI  0x00000004

//*****************************************************************************
//
// The defines used with the USBDCDFeatureSet() or USBHCDFeatureSet() calls
// for \b USBLIB_FEATURE_USBULPI feature requests.
//
//*****************************************************************************
#define USBLIB_FEATURE_ULPI_NONE                                              \
                                0x00000000
#define USBLIB_FEATURE_ULPI_HS  0x00000010
#define USBLIB_FEATURE_ULPI_FS  0x00000020

//*****************************************************************************
//
//
//*****************************************************************************
#define USBLIB_FEATURE_POWER    0x00000005

//*****************************************************************************
//
// The defines used with the USBDCDFeatureSet() or USBHCDFeatureSet() calls
// for \b USBLIB_FEATURE_POWER feature requests.
//
//*****************************************************************************
#define USBLIB_FEATURE_POWER_SELF                                             \
                                0x00000001
#define USBLIB_FEATURE_POWER_BUS                                              \
                                0x00000000
#define USBLIB_FEATURE_REMOTE_WAKE                                            \
                                0x00000002

//*****************************************************************************
//
// The structure used with the USBDCDFeatureSet() or USBHCDFeatureSet() calls
// to set feature enables and resume timing parameter.
//
//*****************************************************************************
typedef struct
{
    uint32_t ui32HIRD;
    uint32_t ui32Features;
}
tLPMFeature;

//*****************************************************************************
//
//
//*****************************************************************************
typedef struct
{
    //
    //
    uint32_t ui32Size;

    //
    //
    volatile uint32_t ui32WriteIndex;

    //
    //
    volatile uint32_t ui32ReadIndex;

    //
    //
    uint8_t *pui8Buf;
}
tUSBRingBufObject;

//*****************************************************************************
//
// Workspace variables required by each buffer instance.  This structure is
// private and should not be accessed directly by the application.
//
//*****************************************************************************
typedef struct
{
    tUSBRingBufObject sRingBuf;
    uint32_t ui32LastSent;
    uint32_t ui32Flags;
}
tUSBBufferVars;

//*****************************************************************************
//
//
//*****************************************************************************
typedef struct
{
    //
    //
    bool bTransmitBuffer;

    //
    //
    tUSBCallback pfnCallback;

    //
    //
    void *pvCBData;

    //
    //
    tUSBPacketTransfer pfnTransfer;

    //
    //
    tUSBPacketAvailable pfnAvailable;

    //
    //
    void *pvHandle;

    //
    //
    uint8_t *pui8Buffer;

    //
    //
    uint32_t ui32BufferSize;

    //
    //
    tUSBBufferVars sPrivateData;
}
tUSBBuffer;

//*****************************************************************************
//
// Close the Doxygen group.
//
//*****************************************************************************

//*****************************************************************************
//
// USB buffer API function prototypes.
//
//*****************************************************************************
extern const tUSBBuffer *USBBufferInit(tUSBBuffer *psBuffer);
extern void USBBufferZeroLengthPacketInsert(const tUSBBuffer *psBuffer,
                                            bool bSendZLP);
extern void USBBufferInfoGet(const tUSBBuffer *psBuffer,
                             tUSBRingBufObject *psRingBuf);
extern void *USBBufferCallbackDataSet(tUSBBuffer *psBuffer, void *pvCBData);
extern uint32_t USBBufferWrite(const tUSBBuffer *psBuffer,
                               const uint8_t *pui8Data, uint32_t ui32Length);
extern void USBBufferDataWritten(const tUSBBuffer *psBuffer,
                                 uint32_t ui32Length);
extern void USBBufferDataRemoved(const tUSBBuffer *psBuffer,
                                 uint32_t ui32Length);
extern void USBBufferFlush(const tUSBBuffer *psBuffer);
extern uint32_t USBBufferRead(const tUSBBuffer *psBuffer, uint8_t *pui8Data,
                              uint32_t ui32Length);
extern uint32_t USBBufferDataAvailable(const tUSBBuffer *psBuffer);
extern uint32_t USBBufferSpaceAvailable(const tUSBBuffer *psBuffer);
extern uint32_t USBBufferEventCallback(void *pvCBData, uint32_t ui32Event,
                                       uint32_t ui32MsgValue, void *pvMsgData);
extern bool USBRingBufFull(tUSBRingBufObject *psUSBRingBuf);
extern bool USBRingBufEmpty(tUSBRingBufObject *psUSBRingBuf);
extern void USBRingBufFlush(tUSBRingBufObject *psUSBRingBuf);
extern uint32_t USBRingBufUsed(tUSBRingBufObject *psUSBRingBuf);
extern uint32_t USBRingBufFree(tUSBRingBufObject *psUSBRingBuf);
extern uint32_t USBRingBufContigUsed(tUSBRingBufObject *psUSBRingBuf);
extern uint32_t USBRingBufContigFree(tUSBRingBufObject *psUSBRingBuf);
extern uint32_t USBRingBufSize(tUSBRingBufObject *psUSBRingBuf);
extern uint8_t USBRingBufReadOne(tUSBRingBufObject *psUSBRingBuf);
extern void USBRingBufRead(tUSBRingBufObject *psUSBRingBuf,
                           uint8_t *pui8Data, uint32_t ui32Length);
extern void USBRingBufWriteOne(tUSBRingBufObject *psUSBRingBuf,
                               uint8_t ui8Data);
extern void USBRingBufWrite(tUSBRingBufObject *psUSBRingBuf,
                            const uint8_t *pui8Data, uint32_t ui32Length);
extern void USBRingBufAdvanceWrite(tUSBRingBufObject *psUSBRingBuf,
                                   uint32_t ui32NumBytes);
extern void USBRingBufAdvanceRead(tUSBRingBufObject *psUSBRingBuf,
                                  uint32_t ui32NumBytes);
extern void USBRingBufInit(tUSBRingBufObject *psUSBRingBuf,
                           uint8_t *pui8Buf, uint32_t ui32Size);

//*****************************************************************************
//
// Mode selection and dual mode interrupt steering functions.
//
//*****************************************************************************
extern void USBStackModeSet(uint32_t ui32Index, tUSBMode iUSBMode,
                            tUSBModeCallback pfnCallback);
extern void USBDualModeInit(uint32_t ui32Index);
extern void USBDualModeTerm(uint32_t ui32Index);
extern void USBOTGMain(uint32_t ui32MsTicks);
extern void USBOTGPollRate(uint32_t ui32Index, uint32_t ui32PollRate);
extern void USBOTGModeInit(uint32_t ui32Index, uint32_t ui32PollRate,
                           void *pHostData, uint32_t ui32HostDataSize);
extern void USBOTGModeTerm(uint32_t ui32Index);
extern void USB0_IRQOTGModeHandler(void);
extern bool USBOTGFeatureSet(uint32_t ui32Index, uint32_t ui32Feature,
                             void *pvFeature);
extern void USB0DualModeIntHandler(void);

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

#endif // __USBLIB_H__