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 #if 1//ndef 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 _LONG_CALL_ 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 */ 413