1 /* ==========================================================================
2 * $File: //dwh/usb_iip/dev/software/otg/linux/drivers/dwc_otg_hcd_if.h $
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.
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.
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
32 * ========================================================================== */
33 #ifndef DWC_DEVICE_ONLY
34 #ifndef __DWC_HCD_IF_H__
35 #define __DWC_HCD_IF_H__
37 #include "dwc_otg_core_if.h"
40 * This file defines DWC_OTG HCD Core API.
44 typedef struct dwc_otg_hcd dwc_otg_hcd_t;
46 struct dwc_otg_hcd_urb;
47 typedef struct dwc_otg_hcd_urb dwc_otg_hcd_urb_t;
49 /** @name HCD Function Driver Callbacks */
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);
55 /** This function is called when device has been disconnected */
56 typedef int (*dwc_otg_hcd_disconnect_cb_t) (dwc_otg_hcd_t * hcd);
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,
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,
67 /** This function is called when urb is completed */
68 typedef int (*dwc_otg_hcd_complete_urb_cb_t) (dwc_otg_hcd_t * hcd,
70 dwc_otg_hcd_urb_t * dwc_otg_urb,
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);
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;
86 /** @name HCD Core API */
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);
91 /** This function should be called to initiate HCD Core.
94 * @param core_if The DWC_OTG Core
96 * Returns -DWC_E_NO_MEMORY if no enough memory.
97 * Returns 0 on success
99 extern int dwc_otg_hcd_init(dwc_otg_hcd_t * hcd, dwc_otg_core_if_t * core_if);
105 extern void dwc_otg_hcd_remove(dwc_otg_hcd_t * hcd);
107 /** This function should be called on every hardware interrupt.
109 * @param dwc_otg_hcd The HCD
111 * Returns non zero if interrupt is handled
112 * Return 0 if interrupt is not handled
114 extern int32_t dwc_otg_hcd_handle_intr(dwc_otg_hcd_t * dwc_otg_hcd);
117 * Returns private data set by
118 * dwc_otg_hcd_set_priv_data function.
122 extern void *dwc_otg_hcd_get_priv_data(dwc_otg_hcd_t * hcd);
128 * @param priv_data pointer to be stored in private data
130 extern void dwc_otg_hcd_set_priv_data(dwc_otg_hcd_t * hcd, void *priv_data);
133 * This function initializes the HCD Core.
136 * @param fops The Function Driver Operations data structure containing pointers to all callbacks.
138 * Returns -DWC_E_NO_DEVICE if Core is currently is in device mode.
139 * Returns 0 on success
141 extern int dwc_otg_hcd_start(dwc_otg_hcd_t * hcd,
142 struct dwc_otg_hcd_function_ops *fops);
145 * Halts the DWC_otg host mode operations in a clean manner. USB transfers are
150 extern void dwc_otg_hcd_stop(dwc_otg_hcd_t * hcd);
153 * Handles hub class-specific requests.
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
162 * Returns -DWC_E_INVALID if invalid argument is passed
163 * Returns 0 on success
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,
171 * Returns otg port number.
175 extern uint32_t dwc_otg_hcd_otg_port(dwc_otg_hcd_t * hcd);
178 * Returns OTG version - either 1.3 or 2.0.
180 * @param core_if The core_if structure pointer
182 extern uint16_t dwc_otg_get_otg_version(dwc_otg_core_if_t * core_if);
185 * Returns 1 if currently core is acting as B host, and 0 otherwise.
189 extern uint32_t dwc_otg_hcd_is_b_host(dwc_otg_hcd_t * hcd);
192 * Returns current frame number.
196 extern int dwc_otg_hcd_get_frame_number(dwc_otg_hcd_t * hcd);
203 extern void dwc_otg_hcd_dump_state(dwc_otg_hcd_t * hcd);
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.
213 extern void dwc_otg_hcd_dump_frrem(dwc_otg_hcd_t * hcd);
216 * Sends LPM transaction to the local device.
219 * @param devaddr Device Address
220 * @param hird Host initiated resume duration
221 * @param bRemoteWake Value of bRemoteWake field in LPM transaction
223 * Returns negative value if sending LPM transaction was not succeeded.
224 * Returns 0 on success.
226 extern int dwc_otg_hcd_send_lpm(dwc_otg_hcd_t * hcd, uint8_t devaddr,
227 uint8_t hird, uint8_t bRemoteWake);
232 * Allocates memory for dwc_otg_hcd_urb structure.
233 * Allocated memory should be freed by call of DWC_FREE.
236 * @param iso_desc_count Count of ISOC descriptors
237 * @param atomic_alloc Specefies whether to perform atomic allocation.
239 extern dwc_otg_hcd_urb_t *dwc_otg_hcd_urb_alloc(dwc_otg_hcd_t * hcd,
244 * Set pipe information in URB.
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
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,
259 #define URB_GIVEBACK_ASAP 0x1
260 #define URB_SEND_ZERO_PACKET 0x2
263 * Sets dwc_otg_hcd_urb parameters.
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.
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,
282 /** Gets status from dwc_otg_hcd_urb
284 * @param dwc_otg_urb DWC_OTG URB
286 extern uint32_t dwc_otg_hcd_urb_get_status(dwc_otg_hcd_urb_t * dwc_otg_urb);
288 /** Gets actual length from dwc_otg_hcd_urb
290 * @param dwc_otg_urb DWC_OTG URB
292 extern uint32_t dwc_otg_hcd_urb_get_actual_length(dwc_otg_hcd_urb_t *
295 /** Gets error count from dwc_otg_hcd_urb. Only for ISOC URBs
297 * @param dwc_otg_urb DWC_OTG URB
299 extern uint32_t dwc_otg_hcd_urb_get_error_count(dwc_otg_hcd_urb_t *
302 /** Set ISOC descriptor offset and length
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
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,
313 /** Get status of ISOC descriptor, specified by desc_num
315 * @param dwc_otg_urb DWC_OTG URB
316 * @param desc_num ISOC descriptor number
318 extern uint32_t dwc_otg_hcd_urb_get_iso_desc_status(dwc_otg_hcd_urb_t *
319 dwc_otg_urb, int desc_num);
321 /** Get actual length of ISOC descriptor, specified by desc_num
323 * @param dwc_otg_urb DWC_OTG URB
324 * @param desc_num ISOC descriptor number
326 extern uint32_t dwc_otg_hcd_urb_get_iso_desc_actual_length(dwc_otg_hcd_urb_t *
330 /** Queue URB. After transfer is completes, the complete callback will be called with the URB status
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
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.
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);
345 /** De-queue the specified URB
347 * @param dwc_otg_hcd The HCD
348 * @param dwc_otg_urb DWC_OTG URB
350 extern int dwc_otg_hcd_urb_dequeue(dwc_otg_hcd_t * dwc_otg_hcd,
351 dwc_otg_hcd_urb_t * dwc_otg_urb);
353 /** Frees resources in the DWC_otg controller related to a given endpoint.
354 * Any URBs for the endpoint must already be dequeued.
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.
360 * Returns -DWC_E_INVALID if invalid arguments are passed.
361 * Returns 0 on success
363 extern int dwc_otg_hcd_endpoint_disable(dwc_otg_hcd_t * hcd, void *ep_handle,
366 /* Resets the data toggle in qh structure. This function can be called from
367 * usb_clear_halt routine.
370 * @param ep_handle Endpoint handle, returned by dwc_otg_hcd_urb_enqueue function
372 * Returns -DWC_E_INVALID if invalid arguments are passed.
373 * Returns 0 on success
375 extern int dwc_otg_hcd_endpoint_reset(dwc_otg_hcd_t * hcd, void *ep_handle);
377 /** Returns 1 if status of specified port is changed and 0 otherwise.
380 * @param port Port number
382 extern int dwc_otg_hcd_is_status_changed(dwc_otg_hcd_t * hcd, int port);
384 /** Call this function to check if bandwidth was allocated for specified endpoint.
385 * Only for ISOC and INTERRUPT endpoints.
388 * @param ep_handle Endpoint handle
390 extern int dwc_otg_hcd_is_bandwidth_allocated(dwc_otg_hcd_t * hcd,
393 /** Call this function to check if bandwidth was freed for specified endpoint.
396 * @param ep_handle Endpoint handle
398 extern int dwc_otg_hcd_is_bandwidth_freed(dwc_otg_hcd_t * hcd, void *ep_handle);
400 /** Returns bandwidth allocated for specified endpoint in microseconds.
401 * Only for ISOC and INTERRUPT endpoints.
404 * @param ep_handle Endpoint handle
406 extern uint8_t dwc_otg_hcd_get_ep_bandwidth(dwc_otg_hcd_t * hcd,
411 #endif /* __DWC_HCD_IF_H__ */
412 #endif /* DWC_DEVICE_ONLY */