NIM_DSP6748/extern/usblib/include/usbhost.h

//*****************************************************************************
//
// usbhost.h - Host specific definitions for the USB host library.
//
// Copyright (c) 2008-2010 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.
// 
// This is part of revision 6288 of the Stellaris USB Library.
//
//*****************************************************************************

#ifndef __USBHOST_H__
#define __USBHOST_H__

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

//*****************************************************************************
//
//! \addtogroup usblib_hcd
//! @{
//
//*****************************************************************************

//*****************************************************************************
//
// This is the type used to identify what the pipe is currently in use for.
//
//*****************************************************************************
#define USBHCD_PIPE_UNUSED          0x00100000
#define USBHCD_PIPE_CONTROL         0x00130000
#define USBHCD_PIPE_BULK_OUT        0x00210000
#define USBHCD_PIPE_BULK_IN         0x00220000
#define USBHCD_PIPE_INTR_OUT        0x00410000
#define USBHCD_PIPE_INTR_IN         0x00420000
#define USBHCD_PIPE_ISOC_OUT        0x00810000
#define USBHCD_PIPE_ISOC_IN         0x00820000
#define USBHCD_PIPE_ISOC_OUT_DMA    0x01810000
#define USBHCD_PIPE_ISOC_IN_DMA     0x01820000
#define USBHCD_PIPE_BULK_OUT_DMA    0x01210000
#define USBHCD_PIPE_BULK_IN_DMA     0x01220000


//*****************************************************************************
//
// These are the defines that are used with USBHCDPowerConfigInit().
//
//*****************************************************************************
#define USBHCD_FAULT_LOW        0x00000010
#define USBHCD_FAULT_HIGH       0x00000030
#define USBHCD_FAULT_VBUS_NONE  0x00000000
#define USBHCD_FAULT_VBUS_TRI   0x00000140
#define USBHCD_FAULT_VBUS_DIS   0x00000400
#define USBHCD_VBUS_MANUAL      0x00000004
#define USBHCD_VBUS_AUTO_LOW    0x00000002
#define USBHCD_VBUS_AUTO_HIGH   0x00000003
#define USBHCD_VBUS_FILTER      0x00010000

//*****************************************************************************
//
// This is a fixed number as it relates to the maximum number of USB pipes
// available on any USB controller.  The actual number on a given device may
// be less than this number.
//
//*****************************************************************************
#define USBHCD_DEV_RECOVER_RETRY 3

//*****************************************************************************
//
// This is a fixed number as it relates to the maximum number of USB pipes
// available on any USB controller.  The actual number on a given device may
// be less than this number.
//
//*****************************************************************************
#define MAX_NUM_PIPES           15

//*****************************************************************************
//
// This is a fixed number as it relates to the number of USB pipes available
// in the USB controller.
//
//*****************************************************************************
#define MAX_NUM_DMA_CHANNELS    6

//*****************************************************************************
//
// Marker for an unused DMA channel slot.
//
//*****************************************************************************
#define USBHCD_DMA_UNUSED       0xff

//*****************************************************************************
//
// This structure holds the timeOut values for different communications.
//
//*****************************************************************************
#define USB_EP0_TIMEOUT_MILLISECS                   7000
#define USB_NONEP0_TIMEOUT_MILLISECS                7000
#define USB_TIMEOUT_DISABLE                           -1

typedef struct
{
    signed int slEP0;
    signed int slNonEP0;
}
tUSBHTimeOutType;
typedef struct
{
    tUSBHTimeOutType Value;
    tUSBHTimeOutType Status;
}
tUSBHTimeOut;

//*****************************************************************************
//
//! This macro is used to declare an instance of an Event driver for the USB
//! library.
//!
//! \param VarName is the name of the variable.
//! \param pfnOpen is the callback for the Open call to this driver.  This
//! value is currently reserved and should be set to 0.
//! \param pfnClose is the callback for the Close call to this driver.  This
//! value is currently reserved and should be set to 0.
//! \param pfnEvent is the callback that will be called for various USB events.
//!
//! The first parameter is the actual name of the variable that will
//! be declared by this macro.  The second and third parameter are reserved
//! for future functionality and are unused and should be set to zero.  The
//! last parameter is the actual callback function and is specified as
//! a function pointer of the type:
//!
//! void (*pfnEvent)(void *pvData);
//!
//! When the \e pfnEvent function is called the void pointer that is passed in
//! as a parameter should be cast to a pointer to a structure of type
//! tEventInfo.  This will contain the event that caused the pfnEvent function
//! to be called.
//
//*****************************************************************************
#define DECLARE_EVENT_DRIVER(VarName, pfnOpen, pfnClose, pfnEvent)          \
void IntFn(void *pvData);                                                   \
const tUSBHostClassDriver VarName =                                         \
{                                                                           \
    USB_CLASS_EVENTS,                                                       \
    0,                                                                      \
    0,                                                                      \
    pfnEvent                                                                \
}

//*****************************************************************************
//
//! This is the structure that holds all of the information for devices
//! that are enumerated in the system.   It is passed in to Open function of
//! USB host class drivers so that they can allocate any endpoints and parse
//! out other information that the device class needs to complete enumeration.
//
//*****************************************************************************
typedef struct
{
    //
    //! The current device address for this device.
    //
    unsigned int ulAddress;

    //
    //! The current interface for this device.
    //
    unsigned int ulInterface;

    //
    //! A pointer to the device descriptor for this device.
    //
    tDeviceDescriptor DeviceDescriptor;

    //
    //! A pointer to the configuration descriptor for this device.
    //
    tConfigDescriptor *pConfigDescriptor;

    //
    //! The size of the buffer allocated to pConfigDescriptor.
    //
    unsigned int ulConfigDescriptorSize;
	
    //
    //! Operating speed of the device
    //
    unsigned int ulDeviceSpeed;
}
tUSBHostDevice;

//*****************************************************************************
//
//! This structure defines a USB host class driver interface, it is parsed to
//! find a USB class driver once a USB device is enumerated.
//
//*****************************************************************************
typedef struct
{
    //
    //! The interface class that this device class driver supports.
    //
    unsigned int ulInterfaceClass;

    //
    //! The function is called when this class of device has been detected.
    //
    void * (*pfnOpen)(tUSBHostDevice *pDevice, unsigned int instNum);

    //
    //! The function is called when the device, originally opened with a call
    //! to the pfnOpen function, is disconnected.
    //
    void (*pfnClose)(void *pvInstance);

    //
    //! This is the optional interrupt handler that will be called when an
    //! endpoint associated with this device instance generates an interrupt.
    //
    void (*pfnIntHandler)(void *pvInstance);
}
tUSBHostClassDriver;

//*****************************************************************************
//
//! This structure is used to return generic event based information to an
//! application.  The following events are currently supported:
//! USB_EVENT_CONNECTED, USB_EVENT_DISCONNECTED, and USB_EVENT_POWER_FAULT.
//
//*****************************************************************************
typedef struct
{
    unsigned int ulEvent;

    unsigned int ulInstance;
}
tEventInfo;

//*****************************************************************************
//
// This is the type definition a call back for events on USB Pipes allocated
// by USBHCDPipeAlloc().
//
// \param ulPipe is well the pipe
// \param ulEvent is well the event
//
// inter def thand may need more text in order to be recogized what should
// this really say about ourselves.
//
// \return None.
//
//*****************************************************************************
typedef void (* tHCDPipeCallback)(unsigned int ulIndex, unsigned int ulPipe,
                                  unsigned int ulEvent);

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

//*****************************************************************************
//
// If the g_USBEventDriver is included in the host controller driver list then
// this function must be provided by the application.
//
//*****************************************************************************
void USBHCDEvents(void *pvData);
void USBMOUSEHCDEvents(void *pvData);


//*****************************************************************************
//
// Prototypes for the USB Host controller APIs.
//
//*****************************************************************************
extern void USBHCDMain(unsigned int ulIndex, unsigned int ulInstance);
extern void USBHCDInit(unsigned int ulIndex, void *pData,
                       unsigned int ulSize);
extern void USBHCDPowerConfigInit(unsigned int ulIndex,
                                  unsigned int ulFlags);
extern unsigned int USBHCDPowerConfigGet(unsigned int ulIndex);
extern unsigned int USBHCDPowerConfigSet(unsigned int ulIndex,
                                          unsigned int ulConfig);
extern unsigned int USBHCDPowerAutomatic(unsigned int ulIndex);
extern void
       USBHCDRegisterDrivers(unsigned int ulIndex,
                             const tUSBHostClassDriver * const *ppHClassDrvrs,
                             unsigned int ulNumDrivers);
extern void USBHCDTerm(unsigned int ulIndex);
extern void USBHCDSetConfig(unsigned int ulIndex, unsigned int ulDevice,
                            unsigned int ulConfiguration);
extern void USBHCDSetInterface(unsigned int ulIndex, unsigned int ulDevice,
                               unsigned int ulInterface,
                               unsigned ulAltSetting);
extern unsigned int USBHCDGetSpeed(unsigned int ulIndex);
extern void USBHCDSuspend(unsigned int ulIndex);
extern void USBHCDResume(unsigned int ulIndex);
extern void USBHCDReset(unsigned int ulIndex);
extern void USBHCDPipeFree(unsigned int ulIndex, unsigned int ulPipe);
extern unsigned int USBHCDPipeAlloc(unsigned int ulIndex,
                                     unsigned int ulEndpointType,
                                     unsigned int ulDevAddr,
                                     tHCDPipeCallback pCallback);
extern unsigned int USBHCDPipeAllocSize(unsigned int ulIndex,
                                     unsigned int ulEndpointType,
                                     unsigned int ulDevAddr,
                                     unsigned int ulFIFOSize,
                                     tHCDPipeCallback pCallback);
extern unsigned int USBHCDPipeConfig(unsigned int ulIndex,
                                      unsigned int ulPipe,
                                      unsigned int ulMaxPayload,
                                      unsigned int ulInterval,
                                      unsigned int ulTargetEndpoint);
extern unsigned int USBHCDPipeStatus(unsigned int ulPipe);
extern unsigned int USBHCDPipeWrite(unsigned int ulIndex,
                                    unsigned int ulPipe,
                                     unsigned char *pData,
                                     unsigned int ulSize);
extern unsigned int USBHCDPipeRead(unsigned int ulIndex,
                                    unsigned int ulPipe, 
                                    unsigned char *pData,
                                    unsigned int ulSize);
extern unsigned int USBHCDPipeSchedule(unsigned int ulIndex,
                                        unsigned int ulPipe,
                                        unsigned char *pucData,
                                        unsigned int ulSize);
extern unsigned int USBHCDPipeReadNonBlocking(unsigned int ulIndex, 
                                               unsigned int ulPipe,
                                               unsigned char *pucData,
                                               unsigned int ulSize);
extern unsigned int USBHCDControlTransfer(unsigned int ulIndex,
                                           tUSBRequest *pSetupPacket,
                                           unsigned int ulAddress,
                                           unsigned char *pData,
                                           unsigned int ulSize,
                                           unsigned int ulMaxPacketSize);
extern void USB0HostIntHandler(void);
extern void USB1HostIntHandler(void);
extern void USBHCDTimeOutHook(unsigned int ulIndex, 
	                                                        tUSBHTimeOut **USBHTimeOut);

//*****************************************************************************
//
// The host class drivers supported by the USB library.
//
//*****************************************************************************
extern const tUSBHostClassDriver g_USBHostMSCClassDriver;
extern const tUSBHostClassDriver g_USBHIDClassDriver;
extern const tUSBHostClassDriver g_USBHostAudioClassDriver;

//*****************************************************************************
//
// This is the structure used to hold the information for a given USB pipe
// that is attached to a device.
//
//*****************************************************************************
typedef struct
{
    //
    // The current address for this pipe.
    //
    unsigned int ulDevAddr;

    //
    // The current address for this pipe.
    //
    unsigned char ucEPNumber;

    //
    // The DMA channel assigned to this endpoint.
    //
    unsigned char ucDMAChannel;

    //
    // The current type for this pipe.
    //
    unsigned int ulType;

    //
    // The millisecond interval for this pipe.
    //
    unsigned int ulInterval;

    //
    // The next tick value to trigger and event on this pipe.
    //
    unsigned int ulNextEventTick;

    //
    // The current call back for this pipe.
    //
    tHCDPipeCallback pfnCallback;

    //
    // The state of a given USB pipe.
    //
    volatile enum
    {
        PIPE_READING,
        PIPE_DATA_READY,
        PIPE_DATA_SENT,
        PIPE_WRITING,
        PIPE_STALLED,
        PIPE_ERROR,
        PIPE_IDLE,
        PIPE_DISABLED
    }
    eState;

    //
    // The actual FIFO offset allocated to this endpoint.
    //
    unsigned short usFIFOAddr;

    //
    // The size of the FIFO entry based on the size parameter.  These are
    // equivalent to the USB_FIFO_SZ_* values in usb.h.
    //
    unsigned char ucFIFOSize;

    //
    // The bit offset in the allocation structure.
    //
    unsigned char ucFIFOBitOffset;
	
    //
    // Speed of the pipe.
    //
    unsigned int ulPipeSpeed;

    //
    // Speed of the pipe.
    //
    unsigned int ulEpMaxPacketSize;	

}
tUSBHCDPipe;

//*****************************************************************************
//
// The internal state of the device.
//
//*****************************************************************************
typedef enum
{
    HCD_DEV_DISCONNECTED,
    HCD_DEV_CONNECTED,
    HCD_DEV_REQUEST,
    HCD_DEV_RESET,
    HCD_DEV_ADDRESSED,
    HCD_DEV_CONFIGURED,
    HCD_DEV_GETSTRINGS,
    HCD_DEV_ERROR,
    HCD_VBUS_ERROR,
    HCD_POWER_FAULT,
    HCD_IDLE,
    HCD_BABBLE_ERROR
}
tUSBHDeviceState;


//*****************************************************************************
//
// This structure holds the state information for a given host controller.
//
//*****************************************************************************
typedef struct
{

        
    unsigned int ulUSBBase;
    unsigned int ulIndex;
    
    unsigned char *rxBuffer;
    volatile unsigned int ulUSBHIntEvents;
    volatile unsigned int ulDMAPending;
    unsigned int ulPowerConfig;
    volatile unsigned int ulCurrentTick;
    int iUSBHActiveDriver;
    void *pvDriverInstance;

    tUSBHCDPipe USBControlPipe;
    tUSBHCDPipe USBOUTPipes[MAX_NUM_PIPES];
    tUSBHCDPipe USBINPipes[MAX_NUM_PIPES];
    unsigned char ucDMAChannels[MAX_NUM_DMA_CHANNELS];

    //
    // Each devices state.
    //
    tUSBHostDevice USBDevice[1];

    //
    // Holds the current state of the device.
    //
    volatile tUSBHDeviceState eDeviceState[1];

    //
    // Pointer to the memory pool for this controller.
    //
    void *pvPool;

    //
    // The pool size for this controller.
    //
    unsigned int ulPoolSize;

    //
    // The class drivers for this controller.
    //
    const tUSBHostClassDriver * const *pClassDrivers;

    //
    // The number of class drivers.
    //
    unsigned int ulNumClassDrivers;

    //
    // This is the index in the driver list of the event driver.
    //
    int iEventDriver;

    //
    // This is the generic event information used by the event driver.
    //
    tEventInfo EventInfo;

    unsigned int ulClass;

    //
    // Error handling specific information.
    //
    // This indicates the number of times host trys to re-initiate communication with device before
    // escalating to the application. By default, it is initialized to USBHCD_DEV_RECOVER_RETRY
    // in HCDINIT. User can update this using 'SET_CONNECT_RETRY' MACRO after HCDINIT
    unsigned int ulConnectRetry;

    // This field is maintained by the USB stack and stores the Timeout related information.
    tUSBHTimeOut USBHTimeOut;
    // This is a pointer to Timeout related information and can be used by 
    // the application.
    tUSBHTimeOut *pUSBHTimeOut;
}
tUSBHCD;

extern unsigned int g_ulConnectRetry[USB_NUM_INSTANCE];
#define SET_CONNECT_RETRY(USBINSTANCE, RETRY_COUNT) g_ulConnectRetry[USBINSTANCE] = RETRY_COUNT

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

#endif // __USBHOST_H__