drivers/usb/dwc_otg_310/dwc_otg_pcd_if.h

   1 /* ==========================================================================
   2  * $File: //dwh/usb_iip/dev/software/otg/linux/drivers/dwc_otg_pcd_if.h $
   3  * $Revision: #13 $
   4  * $Date: 2012/12/12 $
   5  * $Change: 2125019 $
   6  *
   7  * Synopsys HS OTG Linux Software Driver and documentation (hereinafter,
   8  * "Software") is an Unsupported proprietary work of Synopsys, Inc. unless
   9  * otherwise expressly agreed to in writing between Synopsys and you.
  10  *
  11  * The Software IS NOT an item of Licensed Software or Licensed Product under
  12  * any End User Software License Agreement or Agreement for Licensed Product
  13  * with Synopsys or any supplement thereto. You are permitted to use and
  14  * redistribute this Software in source and binary forms, with or without
  15  * modification, provided that redistributions of source code must retain this
  16  * notice. You may not view, use, disclose, copy or distribute this file or
  17  * any information contained herein except pursuant to this license grant from
  18  * Synopsys. If you do not agree with this notice, including the disclaimer
  19  * below, then you are not authorized to use the Software.
  20  *
  21  * THIS SOFTWARE IS BEING DISTRIBUTED BY SYNOPSYS SOLELY ON AN "AS IS" BASIS
  22  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24  * ARE HEREBY DISCLAIMED. IN NO EVENT SHALL SYNOPSYS BE LIABLE FOR ANY DIRECT,
  25  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  26  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  27  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  28  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  31  * DAMAGE.
  32  * ========================================================================== */
  33 #ifndef DWC_HOST_ONLY
  34
  35 #if !defined(__DWC_PCD_IF_H__)
  36 #define __DWC_PCD_IF_H__
  37
  38 /* #include "common_port/dwc_os.h" */
  39 #include "dwc_otg_core_if.h"
  40
  41 /** @file
  42  * This file defines DWC_OTG PCD Core API.
  43  */
  44
  45 struct dwc_otg_pcd;
  46 typedef struct dwc_otg_pcd dwc_otg_pcd_t;
  47
  48 /** Maxpacket size for EP0 */
  49 #define MAX_EP0_SIZE    64
  50 /** Maxpacket size for any EP */
  51 #define MAX_PACKET_SIZE 1024
  52
  53 /** @name Function Driver Callbacks */
  54 /** @{ */
  55
  56 /** This function will be called whenever a previously queued request has
  57  * completed.  The status value will be set to -DWC_E_SHUTDOWN to indicated a
  58  * failed or aborted transfer, or -DWC_E_RESTART to indicate the device was reset,
  59  * or -DWC_E_TIMEOUT to indicate it timed out, or -DWC_E_INVALID to indicate invalid
  60  * parameters. */
  61 typedef int (*dwc_completion_cb_t) (dwc_otg_pcd_t *pcd, void *ep_handle,
  62                                     void *req_handle, int32_t status,
  63                                     uint32_t actual);
  64 /**
  65  * This function will be called whenever a previousle queued ISOC request has
  66  * completed. Count of ISOC packets could be read using dwc_otg_pcd_get_iso_packet_count
  67  * function.
  68  * The status of each ISOC packet could be read using dwc_otg_pcd_get_iso_packet_*
  69  * functions.
  70  */
  71 typedef int (*dwc_isoc_completion_cb_t) (dwc_otg_pcd_t *pcd, void *ep_handle,
  72                                          void *req_handle, int proc_buf_num);
  73 /** This function should handle any SETUP request that cannot be handled by the
  74  * PCD Core.  This includes most GET_DESCRIPTORs, SET_CONFIGS, Any
  75  * class-specific requests, etc.  The function must non-blocking.
  76  *
  77  * Returns 0 on success.
  78  * Returns -DWC_E_NOT_SUPPORTED if the request is not supported.
  79  * Returns -DWC_E_INVALID if the setup request had invalid parameters or bytes.
  80  * Returns -DWC_E_SHUTDOWN on any other error. */
  81 typedef int (*dwc_setup_cb_t) (dwc_otg_pcd_t *pcd, uint8_t *bytes);
  82 /** This is called whenever the device has been disconnected.  The function
  83  * driver should take appropriate action to clean up all pending requests in the
  84  * PCD Core, remove all endpoints (except ep0), and initialize back to reset
  85  * state. */
  86 typedef int (*dwc_disconnect_cb_t) (dwc_otg_pcd_t *pcd);
  87 /** This function is called when device has been connected. */
  88 typedef int (*dwc_connect_cb_t) (dwc_otg_pcd_t *pcd, int speed);
  89 /** This function is called when device has been suspended */
  90 typedef int (*dwc_suspend_cb_t) (dwc_otg_pcd_t *pcd);
  91 /** This function is called when device has received LPM tokens, i.e.
  92  * device has been sent to sleep state. */
  93 typedef int (*dwc_sleep_cb_t) (dwc_otg_pcd_t *pcd);
  94 /** This function is called when device has been resumed
  95  * from suspend(L2) or L1 sleep state. */
  96 typedef int (*dwc_resume_cb_t) (dwc_otg_pcd_t *pcd);
  97 /** This function is called whenever hnp params has been changed.
  98  * User can call get_b_hnp_enable, get_a_hnp_support, get_a_alt_hnp_support functions
  99  * to get hnp parameters. */
 100 typedef int (*dwc_hnp_params_changed_cb_t) (dwc_otg_pcd_t *pcd);
 101 /** This function is called whenever USB RESET is detected. */
 102 typedef int (*dwc_reset_cb_t) (dwc_otg_pcd_t *pcd);
 103
 104 typedef int (*cfi_setup_cb_t) (dwc_otg_pcd_t *pcd, void *ctrl_req_bytes);
 105
 106 /**
 107  *
 108  * @param ep_handle     Void pointer to the usb_ep structure
 109  * @param ereq_port Pointer to the extended request structure created in the
 110  *                                      portable part.
 111  */
 112 typedef int (*xiso_completion_cb_t) (dwc_otg_pcd_t *pcd, void *ep_handle,
 113                                      void *req_handle, int32_t status,
 114                                      void *ereq_port);
 115 /** Function Driver Ops Data Structure */
 116 struct dwc_otg_pcd_function_ops {
 117         dwc_connect_cb_t connect;
 118         dwc_disconnect_cb_t disconnect;
 119         dwc_setup_cb_t setup;
 120         dwc_completion_cb_t complete;
 121         dwc_isoc_completion_cb_t isoc_complete;
 122         dwc_suspend_cb_t suspend;
 123         dwc_sleep_cb_t sleep;
 124         dwc_resume_cb_t resume;
 125         dwc_reset_cb_t reset;
 126         dwc_hnp_params_changed_cb_t hnp_changed;
 127         cfi_setup_cb_t cfi_setup;
 128 #ifdef DWC_UTE_PER_IO
 129         xiso_completion_cb_t xisoc_complete;
 130 #endif
 131 };
 132 /** @} */
 133
 134 /** @name Function Driver Functions */
 135 /** @{ */
 136
 137 /** Call this function to get pointer on dwc_otg_pcd_t,
 138  * this pointer will be used for all PCD API functions.
 139  *
 140  * @param core_if The DWC_OTG Core
 141  */
 142 extern dwc_otg_pcd_t *dwc_otg_pcd_init(dwc_otg_core_if_t *core_if);
 143
 144 /** Frees PCD allocated by dwc_otg_pcd_init
 145  *
 146  * @param pcd The PCD
 147  */
 148 extern void dwc_otg_pcd_remove(dwc_otg_pcd_t *pcd);
 149
 150 /** Call this to bind the function driver to the PCD Core.
 151  *
 152  * @param pcd Pointer on dwc_otg_pcd_t returned by dwc_otg_pcd_init function.
 153  * @param fops The Function Driver Ops data structure containing pointers to all callbacks.
 154  */
 155 extern void dwc_otg_pcd_start(dwc_otg_pcd_t *pcd,
 156                               const struct dwc_otg_pcd_function_ops *fops);
 157
 158 /** Enables an endpoint for use.  This function enables an endpoint in
 159  * the PCD.  The endpoint is described by the ep_desc which has the
 160  * same format as a USB ep descriptor.  The ep_handle parameter is used to refer
 161  * to the endpoint from other API functions and in callbacks.  Normally this
 162  * should be called after a SET_CONFIGURATION/SET_INTERFACE to configure the
 163  * core for that interface.
 164  *
 165  * Returns -DWC_E_INVALID if invalid parameters were passed.
 166  * Returns -DWC_E_SHUTDOWN if any other error ocurred.
 167  * Returns 0 on success.
 168  *
 169  * @param pcd The PCD
 170  * @param ep_desc Endpoint descriptor
 171  * @param ep_handle Handle on endpoint, that will be used to identify endpoint.
 172  */
 173 extern int dwc_otg_pcd_ep_enable(dwc_otg_pcd_t *pcd,
 174                                  const uint8_t *ep_desc, void *ep_handle);
 175
 176 /** Disable the endpoint referenced by ep_handle.
 177  *
 178  * Returns -DWC_E_INVALID if invalid parameters were passed.
 179  * Returns -DWC_E_SHUTDOWN if any other error occurred.
 180  * Returns 0 on success. */
 181 extern int dwc_otg_pcd_ep_disable(dwc_otg_pcd_t *pcd, void *ep_handle);
 182
 183 /** Queue a data transfer request on the endpoint referenced by ep_handle.
 184  * After the transfer is completes, the complete callback will be called with
 185  * the request status.
 186  *
 187  * @param pcd The PCD
 188  * @param ep_handle The handle of the endpoint
 189  * @param buf The buffer for the data
 190  * @param dma_buf The DMA buffer for the data
 191  * @param buflen The length of the data transfer
 192  * @param zero Specifies whether to send zero length last packet.
 193  * @param req_handle Set this handle to any value to use to reference this
 194  * request in the ep_dequeue function or from the complete callback
 195  * @param atomic_alloc If driver need to perform atomic allocations
 196  * for internal data structures.
 197  *
 198  * Returns -DWC_E_INVALID if invalid parameters were passed.
 199  * Returns -DWC_E_SHUTDOWN if any other error ocurred.
 200  * Returns 0 on success. */
 201 extern int dwc_otg_pcd_ep_queue(dwc_otg_pcd_t *pcd, void *ep_handle,
 202                                 uint8_t *buf, dwc_dma_t dma_buf,
 203                                 uint32_t buflen, int zero, void *req_handle,
 204                                 int atomic_alloc);
 205 #ifdef DWC_UTE_PER_IO
 206 /**
 207  *
 208  * @param ereq_nonport  Pointer to the extended request part of the
 209  *                                              usb_request structure defined in usb_gadget.h file.
 210  */
 211 extern int dwc_otg_pcd_xiso_ep_queue(dwc_otg_pcd_t *pcd, void *ep_handle,
 212                                      uint8_t *buf, dwc_dma_t dma_buf,
 213                                      uint32_t buflen, int zero,
 214                                      void *req_handle, int atomic_alloc,
 215                                      void *ereq_nonport);
 216
 217 #endif
 218
 219 /** De-queue the specified data transfer that has not yet completed.
 220  *
 221  * Returns -DWC_E_INVALID if invalid parameters were passed.
 222  * Returns -DWC_E_SHUTDOWN if any other error ocurred.
 223  * Returns 0 on success. */
 224 extern int dwc_otg_pcd_ep_dequeue(dwc_otg_pcd_t *pcd, void *ep_handle,
 225                                   void *req_handle);
 226
 227 /** Halt (STALL) an endpoint or clear it.
 228  *
 229  * Returns -DWC_E_INVALID if invalid parameters were passed.
 230  * Returns -DWC_E_SHUTDOWN if any other error ocurred.
 231  * Returns -DWC_E_AGAIN if the STALL cannot be sent and must be tried again later
 232  * Returns 0 on success. */
 233 extern int dwc_otg_pcd_ep_halt(dwc_otg_pcd_t *pcd, void *ep_handle, int value);
 234
 235 /** This function should be called on every hardware interrupt */
 236 extern int32_t dwc_otg_pcd_handle_intr(dwc_otg_pcd_t *pcd);
 237
 238 /** This function returns current frame number */
 239 extern int dwc_otg_pcd_get_frame_number(dwc_otg_pcd_t *pcd);
 240
 241 /**
 242  * Start isochronous transfers on the endpoint referenced by ep_handle.
 243  * For isochronous transfers duble buffering is used.
 244  * After processing each of buffers comlete callback will be called with
 245  * status for each transaction.
 246  *
 247  * @param pcd The PCD
 248  * @param ep_handle The handle of the endpoint
 249  * @param buf0 The virtual address of first data buffer
 250  * @param buf1 The virtual address of second data buffer
 251  * @param dma0 The DMA address of first data buffer
 252  * @param dma1 The DMA address of second data buffer
 253  * @param sync_frame Data pattern frame number
 254  * @param dp_frame Data size for pattern frame
 255  * @param data_per_frame Data size for regular frame
 256  * @param start_frame Frame number to start transfers, if -1 then start transfers ASAP.
 257  * @param buf_proc_intrvl Interval of ISOC Buffer processing
 258  * @param req_handle Handle of ISOC request
 259  * @param atomic_alloc Specefies whether to perform atomic allocation for
 260  *                      internal data structures.
 261  *
 262  * Returns -DWC_E_NO_MEMORY if there is no enough memory.
 263  * Returns -DWC_E_INVALID if incorrect arguments are passed to the function.
 264  * Returns -DW_E_SHUTDOWN for any other error.
 265  * Returns 0 on success
 266  */
 267 extern int dwc_otg_pcd_iso_ep_start(dwc_otg_pcd_t *pcd, void *ep_handle,
 268                                     uint8_t *buf0, uint8_t *buf1,
 269                                     dwc_dma_t dma0, dwc_dma_t dma1,
 270                                     int sync_frame, int dp_frame,
 271                                     int data_per_frame, int start_frame,
 272                                     int buf_proc_intrvl, void *req_handle,
 273                                     int atomic_alloc);
 274
 275 /** Stop ISOC transfers on endpoint referenced by ep_handle.
 276  *
 277  * @param pcd The PCD
 278  * @param ep_handle The handle of the endpoint
 279  * @param req_handle Handle of ISOC request
 280  *
 281  * Returns -DWC_E_INVALID if incorrect arguments are passed to the function
 282  * Returns 0 on success
 283  */
 284 int dwc_otg_pcd_iso_ep_stop(dwc_otg_pcd_t *pcd, void *ep_handle,
 285                             void *req_handle);
 286
 287 /** Get ISOC packet status.
 288  *
 289  * @param pcd The PCD
 290  * @param ep_handle The handle of the endpoint
 291  * @param iso_req_handle Isochronoush request handle
 292  * @param packet Number of packet
 293  * @param status Out parameter for returning status
 294  * @param actual Out parameter for returning actual length
 295  * @param offset Out parameter for returning offset
 296  *
 297  */
 298 extern void dwc_otg_pcd_get_iso_packet_params(dwc_otg_pcd_t *pcd,
 299                                               void *ep_handle,
 300                                               void *iso_req_handle, int packet,
 301                                               int *status, int *actual,
 302                                               int *offset);
 303
 304 /** Get ISOC packet count.
 305  *
 306  * @param pcd The PCD
 307  * @param ep_handle The handle of the endpoint
 308  * @param iso_req_handle
 309  */
 310 extern int dwc_otg_pcd_get_iso_packet_count(dwc_otg_pcd_t *pcd,
 311                                             void *ep_handle,
 312                                             void *iso_req_handle);
 313
 314 /** This function starts the SRP Protocol if no session is in progress. If
 315  * a session is already in progress, but the device is suspended,
 316  * remote wakeup signaling is started.
 317  */
 318 extern int dwc_otg_pcd_wakeup(dwc_otg_pcd_t *pcd);
 319
 320 /** This function returns 1 if LPM support is enabled, and 0 otherwise. */
 321 extern int dwc_otg_pcd_is_lpm_enabled(dwc_otg_pcd_t *pcd);
 322
 323 /** This function returns 1 if LPM Errata support is enabled, and 0 otherwise. */
 324 extern int dwc_otg_pcd_is_besl_enabled(dwc_otg_pcd_t *pcd);
 325
 326 /** This function returns baseline_besl module parametr. */
 327 extern int dwc_otg_pcd_get_param_baseline_besl(dwc_otg_pcd_t *pcd);
 328
 329 /** This function returns deep_besl module parametr. */
 330 extern int dwc_otg_pcd_get_param_deep_besl(dwc_otg_pcd_t *pcd);
 331
 332 /** This function returns 1 if remote wakeup is allowed and 0, otherwise. */
 333 extern int dwc_otg_pcd_get_rmwkup_enable(dwc_otg_pcd_t *pcd);
 334
 335 /** Initiate SRP */
 336 extern void dwc_otg_pcd_initiate_srp(dwc_otg_pcd_t *pcd);
 337
 338 /** Starts remote wakeup signaling. */
 339 extern void dwc_otg_pcd_remote_wakeup(dwc_otg_pcd_t *pcd, int set);
 340
 341 /** Starts micorsecond soft disconnect. */
 342 extern void dwc_otg_pcd_disconnect_us(dwc_otg_pcd_t *pcd, int no_of_usecs);
 343 /** This function returns whether device is dualspeed.*/
 344 extern uint32_t dwc_otg_pcd_is_dualspeed(dwc_otg_pcd_t *pcd);
 345
 346 /** This function returns whether device is otg. */
 347 extern uint32_t dwc_otg_pcd_is_otg(dwc_otg_pcd_t *pcd);
 348
 349 /** These functions allow to get hnp parameters */
 350 extern uint32_t get_b_hnp_enable(dwc_otg_pcd_t *pcd);
 351 extern uint32_t get_a_hnp_support(dwc_otg_pcd_t *pcd);
 352 extern uint32_t get_a_alt_hnp_support(dwc_otg_pcd_t *pcd);
 353
 354 /** CFI specific Interface functions */
 355 /** Allocate a cfi buffer */
 356 extern uint8_t *cfiw_ep_alloc_buffer(dwc_otg_pcd_t *pcd, void *pep,
 357                                      dwc_dma_t *addr, size_t buflen,
 358                                      int flags);
 359
 360 /** Device soft-connect and soft-disconnect*/
 361 extern void dwc_otg_pcd_pullup_enable(dwc_otg_pcd_t *pcd);
 362 extern void dwc_otg_pcd_pullup_disable(dwc_otg_pcd_t *pcd);
 363
 364 /******************************************************************************/
 365
 366 /** @} */
 367
 368 #endif /* __DWC_PCD_IF_H__ */
 369
 370 #endif /* DWC_HOST_ONLY */