xusbps.h File Reference

#include "xusbps_hw.h"
#include "xil_types.h"
#include "xstatus.h"

Classes
struct	XUsbPs_EpOut
struct	XUsbPs_EpIn
struct	XUsbPs_Endpoint
struct	XUsbPs_SetupData
struct	XUsbPs_EpSetup
struct	XUsbPs_EpConfig
struct	XUsbPs_DeviceConfig
struct	XUsbPs_Config
struct	XUsbPs
Defines
#define	XUSBPS_MAX_PACKET_SIZE 1024
#define	XUsbPs_GetFrameNum(InstancePtr) XUsbPs_ReadReg((InstancePtr)->Config.BaseAddress, XUSBPS_FRAME_OFFSET)
#define	XUsbPs_Start(InstancePtr) XUsbPs_SetBits(InstancePtr, XUSBPS_CMD_OFFSET, XUSBPS_CMD_RS_MASK)
#define	XUsbPs_Stop(InstancePtr) XUsbPs_ClrBits(InstancePtr, XUSBPS_CMD_OFFSET, XUSBPS_CMD_RS_MASK)
#define	XUsbPs_ForceFS(InstancePtr)
#define	XUsbPs_StartTimer0(InstancePtr, Interval)
#define	XUsbPs_StopTimer0(InstancePtr)
#define	XUsbPs_ReadTimer0(InstancePtr)
#define	XUsbPs_RemoteWakeup(InstancePtr)
#define	XUsbPs_EpEnable(InstancePtr, EpNum, Dir)
#define	XUsbPs_EpDisable(InstancePtr, EpNum, Dir)
#define	XUsbPs_EpStall(InstancePtr, EpNum, Dir)
#define	XUsbPs_EpUnStall(InstancePtr, EpNum, Dir)
#define	XUsbPs_EpFlush(InstancePtr, EpNum, Dir)
#define	XUsbPs_IntrEnable(InstancePtr, IntrMask) XUsbPs_SetBits(InstancePtr, XUSBPS_IER_OFFSET, IntrMask)
#define	XUsbPs_IntrDisable(InstancePtr, IntrMask) XUsbPs_ClrBits(InstancePtr, XUSBPS_IER_OFFSET, IntrMask)
#define	XUsbPs_NakIntrEnable(InstancePtr, NakIntrMask) XUsbPs_SetBits(InstancePtr, XUSBPS_EPNAKIER_OFFSET, NakIntrMask)
#define	XUsbPs_NakIntrDisable(InstancePtr, NakIntrMask) XUsbPs_ClrBits(InstancePtr, XUSBPS_EPNAKIER_OFFSET, NakIntrMask)
#define	XUsbPs_NakIntrClear(InstancePtr, NakIntrMask)
#define	XUsbPs_SetIntrThreshold(InstancePtr, Threshold)
#define	XUsbPs_SetSetupTripwire(InstancePtr)
#define	XUsbPs_ClrSetupTripwire(InstancePtr)
#define	XUsbPs_SetupTripwireIsSet(InstancePtr)
#define	XUsbPs_SetBits(InstancePtr, RegOffset, Bits)
#define	XUsbPs_ClrBits(InstancePtr, RegOffset, Bits)
System hang prevention Timeout counter value.
This value is used throughout the code to initialize a Timeout counter that is used when hard polling a register. The ides is to initialize the Timeout counter to a value that is longer than any expected Timeout but short enough so the system will continue to work and report an error while the user is still paying attention. A reasonable Timeout time would be about 10 seconds. The XUSBPS_TIMEOUT_COUNTER value should be chosen so a polling loop would run about 10 seconds before a Timeout is detected. For example: int Timeout = XUSBPS_TIMEOUT_COUNTER; while ((XUsbPs_ReadReg(InstancePtr->Config.BaseAddress, XUSBPS_CMD_OFFSET) & XUSBPS_CMD_RST_MASK) && --Timeout) { ; } if (0 == Timeout) { return XST_FAILURE; }
#define	XUSBPS_TIMEOUT_COUNTER 1000000
Endpoint Direction (bitmask)
Definitions to be used with Endpoint related function that require a 'Direction' parameter. NOTE: The direction is always defined from the perspective of the HOST! This means that an IN endpoint on the controller is used for sending data while the OUT endpoint on the controller is used for receiving data.
#define	XUSBPS_EP_DIRECTION_IN 0x01
#define	XUSBPS_EP_DIRECTION_OUT 0x02
Endpoint Type
Definitions to be used with Endpoint related functions that require a 'Type' parameter.
#define	XUSBPS_EP_TYPE_NONE 0
#define	XUSBPS_EP_TYPE_CONTROL 1
#define	XUSBPS_EP_TYPE_ISOCHRONOUS 2
#define	XUSBPS_EP_TYPE_BULK 3
#define	XUSBPS_EP_TYPE_INTERRUPT 4


#define	ENDPOINT_MAXP_LENGTH 0x400
#define	ENDPOINT_MAXP_MULT_MASK 0xC00
#define	ENDPOINT_MAXP_MULT_SHIFT 10
Field names for status retrieval
Definitions for the XUsbPs_GetStatus() function call 'StatusType' parameter.
#define	XUSBPS_EP_STS_ADDRESS 1
#define	XUSBPS_EP_STS_CONTROLLER_STATE 2
USB Default alternate setting

#define	XUSBPS_DEFAULT_ALT_SETTING 0
Endpoint event types
Definitions that are used to identify events that occur on endpoints. Passed to the endpoint event handler functions registered with XUsbPs_EpSetHandler().
#define	XUSBPS_EP_EVENT_SETUP_DATA_RECEIVED 0x01
#define	XUSBPS_EP_EVENT_DATA_RX 0x02
#define	XUSBPS_EP_EVENT_DATA_TX 0x03
Typedefs
typedef void(*	XUsbPs_EpHandlerFunc )(void CallBackRef, u8 EpNum, u8 EventType, void Data)
typedef void(*	XUsbPs_IntrHandlerFunc )(void *CallBackRef, u32 IrqMask)
typedef u8	XUsbPs_dQH [XUSBPS_dQH_ALIGN]
typedef u8	XUsbPs_dTD [XUSBPS_dTD_ALIGN]
Functions
int	XUsbPs_CfgInitialize (XUsbPs InstancePtr, const XUsbPs_Config ConfigPtr, u32 BaseAddress)
int	XUsbPs_ConfigureDevice (XUsbPs InstancePtr, const XUsbPs_DeviceConfig CfgPtr)
int	XUsbPs_Reset (XUsbPs *InstancePtr)
void	XUsbPs_DeviceReset (XUsbPs *InstancePtr)
int	XUsbPs_BusReset (XUsbPs *InstancePtr)
int	XUsbPs_SetDeviceAddress (XUsbPs *InstancePtr, u8 Address)
int	XUsbPs_Suspend (const XUsbPs *InstancePtr)
int	XUsbPs_Resume (const XUsbPs *InstancePtr)
int	XUsbPs_RequestHostResume (const XUsbPs *InstancePtr)
int	XUsbPs_EpBufferSend (XUsbPs InstancePtr, u8 EpNum, const u8 BufferPtr, u32 BufferLen)
int	XUsbPs_EpBufferSendWithZLT (XUsbPs InstancePtr, u8 EpNum, const u8 BufferPtr, u32 BufferLen)
int	XUsbPs_EpBufferReceive (XUsbPs InstancePtr, u8 EpNum, u8 BufferPtr, u32 BufferLenPtr, u32 *Handle)
void	XUsbPs_EpBufferRelease (u32 Handle)
int	XUsbPs_EpSetHandler (XUsbPs InstancePtr, u8 EpNum, u8 Direction, XUsbPs_EpHandlerFunc CallBackFunc, void CallBackRef)
int	XUsbPs_EpGetSetupData (XUsbPs InstancePtr, int EpNum, XUsbPs_SetupData SetupDataPtr)
int	XUsbPs_EpPrime (XUsbPs *InstancePtr, u8 EpNum, u8 Direction)
int	XUsbPs_ReconfigureEp (XUsbPs InstancePtr, XUsbPs_DeviceConfig CfgPtr, int EpNum, unsigned short NewDirection, int DirectionChanged)
void	XUsbPs_IntrHandler (void *InstancePtr)
int	XUsbPs_IntrSetHandler (XUsbPs InstancePtr, XUsbPs_IntrHandlerFunc CallBackFunc, void CallBackRef, u32 Mask)
XUsbPs_Config *	XUsbPs_LookupConfig (u16 DeviceId)

Detailed Description

Define Documentation

#define ENDPOINT_MAXP_LENGTH 0x400

Endpoint Max Packet Length in DeviceConfig is a coded value, ch9.6.6.

#define ENDPOINT_MAXP_MULT_MASK 0xC00

#define ENDPOINT_MAXP_MULT_SHIFT 10

#define XUsbPs_ClrBits	(	InstancePtr,
		RegOffset,
		Bits	)

Value:

XUsbPs_WriteReg((InstancePtr)->Config.BaseAddress, RegOffset,   \
                XUsbPs_ReadReg((InstancePtr)->Config.BaseAddress,       \
                                RegOffset) & ~(Bits));

This macro clears the given bits in the register.

Parameters:

	InstancePtr	is a pointer to XUsbPs instance of the controller.
	RegOffset	is the register offset to be written.
	Bits	are the bits to be cleared in the register

Returns:: None.

Note:: C-style signature: void XUsbPs_ClrBits(u32 BaseAddress, u32 RegOffset, u32 Bits)

#define XUsbPs_ClrSetupTripwire ( InstancePtr )

Value:

XUsbPs_ClrBits(InstancePtr, XUSBPS_CMD_OFFSET,  \
                                XUSBPS_CMD_SUTW_MASK)

This macro clears the Tripwire bit in the USB command register.

Parameters:

InstancePtr

is a pointer to XUsbPs instance of the controller.

Note:: C-style signature: void XUsbPs_ClrTripwire(XUsbPs *InstancePtr)

#define XUSBPS_DEFAULT_ALT_SETTING 0

The default alternate setting is 0

#define XUSBPS_EP_DIRECTION_IN 0x01

Endpoint direction IN.

#define XUSBPS_EP_DIRECTION_OUT 0x02

Endpoint direction OUT.

#define XUSBPS_EP_EVENT_DATA_RX 0x02

Data frame has been received on the endpoint.

#define XUSBPS_EP_EVENT_DATA_TX 0x03

Data frame has been sent on the endpoint.

#define XUSBPS_EP_EVENT_SETUP_DATA_RECEIVED 0x01

Setup data has been received on the enpoint.

#define XUSBPS_EP_STS_ADDRESS 1

Address of controller.

#define XUSBPS_EP_STS_CONTROLLER_STATE 2

Current controller state.

#define XUSBPS_EP_TYPE_BULK 3

Endpoint for BULK Transfers.

#define XUSBPS_EP_TYPE_CONTROL 1

Endpoint for Control Transfers

#define XUSBPS_EP_TYPE_INTERRUPT 4

Endpoint for interrupt Transfers

#define XUSBPS_EP_TYPE_ISOCHRONOUS 2

Endpoint for isochronous data

#define XUSBPS_EP_TYPE_NONE 0

Endpoint is not used.

#define XUsbPs_EpDisable	(	InstancePtr,
		EpNum,
		Dir	)

Value:

XUsbPs_ClrBits(InstancePtr, XUSBPS_EPCRn_OFFSET(EpNum),          \
                ((Dir) & XUSBPS_EP_DIRECTION_OUT ? XUSBPS_EPCR_RXE_MASK : 0) | \
                ((Dir) & XUSBPS_EP_DIRECTION_IN  ? XUSBPS_EPCR_TXE_MASK : 0))

This macro disables the given endpoint for the given direction.

Parameters:

InstancePtr

is a pointer to the XUsbPs instance of the controller.

EpNum

is the number of the endpoint to disable.

Dir

is the direction of the endpoint (bitfield):

XUSBPS_EP_DIRECTION_OUT
XUSBPS_EP_DIRECTION_IN

Note:: C-style signature: void XUsbPs_EpDisable(XUsbPs *InstancePtr, u8 EpNum, u8 Dir)

#define XUsbPs_EpEnable	(	InstancePtr,
		EpNum,
		Dir	)

Value:

XUsbPs_SetBits(InstancePtr, XUSBPS_EPCRn_OFFSET(EpNum),  \
        ((Dir) & XUSBPS_EP_DIRECTION_OUT ? XUSBPS_EPCR_RXE_MASK : 0) | \
        ((Dir) & XUSBPS_EP_DIRECTION_IN  ? XUSBPS_EPCR_TXE_MASK : 0))

This macro enables the given endpoint for the given direction.

Parameters:

InstancePtr

is a pointer to the XUsbPs instance of the controller.

EpNum

is number of the endpoint to enable.

Dir

is direction of the endpoint (bitfield):

XUSBPS_EP_DIRECTION_OUT
XUSBPS_EP_DIRECTION_IN

Note:: C-style signature: void XUsbPs_EpEnable(XUsbPs *InstancePtr, u8 EpNum, u8 Dir)

#define XUsbPs_EpFlush	(	InstancePtr,
		EpNum,
		Dir	)

Value:

XUsbPs_SetBits(InstancePtr, XUSBPS_EPFLUSH_OFFSET,      \
                EpNum << ((Dir) & XUSBPS_EP_DIRECTION_OUT ?             \
                        XUSBPS_EPFLUSH_RX_SHIFT:XUSBPS_EPFLUSH_TX_SHIFT)) \

This macro flush an endpoint upon interface disable

Parameters:

InstancePtr

is a pointer to the XUsbPs instance of the controller.

EpNum

is the number of the endpoint to flush.

Dir

is the direction of the endpoint (bitfield):

XUSBPS_EP_DIRECTION_OUT
XUSBPS_EP_DIRECTION_IN

Note:: C-style signature: void XUsbPs_EpFlush(XUsbPs *InstancePtr, u8 EpNum, u8 Dir)

#define XUsbPs_EpStall	(	InstancePtr,
		EpNum,
		Dir	)

Value:

XUsbPs_SetBits(InstancePtr, XUSBPS_EPCRn_OFFSET(EpNum),  \
        ((Dir) & XUSBPS_EP_DIRECTION_OUT ? XUSBPS_EPCR_RXS_MASK : 0) | \
        ((Dir) & XUSBPS_EP_DIRECTION_IN  ? XUSBPS_EPCR_TXS_MASK : 0))

This macro stalls the given endpoint for the given direction, and flush the buffers.

Parameters:

InstancePtr

is a pointer to the XUsbPs instance of the controller.

EpNum

is number of the endpoint to stall.

Dir

is the direction of the endpoint (bitfield):

XUSBPS_EP_DIRECTION_OUT
XUSBPS_EP_DIRECTION_IN

Note:: C-style signature: void XUsbPs_EpStall(XUsbPs *InstancePtr, u8 EpNum, u8 Dir)

#define XUsbPs_EpUnStall	(	InstancePtr,
		EpNum,
		Dir	)

Value:

XUsbPs_ClrBits(InstancePtr, XUSBPS_EPCRn_OFFSET(EpNum),  \
        ((Dir) & XUSBPS_EP_DIRECTION_OUT ? XUSBPS_EPCR_RXS_MASK : 0) | \
        ((Dir) & XUSBPS_EP_DIRECTION_IN  ? XUSBPS_EPCR_TXS_MASK : 0))

This macro unstalls the given endpoint for the given direction.

Parameters:

InstancePtr

is a pointer to the XUsbPs instance of the controller.

EpNum

is the Number of the endpoint to unstall.

Dir

is the Direction of the endpoint (bitfield):

XUSBPS_EP_DIRECTION_OUT
XUSBPS_EP_DIRECTION_IN

Note:: C-style signature: void XUsbPs_EpUnStall(XUsbPs *InstancePtr, u8 EpNum, u8 Dir)

#define XUsbPs_ForceFS ( InstancePtr )

Value:

XUsbPs_SetBits(InstancePtr, XUSBPS_PORTSCR1_OFFSET,             \
                XUSBPS_PORTSCR_PFSC_MASK)

This macro forces the USB engine to be in Full Speed (FS) mode.

Parameters:

InstancePtr

is a pointer to the XUsbPs instance of the controller.

Note:: C-style signature: void XUsbPs_ForceFS(XUsbPs *InstancePtr)

#define XUsbPs_GetFrameNum ( InstancePtr ) XUsbPs_ReadReg((InstancePtr)->Config.BaseAddress, XUSBPS_FRAME_OFFSET)

This macro returns the current frame number.

Parameters:

InstancePtr

is a pointer to the XUsbPs instance of the controller.

Returns:: The current frame number.

Note:: C-style signature: u32 XUsbPs_GetFrameNum(const XUsbPs *InstancePtr)

#define XUsbPs_IntrDisable	(	InstancePtr,
		IntrMask		)	XUsbPs_ClrBits(InstancePtr, XUSBPS_IER_OFFSET, IntrMask)

This function disables the interrupts defined by the bit mask.

Parameters:

	InstancePtr	is a pointer to XUsbPs instance of the controller.
	IntrMask	is a Bit mask of interrupts to be disabled.

Note:: C-style signature: void XUsbPs_IntrDisable(XUsbPs *InstancePtr, u32 IntrMask)

#define XUsbPs_IntrEnable	(	InstancePtr,
		IntrMask		)	XUsbPs_SetBits(InstancePtr, XUSBPS_IER_OFFSET, IntrMask)

This macro enables the interrupts defined by the bit mask.

Parameters:

	InstancePtr	is a pointer to XUsbPs instance of the controller.
	IntrMask	is the Bit mask of interrupts to be enabled.

Note:: C-style signature: void XUsbPs_IntrEnable(XUsbPs *InstancePtr, u32 IntrMask)

#define XUSBPS_MAX_PACKET_SIZE 1024

Maximum value can be put into the queue head

#define XUsbPs_NakIntrClear	(	InstancePtr,
		NakIntrMask		)

Value:

XUsbPs_WriteReg((InstancePtr)->Config.BaseAddress,              \
                                XUSBPS_EPNAKISR_OFFSET, NakIntrMask)

This function clears the endpoint NAK interrupts status defined by the bit mask.

Parameters:

	InstancePtr	is a pointer to XUsbPs instance of the controller.
	NakIntrMask	is the Bit mask of endpoint NAK interrupts to be cleared.

Note:: C-style signature: void XUsbPs_NakIntrClear(XUsbPs *InstancePtr, u32 NakIntrMask)

#define XUsbPs_NakIntrDisable	(	InstancePtr,
		NakIntrMask		)	XUsbPs_ClrBits(InstancePtr, XUSBPS_EPNAKIER_OFFSET, NakIntrMask)

This macro disables the endpoint NAK interrupts defined by the bit mask.

Parameters:

	InstancePtr	is a pointer to XUsbPs instance of the controller.
	NakIntrMask	is a Bit mask of endpoint NAK interrupts to be disabled.

Note:: C-style signature: void XUsbPs_NakIntrDisable(XUsbPs *InstancePtr, u32 NakIntrMask)

#define XUsbPs_NakIntrEnable	(	InstancePtr,
		NakIntrMask		)	XUsbPs_SetBits(InstancePtr, XUSBPS_EPNAKIER_OFFSET, NakIntrMask)

This macro enables the endpoint NAK interrupts defined by the bit mask.

Parameters:

	InstancePtr	is a pointer to XUsbPs instance of the controller.
	NakIntrMask	is the Bit mask of endpoint NAK interrupts to be enabled.

Note:: C-style signature: void XUsbPs_NakIntrEnable(XUsbPs *InstancePtr, u32 NakIntrMask)

#define XUsbPs_ReadTimer0 ( InstancePtr )

Value:

XUsbPs_ReadReg((InstancePtr)->Config.BaseAddress,               \
                        XUSBPS_TIMER0_CTL_OFFSET) &                     \
                                        XUSBPS_TIMER_COUNTER_MASK

This macro reads Timer 0.

Parameters:

InstancePtr

is a pointer to XUsbPs instance of the controller.

Note:: C-style signature: void XUsbPs_ReadTimer0(XUsbPs *InstancePtr)

#define XUsbPs_RemoteWakeup ( InstancePtr )

Value:

XUsbPs_SetBits(InstancePtr, XUSBPS_PORTSCR1_OFFSET,              \
                        XUSBPS_PORTSCR_FPR_MASK)

This macro force remote wakeup on host

Parameters:

InstancePtr

is a pointer to XUsbPs instance of the controller.

Note:: C-style signature: void XUsbPs_RemoteWakeup(XUsbPs *InstancePtr)

#define XUsbPs_SetBits	(	InstancePtr,
		RegOffset,
		Bits	)

Value:

XUsbPs_WriteReg((InstancePtr)->Config.BaseAddress, RegOffset,   \
                XUsbPs_ReadReg((InstancePtr)->Config.BaseAddress,       \
                                        RegOffset) | (Bits));

This macro sets the given bit mask in the register.

Parameters:

	InstancePtr	is a pointer to XUsbPs instance of the controller.
	RegOffset	is the register offset to be written.
	Bits	is the Bits to be set in the register

Returns:: None.

Note:: C-style signature: void XUsbPs_SetBits(u32 BaseAddress, u32 RegOffset, u32 Bits)

#define XUsbPs_SetIntrThreshold	(	InstancePtr,
		Threshold		)

Value:

XUsbPs_WriteReg((InstancePtr)->Config.BaseAddress,      \
                                        XUSBPS_CMD_OFFSET, (Threshold))\

This macro sets the Interrupt Threshold value in the control register

Parameters:

InstancePtr

is a pointer to XUsbPs instance of the controller.

Threshold

is the Interrupt threshold to be set. Allowed values:

XUSBPS_CMD_ITHRESHOLD_0 - Immediate interrupt
XUSBPS_CMD_ITHRESHOLD_1 - 1 Frame
XUSBPS_CMD_ITHRESHOLD_2 - 2 Frames
XUSBPS_CMD_ITHRESHOLD_4 - 4 Frames
XUSBPS_CMD_ITHRESHOLD_8 - 8 Frames
XUSBPS_CMD_ITHRESHOLD_16 - 16 Frames
XUSBPS_CMD_ITHRESHOLD_32 - 32 Frames
XUSBPS_CMD_ITHRESHOLD_64 - 64 Frames

Note:: C-style signature: void XUsbPs_SetIntrThreshold(XUsbPs *InstancePtr, u8 Threshold)

#define XUsbPs_SetSetupTripwire ( InstancePtr )

Value:

XUsbPs_SetBits(InstancePtr, XUSBPS_CMD_OFFSET,  \
                                XUSBPS_CMD_SUTW_MASK)

This macro sets the Tripwire bit in the USB command register.

Parameters:

InstancePtr

is a pointer to XUsbPs instance of the controller.

Note:: C-style signature: void XUsbPs_SetTripwire(XUsbPs *InstancePtr)

#define XUsbPs_SetupTripwireIsSet ( InstancePtr )

Value:

(XUsbPs_ReadReg((InstancePtr)->Config.BaseAddress,      \
                                XUSBPS_CMD_OFFSET) &                    \
                                XUSBPS_CMD_SUTW_MASK ? TRUE : FALSE)

This macro checks if the Tripwire bit in the USB command register is set.

Parameters:

InstancePtr

is a pointer to XUsbPs instance of the controller.

Returns:

TRUE: The tripwire bit is still set.
FALSE: The tripwire bit has been cleared.

Note:: C-style signature: int XUsbPs_TripwireIsSet(XUsbPs *InstancePtr)

#define XUsbPs_Start ( InstancePtr ) XUsbPs_SetBits(InstancePtr, XUSBPS_CMD_OFFSET, XUSBPS_CMD_RS_MASK)

This macro starts the USB engine.

Parameters:

InstancePtr

is a pointer to the XUsbPs instance of the controller.

Note:: C-style signature: void XUsbPs_Start(XUsbPs *InstancePtr)

#define XUsbPs_StartTimer0	(	InstancePtr,
		Interval		)

Value:

{                                                                       \
        XUsbPs_WriteReg((InstancePtr)->Config.BaseAddress,              \
                        XUSBPS_TIMER0_LD_OFFSET, (Interval));           \
        XUsbPs_SetBits(InstancePtr, XUSBPS_TIMER0_CTL_OFFSET,           \
                        XUSBPS_TIMER_RUN_MASK |                 \
                        XUSBPS_TIMER_RESET_MASK |                       \
                        XUSBPS_TIMER_REPEAT_MASK);                      \
}                                                                       \

This macro starts the USB Timer 0, with repeat option for period of one second.

Parameters:

	InstancePtr	is a pointer to XUsbPs instance of the controller.
	Interval	is the interval for Timer0 to generate an interrupt

Note:: C-style signature: void XUsbPs_StartTimer0(XUsbPs *InstancePtr, u32 Interval)

#define XUsbPs_Stop ( InstancePtr ) XUsbPs_ClrBits(InstancePtr, XUSBPS_CMD_OFFSET, XUSBPS_CMD_RS_MASK)

This macro stops the USB engine.

Parameters:

InstancePtr

is a pointer to the XUsbPs instance of the controller.

Note:: C-style signature: void XUsbPs_Stop(XUsbPs *InstancePtr)

#define XUsbPs_StopTimer0 ( InstancePtr )

Value:

XUsbPs_ClrBits(InstancePtr, XUSBPS_TIMER0_CTL_OFFSET,           \
                XUSBPS_TIMER_RUN_MASK)

This macro stops Timer 0.

Parameters:

InstancePtr

is a pointer to XUsbPs instance of the controller.

Note:: C-style signature: void XUsbPs_StopTimer0(XUsbPs *InstancePtr)

#define XUSBPS_TIMEOUT_COUNTER 1000000

Typedef Documentation

typedef u8 XUsbPs_dQH[XUSBPS_dQH_ALIGN]

typedef u8 XUsbPs_dTD[XUSBPS_dTD_ALIGN]

typedef void(* XUsbPs_EpHandlerFunc)(void *CallBackRef, u8 EpNum, u8 EventType, void *Data)

typedef void(* XUsbPs_IntrHandlerFunc)(void *CallBackRef, u32 IrqMask)

Function Documentation

int XUsbPs_BusReset ( XUsbPs * InstancePtr )

DEVICE mode specific functions.

int XUsbPs_CfgInitialize	(	XUsbPs *	InstancePtr,
		const XUsbPs_Config *	ConfigPtr,
		u32	VirtBaseAddress
	)

Setup / Initialize functions.

Implemented in file xusbps.c

This function initializes a XUsbPs instance/driver.

The initialization entails:

Initialize all members of the XUsbPs structure.

Parameters:

	InstancePtr	is a pointer to XUsbPs instance of the controller.
	ConfigPtr	is a pointer to a XUsbPs_Config configuration structure. This structure will contain the requested configuration for the device. Typically, this is a local structure and the content of which will be copied into the configuration structure within XUsbPs.
	VirtBaseAddress	is the base address of the device. For systems with virtual memory, this address must be the virtual address of the device. For systems that do not support virtual memory this address should be the physical address of the device. For backwards compatibilty NULL may be passed in systems that do not support virtual memory (deprecated).

Returns:

XST_SUCCESS no errors occured.
XST_FAILURE an error occured during initialization.

Note:: After calling XUsbPs_CfgInitialize() the controller IS NOT READY for use. Before the controller can be used its DEVICE parameters must be configured. See xusbps.h for details.

int XUsbPs_ConfigureDevice	(	XUsbPs *	InstancePtr,
		const XUsbPs_DeviceConfig *	CfgPtr
	)

This function configures the DEVICE side of the controller. The caller needs to pass in the desired configuration (e.g. number of endpoints) and a DMAable buffer that will hold the Queue Head List and the Transfer Descriptors. The required size for this buffer can be obtained by the caller using the: XUsbPs_DeviceMemRequired() macro.

Parameters:

	InstancePtr	is a pointer to the XUsbPs instance of the controller.
	CfgPtr	is a pointer to the configuration structure that contains the desired DEVICE side configuration.

Returns:

XST_SUCCESS: The operation completed successfully.
XST_FAILURE: An error occured.

Note:: The caller may configure the controller for both, DEVICE and HOST side.

void XUsbPs_DeviceReset ( XUsbPs * InstancePtr )

This function performs device reset, device is stopped at the end.

Parameters:

InstancePtr

is a pointer to XUsbPs instance of the controller.

Returns:: None.

Note:: None.

int XUsbPs_EpBufferReceive	(	XUsbPs *	InstancePtr,
		u8	EpNum,
		u8 **	BufferPtr,
		u32 *	BufferLenPtr,
		u32 *	Handle
	)

This function receives a data buffer from the endpoint of the given endpoint number.

Parameters:

	InstancePtr	is a pointer to the XUsbPs instance of the controller.
	EpNum	is the number of the endpoint to receive data from.
	BufferPtr	(OUT param) is a pointer to the buffer pointer to hold the reference of the data buffer.
	BufferLenPtr	(OUT param) is a pointer to the integer that will hold the buffer length.
	Handle	is the opaque handle to be used when the buffer is released.

Returns:

XST_SUCCESS: The operation completed successfully.
XST_FAILURE: An error occured.
XST_USB_NO_BUF: No buffer available.

Note:: After handling the data in the buffer, the user MUST release the buffer using the Handle by calling the XUsbPs_EpBufferRelease() function.

void XUsbPs_EpBufferRelease ( u32 Handle )

This function returns a previously received data buffer to the driver.

Parameters:

Handle

is a pointer to the buffer that is returned.

Returns:: None.

int XUsbPs_EpBufferSend	(	XUsbPs *	InstancePtr,
		u8	EpNum,
		const u8 *	BufferPtr,
		u32	BufferLen
	)

This function sends a given data buffer.

Parameters:

	InstancePtr	is a pointer to XUsbPs instance of the controller.
	EpNum	is the number of the endpoint to receive data from.
	BufferPtr	is a pointer to the buffer to send.
	BufferLen	is the Buffer length.

Returns:

XST_SUCCESS: The operation completed successfully.
XST_FAILURE: An error occured.
XST_USB_BUF_TOO_BIG: Provided buffer is too big (>16kB).
XST_USB_NO_DESC_AVAILABLE: No TX descriptor is available.

int XUsbPs_EpBufferSendWithZLT	(	XUsbPs *	InstancePtr,
		u8	EpNum,
		const u8 *	BufferPtr,
		u32	BufferLen
	)

This function sends a given data buffer and also zero length packet if the Bufferlen is in multiples of endpoint max packet size.

Parameters:

	InstancePtr	is a pointer to XUsbPs instance of the controller.
	EpNum	is the number of the endpoint to receive data from.
	BufferPtr	is a pointer to the buffer to send.
	BufferLen	is the Buffer length.

Returns:

XST_SUCCESS: The operation completed successfully.
XST_FAILURE: An error occured.
XST_USB_BUF_TOO_BIG: Provided buffer is too big (>16kB).
XST_USB_NO_DESC_AVAILABLE: No TX descriptor is available.

int XUsbPs_EpGetSetupData	(	XUsbPs *	InstancePtr,
		int	EpNum,
		XUsbPs_SetupData *	SetupDataPtr
	)

This function extracts the Setup Data from a given endpoint.

Parameters:

	InstancePtr	is a pointer to the XUsbPs instance of the controller.
	EpNum	is the number of the endpoint to receive data from.
	SetupDataPtr	is a pointer to the setup data structure to be filled.

Returns:

XST_SUCCESS: The operation completed successfully.
XST_FAILURE: An error occured.

Note:: None.

int XUsbPs_EpPrime	(	XUsbPs *	InstancePtr,
		u8	EpNum,
		u8	Direction
	)

This function primes an endpoint.

Parameters:

InstancePtr

is pointer to the XUsbPs instance.

EpNum

is the number of the endpoint to receive data from.

Direction

is the direction of the endpoint (bitfield):

XUSBPS_EP_DIRECTION_OUT
XUSBPS_EP_DIRECTION_IN

Returns:

XST_SUCCESS: The operation completed successfully.
XST_FAILURE: An error occured.
XST_INVALID_PARAM: Invalid parameter passed.

Note:: None.

int XUsbPs_EpSetHandler	(	XUsbPs *	InstancePtr,
		u8	EpNum,
		u8	Direction,
		XUsbPs_EpHandlerFunc	CallBackFunc,
		void *	CallBackRef
	)

This function sets the handler for endpoint events.

Parameters:

	InstancePtr	is a pointer to the XUsbPs instance of the controller.
	EpNum	is the number of the endpoint to receive data from.
	Direction	is the direction of the endpoint (bitfield): XUSBPS_EP_DIRECTION_OUT XUSBPS_EP_DIRECTION_IN
	CallBackFunc	is the Handler callback function. Can be NULL if the user wants to disable the handler entry.
	CallBackRef	is the user definable data pointer that will be passed back if the handler is called. May be NULL.

Returns:

XST_SUCCESS: The operation completed successfully.
XST_FAILURE: An error occured.
XST_INVALID_PARAM: Invalid parameter passed.

Note:: The user can disable a handler by setting the callback function pointer to NULL.

void XUsbPs_IntrHandler ( void * HandlerRef )

This function is the first-level interrupt handler for the USB core. All USB interrupts will be handled here. Depending on the type of the interrupt, second level interrupt handler may be called. Second level interrupt handlers will be registered by the user using the: XUsbPs_IntrSetHandler() and/or XUsbPs_EpSetHandler() functions.

Parameters:

HandlerRef

is a Reference passed to the interrupt register function. In our case this will be a pointer to the XUsbPs instance.

Returns:: None

Note:: None

int XUsbPs_IntrSetHandler	(	XUsbPs *	InstancePtr,
		XUsbPs_IntrHandlerFunc	CallBackFunc,
		void *	CallBackRef,
		u32	Mask
	)

This function registers the user callback handler for controller (non-endpoint) interrupts.

Parameters:

	InstancePtr	is a pointer to the XUsbPs instance of the controller.
	CallBackFunc	is the Callback function to register. CallBackFunc may be NULL to clear the entry.
	CallBackRef	is the user data reference passed to the callback function. CallBackRef may be NULL.
	Mask	is the User interrupt mask. Defines which interrupts will cause the callback to be called.

Returns:

XST_SUCCESS: Callback registered successfully.
XST_FAILURE: Callback could not be registered.

Note:: None.

XUsbPs_Config* XUsbPs_LookupConfig ( u16 DeviceID )

Looks up the controller configuration based on the unique controller ID. A table contains the configuration info for each controller in the system.

Parameters:

DeviceID

is the ID of the controller to look up the configuration for.

Returns:: A pointer to the configuration found or NULL if the specified controller ID was not found.

int XUsbPs_ReconfigureEp	(	XUsbPs *	InstancePtr,
		XUsbPs_DeviceConfig *	CfgPtr,
		int	EpNum,
		unsigned short	NewDirection,
		int	DirectionChanged
	)

This function reconfigures one Ep corresponding to host's request of setting alternate interface. The endpoint has been disabled before this call.

Both QH and dTDs are updated for the new configuration.

Parameters:

	InstancePtr	is a pointer to the XUsbPs instance of the controller.
	CfgPtr	Pointer to the updated XUsbPs DEVICE configuration structure.
	EpNum	The endpoint to be reconfigured.
	NewDirection	The new transfer direction the endpoint.
	DirectionChanged	A boolean value indicate whether the transfer direction has changed.

Returns:: XST_SUCCESS upon success, XST_FAILURE otherwise.

int XUsbPs_RequestHostResume ( const XUsbPs * InstancePtr )

USB Assert Resume

Parameters:

InstancePtr

is a pointer to XUsbPs instance of the controller.

Returns:

XST_SUCCESS if the USB device has Resumed successfully
XST_FAILURE on any error

Note:: None.

int XUsbPs_Reset ( XUsbPs * InstancePtr )

Common functions used for DEVICE/HOST mode.

This function resets the USB device. All the configuration registers are reset to their default values. The function waits until the reset operation is complete or for a certain duration within which the reset operation is expected to be completed.

Parameters:

InstancePtr

is a pointer to XUsbPs instance of the controller.

Returns:

XST_SUCCESS Reset operation completed successfully.
XST_FAILURE Reset operation timed out.

Note:: None.

int XUsbPs_Resume ( const XUsbPs * InstancePtr )

USB Resume

If the USB controller is suspended, its operation is resumed when any non-idle signaling is received on its upstream facing port.

Parameters:

InstancePtr

is a pointer to XUsbPs instance of the controller.

Returns:

XST_SUCCESS if the USB device has Resumed successfully
XST_FAILURE on any error

Note:: None.

int XUsbPs_SetDeviceAddress	(	XUsbPs *	InstancePtr,
		u8	Address
	)

This functions sets the controller's DEVICE address. It also sets the advance bit so the controller will wait for the next IN-ACK before the new address takes effect.

Parameters:

	InstancePtr	is a pointer to XUsbPs instance of the controller.
	Address	is the Address of the device.

Returns:

XST_SUCCESS: Address set successfully.
XST_FAILURE: An error occured.
XST_INVALID_PARAM: Invalid parameter passed, e.g. address value too big.

Note:: None.

int XUsbPs_Suspend ( const XUsbPs * InstancePtr )

Handling Suspend and Resume.

Implemented in xusbps.c

USB Suspend

In order to conserve power, USB devices automatically enter the suspended state when the device has observed no bus traffic for a specified period. When suspended, the USB device maintains any internal status, including its address and configuration. Attached devices must be prepared to suspend at any time they are powered, regardless of if they have been assigned a non-default address, are configured, or neither. Bus activity may cease due to the host entering a suspend mode of its own. In addition, a USB device shall also enter the suspended state when the hub port it is attached to is disabled.

A USB device exits suspend mode when there is bus activity. A USB device may also request the host to exit suspend mode or selective suspend by using electrical signaling to indicate remote wakeup. The ability of a device to signal remote wakeup is optional. If the USB device is capable of remote wakeup signaling, the device must support the ability of the host to enable and disable this capability. When the device is reset, remote wakeup signaling must be disabled.

Parameters:

InstancePtr

is a pointer to XUsbPs instance of the controller.

Returns:

XST_SUCCESS if the USB device has entered Suspend mode successfully
XST_FAILURE on any error

Note:: None.

Xilinx Processor IP Library

xusbps.h File Reference

Classes

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation