xusbps.h

自学ZedBoard：使用IP通过ARM PS访问FPGA（源代码）

/******************************************************************************
*
* (c) Copyright 2010-12 Xilinx, Inc. All rights reserved.
*
* This file contains confidential and proprietary information of Xilinx, Inc.
* and is protected under U.S. and international copyright and other
* intellectual property laws.
*
* DISCLAIMER
* This disclaimer is not a license and does not grant any rights to the
* materials distributed herewith. Except as otherwise provided in a valid
* license issued to you by Xilinx, and to the maximum extent permitted by
* applicable law: (1) THESE MATERIALS ARE MADE AVAILABLE "AS IS" AND WITH ALL
* FAULTS, AND XILINX HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS,
* IMPLIED, OR STATUTORY, INCLUDING BUT NOT LIMITED TO WARRANTIES OF
* MERCHANTABILITY, NON-INFRINGEMENT, OR FITNESS FOR ANY PARTICULAR PURPOSE;
* and (2) Xilinx shall not be liable (whether in contract or tort, including
* negligence, or under any other theory of liability) for any loss or damage
* of any kind or nature related to, arising under or in connection with these
* materials, including for any direct, or any indirect, special, incidental,
* or consequential loss or damage (including loss of data, profits, goodwill,
* or any type of loss or damage suffered as a result of any action brought by
* a third party) even if such damage or loss was reasonably foreseeable or
* Xilinx had been advised of the possibility of the same.
*
* CRITICAL APPLICATIONS
* Xilinx products are not designed or intended to be fail-safe, or for use in
* any application requiring fail-safe performance, such as life-support or
* safety devices or systems, Class III medical devices, nuclear facilities,
* applications related to the deployment of airbags, or any other applications
* that could lead to death, personal injury, or severe property or
* environmental damage (individually and collectively, "Critical
* Applications"). Customer assumes the sole risk and liability of any use of
* Xilinx products in Critical Applications, subject only to applicable laws
* and regulations governing limitations on product liability.
*
* THIS COPYRIGHT NOTICE AND DISCLAIMER MUST BE RETAINED AS PART OF THIS FILE
* AT ALL TIMES.
*
******************************************************************************/
/*****************************************************************************/
/**
 *
 * @file xusbps.h
 *
 * This file contains the implementation of the XUsbPs driver. It is the
 * driver for an USB controller in DEVICE or HOST mode.
 *
 * <h2>Introduction</h2>
 *
 * The Spartan-3AF Embedded Peripheral Block contains a USB controller for
 * communication with serial peripherals or hosts. The USB controller supports
 * Host, Device and On the Go (OTG) applications.
 *
 * <h2>USB Controller Features</h2>
 *
 * - Supports Low Speed USB 1.1 (1.5Mbps), Full Speed USB 1.1 (12Mbps), and
 *   High Speed USB 2.0 (480Mbps) data speeds
 * - Supports Device, Host and OTG operational modes
 * - ULPI transceiver interface for USB 2.0 operation
 * - Integrated USB Full and Low speed serial transceiver interfaces for lowest
 *   cost connections
 *
 * <h2>Initialization & Configuration</h2>
 *
 * The configuration of the USB driver happens in multiple stages:
 *
 * - (a) Configuration of the basic parameters:
 *   In this stage the basic parameters for the driver are configured,
 *   including the base address and the controller ID.
 *
 * - (b) Configuration of the DEVICE endpoints (if applicable):
 *   If DEVICE mode is desired, the endpoints of the controller need to be
 *   configured using the XUsbPs_DeviceConfig data structure. Once the
 *   endpoint configuration is set up in the data structure, the user needs to
 *   call XUsbPs_DeviceMemRequired() to obtain the required size of DMAable
 *   memory that the driver needs for operation with the given configuration.
 *   The user then needs to allocate the required amount of DMAable memory and
 *   finalize the configuration of the XUsbPs_DeviceConfig data structure,
 *   e.g. setting the DMAMemVirt and DMAMemPhys members.
 *
 * - (c) Configuration of the DEVICE modes:
 *   In the second stage the parameters for DEVICE are configured.
 *   The caller only needs to configure the modes that are
 *   actually used. Configuration is done with the:
 *   	XUsbPs_ConfigureDevice()
 * Configuration parameters are defined and passed
 *   into these functions using the:
 *      XUsbPs_DeviceConfig data structures.
 *
 *
 * <h2>USB Device Endpoints</h2>
 *
 * The USB core supports up to 4 endpoints. Each endpoint has two directions,
 * an OUT (RX) and an IN (TX) direction. Note that the direction is viewed from
 * the host's perspective. Endpoint 0 defaults to be the control endpoint and
 * does not need to be set up. Other endpoints need to be configured and set up
 * depending on the application. Only endpoints that are actuelly used by the
 * application need to be initialized.
 * See the example code (xusbps_intr_example.c) for more information.
 *
 *
 * <h2>Interrupt Handling</h2>
 *
 * The USB core uses one interrupt line to report interrupts to the CPU.
 * Interrupts are handled by the driver's interrupt handler function
 * XUsbPs_IntrHandler().
 * It has to be registered with the OS's interrupt subsystem. The driver's
 * interrupt handler divides incoming interrupts into two categories:
 *
 *  - General device interrupts
 *  - Endopint related interrupts
 *
 * The user (typically the adapter layer) can register general interrupt
 * handler fucntions and endpoint specific interrupt handler functions with the
 * driver to receive those interrupts by calling the
 *    XUsbPs_IntrSetHandler()
 * and
 *    XUsbPs_EpSetHandler()
 * functions respectively. Calling these functions with a NULL pointer as the
 * argument for the function pointer will "clear" the handler function.
 *
 * The user can register one handler function for the generic interrupts and
 * two handler functions for each endpoint, one for the RX (OUT) and one for
 * the TX (IN) direction. For some applications it may be useful to register a
 * single endpoint handler function for muliple endpoints/directions.
 *
 * When a callback function is called by the driver, parameters identifying the
 * type of the interrupt will be passed into the handler functions. For general
 * interrupts the interrupt mask will be passed into the handler function. For
 * endpoint interrupts the parameters include the number of the endpoint, the
 * direction (OUT/IN) and the type of the interrupt.
 *
 *
 * <h2>Data buffer handling</h2>
 *
 * Data buffers are sent to and received from endpoint using the
 *    XUsbPs_EpBufferSend()
 * and
 *    XUsbPs_EpBufferReceive()
 * functions.
 *
 * User data buffer size is limited to 16 Kbytes. If the user wants to send a
 * data buffer that is bigger than this limit it needs to break down the data
 * buffer into multiple fragments and send the fragments individually.
 *
 * Data buffers can be aligned at any boundary.
 *
 *
 * <h3>Zero copy</h3>
 *
 * The driver uses a zero copy mechanism which imposes certain restrictions to
 * the way the user can handle the data buffers.
 *
 * One restriction is that the user needs to release a buffer after it is done
 * processing the data in the buffer.
 *
 * Similarly, when the user sends a data buffer it MUST not re-use the buffer
 * until it is notified by the driver that the buffer has been transmitted. The
 * driver will notify the user via the registered endpoint interrupt handling
 * function by sending a XUSBPS_EP_EVENT_DATA_TX event.
 *
 *
 * <h2>DMA</h2>
 *
 * The driver uses DMA internally to move data from/to memory. This behaviour
 * is transparent to the user. Keeping the DMA handling hidden from the user
 * has the advantage that the same API can be used with USB cores that do not
 * support DMA.
 *
 *
 * <pre>
 * MODIFICATION HISTORY:
 *
 * Ver   Who  Date     Changes
 * ----- ---- -------- ----------------------------------------------------------
 * 1.00a wgr  10/10/10 First release
 * 1.02a wgr  05/16/12 Removed comments as they are showing up in SDK
 *		       Tabs for CR 657898
 * </pre>
 *
 ******************************************************************************/

#ifndef XUSBPS_H
#define XUSBPS_H

#ifdef __cplusplus
extern "C" {
#endif

/***************************** Include Files *********************************/

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

/************************** Constant Definitions *****************************/

/**
 * @name 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


/**
 * @name 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 /**< Endpoint direction IN. */
#define XUSBPS_EP_DIRECTION_OUT		0x02 /**< Endpoint direction OUT. */
/* @} */


/**
 * @name Endpoint Type
 * Definitions to be used with Endpoint related functions that require a 'Type'
 * parameter.
 * @{
 */
#define XUSBPS_EP_TYPE_NONE		0 /**< Endpoint is not used. */
#define XUSBPS_EP_TYPE_CONTROL		1 /**< Endpoint for Control Transfers */
#define XUSBPS_EP_TYPE_ISOCHRONOUS 	2 /**< Endpoint for isochronous data */
#define XUSBPS_EP_TYPE_BULK		3 /**< Endpoint for BULK Transfers. */
#define XUSBPS_EP_TYPE_INTERRUPT	4 /**< Endpoint for interrupt Transfers */
/* @} */

/**
 * Endpoint Max Packet Length in DeviceConfig is a coded value, ch9.6.6.
 *
 * @{
 */
#define ENDPOINT_MAXP_LENGTH_MASK	0x7FF
#define ENDPOINT_MAXP_MULT_MASK		0x1800
#define ENDPOINT_MAXP_MULT_SHIFT	11
/* @} */

/**
 * @name Field names for status retrieval
 * Definitions for the XUsbPs_GetStatus() function call 'StatusType'
 * parameter.
 * @{
 */
#define XUSBPS_EP_STS_ADDRESS		1 /**< Address of controller. */
#define XUSBPS_EP_STS_CONTROLLER_STATE	2 /**< Current controller state. */
/* @} */



/**
 * @name USB Default alternate setting
 *
 * @{
 */
#define XUSBPS_DEFAULT_ALT_SETTING	0 /**< The default alternate setting is 0 */
/* @} */

/**
 * @name 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
			/**< Setup data has been received on the enpoint. */
#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. */
/* @} */


/*
 * Maximum packet size for endpoint, 1024
 * @{
 */
#define XUSBPS_MAX_PACKET_SIZE		1024
				/**< Maximum value can be put into the queue head */
/* @} */
/**************************** Type Definitions *******************************/

/******************************************************************************
 * This data type defines the callback function to be used for Endpoint
 * handlers.
 *
 * @param	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.
 * @param	EpNum is the Number of the endpoint that caused the event.
 * @param	EventType is the type of the event that occured on the endpoint.
 * @param	Data is a pointer to user data pointer specified when callback
 *		was registered.
 */
typedef void (*XUsbPs_EpHandlerFunc)(void *CallBackRef,
				      u8 EpNum, u8 EventType, void *Data);


/******************************************************************************
 * This data type defines the callback function to be used for the general
 * interrupt handler.
 *
 * @param	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.
 * @param	IrqMask is the Content of the interrupt status register. This
 *		value can be used by the callback function to distinguish the
 *		individual interrupt types.
 */
typedef void (*XUsbPs_IntrHandlerFunc)(void *CallBackRef, u32 IrqMask);


/******************************************************************************/

/* The following type definitions are used for referencing Queue Heads and
 * Transfer Descriptors. The structures themselves are not used, however, the
 * types are used in the API to avoid using (void *) pointers.
 */
typedef u8	XUsbPs_dQH[XUSBPS_dQH_ALIGN];
typedef u8	XUsbPs_dTD[XUSBPS_dTD_ALIGN];


/**
 * The following data structures are used internally by the L0/L1 driver.
 * Their contents MUST NOT be changed by the upper layers.
 */

/**
 * The following data structure represents OUT endpoint.
 */
typedef struct {
	XUsbPs_dQH	*dQH;
		/**< Pointer to the Queue Head structure of the endpoint. */

	XUsbPs_dTD	*dTDs;
		/**< Pointer to the first dTD of the dTD list for this
		 * endpoint. */