xbuf_descriptor.h

linux嵌入式系统的dma方式的实现代码

/* $Id: xbuf_descriptor.h,v 1.13 2006/06/02 21:43:44 meinelte Exp $ */
/******************************************************************************
*
*       XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS"
*       AS A COURTESY TO YOU, SOLELY FOR USE IN DEVELOPING PROGRAMS AND
*       SOLUTIONS FOR XILINX DEVICES.  BY PROVIDING THIS DESIGN, CODE,
*       OR INFORMATION AS ONE POSSIBLE IMPLEMENTATION OF THIS FEATURE,
*       APPLICATION OR STANDARD, XILINX IS MAKING NO REPRESENTATION
*       THAT THIS IMPLEMENTATION IS FREE FROM ANY CLAIMS OF INFRINGEMENT,
*       AND YOU ARE RESPONSIBLE FOR OBTAINING ANY RIGHTS YOU MAY REQUIRE
*       FOR YOUR IMPLEMENTATION.  XILINX EXPRESSLY DISCLAIMS ANY
*       WARRANTY WHATSOEVER WITH RESPECT TO THE ADEQUACY OF THE
*       IMPLEMENTATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OR
*       REPRESENTATIONS THAT THIS IMPLEMENTATION IS FREE FROM CLAIMS OF
*       INFRINGEMENT, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
*       FOR A PARTICULAR PURPOSE.
*
*       (c) Copyright 2001-2004 Xilinx Inc.
*       All rights reserved.
*
******************************************************************************/
/*****************************************************************************/
/**
*
* @file xbuf_descriptor.h
*
* <b>Description</b>
*
* This file contains the interface for the XBufDescriptor component.
* The XBufDescriptor component is a passive component that only maps over
* a buffer descriptor data structure shared by the scatter gather DMA hardware
* and software. The component's primary purpose is to provide encapsulation of
* the buffer descriptor processing.  See the source file xbuf_descriptor.c for
* details.
*
* @note
*
* Most of the functions of this component are implemented as macros in order
* to optimize the processing.  The names are not all uppercase such that they
* can be switched between macros and functions easily.
*
* <pre>
* MODIFICATION HISTORY:
*
* Ver   Who  Date     Changes
* ----- ---- -------- -----------------------------------------------
* 1.00a xd   10/27/04 Doxygenated for inclusion in API documentation
* 1.00b ecm  10/31/05 Updated for the check sum offload changes.
* </pre>
*
******************************************************************************/

#ifndef XBUF_DESCRIPTOR_H    /* prevent circular inclusions */
#define XBUF_DESCRIPTOR_H    /* by using protection macros */

#ifdef __cplusplus
extern "C" {
#endif

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

#include "xbasic_types.h"
#include "xdma_channel_i.h"

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

/** @name Buffer Descriptor fields
 *
 * @{
 */
/** This constant allows access to fields of a buffer descriptor
 * and is necessary at this level of visibility to allow macros to access
 * and modify the fields of a buffer descriptor.  It is not expected that the
 * user of a buffer descriptor would need to use this constant.
 */
#define XBD_DEVICE_STATUS_OFFSET    0
#define XBD_CONTROL_OFFSET          1
#define XBD_SOURCE_OFFSET           2
#define XBD_DESTINATION_OFFSET      3
#define XBD_LENGTH_OFFSET           4
#define XBD_STATUS_OFFSET           5
#define XBD_NEXT_PTR_OFFSET         6
#define XBD_ID_OFFSET               7
#define XBD_FLAGS_OFFSET            8
#define XBD_RQSTED_LENGTH_OFFSET    9
#define XBD_SIZE_IN_WORDS           10
/* @} */

/**
 * The following constants define the bits of the flags field of a buffer
 * descriptor
 */
#define XBD_FLAGS_LOCKED_MASK       1UL

/**************************** Type Definitions *******************************/

typedef Xuint32 XBufDescriptor[XBD_SIZE_IN_WORDS];

/***************** Macros (Inline Functions) Definitions *********************/

/**
 * each of the following macros are named the same as functions rather than all
 * upper case in order to allow either the macros or the functions to be
 * used, see the source file xbuf_descriptor.c for documentation
 */


/*****************************************************************************/
/**
*
* This function initializes a buffer descriptor component by zeroing all of the
* fields of the buffer descriptor.  This function should be called prior to
* using a buffer descriptor.
*
* @param
*
* InstancePtr points to the buffer descriptor to operate on.
*
* @return
*
* None.
*
* @note
*
* None.
*
******************************************************************************/
#define XBufDescriptor_Initialize(InstancePtr)                  \
{                                                               \
    (*((Xuint32 *)InstancePtr + XBD_CONTROL_OFFSET) = 0);       \
    (*((Xuint32 *)InstancePtr + XBD_SOURCE_OFFSET) = 0);        \
    (*((Xuint32 *)InstancePtr + XBD_DESTINATION_OFFSET) = 0);   \
    (*((Xuint32 *)InstancePtr + XBD_LENGTH_OFFSET) = 0);        \
    (*((Xuint32 *)InstancePtr + XBD_STATUS_OFFSET) = 0);        \
    (*((Xuint32 *)InstancePtr + XBD_DEVICE_STATUS_OFFSET) = 0); \
    (*((Xuint32 *)InstancePtr + XBD_NEXT_PTR_OFFSET) = 0);      \
    (*((Xuint32 *)InstancePtr + XBD_ID_OFFSET) = 0);            \
    (*((Xuint32 *)InstancePtr + XBD_FLAGS_OFFSET) = 0);         \
    (*((Xuint32 *)InstancePtr + XBD_RQSTED_LENGTH_OFFSET) = 0); \
}

/*****************************************************************************/
/**
*
* This function gets the control field of a buffer descriptor component.  The
* DMA channel hardware transfers the control field from the buffer descriptor
* into the DMA control register when a buffer descriptor is processed.  It
* controls the details of the DMA transfer.
*
* @param
*
* InstancePtr points to the buffer descriptor to operate on.
*
* @return
*
* The control field contents of the buffer descriptor. One or more of the
* following values may be contained the field.  Each of the values are
* unique bit masks.
*                               <br><br>
* - XDC_DMACR_SOURCE_INCR_MASK  Increment the source address
*                               <br><br>
* - XDC_DMACR_DEST_INCR_MASK    Increment the destination address
*                               <br><br>
* - XDC_DMACR_SOURCE_LOCAL_MASK Local source address
*                               <br><br>
* - XDC_DMACR_DEST_LOCAL_MASK   Local destination address
*                               <br><br>
* - XDC_DMACR_SG_ENABLE_MASK    Scatter gather enable
*                               <br><br>
* - XDC_DMACR_GEN_BD_INTR_MASK  Individual buffer descriptor interrupt
*                               <br><br>
* - XDC_DMACR_LAST_BD_MASK      Last buffer descriptor in a packet
*
* @note
*
* None.
*
******************************************************************************/
#define XBufDescriptor_GetControl(InstancePtr)   \
    (Xuint32)(*((Xuint32 *)InstancePtr + XBD_CONTROL_OFFSET))

/*****************************************************************************/
/**
*
* This function sets the control field of a buffer descriptor component.  The
* DMA channel hardware transfers the control field from the buffer descriptor
* into the DMA control register when a buffer descriptor is processed.  It
* controls the details of the DMA transfer such as
*
* @param
*
* InstancePtr points to the buffer descriptor to operate on.
*
* @param
*
* Control contains the value to be written to the control field of the buffer
* descriptor. One or more of the following values may be contained the field.
* Each of the values are unique bit masks such that they may be ORed together
* to enable multiple bits or inverted and ANDed to disable multiple bits.
* - XDC_DMACR_SOURCE_INCR_MASK  Increment the source address
* - XDC_DMACR_DEST_INCR_MASK    Increment the destination address
* - XDC_DMACR_SOURCE_LOCAL_MASK Local source address
* - XDC_DMACR_DEST_LOCAL_MASK   Local destination address
* - XDC_DMACR_SG_ENABLE_MASK    Scatter gather enable
* - XDC_DMACR_GEN_BD_INTR_MASK  Individual buffer descriptor interrupt
* - XDC_DMACR_LAST_BD_MASK      Last buffer descriptor in a packet
*
* @return
*
* None.
*
* @note
*
* None.
*
******************************************************************************/
#define XBufDescriptor_SetControl(InstancePtr, Control)  \
    (*((Xuint32 *)InstancePtr + XBD_CONTROL_OFFSET) = (Xuint32)Control)

/*****************************************************************************/
/**
*
* This function determines if this buffer descriptor is marked as being the
* last in the control field.  A packet may be broken up across multiple
* buffer descriptors such that the last buffer descriptor is the end of the
* packet.  The DMA channel hardware copies the control field from the buffer
* descriptor to the control register of the DMA channel when the buffer
* descriptor is processed.
*
* @param
*
* InstancePtr points to the buffer descriptor to operate on.
*
* @return
*
* XTRUE if the buffer descriptor is marked as last in the control field,
* otherwise, XFALSE.
*
* @note
*
* None.
*
******************************************************************************/
#define XBufDescriptor_IsLastControl(InstancePtr) \
    (Xboolean)((*((Xuint32 *)InstancePtr + XBD_CONTROL_OFFSET) & \
               XDC_CONTROL_LAST_BD_MASK) == XDC_CONTROL_LAST_BD_MASK)

/*****************************************************************************/
/**
*
* This function marks the buffer descriptor as being last in the control
* field of the buffer descriptor.  A packet may be broken up across multiple
* buffer descriptors such that the last buffer descriptor is the end of the
* packet.  The DMA channel hardware copies the control field from the buffer
* descriptor to the control register of the DMA channel when the buffer
* descriptor is processed.
*
* @param
*
* InstancePtr points to the buffer descriptor to operate on.
*
* @return
*
* None.
*
* @note
*
* None.
*
******************************************************************************/
#define XBufDescriptor_SetLast(InstancePtr) \
    (*((Xuint32 *)InstancePtr + XBD_CONTROL_OFFSET) |= XDC_CONTROL_LAST_BD_MASK)

/*****************************************************************************/
/**
*
* This function gets the source address field of the buffer descriptor.
* The source address indicates the address of memory which is the
* source of a DMA scatter gather operation.  The DMA channel hardware
* copies the source address from the buffer descriptor to the source
* address register of the DMA channel when the buffer descriptor is processed.
*
* @param
*
* InstancePtr points to the buffer descriptor to operate on.
*
* @return
*
* The source address field of the buffer descriptor.
*
* @note
*
* None.
*
******************************************************************************/
#define XBufDescriptor_GetSrcAddress(InstancePtr) \
    ((Xuint32 *)(*((Xuint32 *)InstancePtr + XBD_SOURCE_OFFSET)))

/*****************************************************************************/
/**
*
* This function sets the source address field of the buffer descriptor.
* The source address indicates the address of memory which is the
* source of a DMA scatter gather operation.  The DMA channel hardware
* copies the source address from the buffer descriptor to the source
* address register of the DMA channel when the buffer descriptor is processed.
*
* @param
*
* InstancePtr points to the buffer descriptor to operate on.
*
* @param
*
* SourceAddress contains the source address field for the buffer descriptor.
*
* @return
*
* None.
*
* @note
*
* None.
*
******************************************************************************/
#define XBufDescriptor_SetSrcAddress(InstancePtr, Source) \
    (*((Xuint32 *)InstancePtr + XBD_SOURCE_OFFSET) = (Xuint32)Source)

/*****************************************************************************/
/**
*
* This function gets the destination address field of the buffer descriptor.
* The destination address indicates the address of memory which is the
* destination of a DMA scatter gather operation.  The DMA channel hardware
* copies the destination address from the buffer descriptor to the destination
* address register of the DMA channel when the buffer descriptor is processed.
*
* @param
*
* InstancePtr points to the buffer descriptor to operate on.
*
* @return
*
* The destination address field of the buffer descriptor.
*
* @note
*
* None.
*
******************************************************************************/
#define XBufDescriptor_GetDestAddress(InstancePtr) \
    ((Xuint32 *)(*((Xuint32 *)InstancePtr + XBD_DESTINATION_OFFSET)))

/*****************************************************************************/
/**
*
* This function sets the destination address field of the buffer descriptor.
* The destination address indicates the address of memory which is the
* destination of a DMA scatter gather operation.  The DMA channel hardware
* copies the destination address from the buffer descriptor to the destination
* address register of the DMA channel when the buffer descriptor is processed.
*
* @param
*
* InstancePtr points to the buffer descriptor to operate on.
*
* @param