drivers/usb/dwc_otg_310/dwc_otg_hcd_if.h

   1 /* ==========================================================================
   2  * $File: //dwh/usb_iip/dev/software/otg/linux/drivers/dwc_otg_hcd_if.h $
   3  * $Revision: #12 $
   4  * $Date: 2011/10/26 $
   5  * $Change: 1873028 $
   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_DEVICE_ONLY
  34 #ifndef __DWC_HCD_IF_H__
  35 #define __DWC_HCD_IF_H__
  36
  37 #include "dwc_otg_core_if.h"
  38
  39 /** @file
  40  * This file defines DWC_OTG HCD Core API.
  41  */
  42
  43 struct dwc_otg_hcd;
  44 typedef struct dwc_otg_hcd dwc_otg_hcd_t;
  45
  46 struct dwc_otg_hcd_urb;
  47 typedef struct dwc_otg_hcd_urb dwc_otg_hcd_urb_t;
  48
  49 /** @name HCD Function Driver Callbacks */
  50 /** @{ */
  51
  52 /** This function is called whenever core switches to host mode. */
  53 typedef int (*dwc_otg_hcd_start_cb_t) (dwc_otg_hcd_t *hcd);
  54
  55 /** This function is called when device has been disconnected */
  56 typedef int (*dwc_otg_hcd_disconnect_cb_t) (dwc_otg_hcd_t *hcd);
  57
  58 /** Wrapper provides this function to HCD to core, so it can get hub information to which device is connected */
  59 typedef int (*dwc_otg_hcd_hub_info_from_urb_cb_t) (dwc_otg_hcd_t *hcd,
  60                                                    void *urb_handle,
  61                                                    uint32_t *hub_addr,
  62                                                    uint32_t *port_addr);
  63 /** Via this function HCD core gets device speed */
  64 typedef int (*dwc_otg_hcd_speed_from_urb_cb_t) (dwc_otg_hcd_t *hcd,
  65                                                 void *urb_handle);
  66
  67 /** This function is called when urb is completed */
  68 typedef int (*dwc_otg_hcd_complete_urb_cb_t) (dwc_otg_hcd_t *hcd,
  69                                               void *urb_handle,
  70                                               dwc_otg_hcd_urb_t *dwc_otg_urb,
  71                                               int32_t status);
  72
  73 /** Via this function HCD core gets b_hnp_enable parameter */
  74 typedef int (*dwc_otg_hcd_get_b_hnp_enable) (dwc_otg_hcd_t *hcd);
  75
  76 struct dwc_otg_hcd_function_ops {
  77         dwc_otg_hcd_start_cb_t start;
  78         dwc_otg_hcd_disconnect_cb_t disconnect;
  79         dwc_otg_hcd_hub_info_from_urb_cb_t hub_info;
  80         dwc_otg_hcd_speed_from_urb_cb_t speed;
  81         dwc_otg_hcd_complete_urb_cb_t complete;
  82         dwc_otg_hcd_get_b_hnp_enable get_b_hnp_enable;
  83 };
  84 /** @} */
  85
  86 /** @name HCD Core API */
  87 /** @{ */
  88 /** This function allocates dwc_otg_hcd structure and returns pointer on it. */
  89 extern dwc_otg_hcd_t *dwc_otg_hcd_alloc_hcd(void);
  90
  91 /** This function should be called to initiate HCD Core.
  92  *
  93  * @param hcd The HCD
  94  * @param core_if The DWC_OTG Core
  95  *
  96  * Returns -DWC_E_NO_MEMORY if no enough memory.
  97  * Returns 0 on success
  98  */
  99 extern int dwc_otg_hcd_init(dwc_otg_hcd_t *hcd, dwc_otg_core_if_t *core_if);
 100
 101 /** Frees HCD
 102  *
 103  * @param hcd The HCD
 104  */
 105 extern void dwc_otg_hcd_remove(dwc_otg_hcd_t *hcd);
 106
 107 /** This function should be called on every hardware interrupt.
 108  *
 109  * @param dwc_otg_hcd The HCD
 110  *
 111  * Returns non zero if interrupt is handled
 112  * Return 0 if interrupt is not handled
 113  */
 114 extern int32_t dwc_otg_hcd_handle_intr(dwc_otg_hcd_t *dwc_otg_hcd);
 115
 116 /**
 117  * Returns private data set by
 118  *dwc_otg_hcd_set_priv_data function.
 119  *
 120  * @param hcd The HCD
 121  */
 122 extern void *dwc_otg_hcd_get_priv_data(dwc_otg_hcd_t *hcd);
 123
 124 /**
 125  * Set private data.
 126  *
 127  * @param hcd The HCD
 128  * @param priv_data pointer to be stored in private data
 129  */
 130 extern void dwc_otg_hcd_set_priv_data(dwc_otg_hcd_t *hcd, void *priv_data);
 131
 132 /**
 133  * This function initializes the HCD Core.
 134  *
 135  * @param hcd The HCD
 136  * @param fops The Function Driver Operations data structure containing pointers to all callbacks.
 137  *
 138  * Returns -DWC_E_NO_DEVICE if Core is currently is in device mode.
 139  * Returns 0 on success
 140  */
 141 extern int dwc_otg_hcd_start(dwc_otg_hcd_t *hcd,
 142                              struct dwc_otg_hcd_function_ops *fops);
 143
 144 /**
 145  * Halts the DWC_otg host mode operations in a clean manner. USB transfers are
 146  * stopped.
 147  *
 148  * @param hcd The HCD
 149  */
 150 extern void dwc_otg_hcd_stop(dwc_otg_hcd_t *hcd);
 151
 152 /**
 153  * Handles hub class-specific requests.
 154  *
 155  * @param dwc_otg_hcd The HCD
 156  * @param typeReq Request Type
 157  * @param wValue wValue from control request
 158  * @param wIndex wIndex from control request
 159  * @param buf data buffer
 160  * @param wLength data buffer length
 161  *
 162  * Returns -DWC_E_INVALID if invalid argument is passed
 163  * Returns 0 on success
 164  */
 165 extern int dwc_otg_hcd_hub_control(dwc_otg_hcd_t *dwc_otg_hcd,
 166                                    uint16_t typeReq, uint16_t wValue,
 167                                    uint16_t wIndex, uint8_t *buf,
 168                                    uint16_t wLength);
 169
 170 /**
 171  * Returns otg port number.
 172  *
 173  * @param hcd The HCD
 174  */
 175 extern uint32_t dwc_otg_hcd_otg_port(dwc_otg_hcd_t *hcd);
 176
 177 /**
 178  * Returns OTG version - either 1.3 or 2.0.
 179  *
 180  * @param core_if The core_if structure pointer
 181  */
 182 extern uint16_t dwc_otg_get_otg_version(dwc_otg_core_if_t *core_if);
 183
 184 /**
 185  * Returns 1 if currently core is acting as B host, and 0 otherwise.
 186  *
 187  * @param hcd The HCD
 188  */
 189 extern uint32_t dwc_otg_hcd_is_b_host(dwc_otg_hcd_t *hcd);
 190
 191 /**
 192  * Returns current frame number.
 193  *
 194  * @param hcd The HCD
 195  */
 196 extern int dwc_otg_hcd_get_frame_number(dwc_otg_hcd_t *hcd);
 197
 198 /**
 199  * Dumps hcd state.
 200  *
 201  * @param hcd The HCD
 202  */
 203 extern void dwc_otg_hcd_dump_state(dwc_otg_hcd_t *hcd);
 204
 205 /**
 206  * Dump the average frame remaining at SOF. This can be used to
 207  * determine average interrupt latency. Frame remaining is also shown for
 208  * start transfer and two additional sample points.
 209  * Currently this function is not implemented.
 210  *
 211  * @param hcd The HCD
 212  */
 213 extern void dwc_otg_hcd_dump_frrem(dwc_otg_hcd_t *hcd);
 214
 215 /**
 216  * Sends LPM transaction to the local device.
 217  *
 218  * @param hcd The HCD
 219  * @param devaddr Device Address
 220  * @param hird Host initiated resume duration
 221  * @param bRemoteWake Value of bRemoteWake field in LPM transaction
 222  *
 223  * Returns negative value if sending LPM transaction was not succeeded.
 224  * Returns 0 on success.
 225  */
 226 extern int dwc_otg_hcd_send_lpm(dwc_otg_hcd_t *hcd, uint8_t devaddr,
 227                                 uint8_t hird, uint8_t bRemoteWake);
 228
 229 /* URB interface */
 230
 231 /**
 232  * Allocates memory for dwc_otg_hcd_urb structure.
 233  * Allocated memory should be freed by call of DWC_FREE.
 234  *
 235  * @param hcd The HCD
 236  * @param iso_desc_count Count of ISOC descriptors
 237  * @param atomic_alloc Specefies whether to perform atomic allocation.
 238  */
 239 extern dwc_otg_hcd_urb_t *dwc_otg_hcd_urb_alloc(dwc_otg_hcd_t *hcd,
 240                                                 int iso_desc_count,
 241                                                 int atomic_alloc);
 242
 243 /**
 244  * Set pipe information in URB.
 245  *
 246  * @param hcd_urb DWC_OTG URB
 247  * @param devaddr Device Address
 248  * @param ep_num Endpoint Number
 249  * @param ep_type Endpoint Type
 250  * @param ep_dir Endpoint Direction
 251  * @param mps Max Packet Size
 252  */
 253 extern void dwc_otg_hcd_urb_set_pipeinfo(dwc_otg_hcd_urb_t *hcd_urb,
 254                                          uint8_t devaddr, uint8_t ep_num,
 255                                          uint8_t ep_type, uint8_t ep_dir,
 256                                          uint16_t mps);
 257
 258 /* Transfer flags */
 259 #define URB_GIVEBACK_ASAP 0x1
 260 #define URB_SEND_ZERO_PACKET 0x2
 261
 262 /**
 263  * Sets dwc_otg_hcd_urb parameters.
 264  *
 265  * @param urb DWC_OTG URB allocated by dwc_otg_hcd_urb_alloc function.
 266  * @param urb_handle Unique handle for request, this will be passed back
 267  * to function driver in completion callback.
 268  * @param buf The buffer for the data
 269  * @param dma The DMA buffer for the data
 270  * @param buflen Transfer length
 271  * @param sp Buffer for setup data
 272  * @param sp_dma DMA address of setup data buffer
 273  * @param flags Transfer flags
 274  * @param interval Polling interval for interrupt or isochronous transfers.
 275  */
 276 extern void dwc_otg_hcd_urb_set_params(dwc_otg_hcd_urb_t *urb,
 277                                        void *urb_handle, void *buf,
 278                                        dwc_dma_t dma, uint32_t buflen, void *sp,
 279                                        dwc_dma_t sp_dma, uint32_t flags,
 280                                        uint16_t interval);
 281
 282 /** Gets status from dwc_otg_hcd_urb
 283  *
 284  * @param dwc_otg_urb DWC_OTG URB
 285  */
 286 extern uint32_t dwc_otg_hcd_urb_get_status(dwc_otg_hcd_urb_t *dwc_otg_urb);
 287
 288 /** Gets actual length from dwc_otg_hcd_urb
 289  *
 290  * @param dwc_otg_urb DWC_OTG URB
 291  */
 292 extern uint32_t dwc_otg_hcd_urb_get_actual_length(dwc_otg_hcd_urb_t *
 293                                                   dwc_otg_urb);
 294
 295 /** Gets error count from dwc_otg_hcd_urb. Only for ISOC URBs
 296  *
 297  * @param dwc_otg_urb DWC_OTG URB
 298  */
 299 extern uint32_t dwc_otg_hcd_urb_get_error_count(dwc_otg_hcd_urb_t *
 300                                                 dwc_otg_urb);
 301
 302 /** Set ISOC descriptor offset and length
 303  *
 304  * @param dwc_otg_urb DWC_OTG URB
 305  * @param desc_num ISOC descriptor number
 306  * @param offset Offset from beginig of buffer.
 307  * @param length Transaction length
 308  */
 309 extern void dwc_otg_hcd_urb_set_iso_desc_params(dwc_otg_hcd_urb_t *dwc_otg_urb,
 310                                                 int desc_num, uint32_t offset,
 311                                                 uint32_t length);
 312
 313 /** Get status of ISOC descriptor, specified by desc_num
 314  *
 315  * @param dwc_otg_urb DWC_OTG URB
 316  * @param desc_num ISOC descriptor number
 317  */
 318 extern uint32_t dwc_otg_hcd_urb_get_iso_desc_status(dwc_otg_hcd_urb_t *
 319                                                     dwc_otg_urb, int desc_num);
 320
 321 /** Get actual length of ISOC descriptor, specified by desc_num
 322  *
 323  * @param dwc_otg_urb DWC_OTG URB
 324  * @param desc_num ISOC descriptor number
 325  */
 326 extern uint32_t dwc_otg_hcd_urb_get_iso_desc_actual_length(dwc_otg_hcd_urb_t *
 327                                                            dwc_otg_urb,
 328                                                            int desc_num);
 329
 330 /** Queue URB. After transfer is completes, the complete callback will be called with the URB status
 331  *
 332  * @param dwc_otg_hcd The HCD
 333  * @param dwc_otg_urb DWC_OTG URB
 334  * @param ep_handle Out parameter for returning endpoint handle
 335  * @param atomic_alloc Flag to do atomic allocation if needed
 336  *
 337  * Returns -DWC_E_NO_DEVICE if no device is connected.
 338  * Returns -DWC_E_NO_MEMORY if there is no enough memory.
 339  * Returns 0 on success.
 340  */
 341 extern int dwc_otg_hcd_urb_enqueue(dwc_otg_hcd_t *dwc_otg_hcd,
 342                                    dwc_otg_hcd_urb_t *dwc_otg_urb,
 343                                    void **ep_handle, int atomic_alloc);
 344
 345 /** De-queue the specified URB
 346  *
 347  * @param dwc_otg_hcd The HCD
 348  * @param dwc_otg_urb DWC_OTG URB
 349  */
 350 extern int dwc_otg_hcd_urb_dequeue(dwc_otg_hcd_t *dwc_otg_hcd,
 351                                    dwc_otg_hcd_urb_t *dwc_otg_urb);
 352
 353 /** Frees resources in the DWC_otg controller related to a given endpoint.
 354  * Any URBs for the endpoint must already be dequeued.
 355  *
 356  * @param hcd The HCD
 357  * @param ep_handle Endpoint handle, returned by dwc_otg_hcd_urb_enqueue function
 358  * @param retry Number of retries if there are queued transfers.
 359  *
 360  * Returns -DWC_E_INVALID if invalid arguments are passed.
 361  * Returns 0 on success
 362  */
 363 extern int dwc_otg_hcd_endpoint_disable(dwc_otg_hcd_t *hcd, void *ep_handle,
 364                                         int retry);
 365
 366 /* Resets the data toggle in qh structure. This function can be called from
 367  * usb_clear_halt routine.
 368  *
 369  * @param hcd The HCD
 370  * @param ep_handle Endpoint handle, returned by dwc_otg_hcd_urb_enqueue function
 371  *
 372  * Returns -DWC_E_INVALID if invalid arguments are passed.
 373  * Returns 0 on success
 374  */
 375 extern int dwc_otg_hcd_endpoint_reset(dwc_otg_hcd_t *hcd, void *ep_handle);
 376
 377 /** Returns 1 if status of specified port is changed and 0 otherwise.
 378  *
 379  * @param hcd The HCD
 380  * @param port Port number
 381  */
 382 extern int dwc_otg_hcd_is_status_changed(dwc_otg_hcd_t *hcd, int port);
 383
 384 /** Call this function to check if bandwidth was allocated for specified endpoint.
 385  * Only for ISOC and INTERRUPT endpoints.
 386  *
 387  * @param hcd The HCD
 388  * @param ep_handle Endpoint handle
 389  */
 390 extern int dwc_otg_hcd_is_bandwidth_allocated(dwc_otg_hcd_t *hcd,
 391                                               void *ep_handle);
 392
 393 /** Call this function to check if bandwidth was freed for specified endpoint.
 394  *
 395  * @param hcd The HCD
 396  * @param ep_handle Endpoint handle
 397  */
 398 extern int dwc_otg_hcd_is_bandwidth_freed(dwc_otg_hcd_t *hcd, void *ep_handle);
 399
 400 /** Returns bandwidth allocated for specified endpoint in microseconds.
 401  * Only for ISOC and INTERRUPT endpoints.
 402  *
 403  * @param hcd The HCD
 404  * @param ep_handle Endpoint handle
 405  */
 406 extern uint8_t dwc_otg_hcd_get_ep_bandwidth(dwc_otg_hcd_t *hcd,
 407                                             void *ep_handle);
 408
 409 /** @} */
 410
 411 #endif /* __DWC_HCD_IF_H__ */
 412 #endif /* DWC_DEVICE_ONLY */