dwc_otg_pcd_if.h File Reference

This file defines DWC_OTG PCD Core API. More...

#include "dwc_os.h"
#include "dwc_otg_core_if.h"

Go to the source code of this file.

Data Structures

struct dwc_otg_pcd_function_ops

Function Driver Ops Data Structure. More...

Function Driver Callbacks

typedef int(*) dwc_completion_cb_t (dwc_otg_pcd_t *pcd, void *ep_handle, void *req_handle, int32_t status, uint32_t actual)

This function will be called whenever a previously queued request has completed.

typedef int(*) dwc_isoc_completion_cb_t (dwc_otg_pcd_t *pcd, void *ep_handle, void *req_handle, int proc_buf_num)

This function will be called whenever a previousle queued ISOC request has completed.

typedef int(*) dwc_setup_cb_t (dwc_otg_pcd_t *pcd, uint8_t *bytes)

This function should handle any SETUP request that cannot be handled by the PCD Core.

typedef int(*) dwc_disconnect_cb_t (dwc_otg_pcd_t *pcd)

This is called whenever the device has been disconnected.

typedef int(*) dwc_connect_cb_t (dwc_otg_pcd_t *pcd, int speed)

This function is called when device has been connected.

typedef int(*) dwc_suspend_cb_t (dwc_otg_pcd_t *pcd)

This function is called when device has been suspended.

typedef int(*) dwc_sleep_cb_t (dwc_otg_pcd_t *pcd)

This function is called when device has received LPM tokens, i.e.

typedef int(*) dwc_resume_cb_t (dwc_otg_pcd_t *pcd)

This function is called when device has been resumed from suspend(L2) or L1 sleep state.

typedef int(*) dwc_hnp_params_changed_cb_t (dwc_otg_pcd_t *pcd)

This function is called whenever hnp params has been changed.

typedef int(*) dwc_reset_cb_t (dwc_otg_pcd_t *pcd)

This function is called whenever USB RESET is detected.

typedef int(*) cfi_setup_cb_t (dwc_otg_pcd_t *pcd, void *ctrl_req_bytes)

Function Driver Functions

dwc_otg_pcd_t * dwc_otg_pcd_init (dwc_otg_core_if_t *core_if)

Call this function to get pointer on dwc_otg_pcd_t, this pointer will be used for all PCD API functions.

void dwc_otg_pcd_remove (dwc_otg_pcd_t *pcd)

Frees PCD allocated by dwc_otg_pcd_init.

void dwc_otg_pcd_start (dwc_otg_pcd_t *pcd, const struct dwc_otg_pcd_function_ops *fops)

Call this to bind the function driver to the PCD Core.

int dwc_otg_pcd_ep_enable (dwc_otg_pcd_t *pcd, const uint8_t *ep_desc, void *ep_handle)

Enables an endpoint for use.

int dwc_otg_pcd_ep_disable (dwc_otg_pcd_t *pcd, void *ep_handle)

Disable the endpoint referenced by ep_handle.

int dwc_otg_pcd_ep_queue (dwc_otg_pcd_t *pcd, void *ep_handle, uint8_t *buf, dwc_dma_t dma_buf, uint32_t buflen, int zero, void *req_handle, int atomic_alloc)

Queue a data transfer request on the endpoint referenced by ep_handle.

int dwc_otg_pcd_ep_dequeue (dwc_otg_pcd_t *pcd, void *ep_handle, void *req_handle)

De-queue the specified data transfer that has not yet completed.

int dwc_otg_pcd_ep_halt (dwc_otg_pcd_t *pcd, void *ep_handle, int value)

Halt (STALL) an endpoint or clear it.

int32_t dwc_otg_pcd_handle_intr (dwc_otg_pcd_t *pcd)

This function should be called on every hardware interrupt.

int dwc_otg_pcd_get_frame_number (dwc_otg_pcd_t *pcd)

This function returns current frame number.

int dwc_otg_pcd_iso_ep_start (dwc_otg_pcd_t *pcd, void *ep_handle, uint8_t *buf0, uint8_t *buf1, dwc_dma_t dma0, dwc_dma_t dma1, int sync_frame, int dp_frame, int data_per_frame, int start_frame, int buf_proc_intrvl, void *req_handle, int atomic_alloc)

Start isochronous transfers on the endpoint referenced by ep_handle.

int dwc_otg_pcd_iso_ep_stop (dwc_otg_pcd_t *pcd, void *ep_handle, void *req_handle)

Stop ISOC transfers on endpoint referenced by ep_handle.

void dwc_otg_pcd_get_iso_packet_params (dwc_otg_pcd_t *pcd, void *ep_handle, void *iso_req_handle, int packet, int *status, int *actual, int *offset)

Get ISOC packet status.

int dwc_otg_pcd_get_iso_packet_count (dwc_otg_pcd_t *pcd, void *ep_handle, void *iso_req_handle)

Get ISOC packet count.

int dwc_otg_pcd_wakeup (dwc_otg_pcd_t *pcd)

This function starts the SRP Protocol if no session is in progress.

int dwc_otg_pcd_is_lpm_enabled (dwc_otg_pcd_t *pcd)

This function returns 1 if LPM support is enabled, and 0 otherwise.

int dwc_otg_pcd_get_rmwkup_enable (dwc_otg_pcd_t *pcd)

This function returns 1 if remote wakeup is allowed and 0, otherwise.

void dwc_otg_pcd_initiate_srp (dwc_otg_pcd_t *pcd)

Initiate SRP.

void dwc_otg_pcd_remote_wakeup (dwc_otg_pcd_t *pcd, int set)

Starts remote wakeup signaling.

uint32_t dwc_otg_pcd_is_dualspeed (dwc_otg_pcd_t *pcd)

This function returns whether device is dualspeed.

uint32_t dwc_otg_pcd_is_otg (dwc_otg_pcd_t *pcd)

This function returns whether device is otg.

uint32_t get_b_hnp_enable (dwc_otg_pcd_t *pcd)

These functions allow to get hnp parameters.

uint32_t get_a_hnp_support (dwc_otg_pcd_t *pcd)

uint32_t get_a_alt_hnp_support (dwc_otg_pcd_t *pcd)

uint8_t * cfiw_ep_alloc_buffer (dwc_otg_pcd_t *pcd, void *pep, dwc_dma_t *addr, size_t buflen, int flags)

Allocate a cfi buffer.

Defines

#define __DWC_PCD_IF_H__

#define MAX_EP0_SIZE 64

Maxpacket size for EP0.

#define MAX_PACKET_SIZE 1024

Maxpacket size for any EP.

Typedefs

typedef dwc_otg_pcd dwc_otg_pcd_t

Detailed Description

This file defines DWC_OTG PCD Core API.

Definition in file dwc_otg_pcd_if.h.

Typedef Documentation

typedef int(*) dwc_completion_cb_t(dwc_otg_pcd_t *pcd, void *ep_handle, void *req_handle, int32_t status, uint32_t actual)

This function will be called whenever a previously queued request has completed.

The status value will be set to -DWC_E_SHUTDOWN to indicated a failed or aborted transfer, or -DWC_E_RESTART to indicate the device was reset, or -DWC_E_TIMEOUT to indicate it timed out, or -DWC_E_INVALID to indicate invalid parameters.

Definition at line 61 of file dwc_otg_pcd_if.h.

typedef int(*) dwc_isoc_completion_cb_t(dwc_otg_pcd_t *pcd, void *ep_handle, void *req_handle, int proc_buf_num)

This function will be called whenever a previousle queued ISOC request has completed.

Count of ISOC packets could be read using dwc_otg_pcd_get_iso_packet_count function. The status of each ISOC packet could be read using dwc_otg_pcd_get_iso_packet_* functions.

Definition at line 71 of file dwc_otg_pcd_if.h.

typedef int(*) dwc_setup_cb_t(dwc_otg_pcd_t *pcd, uint8_t *bytes)

This function should handle any SETUP request that cannot be handled by the PCD Core.

This includes most GET_DESCRIPTORs, SET_CONFIGS, Any class-specific requests, etc. The function must non-blocking.

Returns 0 on success. Returns -DWC_E_NOT_SUPPORTED if the request is not supported. Returns -DWC_E_INVALID if the setup request had invalid parameters or bytes. Returns -DWC_E_SHUTDOWN on any other error.

Definition at line 81 of file dwc_otg_pcd_if.h.

typedef int(*) dwc_disconnect_cb_t(dwc_otg_pcd_t *pcd)

This is called whenever the device has been disconnected.

The function driver should take appropriate action to clean up all pending requests in the PCD Core, remove all endpoints (except ep0), and initialize back to reset state.

Definition at line 86 of file dwc_otg_pcd_if.h.

typedef int(*) dwc_sleep_cb_t(dwc_otg_pcd_t *pcd)

This function is called when device has received LPM tokens, i.e.

device has been sent to sleep state.

Definition at line 93 of file dwc_otg_pcd_if.h.

typedef int(*) dwc_hnp_params_changed_cb_t(dwc_otg_pcd_t *pcd)

This function is called whenever hnp params has been changed.

User can call get_b_hnp_enable, get_a_hnp_support, get_a_alt_hnp_support functions to get hnp parameters.

Definition at line 100 of file dwc_otg_pcd_if.h.

Function Documentation

dwc_otg_pcd_t* dwc_otg_pcd_init ( dwc_otg_core_if_t * core_if )

Call this function to get pointer on dwc_otg_pcd_t, this pointer will be used for all PCD API functions.

Parameters:

core_if

The DWC_OTG Core

Definition at line 1056 of file dwc_otg_pcd.c.

void dwc_otg_pcd_remove ( dwc_otg_pcd_t * pcd )

Frees PCD allocated by dwc_otg_pcd_init.

Parameters:

pcd

The PCD

Definition at line 1215 of file dwc_otg_pcd.c.

void dwc_otg_pcd_start	(	dwc_otg_pcd_t *	pcd,
		const struct dwc_otg_pcd_function_ops *	fops
	)

Call this to bind the function driver to the PCD Core.

Parameters:

	pcd	Pointer on dwc_otg_pcd_t returned by dwc_otg_pcd_init function.
	fops	The Function Driver Ops data structure containing pointers to all callbacks.

Definition at line 117 of file dwc_otg_pcd.c.

int dwc_otg_pcd_ep_enable	(	dwc_otg_pcd_t *	pcd,
		const uint8_t *	ep_desc,
		void *	ep_handle
	)

Enables an endpoint for use.

This function enables an endpoint in the PCD. The endpoint is described by the ep_desc which has the same format as a USB ep descriptor. The ep_handle parameter is used to refer to the endpoint from other API functions and in callbacks. Normally this should be called after a SET_CONFIGURATION/SET_INTERFACE to configure the core for that interface.

Returns -DWC_E_INVALID if invalid parameters were passed. Returns -DWC_E_SHUTDOWN if any other error ocurred. Returns 0 on success.

Parameters:

	pcd	The PCD
	ep_desc	Endpoint descriptor
	ep_handle	Handle on endpoint, that will be used to identify endpoint.

Definition at line 1341 of file dwc_otg_pcd.c.

int dwc_otg_pcd_ep_disable	(	dwc_otg_pcd_t *	pcd,
		void *	ep_handle
	)

Disable the endpoint referenced by ep_handle.

Returns -DWC_E_INVALID if invalid parameters were passed. Returns -DWC_E_SHUTDOWN if any other error ocurred. Returns 0 on success.

Definition at line 1449 of file dwc_otg_pcd.c.

int dwc_otg_pcd_ep_queue	(	dwc_otg_pcd_t *	pcd,
		void *	ep_handle,
		uint8_t *	buf,
		dwc_dma_t	dma_buf,
		uint32_t	buflen,
		int	zero,
		void *	req_handle,
		int	atomic_alloc
	)

Queue a data transfer request on the endpoint referenced by ep_handle.

After the transfer is completes, the complete callback will be called with the request status.

Parameters:

	pcd	The PCD
	ep_handle	The handle of the endpoint
	buf	The buffer for the data
	dma_buf	The DMA buffer for the data
	buflen	The length of the data transfer
	zero	Specifies whether to send zero length last packet.
	req_handle	Set this handle to any value to use to reference this request in the ep_dequeue function or from the complete callback
	atomic_alloc	If driver need to perform atomic allocations for internal data structures.

Returns -DWC_E_INVALID if invalid parameters were passed. Returns -DWC_E_SHUTDOWN if any other error ocurred. Returns 0 on success.

Todo:: NGS Create a function for this.

Definition at line 1502 of file dwc_otg_pcd.c.

int dwc_otg_pcd_ep_dequeue	(	dwc_otg_pcd_t *	pcd,
		void *	ep_handle,
		void *	req_handle
	)

De-queue the specified data transfer that has not yet completed.

Returns -DWC_E_INVALID if invalid parameters were passed. Returns -DWC_E_SHUTDOWN if any other error ocurred. Returns 0 on success.

Definition at line 1694 of file dwc_otg_pcd.c.

int dwc_otg_pcd_ep_halt	(	dwc_otg_pcd_t *	pcd,
		void *	ep_handle,
		int	value
	)

Halt (STALL) an endpoint or clear it.

Returns -DWC_E_INVALID if invalid parameters were passed. Returns -DWC_E_SHUTDOWN if any other error ocurred. Returns -DWC_E_AGAIN if the STALL cannot be sent and must be tried again later Returns 0 on success.

Definition at line 1733 of file dwc_otg_pcd.c.

int32_t dwc_otg_pcd_handle_intr ( dwc_otg_pcd_t * pcd )

This function should be called on every hardware interrupt.

The PCD handles the device interrupts. Many conditions can cause a device interrupt. When an interrupt occurs, the device interrupt service routine determines the cause of the interrupt and dispatches handling to the appropriate function. These interrupt handling functions are described below.

All interrupt registers are processed from LSB to MSB.

Definition at line 3971 of file dwc_otg_pcd_intr.c.

int dwc_otg_pcd_iso_ep_start	(	dwc_otg_pcd_t *	pcd,
		void *	ep_handle,
		uint8_t *	buf0,
		uint8_t *	buf1,
		dwc_dma_t	dma0,
		dwc_dma_t	dma1,
		int	sync_frame,
		int	dp_frame,
		int	data_per_frame,
		int	start_frame,
		int	buf_proc_intrvl,
		void *	req_handle,
		int	atomic_alloc
	)

Start isochronous transfers on the endpoint referenced by ep_handle.

For isochronous transfers duble buffering is used. After processing each of buffers comlete callback will be called with status for each transaction.

Parameters:

	pcd	The PCD
	ep_handle	The handle of the endpoint
	buf0	The virtual address of first data buffer
	buf1	The virtual address of second data buffer
	dma0	The DMA address of first data buffer
	dma1	The DMA address of second data buffer
	sync_frame	Data pattern frame number
	dp_frame	Data size for pattern frame
	data_per_frame	Data size for regular frame
	start_frame	Frame number to start transfers, if -1 then start transfers ASAP.
	buf_proc_intrvl	Interval of ISOC Buffer processing
	req_handle	Handle of ISOC request
	atomic_alloc	Specefies whether to perform atomic allocation for internal data structures.

Returns -DWC_E_NO_MEMORY if there is no enough memory. Returns -DWC_E_INVALID if incorrect arguments are passed to the function. Returns -DW_E_SHUTDOWN for any other error. Returns 0 on success

Todo:

pattern data support is to be implemented in the future

Definition at line 685 of file dwc_otg_pcd.c.

int dwc_otg_pcd_iso_ep_stop	(	dwc_otg_pcd_t *	pcd,
		void *	ep_handle,
		void *	req_handle
	)

Stop ISOC transfers on endpoint referenced by ep_handle.

Parameters:

	pcd	The PCD
	ep_handle	The handle of the endpoint
	req_handle	Handle of ISOC request

Returns -DWC_E_INVALID if incorrect arguments are passed to the function Returns 0 on success

Definition at line 794 of file dwc_otg_pcd.c.

void dwc_otg_pcd_get_iso_packet_params	(	dwc_otg_pcd_t *	pcd,
		void *	ep_handle,
		void *	iso_req_handle,
		int	packet,
		int *	status,
		int *	actual,
		int *	offset
	)

Get ISOC packet status.

Parameters:

	pcd	The PCD
	ep_handle	The handle of the endpoint
	iso_req_handle	Isochronoush request handle
	packet	Number of packet
	status	Out parameter for returning status
	actual	Out parameter for returning actual length
	offset	Out parameter for returning offset

Definition at line 862 of file dwc_otg_pcd.c.

int dwc_otg_pcd_get_iso_packet_count	(	dwc_otg_pcd_t *	pcd,
		void *	ep_handle,
		void *	iso_req_handle
	)

Get ISOC packet count.

Parameters:

	pcd	The PCD
	ep_handle	The handle of the endpoint
	iso_req_handle

Definition at line 850 of file dwc_otg_pcd.c.

int dwc_otg_pcd_wakeup ( dwc_otg_pcd_t * pcd )

This function starts the SRP Protocol if no session is in progress.

If a session is already in progress, but the device is suspended, remote wakeup signaling is started.

Definition at line 1896 of file dwc_otg_pcd.c.

Generated on Tue May 5 02:22:49 2009 for DesignWare USB 2.0 OTG Controller (DWC_otg) Device Driver by

1.4.7


Data Structures
struct	dwc_otg_pcd_function_ops
	Function Driver Ops Data Structure. More...
Function Driver Callbacks
typedef int(*)	dwc_completion_cb_t (dwc_otg_pcd_t pcd, void ep_handle, void *req_handle, int32_t status, uint32_t actual)
	This function will be called whenever a previously queued request has completed.
typedef int(*)	dwc_isoc_completion_cb_t (dwc_otg_pcd_t pcd, void ep_handle, void *req_handle, int proc_buf_num)
	This function will be called whenever a previousle queued ISOC request has completed.
typedef int(*)	dwc_setup_cb_t (dwc_otg_pcd_t pcd, uint8_t bytes)
	This function should handle any SETUP request that cannot be handled by the PCD Core.
typedef int(*)	dwc_disconnect_cb_t (dwc_otg_pcd_t *pcd)
	This is called whenever the device has been disconnected.
typedef int(*)	dwc_connect_cb_t (dwc_otg_pcd_t *pcd, int speed)
	This function is called when device has been connected.
typedef int(*)	dwc_suspend_cb_t (dwc_otg_pcd_t *pcd)
	This function is called when device has been suspended.
typedef int(*)	dwc_sleep_cb_t (dwc_otg_pcd_t *pcd)
	This function is called when device has received LPM tokens, i.e.
typedef int(*)	dwc_resume_cb_t (dwc_otg_pcd_t *pcd)
	This function is called when device has been resumed from suspend(L2) or L1 sleep state.
typedef int(*)	dwc_hnp_params_changed_cb_t (dwc_otg_pcd_t *pcd)
	This function is called whenever hnp params has been changed.
typedef int(*)	dwc_reset_cb_t (dwc_otg_pcd_t *pcd)
	This function is called whenever USB RESET is detected.
typedef int(*)	cfi_setup_cb_t (dwc_otg_pcd_t pcd, void ctrl_req_bytes)
Function Driver Functions
dwc_otg_pcd_t *	dwc_otg_pcd_init (dwc_otg_core_if_t *core_if)
	Call this function to get pointer on dwc_otg_pcd_t, this pointer will be used for all PCD API functions.
void	dwc_otg_pcd_remove (dwc_otg_pcd_t *pcd)
	Frees PCD allocated by dwc_otg_pcd_init.
void	dwc_otg_pcd_start (dwc_otg_pcd_t pcd, const struct dwc_otg_pcd_function_ops fops)
	Call this to bind the function driver to the PCD Core.
int	dwc_otg_pcd_ep_enable (dwc_otg_pcd_t pcd, const uint8_t ep_desc, void *ep_handle)
	Enables an endpoint for use.
int	dwc_otg_pcd_ep_disable (dwc_otg_pcd_t pcd, void ep_handle)
	Disable the endpoint referenced by ep_handle.
int	dwc_otg_pcd_ep_queue (dwc_otg_pcd_t pcd, void ep_handle, uint8_t buf, dwc_dma_t dma_buf, uint32_t buflen, int zero, void req_handle, int atomic_alloc)
	Queue a data transfer request on the endpoint referenced by ep_handle.
int	dwc_otg_pcd_ep_dequeue (dwc_otg_pcd_t pcd, void ep_handle, void *req_handle)
	De-queue the specified data transfer that has not yet completed.
int	dwc_otg_pcd_ep_halt (dwc_otg_pcd_t pcd, void ep_handle, int value)
	Halt (STALL) an endpoint or clear it.
int32_t	dwc_otg_pcd_handle_intr (dwc_otg_pcd_t *pcd)
	This function should be called on every hardware interrupt.
int	dwc_otg_pcd_get_frame_number (dwc_otg_pcd_t *pcd)
	This function returns current frame number.
int	dwc_otg_pcd_iso_ep_start (dwc_otg_pcd_t pcd, void ep_handle, uint8_t buf0, uint8_t buf1, dwc_dma_t dma0, dwc_dma_t dma1, int sync_frame, int dp_frame, int data_per_frame, int start_frame, int buf_proc_intrvl, void *req_handle, int atomic_alloc)
	Start isochronous transfers on the endpoint referenced by ep_handle.
int	dwc_otg_pcd_iso_ep_stop (dwc_otg_pcd_t pcd, void ep_handle, void *req_handle)
	Stop ISOC transfers on endpoint referenced by ep_handle.
void	dwc_otg_pcd_get_iso_packet_params (dwc_otg_pcd_t pcd, void ep_handle, void iso_req_handle, int packet, int status, int actual, int offset)
	Get ISOC packet status.
int	dwc_otg_pcd_get_iso_packet_count (dwc_otg_pcd_t pcd, void ep_handle, void *iso_req_handle)
	Get ISOC packet count.
int	dwc_otg_pcd_wakeup (dwc_otg_pcd_t *pcd)
	This function starts the SRP Protocol if no session is in progress.
int	dwc_otg_pcd_is_lpm_enabled (dwc_otg_pcd_t *pcd)
	This function returns 1 if LPM support is enabled, and 0 otherwise.
int	dwc_otg_pcd_get_rmwkup_enable (dwc_otg_pcd_t *pcd)
	This function returns 1 if remote wakeup is allowed and 0, otherwise.
void	dwc_otg_pcd_initiate_srp (dwc_otg_pcd_t *pcd)
	Initiate SRP.
void	dwc_otg_pcd_remote_wakeup (dwc_otg_pcd_t *pcd, int set)
	Starts remote wakeup signaling.
uint32_t	dwc_otg_pcd_is_dualspeed (dwc_otg_pcd_t *pcd)
	This function returns whether device is dualspeed.
uint32_t	dwc_otg_pcd_is_otg (dwc_otg_pcd_t *pcd)
	This function returns whether device is otg.
uint32_t	get_b_hnp_enable (dwc_otg_pcd_t *pcd)
	These functions allow to get hnp parameters.
uint32_t	get_a_hnp_support (dwc_otg_pcd_t *pcd)
uint32_t	get_a_alt_hnp_support (dwc_otg_pcd_t *pcd)
uint8_t *	cfiw_ep_alloc_buffer (dwc_otg_pcd_t pcd, void pep, dwc_dma_t *addr, size_t buflen, int flags)
	Allocate a cfi buffer.
Defines
#define	__DWC_PCD_IF_H__
#define	MAX_EP0_SIZE 64
	Maxpacket size for EP0.
#define	MAX_PACKET_SIZE 1024
	Maxpacket size for any EP.
Typedefs
typedef dwc_otg_pcd	dwc_otg_pcd_t