drivers/usb/host/dwc_otg/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 /** This function is used to handle the fast interrupt
 117  *
 118  */
 119 #ifdef CONFIG_ARM64
 120 extern void dwc_otg_hcd_handle_fiq(void);
 121 #else
 122 extern void __attribute__ ((naked)) dwc_otg_hcd_handle_fiq(void);
 123 #endif
 124
 125 /**
 126  * Returns private data set by
 127  * dwc_otg_hcd_set_priv_data function.
 128  *
 129  * @param hcd The HCD
 130  */
 131 extern void *dwc_otg_hcd_get_priv_data(dwc_otg_hcd_t * hcd);
 132
 133 /**
 134  * Set private data.
 135  *
 136  * @param hcd The HCD
 137  * @param priv_data pointer to be stored in private data
 138  */
 139 extern void dwc_otg_hcd_set_priv_data(dwc_otg_hcd_t * hcd, void *priv_data);
 140
 141 /**
 142  * This function initializes the HCD Core.
 143  *
 144  * @param hcd The HCD
 145  * @param fops The Function Driver Operations data structure containing pointers to all callbacks.
 146  *
 147  * Returns -DWC_E_NO_DEVICE if Core is currently is in device mode.
 148  * Returns 0 on success
 149  */
 150 extern int dwc_otg_hcd_start(dwc_otg_hcd_t * hcd,
 151                              struct dwc_otg_hcd_function_ops *fops);
 152
 153 /**
 154  * Halts the DWC_otg host mode operations in a clean manner. USB transfers are
 155  * stopped.
 156  *
 157  * @param hcd The HCD
 158  */
 159 extern void dwc_otg_hcd_stop(dwc_otg_hcd_t * hcd);
 160
 161 /**
 162  * Handles hub class-specific requests.
 163  *
 164  * @param dwc_otg_hcd The HCD
 165  * @param typeReq Request Type
 166  * @param wValue wValue from control request
 167  * @param wIndex wIndex from control request
 168  * @param buf data buffer
 169  * @param wLength data buffer length
 170  *
 171  * Returns -DWC_E_INVALID if invalid argument is passed
 172  * Returns 0 on success
 173  */
 174 extern int dwc_otg_hcd_hub_control(dwc_otg_hcd_t * dwc_otg_hcd,
 175                                    uint16_t typeReq, uint16_t wValue,
 176                                    uint16_t wIndex, uint8_t * buf,
 177                                    uint16_t wLength);
 178
 179 /**
 180  * Returns otg port number.
 181  *
 182  * @param hcd The HCD
 183  */
 184 extern uint32_t dwc_otg_hcd_otg_port(dwc_otg_hcd_t * hcd);
 185
 186 /**
 187  * Returns OTG version - either 1.3 or 2.0.
 188  *
 189  * @param core_if The core_if structure pointer
 190  */
 191 extern uint16_t dwc_otg_get_otg_version(dwc_otg_core_if_t * core_if);
 192
 193 /**
 194  * Returns 1 if currently core is acting as B host, and 0 otherwise.
 195  *
 196  * @param hcd The HCD
 197  */
 198 extern uint32_t dwc_otg_hcd_is_b_host(dwc_otg_hcd_t * hcd);
 199
 200 /**
 201  * Returns current frame number.
 202  *
 203  * @param hcd The HCD
 204  */
 205 extern int dwc_otg_hcd_get_frame_number(dwc_otg_hcd_t * hcd);
 206
 207 /**
 208  * Dumps hcd state.
 209  *
 210  * @param hcd The HCD
 211  */
 212 extern void dwc_otg_hcd_dump_state(dwc_otg_hcd_t * hcd);
 213
 214 /**
 215  * Dump the average frame remaining at SOF. This can be used to
 216  * determine average interrupt latency. Frame remaining is also shown for
 217  * start transfer and two additional sample points.
 218  * Currently this function is not implemented.
 219  *
 220  * @param hcd The HCD
 221  */
 222 extern void dwc_otg_hcd_dump_frrem(dwc_otg_hcd_t * hcd);
 223
 224 /**
 225  * Sends LPM transaction to the local device.
 226  *
 227  * @param hcd The HCD
 228  * @param devaddr Device Address
 229  * @param hird Host initiated resume duration
 230  * @param bRemoteWake Value of bRemoteWake field in LPM transaction
 231  *
 232  * Returns negative value if sending LPM transaction was not succeeded.
 233  * Returns 0 on success.
 234  */
 235 extern int dwc_otg_hcd_send_lpm(dwc_otg_hcd_t * hcd, uint8_t devaddr,
 236                                 uint8_t hird, uint8_t bRemoteWake);
 237
 238 /* URB interface */
 239
 240 /**
 241  * Allocates memory for dwc_otg_hcd_urb structure.
 242  * Allocated memory should be freed by call of DWC_FREE.
 243  *
 244  * @param hcd The HCD
 245  * @param iso_desc_count Count of ISOC descriptors
 246  * @param atomic_alloc Specefies whether to perform atomic allocation.
 247  */
 248 extern dwc_otg_hcd_urb_t *dwc_otg_hcd_urb_alloc(dwc_otg_hcd_t * hcd,
 249                                                 int iso_desc_count,
 250                                                 int atomic_alloc);
 251
 252 /**
 253  * Set pipe information in URB.
 254  *
 255  * @param hcd_urb DWC_OTG URB
 256  * @param devaddr Device Address
 257  * @param ep_num Endpoint Number
 258  * @param ep_type Endpoint Type
 259  * @param ep_dir Endpoint Direction
 260  * @param mps Max Packet Size
 261  */
 262 extern void dwc_otg_hcd_urb_set_pipeinfo(dwc_otg_hcd_urb_t * hcd_urb,
 263                                          uint8_t devaddr, uint8_t ep_num,
 264                                          uint8_t ep_type, uint8_t ep_dir,
 265                                          uint16_t mps);
 266
 267 /* Transfer flags */
 268 #define URB_GIVEBACK_ASAP 0x1
 269 #define URB_SEND_ZERO_PACKET 0x2
 270
 271 /**
 272  * Sets dwc_otg_hcd_urb parameters.
 273  *
 274  * @param urb DWC_OTG URB allocated by dwc_otg_hcd_urb_alloc function.
 275  * @param urb_handle Unique handle for request, this will be passed back
 276  * to function driver in completion callback.
 277  * @param buf The buffer for the data
 278  * @param dma The DMA buffer for the data
 279  * @param buflen Transfer length
 280  * @param sp Buffer for setup data
 281  * @param sp_dma DMA address of setup data buffer
 282  * @param flags Transfer flags
 283  * @param interval Polling interval for interrupt or isochronous transfers.
 284  */
 285 extern void dwc_otg_hcd_urb_set_params(dwc_otg_hcd_urb_t * urb,
 286                                        void *urb_handle, void *buf,
 287                                        dwc_dma_t dma, uint32_t buflen, void *sp,
 288                                        dwc_dma_t sp_dma, uint32_t flags,
 289                                        uint16_t interval);
 290
 291 /** Gets status from dwc_otg_hcd_urb
 292  *
 293  * @param dwc_otg_urb DWC_OTG URB
 294  */
 295 extern uint32_t dwc_otg_hcd_urb_get_status(dwc_otg_hcd_urb_t * dwc_otg_urb);
 296
 297 /** Gets actual length from dwc_otg_hcd_urb
 298  *
 299  * @param dwc_otg_urb DWC_OTG URB
 300  */
 301 extern uint32_t dwc_otg_hcd_urb_get_actual_length(dwc_otg_hcd_urb_t *
 302                                                   dwc_otg_urb);
 303
 304 /** Gets error count from dwc_otg_hcd_urb. Only for ISOC URBs
 305  *
 306  * @param dwc_otg_urb DWC_OTG URB
 307  */
 308 extern uint32_t dwc_otg_hcd_urb_get_error_count(dwc_otg_hcd_urb_t *
 309                                                 dwc_otg_urb);
 310
 311 /** Set ISOC descriptor offset and length
 312  *
 313  * @param dwc_otg_urb DWC_OTG URB
 314  * @param desc_num ISOC descriptor number
 315  * @param offset Offset from beginig of buffer.
 316  * @param length Transaction length
 317  */
 318 extern void dwc_otg_hcd_urb_set_iso_desc_params(dwc_otg_hcd_urb_t * dwc_otg_urb,
 319                                                 int desc_num, uint32_t offset,
 320                                                 uint32_t length);
 321
 322 /** Get status of ISOC descriptor, specified by desc_num
 323  *
 324  * @param dwc_otg_urb DWC_OTG URB
 325  * @param desc_num ISOC descriptor number
 326  */
 327 extern uint32_t dwc_otg_hcd_urb_get_iso_desc_status(dwc_otg_hcd_urb_t *
 328                                                     dwc_otg_urb, int desc_num);
 329
 330 /** Get actual length of ISOC descriptor, specified by desc_num
 331  *
 332  * @param dwc_otg_urb DWC_OTG URB
 333  * @param desc_num ISOC descriptor number
 334  */
 335 extern uint32_t dwc_otg_hcd_urb_get_iso_desc_actual_length(dwc_otg_hcd_urb_t *
 336                                                            dwc_otg_urb,
 337                                                            int desc_num);
 338
 339 /** Queue URB. After transfer is completes, the complete callback will be called with the URB status
 340  *
 341  * @param dwc_otg_hcd The HCD
 342  * @param dwc_otg_urb DWC_OTG URB
 343  * @param ep_handle Out parameter for returning endpoint handle
 344  * @param atomic_alloc Flag to do atomic allocation if needed
 345  *
 346  * Returns -DWC_E_NO_DEVICE if no device is connected.
 347  * Returns -DWC_E_NO_MEMORY if there is no enough memory.
 348  * Returns 0 on success.
 349  */
 350 extern int dwc_otg_hcd_urb_enqueue(dwc_otg_hcd_t * dwc_otg_hcd,
 351                                    dwc_otg_hcd_urb_t * dwc_otg_urb,
 352                                    void **ep_handle, int atomic_alloc);
 353
 354 /** De-queue the specified URB
 355  *
 356  * @param dwc_otg_hcd The HCD
 357  * @param dwc_otg_urb DWC_OTG URB
 358  */
 359 extern int dwc_otg_hcd_urb_dequeue(dwc_otg_hcd_t * dwc_otg_hcd,
 360                                    dwc_otg_hcd_urb_t * dwc_otg_urb);
 361
 362 /** Frees resources in the DWC_otg controller related to a given endpoint.
 363  * Any URBs for the endpoint must already be dequeued.
 364  *
 365  * @param hcd The HCD
 366  * @param ep_handle Endpoint handle, returned by dwc_otg_hcd_urb_enqueue function
 367  * @param retry Number of retries if there are queued transfers.
 368  *
 369  * Returns -DWC_E_INVALID if invalid arguments are passed.
 370  * Returns 0 on success
 371  */
 372 extern int dwc_otg_hcd_endpoint_disable(dwc_otg_hcd_t * hcd, void *ep_handle,
 373                                         int retry);
 374
 375 /* Resets the data toggle in qh structure. This function can be called from
 376  * usb_clear_halt routine.
 377  *
 378  * @param hcd The HCD
 379  * @param ep_handle Endpoint handle, returned by dwc_otg_hcd_urb_enqueue function
 380  *
 381  * Returns -DWC_E_INVALID if invalid arguments are passed.
 382  * Returns 0 on success
 383  */
 384 extern int dwc_otg_hcd_endpoint_reset(dwc_otg_hcd_t * hcd, void *ep_handle);
 385
 386 /** Returns 1 if status of specified port is changed and 0 otherwise.
 387  *
 388  * @param hcd The HCD
 389  * @param port Port number
 390  */
 391 extern int dwc_otg_hcd_is_status_changed(dwc_otg_hcd_t * hcd, int port);
 392
 393 /** Call this function to check if bandwidth was allocated for specified endpoint.
 394  * Only for ISOC and INTERRUPT endpoints.
 395  *
 396  * @param hcd The HCD
 397  * @param ep_handle Endpoint handle
 398  */
 399 extern int dwc_otg_hcd_is_bandwidth_allocated(dwc_otg_hcd_t * hcd,
 400                                               void *ep_handle);
 401
 402 /** Call this function to check if bandwidth was freed for specified endpoint.
 403  *
 404  * @param hcd The HCD
 405  * @param ep_handle Endpoint handle
 406  */
 407 extern int dwc_otg_hcd_is_bandwidth_freed(dwc_otg_hcd_t * hcd, void *ep_handle);
 408
 409 /** Returns bandwidth allocated for specified endpoint in microseconds.
 410  * Only for ISOC and INTERRUPT endpoints.
 411  *
 412  * @param hcd The HCD
 413  * @param ep_handle Endpoint handle
 414  */
 415 extern uint8_t dwc_otg_hcd_get_ep_bandwidth(dwc_otg_hcd_t * hcd,
 416                                             void *ep_handle);
 417
 418 /** @} */
 419
 420 #endif /* __DWC_HCD_IF_H__ */
 421 #endif /* DWC_DEVICE_ONLY */