xusb.h File Reference

#include "xusb_l.h"
#include "xstatus.h"

Classes
struct	XUsb_EpConfig
struct	XUsb_DeviceConfig
struct	XUsb_Config
struct	XUsb
Defines
Endpoint Direction
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 device is used for sending data while the OUT endpoint on the device is used for receiving data.
#define	XUSB_EP_DIRECTION_IN 1
#define	XUSB_EP_DIRECTION_OUT 0
Speed
Definitions to be used with speed.
#define	XUSB_EP_HIGH_SPEED 1
#define	XUSB_EP_FULL_SPEED 0
USB device specific global configuration constants.

#define	XUSB_MAX_ENDPOINTS 8
#define	XUSB_EP_NUMBER_ZERO 0
#define	XUSB_DEVICEADDR_MAX 127
USB device disconnect state

#define	XUSB_DISCONNECTED 0x1
#define	XUSB_RESET 0x0
Test Modes (Set Feature)

#define	TEST_J 1
#define	TEST_K 2
#define	TEST_SE0_NAK 3
#define	TEST_PKT 4
Typedefs
typedef void(*	XUsb_EpHandlerFunc )(void *CallBackRef, u8 EpNum, u32 EventType)
typedef void(*	XUsb_IntrHandlerFunc )(void *CallBackRef, u32 InterruptType)
Functions
int	XUsb_CfgInitialize (XUsb InstancePtr, XUsb_Config ConfigPtr, u32 EffectiveAddr)
int	XUsb_ConfigureDevice (XUsb InstancePtr, XUsb_DeviceConfig CfgPtr)
void	XUsb_Start (XUsb *InstancePtr)
void	XUsb_Stop (XUsb *InstancePtr)
u32	XUsb_GetFrameNum (const XUsb *InstancePtr)
int	XUsb_SetDeviceAddress (XUsb *InstancePtr, u8 Address)
void	XUsb_SetTestMode (XUsb InstancePtr, u8 TestMode, u8 BufPtr)
void	XUsb_DmaReset (XUsb *InstancePtr)
void	XUsb_DmaTransfer (XUsb InstancePtr, u32 SrcAddr, u32 *DstAddr, u16 Length)
void	XUsb_ReadErrorCounters (XUsb InstancePtr, u8 BitStuffErrors, u8 PidErrors, u8 CrcErrors)
u8	XUsb_UlpiPhyReadRegister (XUsb *InstancePtr, u8 RegAddr)
int	XUsb_UlpiPhyWriteRegister (XUsb *InstancePtr, u8 RegAddr, u8 UlpiPhyRegData)
void	XUsb_SieReset (XUsb *InstancePtr)
void	XUsb_EpEnable (const XUsb *InstancePtr, u8 EpNum)
void	XUsb_EpDisable (const XUsb *InstancePtr, u8 EpNum)
void	XUsb_EpConfigure (XUsb InstancePtr, u8 EpNum, XUsb_EpConfig EpCfgPtr)
int	XUsb_EpDataSend (XUsb InstancePtr, u8 EpNum, u8 BufferPtr, u32 BufferLen)
int	XUsb_EpDataRecv (XUsb InstancePtr, u8 EpNum, u8 BufferPtr, u32 BufferLen)
void	XUsb_EpStall (const XUsb *InstancePtr, u8 EpNum)
void	XUsb_EpUnstall (const XUsb *InstancePtr, u8 EpNum)
void	XUsb_EpIsoTransferConfigure (XUsb *InstancePtr, u8 EpNum, u8 NoOfTransfers)
void	XUsb_IntrEnable (XUsb *InstancePtr, u32 IntrMask)
void	XUsb_IntrDisable (XUsb *InstancePtr, u32 IntrMask)
void	XUsb_IntrHandler (void *InstancePtr)
void	XUsb_IntrSetHandler (XUsb InstancePtr, void CallBackFunc, void *CallBackRef)
void	XUsb_EpSetHandler (XUsb InstancePtr, u8 EpNum, XUsb_EpHandlerFunc CallBackFunc, void *CallBackRef)
void	XUsb_ErrIntrSetHandler (XUsb InstancePtr, void CallBackFunc, void *CallBackRef)
void	XUsb_DmaIntrSetHandler (XUsb InstancePtr, void CallBackFunc, void *CallBackRef)
void	XUsb_UlpiIntrSetHandler (XUsb InstancePtr, void CallBackFunc, void *CallBackRef)
XUsb_Config *	XUsb_LookupConfig (u16 DeviceId)

Detailed Description

Define Documentation

#define TEST_J 1

Chirp J Test

#define TEST_K 2

Chirp K Test

#define TEST_PKT 4

Packet Test

#define TEST_SE0_NAK 3

Chirp SE0 Test

#define XUSB_DEVICEADDR_MAX 127

Max device address

#define XUSB_DISCONNECTED 0x1

Disconnected state

#define XUSB_EP_DIRECTION_IN 1

Endpoint direction IN.

#define XUSB_EP_DIRECTION_OUT 0

Endpoint direction OUT.

#define XUSB_EP_FULL_SPEED 0

Full Speed

#define XUSB_EP_HIGH_SPEED 1

High Speed

#define XUSB_EP_NUMBER_ZERO 0

End point Zero

#define XUSB_MAX_ENDPOINTS 8

Maximum End Points

#define XUSB_RESET 0x0

Reset State

Typedef Documentation

typedef void(* XUsb_EpHandlerFunc)(void *CallBackRef, u8 EpNum, u32 EventType)

This data type defines the callback function to be used for Endpoint handlers.

Parameters:

	CallBackRef	is the Callback reference passed in by the upper layer when setting the handler, and is passed back to the upper layer when the handler is called.
	EpNum	is the endpoint that caused the event.
	EventType	is the type of the event that occurred on that endpoint.

typedef void(* XUsb_IntrHandlerFunc)(void *CallBackRef, u32 InterruptType)

This data type defines the callback function to be used for the general interrupt handler.

Parameters:

	CallBackRef	is the Callback reference passed in by the upper layer when setting the handler, and is passed back to the upper layer when the handler is called.
	InterruptType	is the type of the event that caused the interrupt.

Function Documentation

int XUsb_CfgInitialize	(	XUsb *	InstancePtr,
		XUsb_Config *	ConfigPtr,
		u32	EffectiveAddr
	)

Setup / Initialize and DMA functions

Implemented in the file xusb.c

This function initializes a XUsb instance/driver.

The initialization entails:

Initialize all members of the XUsb structure.

Parameters:

	InstancePtr	is a pointer to the XUsb instance of the USB device.
	ConfigPtr	is a pointer to a XUsb_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 XUsb.
	EffectiveAddr	is the device base address in the virtual memory address space. If the address translation is not used then the physical address is passed. Unexpected errors may occur if the address mapping is changed after this function is invoked.

Returns:

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

Note:: After calling XUsb_CfgInitialize() the USB device IS NOT READY for use. Before the USB device can be used its parameters must be configured. See xusb.h for details.

int XUsb_ConfigureDevice	(	XUsb *	InstancePtr,
		XUsb_DeviceConfig *	CfgPtr
	)

This function initializes USB End points.

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	CfgPtr	is pointer to a XUsb_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 XUsb.

Returns:

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

Note:: None.

void XUsb_DmaIntrSetHandler	(	XUsb *	InstancePtr,
		void *	CallBackFunc,
		void *	CallBackRef
	)

This function installs an asynchronous callback function for the DMA events.

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	CallBackFunc	is the address of the callback function.
	CallBackRef	is a user data item that will be passed to the callback function when it is invoked.

Returns:: None.

Note:: Invoking this function for a handler that already has been installed replaces it with the new handler. The user can disable a handler by setting the callback function pointer to NULL.

void XUsb_DmaReset ( XUsb * InstancePtr )

This function resets the DMA module of the USB device

Parameters:

InstancePtr

is a pointer to the XUsb instance.

Returns:: None.

Note:: After the DMA reset, only the DMA related logic part of the USB device will be reset and all the DMA related registers will be reset to the default values. Upon DMA Reset, any DMA transfer in progress will be stopped.

void XUsb_DmaTransfer	(	XUsb *	InstancePtr,
		u32 *	SrcAddr,
		u32 *	DstAddr,
		u16	Length
	)

This function sets the DMA registers with the given values to initiate a DMA data transfer. This function is called by the XUsb_EpDataSend and XUsb_EpDataRecv functions.

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	SrcAddr	is the source address from where the data is to be read.
	DstAddr	is the destination address to where the data is to be written.
	Length	is the amount of data that can be transferred. The maximum data transfer can be 1024.

Returns:: None.

Note:: This function doesn't guarantee that the transfer is done successfully. This function only initiates the DMA transfer.

void XUsb_EpConfigure	(	XUsb *	InstancePtr,
		u8	EpNum,
		XUsb_EpConfig *	EpCfgPtr
	)

This function configures a specific end point with the given configuration data.

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	EpNum	is the endpoint number which has to be configured.
	EpCfgPtr	is a pointer to the endpoint configuration structure.

Returns:: None.

Note:: None.

int XUsb_EpDataRecv	(	XUsb *	InstancePtr,
		u8	EpNum,
		u8 *	BufferPtr,
		u32	BufferLen
	)

This function copies the received data from end point buffer to the buffer passed and then makes the device ready for receiving data again into the same end point buffer.

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	EpNum	is the endpoint number.
	BufferPtr	is a pointer to buffer where data is to be copied.
	BufferLen	is the number of data bytes to be received.

Returns:

XST_SUCCESS if successful.
XST_FAILURE if there is no received data in any of the ping pong buffers.

Note:: None

int XUsb_EpDataSend	(	XUsb *	InstancePtr,
		u8	EpNum,
		u8 *	BufferPtr,
		u32	BufferLen
	)

This function copies the transmit data to the end point buffer and enables the buffer for transmission.

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	EpNum	is the endpoint number.
	BufferPtr	is a pointer to buffer containing the data to be sent.
	BufferLen	is the number of data bytes to be sent.

Returns:

XST_SUCCESS if successful.
XST_FAILURE if the send operation could not be performed due to non availability of the ping pong buffers in the DPRAM.

Note:: Success doesn't imply that the data is actually transmitted, it only confirms that the DPRAM buffer is updated with send data and the core is enabled for transmitting the data.

void XUsb_EpDisable	(	const XUsb *	InstancePtr,
		u8	EpNum
	)

This function disables the specified endpoint for all operations.

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	EpNum	is the endpoint number which has to be disabled for operations.

Returns:: None.

Note:: None.

void XUsb_EpEnable	(	const XUsb *	InstancePtr,
		u8	EpNum
	)

This function enables the specified endpoint for all operations.

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	EpNum	is the endpoint number which has to be enabled for operations.

Returns:: None.

Note:: None.

void XUsb_EpIsoTransferConfigure	(	XUsb *	InstancePtr,
		u8	EpNum,
		u8	NoOfTransfers
	)

This function sets the number of isochronous transfers in a microframe for a given endpoint.

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	EpNum	is the endpoint number.
	NoOfTransfers	is the number of transfers in a microframe.

Returns:: None

Note:: The values allowed for number of transfers is 1, 2 and 3. This function should be called after all the endpoints are configured. The allowed value for EpNum is 1 to 7

void XUsb_EpSetHandler	(	XUsb *	InstancePtr,
		u8	EpNum,
		XUsb_EpHandlerFunc *	CallBackFunc,
		void *	CallBackRef
	)

This function sets the handler for endpoint events.

Parameters:

	InstancePtr	is a Pointer to the XUsb instance.
	EpNum	is the Number of the endpoint.
	CallBackFunc	is the address of the callback function. It can be NULL if the user wants to disable the handler entry.
	CallBackRef	is a user data item that will be passed to the callback function when it is invoked. This can be NULL.

Returns:: None.

Note:: Invoking this function for a handler that already has been installed replaces it with the new handler. The user can disable a handler by setting the callback function pointer to NULL.

void XUsb_EpStall	(	const XUsb *	InstancePtr,
		u8	EpNum
	)

This function stalls operations for the specified endpoint.

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	EpNum	is the endpoint number which has to be stalled for operations.

Returns:: None.

Note:: This function does not guaranty the Stall operation, it only sets the Stall bit in the Endpoint configuration register.

void XUsb_EpUnstall	(	const XUsb *	InstancePtr,
		u8	EpNum
	)

This function unstalls operations for the specified endpoint.

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	EpNum	is the endpoint number for which the unstall operations are to be carried out.

Returns:: None.

Note:: This function does not guaranty the Stall operation, it only sets the Stall bit in the Endpoint configuration register.

void XUsb_ErrIntrSetHandler	(	XUsb *	InstancePtr,
		void *	CallBackFunc,
		void *	CallBackRef
	)

This function installs an asynchronous callback function for the error events.

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	CallBackFunc	is the address of the callback function.
	CallBackRef	is a user data item that will be passed to the callback function when it is invoked.

Returns:: None.

Note:: Invoking this function for a handler that already has been installed replaces it with the new handler. The user can disable a handler by setting the callback function pointer to NULL.

u32 XUsb_GetFrameNum ( const XUsb * InstancePtr )

This function returns the current frame number.

Parameters:

InstancePtr

is a pointer to the XUsb instance.

Returns:: The current frame number..

Note:: None.

void XUsb_IntrDisable	(	XUsb *	InstancePtr,
		u32	Mask
	)

This function disables the specified interrupts.

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	Mask	is the bit-mask of the interrupts to be disabled. Bit positions of 1 will be enabled. Bit positions of 0 will keep the previous setting. This mask is formed by OR'ing XUSB_STATUS_*_MASK bits defined in xusb_l.h.

Returns:: None.

Note:: None.

void XUsb_IntrEnable	(	XUsb *	InstancePtr,
		u32	Mask
	)

This function enables the specified interrupts.

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	Mask	is the bit-mask of the interrupts to be enabled. Bit positions of 1 will be enabled. Bit positions of 0 will keep the previous setting. This mask is formed by OR'ing XUSB_STATUS_*_MASK bits defined in xusb_l.h.

Returns:: None.

Note:: None.

void XUsb_IntrHandler ( void * InstancePtr )

This function is the interrupt handler for the USB driver. 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 XUsb_IntrSetHandler() and/or XUsb_EpSetHandler() functions.

This handler reads the interrupt status from the Interrupt Status Register, determines the source of the interrupts, calls the corresponding callbacks and finally clears the interrupts.

The interrupt from the USB driver has to be connected to the interrupt controller and the handler has to be registered with the interrupt system.

Applications using this driver are responsible for providing the callbacks to handle interrupts and installing the callbacks using XUsb_SetHandler() during the initialization phase.

Parameters:

InstancePtr

is a pointer to the XUsb instance that just interrupted.

Returns:: None.

Note:: No user handler is defined for the DMA interrupts. The DMA interrupt status is updated in the DMA status variables defined under the USB driver instance.

void XUsb_IntrSetHandler	(	XUsb *	InstancePtr,
		void *	CallBackFunc,
		void *	CallBackRef
	)

This function installs an asynchronous callback function for the general interrupt (interrupts other than the endpoint and error interrupts).

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	CallBackFunc	is the address of the callback function.
	CallBackRef	is a user data item that will be passed to the callback function when it is invoked.

Returns:: None.

Note:: Invoking this function for a handler that already has been installed replaces it with the new handler. The user can disable a handler by setting the callback function pointer to NULL.

XUsb_Config* XUsb_LookupConfig ( u16 DeviceId )

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

Parameters:

DeviceId

contains the ID of the device for which the device configuration pointer is to be returned.

Returns:

A pointer to the configuration found.
NULL if the specified device ID was not found.

void XUsb_ReadErrorCounters	(	XUsb *	InstancePtr,
		u8 *	BitStuffErrors,
		u8 *	PidErrors,
		u8 *	CrcErrors
	)

This function reads the USB error counter regsiter and returns the error counters information.

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	BitStuffErrors	is a pointer to the 8 bit bitstuff error counter.
	PidErrors	is a pointer to the 8 bit pid error counter.
	CrcErrors	is a pointer to the 8 bit crc error counter.

Returns:: None.

Note:: None.

int XUsb_SetDeviceAddress	(	XUsb *	InstancePtr,
		u8	Address
	)

This function sets the USB device address.

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	Address	is the device address to be set.

Returns:

XST_SUCCESS: Address set successfully.
XST_INVALID_PARAM: Invalid parameter passed.

Note:: None.

void XUsb_SetTestMode	(	XUsb *	InstancePtr,
		u8	TestMode,
		u8 *	BufPtr
	)

This function sets the USB device into a given test mode.

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	TestMode	is the type of test to be performed.
	BufPtr	is a pointer to the buffer containing the test packet.

Returns:: None.

Note:: If the test mode is Test packet(TEST_PKT), then user needs to pass the address of the buffer containing the test packet. In other cases, the BufPtr parameter is not used and the user can send a NULL or any value. BufPtr parameter should be 32 bit aligned.

void XUsb_SieReset ( XUsb * InstancePtr )

This function resets the Serial Interface Engine

Parameters:

InstancePtr

is a pointer to the XUsb instance.

Returns:: None.

Note:: After the SIE reset, only the SIE state machine logic part of the USB device will be reset and starts from Init state.

void XUsb_Start ( XUsb * InstancePtr )

This function starts the USB Device.

Parameters:

InstancePtr

is a pointer to the XUsb instance.

Returns:: None.

Note:: None.

void XUsb_Stop ( XUsb * InstancePtr )

This function stops the USB device.

Parameters:

InstancePtr

is a pointer to the XUsb instance.

Returns:: None.

Note:: None.

void XUsb_UlpiIntrSetHandler	(	XUsb *	InstancePtr,
		void *	CallBackFunc,
		void *	CallBackRef
	)

This function installs an asynchronous callback function for the ULPI PHY events.

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	CallBackFunc	is the address of the callback function.
	CallBackRef	is a user data item that will be passed to the callback function when it is invoked.

Returns:: None.

Note:: Invoking this function for a handler that already has been installed replaces it with the new handler. The user can disable a handler by setting the callback function pointer to NULL.

u8 XUsb_UlpiPhyReadRegister	(	XUsb *	InstancePtr,
		u8	RegAddr
	)

This function initiates the USB ULPI PHY regsiter read transaction. This function returns the busy status if the earlier transaction is still in progress and returns the PHY register data upon successful read transaction.

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	RegAddr	is the address of the PHY register.

Returns:

Register data
XST_DEVICE_BUSY: The previous PHY transaction is still in progress.

Note:: This function waits till the BUSY bit is cleared in the ULPI PHY resgiter and then reads the register. The user of this API should note that the PHY interrupt should be ignored during read operation.

int XUsb_UlpiPhyWriteRegister	(	XUsb *	InstancePtr,
		u8	RegAddr,
		u8	UlpiPhyRegData
	)

This function initiates the USB ULPI PHY regsiter write transaction. This function returns the busy status if the earlier transaction is still in progress and returns a success upon successful write transaction initiation.

Parameters:

	InstancePtr	is a pointer to the XUsb instance.
	RegAddr	is the address of the PHY register. counter.
	UlpiPhyRegData	is the data to be written to PHY register.

Returns:

XST_SUCCESS: Read transaction initiated successfully.
XST_DEVICE_BUSY: The previous PHY transaction is still in progress.

Note:: None.

Xilinx Processor IP Library

xusb.h File Reference

Classes

Defines

Typedefs

Functions

Detailed Description

Define Documentation

Typedef Documentation

Function Documentation