usb_drv.h

   1 /*
   2  * Copyright (c) 2014-2019, Texas Instruments Incorporated
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * *  Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  *
  12  * *  Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  *
  16  * *  Neither the name of Texas Instruments Incorporated nor the names of
  17  *    its contributors may be used to endorse or promote products derived
  18  *    from this software without specific prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32 /** ============================================================================
  33  *  @file       usb_drv.h
  34  *
  35  *  @brief      USB driver interface
  36  *
  37  *  The USB header file should be included in an application as follows:
  38  *  @code
  39  *  #include <ti/drv/usb/usb_drv.h>
  40  *  @endcode
  41  *
  42  *  # Operation #
  43  *  The USB driver
  44  *
  45  *  The APIs in this driver serve as an interface to a typical TI-RTOS
  46  *  application. The specific peripheral implementations are responsible to
  47  *  create all the OS specific primitives to allow for thread-safe
  48  *  operation.
  49  *
  50  *  ## Opening the driver #
  51  *
  52  *  @code
  53  *  USB_Handle      handle;
  54  *  USB_Params      params;
  55  *
  56  *  USB_Params_init(&params);
  57  *
  58  *  handle = USB_open(someUSB_configIndexValue, &params);
  59  *  if (!handle) {
  60  *      System_printf("USB did not open");
  61  *  }
  62  *  @endcode
  63  *
  64  *  # Implementation #
  65  *
  66  *  This module serves as the main interface for TI-RTOS
  67  *  applications. Its purpose is to redirect the module's APIs to specific
  68  *  peripheral implementations which are specified using a pointer to a
  69  *  USB_FxnTable.
  70  *
  71  *  The USB driver interface module is joined (at link time) to a
  72  *  NULL-terminated array of USB_Config data structures named *USB_config*.
  73  *  *USB_config* is implemented in the application with each entry being an
  74  *  instance of a USB peripheral. Each entry in *USB_config* contains a:
  75  *  - (USB_FxnTable *) to a set of functions that implement a USB peripheral
  76  *  - (void *) data object that is associated with the USB_FxnTable
  77  *  - (void *) hardware attributes that are associated to the USB_FxnTable
  78  *
  79  *
  80  *  ============================================================================
  81  */
  82
  83 #ifndef ti_drivers_USB__include
  84 #define ti_drivers_USB__include
  85
  86 #ifdef __cplusplus
  87 extern "C" {
  88 #endif
  89
  90
  91 #define USB_ERROR  -1
  92
  93 /******************************************************************************
  94  * The below macro defines the number USB Instances.
  95  *
  96  ******************************************************************************/
  97
  98 /*!
  99  *  @brief      A handle that is returned from a USB_open() call.
 100  */
 101 typedef struct  USB_Config          *USB_Handle;
 102
 103
 104 /*!
 105  *  @brief      USB mode settings
 106  *
 107  *  This enum
 108  *  configured USB.
 109  */
 110 typedef enum USB_Mode {
 111     USB_UNKNOWN_MODE,
 112     USB_HOST_MSC_MODE,
 113     USB_DEVICE_MSC_MODE,
 114     USB_HOST_AC_MODE, /*USB Audio class Host mode*/
 115     USB_DEVICE_AC_MODE,
 116     USB_DEVICE_BULK_MODE,
 117     USB_DEVICE_CDC_MODE
 118 } USB_Mode;
 119
 120 /*!
 121  *  @brief    Basic USB Parameters
 122  */
 123 typedef struct USB_Params {
 124     USB_Mode        usbMode;        /*!< Mode for the controller */
 125     uint32_t        instanceNo;     /* the controller that this instance run on */
 126     USB_Handle      usbHandle;
 127     void*           drvData;        /* pointer to private driver config structure */
 128     void*           usbClassData;   /* pointer to USB Class (MSC, Video, Audio, HID, etc.) data */
 129
 130     void*           readSem;        /* read semaphore */
 131     void*           writeSem;       /* write semaphore */
 132 } USB_Params;
 133
 134
 135
 136
 137 /*!
 138  *  @brief      A function pointer to a driver specific implementation of
 139  *              USB_init().
 140  */
 141 typedef void        (*USB_InitFxn)           (USB_Handle handle);
 142
 143 /*!
 144  *  @brief      A function pointer to a driver specific implementation of
 145  *              USB_OpenFxn().
 146  */
 147 typedef USB_Handle  (*USB_OpenFxn)           (USB_Handle handle,
 148                                              USB_Params *params);
 149
 150
 151 /*!
 152  *  @brief      A function pointer to a driver specific implementation of
 153  *              USB_IrqConfigFxn().
 154  */
 155 typedef void        (*USB_IrqConfigFxn)     (USB_Handle handle,
 156                                              USB_Params* params);
 157
 158 /*!
 159  *  @brief      A handler for USB interrupts driver specific implementation of
 160  *              ISR handler.
 161  */
 162 typedef void        (*USB_IsrHandlerFxn)     (USB_Handle handle, USB_Params* arg);
 163
 164 /*!
 165  *  @brief      The definition of a USB function table that contains the
 166  *              required set of functions to control a specific USB driver
 167  *              implementation.
 168  */
 169 typedef struct USB_FxnTable {
 170     /*! Function to open the specified peripheral */
 171     USB_OpenFxn            openFxn;
 172
 173     /* interrupt Enabler for IP specified interrupts */
 174     USB_IrqConfigFxn       irqConfigFxn;
 175
 176     /* interrupt handler */
 177     USB_IsrHandlerFxn      irqCoreFxn;
 178     USB_IsrHandlerFxn      irqMiscFxn;
 179
 180 } USB_FxnTable;
 181
 182
 183 /*! @brief USB Global configuration */
 184 typedef struct USB_Config {
 185     /*! Pointer to a table of a driver-specific implementation of USB functions */
 186     USB_FxnTable const    *fxnTablePtr;
 187     uint32_t              isOpened;
 188     uint32_t              handleCppiDmaInApp; /* if this is TRUE, AM3 CPPI DMA
 189                                                  handler needs to be registered and
 190                                                  handled in user application.
 191                                                  This setting has no effect on AM4,
 192                                                  AM5, K2s */
 193     uint32_t              dmaEnabled;         /* DMA is optional in AM3 only */
 194     uint32_t              usb30Enabled;       /* TRUE if USB3.0 Super Speed is
 195                                                  enabled. Set to False if USB3.0 SS
 196                                                  is not required. Set to False if USB3.0 SS
 197                                                  is not required. Used in SOC that has
 198                                                  shared SERDES */
 199
 200     USB_Params            *usbParams;
 201
 202     uint32_t              usb2PhyRefClkFreq;  /* frequency (KHz) of the ref clock that's the
 203                                                  the USB2.0 PHY is running at */
 204
 205     uint32_t              vbusDivider;        /* VBUS divider. 1: VBUS goes through a divider
 206                                                *               0: no divider */
 207     uint32_t              serdesId;           /* SERDES instance being used with this USB
 208                                                  instance */
 209
 210 } USB_Config;
 211
 212
 213 /*!
 214  *  @brief  Function to initialize a given USB peripheral specified by the
 215  *          particular index value. The parameter specifies which mode the USB
 216  *          will operate.
 217  *
 218  *  @pre
 219  *
 220  *  @param  index         Physical USB instance number
 221  *
 222  *  @param  params        Pointer to an parameter block, required.
 223  *
 224  *  @return A USB_Handle on success or a NULL on an error or if it has been
 225  *          already opened
 226  *
 227  *  @sa     USB_close
 228  */
 229 extern USB_Handle USB_open(unsigned int index, USB_Params *params);
 230
 231 /*!
 232  *  @brief  Function to setup peripheral internal IRQ settings.
 233  *
 234  *  @pre    USB controller needs to open previously
 235  *
 236  *  @param  handle        handle to the USB instance which has been openned
 237  *
 238  *  @param  params        Pointer to an parameter block, required.
 239  *
 240  */
 241 extern void USB_irqConfig(USB_Handle handle, USB_Params *params);
 242
 243 /*!
 244  *  @brief  core IRQ handler from USB driver.
 245  *
 246  *  @pre    USB controller needs to open previously
 247  *
 248  */
 249 extern void USB_coreIrqHandler(USB_Handle handle, USB_Params *params);
 250
 251 /*!
 252  *  @brief  misc IRQ handler from USB driver.
 253  *
 254  *  @pre    USB controller needs to open previously
 255  *
 256  */
 257 extern void USB_miscIrqHandler(USB_Handle handle, USB_Params *params);
 258
 259 /*!
 260  *  @brief  return USB driver configuration block.
 261  *
 262  *  @pre    none
 263             can be called any time even before the usb_open()
 264  *
 265  */
 266 extern void USB_getConfig(uint32_t usbInstanceNo, USB_Config** usbConfig);
 267
 268
 269 #ifdef __cplusplus
 270 }
 271 #endif
 272
 273 #endif /* ti_drivers_USB__include */