xdma_multi.h

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

/* $Id: xdma_multi.h,v 1.2 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 2003-2004 Xilinx Inc.
*       All rights reserved.
*
******************************************************************************/
/*****************************************************************************/
/**
*
* @file xdma_multi.h
*
* <b>Description</b>
*
* This file contains the multichannel DMA  implementation. This component
* supports a channelized DMA design in which each device can have it's own
* dedicated multichannel DMA, as opposed to a centralized DMA design.
* A device which uses DMA typically contains at least two channels of DMA,
* one for sending data and the other for receiving data.
*
* This component is designed to be used as a basic building block for
* designing a device driver. It provides register accesses such that all
* DMA processing can be maintained easier, but the device driver designer
* must still understand all the details of the multichannel DMA.
*
* The multichannel DMA allows a CPU to minimize the CPU interaction required
* to move data between a memory and a device.  The CPU requests the DMA hardware
* to perform a DMA operation and typically continues performing other
* processing until the DMA operation completes.  DMA could be considered a
* primitive form of multiprocessing such that caching and address translation
* can be an issue.
*
* <b>Scatter Gather Operations</b>
*
* The multichannel DMA may support scatter gather operations. A scatter gather
* operation automates the DMA operation such that multiple buffers can be
* sent or received with minimal software interaction with the hardware.  Buffer
* descriptors, contained in the XBufDescriptor component, are used by the
* scatter gather operations of the multichannel DMA to describe the buffers to be
* processed.
*
* <b>Scatter Gather List Operations</b>
*
* A scatter gather list may be supported by each channel of DMA.  The scatter
* gather list allows buffer descriptors to be put into the list by a device
* driver which requires scatter gather.  The hardware processes the buffer
* descriptors which are contained in the list and modifies the buffer
* descriptors to reflect the status of the DMA operations.  The device driver
* is notified by interrupt that specific DMA events occur including scatter
* gather events.  The device driver removes the completed buffer descriptors
* from the scatter gather list to evaluate the status of each DMA operation.
*
* The scatter gather list is created and buffer descriptors are inserted into
* the list.  Buffer descriptors are never removed from the list after it's
* creation such that a put operation copies from a temporary buffer descriptor
* to a buffer descriptor in the list.  Get operations don't copy from the list
* to a temporary, but return a pointer to the buffer descriptor in the list.
* A buffer descriptor in the list may be locked to prevent it from being
* overwritten by a put operation.  This allows the device driver to get a
* descriptor from a scatter gather list and prevent it from being overwritten
* until the buffer associated with the buffer descriptor has been processed.
*
* <b>Typical Scatter Gather Processing</b>
*
* The following steps illustrate the typical processing to use the
* scatter gather features of a multichannel DMA.
*
* 1. Create a scatter gather list for the each channel of DMA which puts empty
*    buffer descriptors into the list.<br>
* 2. Create buffer descriptors which describe the buffers to be filled with
*    receive data or the buffers which contain data to be sent.<br>
* 3. Put buffer descriptors into the multichannel DMA scatter list such that scatter
*    gather operations are requested.<br>
* 4. Commit the buffer descriptors in the list such that they are ready to be
*    used by the multichannel DMA hardware.<br>
* 5. Start the scatter gather operations of the multichannel DMA.<br>
* 6. Process any interrupts which occur as a result of the scatter gather
*    operations or poll the each channel of DMA to determine the status.
*
* <b>Interrupts</b>
*
* Each channel of the DMA has the ability to generate an interrupt.  This component
* does not perform processing for the interrupt as this processing is typically
* tightly coupled with the device which is using the multichannel DMA.  It is the
* responsibility of the caller of DMA functions to manage the interrupt
* including connecting to the interrupt and enabling/disabling the interrupt.
*
* <b>Critical Sections</b>
*
* It is the responsibility of the device driver designer to use critical
* sections as necessary when calling functions of the multichannel DMA.  This
* component does not protect critical sections and it does access registers using
* read-modify-write operations.  Calls to DMA functions from a main thread
* and from an interrupt context could produce unpredictable behavior such that
* the caller must provide the appropriate protection.
*
* <b>Address Translation</b>
*
* All addresses of data structures which are passed to DMA functions must
* be physical (real) addresses as opposed to logical (virtual) addresses.
*
* <b>Caching</b>
*
* The memory which is passed to the function which creates the scatter gather
* list must not be cached such that buffer descriptors are non-cached.  This
* is necessary because the buffer descriptors are kept in a ring buffer and
* not directly accessible to the caller of DMA functions.
*
* The caller of DMA functions is responsible for ensuring that any data
* buffers which are passed to the multichannel DMA are cache-line aligned if
* necessary.
*
* The caller of DMA functions is responsible for ensuring that any data
* buffers which are passed to the multichannel DMA have been flushed from the
* cache.
*
* The caller of DMA functions is responsible for ensuring that the cache is
* invalidated prior to using any data buffers which are the result of a DMA
* operation.
*
* <b>Memory Alignment</b>
*
* The addresses of data buffers which are passed to DMA functions must be
* 32 bit word aligned if the peripheral is on the OPB bus and must be
* 64-bit word aligned if the peripheral is on the PLB bus since the DMA
* hardware performs bus width word transfers. The alignment of the provided
* buffers is not checked by the driver.
*
* <b>Mutual Exclusion</b>
*
* The functions of the multichannel DMA are not thread safe such that the caller
* of all DMA functions is responsible for ensuring mutual exclusion for each
* channel of DMA.  Mutual exclusion across multiple instances of the
* multichannel DMAs is not necessary.
*
* <b>Asserts</b>
*
* Asserts are used within all Xilinx drivers to enforce constraints on argument
* values. Asserts can be turned off on a system-wide basis by defining, at compile
* time, the NDEBUG identifier.  By default, asserts are turned on and it is
* recommended that application developers leave asserts on during development.
*
* @note
*
* Many of the provided functions which are register accessors don't provide
* a lot of error detection. The caller is expected to understand the impact
* of a function call based upon the current state of the multichannel DMA.  This
* is done to minimize the overhead in this component.
* <br><br>
* In the following diagram, arrows are used to illustrate addresses or pointers
* such that this diagram is aimed for illustration purposes rather than a literal
* implementation.
* <br><br>
* The user memory block is passed in and used by the device driver. The user
* memory is partitioned into two parts with the 1st part being a table of
* addresses (indexed by the channel number) which contains the address of each
* channels registers.  The 2nd part of the memory is a table of structures
* (indexed by the channel number) which contains the scatter gather data for
* each channel.

* <pre>
* MODIFICATION HISTORY:
*
* Ver   Who  Date     Changes
* ----- ---- -------- -----------------------------------------------
* 1.00a ecm  09/16/03 First release
* 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>
*
* @internal
*
* Diagram of memory allocation and usage
*
*
*     XDmaMulti
*     Instance                                           DMA Hardware
*  -------------------                                   -----------
* |  BaseAddress      |-------------------------------->|           |
* |                   |            User Memory          |  device   |
* |-------------------|         -----------------       | registers |
* |  AddrTablePtr     |-----|  |                 |      |-----------|
* |                   |     |  |    Channel      |      |           |
* |-------------------|     |  |    Address      |      |  channel  |
* |  SgDataTablePtr   |---| |  |    Table        |  |-->|     0     |
* |                   |   | |  |   ----------    |  |   | registers |
*  -------------------    | |---->|channel 0 |------|   |-----------|
*                         |    |  | address  |   |      |           |
*                         |    |  |----------|   |      |  channel  |
*                         |    |  |channel 1 |--------->|     1     |
*                         |    |  | address  |   |      | registers |
*                         |    |   ----------    |       -----------
*                         |    |                 |
*                         |    |    Scatter      |
*                         |    |    Gather       |
*                         |    |    Data Table   |
*                         |    |   ----------    |
*                         |------>| sg data  |   |
*                              |  |channel 0 |   |
*                              |  |----------|   |
*                              |  | sg data  |   |
*                              |  |channel 1 |   |
*                              |   ----------    |
*                               -----------------
*
*******************************************************************************/

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

#ifdef __cplusplus
extern "C" {
#endif


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

#include "xdma_multi_i.h" /* constants shared with buffer descriptor */
#include "xbasic_types.h"
#include "xstatus.h"
#include "xbuf_descriptor.h"

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

#define XDM_CHANNEL_BASE_OFFSET        0x10000   /**< channel base offset */
#define XDM_CHANNEL_OFFSET      0x20  /**< interval spacing of DMA registers */

/** @name DMA Control Register bit fields
 *
 * The following constants provide access to the bit fields of the DMA control
 * register (DMACR).
 * @{
 */
#define XDM_DMACR_SOURCE_INCR_MASK  0x80000000UL /**< increment source address */
#define XDM_DMACR_DEST_INCR_MASK    0x40000000UL /**< increment dest address */
#define XDM_DMACR_SOURCE_LOCAL_MASK 0x20000000UL /**< local source address */
#define XDM_DMACR_DEST_LOCAL_MASK   0x10000000UL /**< local dest address */
#define XDM_DMACR_SG_STOP_MASK      0x08000000UL /**< scatter gather stop */
#define XDM_DMACR_LAST_BD_MASK      XDM_CONTROL_LAST_BD_MASK /**< last buffer
                                                                  descriptor  */
/* @} */

/** @name DMA Status Register bit fields
 *
 * The following constants provide access to the bit fields of the DMA status
 * register (DMASR).
 * @{
 */
#define XDM_DMASR_BUSY_MASK         0x80000000UL /**< Channel is busy */
#define XDM_DMASR_BUS_ERROR_MASK    0x40000000UL /**< Bus error occurred */
#define XDM_DMASR_BUS_TIMEOUT_MASK  0x20000000UL /**< Bus timeout occurred */
#define XDM_DMASR_LAST_BD_MASK      XDM_STATUS_LAST_BD_MASK /**< Last buffer
                                                                 descriptor  */