1 /* ==========================================================================
2 * $File: //dwh/usb_iip/dev/software/otg/linux/drivers/dwc_otg_pcd_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 * ========================================================================== */
35 #if !defined(__DWC_PCD_IF_H__)
36 #define __DWC_PCD_IF_H__
39 #include "dwc_otg_core_if.h"
40 #include "dwc_otg_driver.h"
43 * This file defines DWC_OTG PCD Core API.
47 typedef struct dwc_otg_pcd dwc_otg_pcd_t;
49 /** Maxpacket size for EP0 */
50 #define MAX_EP0_SIZE 64
51 /** Maxpacket size for any EP */
52 #define MAX_PACKET_SIZE 1024
54 /** @name Function Driver Callbacks */
57 /** This function will be called whenever a previously queued request has
58 * completed. The status value will be set to -DWC_E_SHUTDOWN to indicated a
59 * failed or aborted transfer, or -DWC_E_RESTART to indicate the device was reset,
60 * or -DWC_E_TIMEOUT to indicate it timed out, or -DWC_E_INVALID to indicate invalid
62 typedef int (*dwc_completion_cb_t) (dwc_otg_pcd_t * pcd, void *ep_handle,
63 void *req_handle, int32_t status,
66 * This function will be called whenever a previousle queued ISOC request has
67 * completed. Count of ISOC packets could be read using dwc_otg_pcd_get_iso_packet_count
69 * The status of each ISOC packet could be read using dwc_otg_pcd_get_iso_packet_*
72 typedef int (*dwc_isoc_completion_cb_t) (dwc_otg_pcd_t * pcd, void *ep_handle,
73 void *req_handle, int proc_buf_num);
74 /** This function should handle any SETUP request that cannot be handled by the
75 * PCD Core. This includes most GET_DESCRIPTORs, SET_CONFIGS, Any
76 * class-specific requests, etc. The function must non-blocking.
78 * Returns 0 on success.
79 * Returns -DWC_E_NOT_SUPPORTED if the request is not supported.
80 * Returns -DWC_E_INVALID if the setup request had invalid parameters or bytes.
81 * Returns -DWC_E_SHUTDOWN on any other error. */
82 typedef int (*dwc_setup_cb_t) (dwc_otg_pcd_t * pcd, uint8_t * bytes);
83 /** This is called whenever the device has been disconnected. The function
84 * driver should take appropriate action to clean up all pending requests in the
85 * PCD Core, remove all endpoints (except ep0), and initialize back to reset
87 typedef int (*dwc_disconnect_cb_t) (dwc_otg_pcd_t * pcd);
88 /** This function is called when device has been connected. */
89 typedef int (*dwc_connect_cb_t) (dwc_otg_pcd_t * pcd, int speed);
90 /** This function is called when device has been suspended */
91 typedef int (*dwc_suspend_cb_t) (dwc_otg_pcd_t * pcd);
92 /** This function is called when device has received LPM tokens, i.e.
93 * device has been sent to sleep state. */
94 typedef int (*dwc_sleep_cb_t) (dwc_otg_pcd_t * pcd);
95 /** This function is called when device has been resumed
96 * from suspend(L2) or L1 sleep state. */
97 typedef int (*dwc_resume_cb_t) (dwc_otg_pcd_t * pcd);
98 /** This function is called whenever hnp params has been changed.
99 * User can call get_b_hnp_enable, get_a_hnp_support, get_a_alt_hnp_support functions
100 * to get hnp parameters. */
101 typedef int (*dwc_hnp_params_changed_cb_t) (dwc_otg_pcd_t * pcd);
102 /** This function is called whenever USB RESET is detected. */
103 typedef int (*dwc_reset_cb_t) (dwc_otg_pcd_t * pcd);
105 typedef int (*cfi_setup_cb_t) (dwc_otg_pcd_t * pcd, void *ctrl_req_bytes);
109 * @param ep_handle Void pointer to the usb_ep structure
110 * @param ereq_port Pointer to the extended request structure created in the
113 typedef int (*xiso_completion_cb_t) (dwc_otg_pcd_t * pcd, void *ep_handle,
114 void *req_handle, int32_t status,
116 /** Function Driver Ops Data Structure */
117 struct dwc_otg_pcd_function_ops {
118 dwc_connect_cb_t connect;
119 dwc_disconnect_cb_t disconnect;
120 dwc_setup_cb_t setup;
121 dwc_completion_cb_t complete;
122 dwc_isoc_completion_cb_t isoc_complete;
123 dwc_suspend_cb_t suspend;
124 dwc_sleep_cb_t sleep;
125 dwc_resume_cb_t resume;
126 dwc_reset_cb_t reset;
127 dwc_hnp_params_changed_cb_t hnp_changed;
128 cfi_setup_cb_t cfi_setup;
129 #ifdef DWC_UTE_PER_IO
130 xiso_completion_cb_t xisoc_complete;
135 /** @name Function Driver Functions */
138 /** Call this function to get pointer on dwc_otg_pcd_t,
139 * this pointer will be used for all PCD API functions.
141 * @param core_if The DWC_OTG Core
143 extern dwc_otg_pcd_t *dwc_otg_pcd_init(dwc_otg_device_t *otg_dev);
145 /** Frees PCD allocated by dwc_otg_pcd_init
149 extern void dwc_otg_pcd_remove(dwc_otg_pcd_t * pcd);
151 /** Call this to bind the function driver to the PCD Core.
153 * @param pcd Pointer on dwc_otg_pcd_t returned by dwc_otg_pcd_init function.
154 * @param fops The Function Driver Ops data structure containing pointers to all callbacks.
156 extern void dwc_otg_pcd_start(dwc_otg_pcd_t * pcd,
157 const struct dwc_otg_pcd_function_ops *fops);
159 /** Enables an endpoint for use. This function enables an endpoint in
160 * the PCD. The endpoint is described by the ep_desc which has the
161 * same format as a USB ep descriptor. The ep_handle parameter is used to refer
162 * to the endpoint from other API functions and in callbacks. Normally this
163 * should be called after a SET_CONFIGURATION/SET_INTERFACE to configure the
164 * core for that interface.
166 * Returns -DWC_E_INVALID if invalid parameters were passed.
167 * Returns -DWC_E_SHUTDOWN if any other error ocurred.
168 * Returns 0 on success.
171 * @param ep_desc Endpoint descriptor
172 * @param usb_ep Handle on endpoint, that will be used to identify endpoint.
174 extern int dwc_otg_pcd_ep_enable(dwc_otg_pcd_t * pcd,
175 const uint8_t * ep_desc, void *usb_ep);
177 /** Disable the endpoint referenced by ep_handle.
179 * Returns -DWC_E_INVALID if invalid parameters were passed.
180 * Returns -DWC_E_SHUTDOWN if any other error occurred.
181 * Returns 0 on success. */
182 extern int dwc_otg_pcd_ep_disable(dwc_otg_pcd_t * pcd, void *ep_handle);
184 /** Queue a data transfer request on the endpoint referenced by ep_handle.
185 * After the transfer is completes, the complete callback will be called with
186 * the request status.
189 * @param ep_handle The handle of the endpoint
190 * @param buf The buffer for the data
191 * @param dma_buf The DMA buffer for the data
192 * @param buflen The length of the data transfer
193 * @param zero Specifies whether to send zero length last packet.
194 * @param req_handle Set this handle to any value to use to reference this
195 * request in the ep_dequeue function or from the complete callback
196 * @param atomic_alloc If driver need to perform atomic allocations
197 * for internal data structures.
199 * Returns -DWC_E_INVALID if invalid parameters were passed.
200 * Returns -DWC_E_SHUTDOWN if any other error ocurred.
201 * Returns 0 on success. */
202 extern int dwc_otg_pcd_ep_queue(dwc_otg_pcd_t * pcd, void *ep_handle,
203 uint8_t * buf, dwc_dma_t dma_buf,
204 uint32_t buflen, int zero, void *req_handle,
206 #ifdef DWC_UTE_PER_IO
209 * @param ereq_nonport Pointer to the extended request part of the
210 * usb_request structure defined in usb_gadget.h file.
212 extern int dwc_otg_pcd_xiso_ep_queue(dwc_otg_pcd_t * pcd, void *ep_handle,
213 uint8_t * buf, dwc_dma_t dma_buf,
214 uint32_t buflen, int zero,
215 void *req_handle, int atomic_alloc,
220 /** De-queue the specified data transfer that has not yet completed.
222 * Returns -DWC_E_INVALID if invalid parameters were passed.
223 * Returns -DWC_E_SHUTDOWN if any other error ocurred.
224 * Returns 0 on success. */
225 extern int dwc_otg_pcd_ep_dequeue(dwc_otg_pcd_t * pcd, void *ep_handle,
228 /** Halt (STALL) an endpoint or clear it.
230 * Returns -DWC_E_INVALID if invalid parameters were passed.
231 * Returns -DWC_E_SHUTDOWN if any other error ocurred.
232 * Returns -DWC_E_AGAIN if the STALL cannot be sent and must be tried again later
233 * Returns 0 on success. */
234 extern int dwc_otg_pcd_ep_halt(dwc_otg_pcd_t * pcd, void *ep_handle, int value);
237 extern int dwc_otg_pcd_ep_wedge(dwc_otg_pcd_t * pcd, void *ep_handle);
239 /** This function should be called on every hardware interrupt */
240 extern int32_t dwc_otg_pcd_handle_intr(dwc_otg_pcd_t * pcd);
242 /** This function returns current frame number */
243 extern int dwc_otg_pcd_get_frame_number(dwc_otg_pcd_t * pcd);
246 * Start isochronous transfers on the endpoint referenced by ep_handle.
247 * For isochronous transfers duble buffering is used.
248 * After processing each of buffers comlete callback will be called with
249 * status for each transaction.
252 * @param ep_handle The handle of the endpoint
253 * @param buf0 The virtual address of first data buffer
254 * @param buf1 The virtual address of second data buffer
255 * @param dma0 The DMA address of first data buffer
256 * @param dma1 The DMA address of second data buffer
257 * @param sync_frame Data pattern frame number
258 * @param dp_frame Data size for pattern frame
259 * @param data_per_frame Data size for regular frame
260 * @param start_frame Frame number to start transfers, if -1 then start transfers ASAP.
261 * @param buf_proc_intrvl Interval of ISOC Buffer processing
262 * @param req_handle Handle of ISOC request
263 * @param atomic_alloc Specefies whether to perform atomic allocation for
264 * internal data structures.
266 * Returns -DWC_E_NO_MEMORY if there is no enough memory.
267 * Returns -DWC_E_INVALID if incorrect arguments are passed to the function.
268 * Returns -DW_E_SHUTDOWN for any other error.
269 * Returns 0 on success
271 extern int dwc_otg_pcd_iso_ep_start(dwc_otg_pcd_t * pcd, void *ep_handle,
272 uint8_t * buf0, uint8_t * buf1,
273 dwc_dma_t dma0, dwc_dma_t dma1,
274 int sync_frame, int dp_frame,
275 int data_per_frame, int start_frame,
276 int buf_proc_intrvl, void *req_handle,
279 /** Stop ISOC transfers on endpoint referenced by ep_handle.
282 * @param ep_handle The handle of the endpoint
283 * @param req_handle Handle of ISOC request
285 * Returns -DWC_E_INVALID if incorrect arguments are passed to the function
286 * Returns 0 on success
288 int dwc_otg_pcd_iso_ep_stop(dwc_otg_pcd_t * pcd, void *ep_handle,
291 /** Get ISOC packet status.
294 * @param ep_handle The handle of the endpoint
295 * @param iso_req_handle Isochronoush request handle
296 * @param packet Number of packet
297 * @param status Out parameter for returning status
298 * @param actual Out parameter for returning actual length
299 * @param offset Out parameter for returning offset
302 extern void dwc_otg_pcd_get_iso_packet_params(dwc_otg_pcd_t * pcd,
304 void *iso_req_handle, int packet,
305 int *status, int *actual,
308 /** Get ISOC packet count.
311 * @param ep_handle The handle of the endpoint
312 * @param iso_req_handle
314 extern int dwc_otg_pcd_get_iso_packet_count(dwc_otg_pcd_t * pcd,
316 void *iso_req_handle);
318 /** This function starts the SRP Protocol if no session is in progress. If
319 * a session is already in progress, but the device is suspended,
320 * remote wakeup signaling is started.
322 extern int dwc_otg_pcd_wakeup(dwc_otg_pcd_t * pcd);
324 /** This function returns 1 if LPM support is enabled, and 0 otherwise. */
325 extern int dwc_otg_pcd_is_lpm_enabled(dwc_otg_pcd_t * pcd);
327 /** This function returns 1 if remote wakeup is allowed and 0, otherwise. */
328 extern int dwc_otg_pcd_get_rmwkup_enable(dwc_otg_pcd_t * pcd);
331 extern void dwc_otg_pcd_initiate_srp(dwc_otg_pcd_t * pcd);
333 /** Starts remote wakeup signaling. */
334 extern void dwc_otg_pcd_remote_wakeup(dwc_otg_pcd_t * pcd, int set);
336 /** Starts micorsecond soft disconnect. */
337 extern void dwc_otg_pcd_disconnect_us(dwc_otg_pcd_t * pcd, int no_of_usecs);
338 /** This function returns whether device is dualspeed.*/
339 extern uint32_t dwc_otg_pcd_is_dualspeed(dwc_otg_pcd_t * pcd);
341 /** This function returns whether device is otg. */
342 extern uint32_t dwc_otg_pcd_is_otg(dwc_otg_pcd_t * pcd);
344 /** These functions allow to get hnp parameters */
345 extern uint32_t get_b_hnp_enable(dwc_otg_pcd_t * pcd);
346 extern uint32_t get_a_hnp_support(dwc_otg_pcd_t * pcd);
347 extern uint32_t get_a_alt_hnp_support(dwc_otg_pcd_t * pcd);
349 /** CFI specific Interface functions */
350 /** Allocate a cfi buffer */
351 extern uint8_t *cfiw_ep_alloc_buffer(dwc_otg_pcd_t * pcd, void *pep,
352 dwc_dma_t * addr, size_t buflen,
355 /******************************************************************************/
359 #endif /* __DWC_PCD_IF_H__ */
361 #endif /* DWC_HOST_ONLY */