source: SVN/rincon/u-boot/board/xilinx/common/xdma_channel.h @ 55

Last change on this file since 55 was 55, checked in by Tim Harvey, 22 months ago

rincon: added latest u-boot source

restored form server backup

Signed-off-by: Tim Harvey <tharvey@…>

File size: 13.1 KB
Line 
1/******************************************************************************
2*
3*     Author: Xilinx, Inc.
4*
5*
6*     This program is free software; you can redistribute it and/or modify it
7*     under the terms of the GNU General Public License as published by the
8*     Free Software Foundation; either version 2 of the License, or (at your
9*     option) any later version.
10*
11*
12*     XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS" AS A
13*     COURTESY TO YOU. BY PROVIDING THIS DESIGN, CODE, OR INFORMATION AS
14*     ONE POSSIBLE IMPLEMENTATION OF THIS FEATURE, APPLICATION OR STANDARD,
15*     XILINX IS MAKING NO REPRESENTATION THAT THIS IMPLEMENTATION IS FREE
16*     FROM ANY CLAIMS OF INFRINGEMENT, AND YOU ARE RESPONSIBLE FOR OBTAINING
17*     ANY THIRD PARTY RIGHTS YOU MAY REQUIRE FOR YOUR IMPLEMENTATION.
18*     XILINX EXPRESSLY DISCLAIMS ANY WARRANTY WHATSOEVER WITH RESPECT TO
19*     THE ADEQUACY OF THE IMPLEMENTATION, INCLUDING BUT NOT LIMITED TO ANY
20*     WARRANTIES OR REPRESENTATIONS THAT THIS IMPLEMENTATION IS FREE FROM
21*     CLAIMS OF INFRINGEMENT, IMPLIED WARRANTIES OF MERCHANTABILITY AND
22*     FITNESS FOR A PARTICULAR PURPOSE.
23*
24*
25*     Xilinx hardware products are not intended for use in life support
26*     appliances, devices, or systems. Use in such applications is
27*     expressly prohibited.
28*
29*
30*     (c) Copyright 2002-2004 Xilinx Inc.
31*     All rights reserved.
32*
33*
34*     You should have received a copy of the GNU General Public License along
35*     with this program; if not, write to the Free Software Foundation, Inc.,
36*     675 Mass Ave, Cambridge, MA 02139, USA.
37*
38* FILENAME:
39*
40* xdma_channel.h
41*
42* DESCRIPTION:
43*
44* This file contains the DMA channel component implementation. This component
45* supports a distributed DMA design in which each device can have it's own
46* dedicated DMA channel, as opposed to a centralized DMA design.
47* A device which uses DMA typically contains two DMA channels, one for
48* sending data and the other for receiving data.
49*
50* This component is designed to be used as a basic building block for
51* designing a device driver. It provides registers accesses such that all
52* DMA processing can be maintained easier, but the device driver designer
53* must still understand all the details of the DMA channel.
54*
55* The DMA channel allows a CPU to minimize the CPU interaction required to move
56* data between a memory and a device.  The CPU requests the DMA channel to
57* perform a DMA operation and typically continues performing other processing
58* until the DMA operation completes.  DMA could be considered a primitive form
59* of multiprocessing such that caching and address translation can be an issue.
60*
61* Scatter Gather Operations
62*
63* The DMA channel may support scatter gather operations. A scatter gather
64* operation automates the DMA channel such that multiple buffers can be
65* sent or received with minimal software interaction with the hardware.  Buffer
66* descriptors, contained in the XBufDescriptor component, are used by the
67* scatter gather operations of the DMA channel to describe the buffers to be
68* processed.
69*
70* Scatter Gather List Operations
71*
72* A scatter gather list may be supported by each DMA channel.  The scatter
73* gather list allows buffer descriptors to be put into the list by a device
74* driver which requires scatter gather.  The hardware processes the buffer
75* descriptors which are contained in the list and modifies the buffer
76* descriptors to reflect the status of the DMA operations.  The device driver
77* is notified by interrupt that specific DMA events occur including scatter
78* gather events.  The device driver removes the completed buffer descriptors
79* from the scatter gather list to evaluate the status of each DMA operation.
80*
81* The scatter gather list is created and buffer descriptors are inserted into
82* the list.  Buffer descriptors are never removed from the list after it's
83* creation such that a put operation copies from a temporary buffer descriptor
84* to a buffer descriptor in the list.  Get operations don't copy from the list
85* to a temporary, but return a pointer to the buffer descriptor in the list.
86* A buffer descriptor in the list may be locked to prevent it from being
87* overwritten by a put operation.  This allows the device driver to get a
88* descriptor from a scatter gather list and prevent it from being overwritten
89* until the buffer associated with the buffer descriptor has been processed.
90*
91* Typical Scatter Gather Processing
92*
93* The following steps illustrate the typical processing to use the
94* scatter gather features of a DMA channel.
95*
96* 1. Create a scatter gather list for the DMA channel which puts empty buffer
97*    descriptors into the list.
98* 2. Create buffer descriptors which describe the buffers to be filled with
99*        receive data or the buffers which contain data to be sent.
100* 3. Put buffer descriptors into the DMA channel scatter list such that scatter
101*    gather operations are requested.
102* 4. Commit the buffer descriptors in the list such that they are ready to be
103*    used by the DMA channel hardware.
104* 5. Start the scatter gather operations of the DMA channel.
105* 6. Process any interrupts which occur as a result of the scatter gather
106*    operations or poll the DMA channel to determine the status.
107*
108* Interrupts
109*
110* Each DMA channel has the ability to generate an interrupt.  This component
111* does not perform processing for the interrupt as this processing is typically
112* tightly coupled with the device which is using the DMA channel.  It is the
113* responsibility of the caller of DMA functions to manage the interrupt
114* including connecting to the interrupt and enabling/disabling the interrupt.
115*
116* Critical Sections
117*
118* It is the responsibility of the device driver designer to use critical
119* sections as necessary when calling functions of the DMA channel.  This
120* component does not use critical sections and it does access registers using
121* read-modify-write operations.  Calls to DMA functions from a main thread
122* and from an interrupt context could produce unpredictable behavior such that
123* the caller must provide the appropriate critical sections.
124*
125* Address Translation
126*
127* All addresses of data structures which are passed to DMA functions must
128* be physical (real) addresses as opposed to logical (virtual) addresses.
129*
130* Caching
131*
132* The memory which is passed to the function which creates the scatter gather
133* list must not be cached such that buffer descriptors are non-cached.  This
134* is necessary because the buffer descriptors are kept in a ring buffer and
135* not directly accessible to the caller of DMA functions.
136*
137* The caller of DMA functions is responsible for ensuring that any data
138* buffers which are passed to the DMA channel are cache-line aligned if
139* necessary.
140*
141* The caller of DMA functions is responsible for ensuring that any data
142* buffers which are passed to the DMA channel have been flushed from the cache.
143*
144* The caller of DMA functions is responsible for ensuring that the cache is
145* invalidated prior to using any data buffers which are the result of a DMA
146* operation.
147*
148* Memory Alignment
149*
150* The addresses of data buffers which are passed to DMA functions must be
151* 32 bit word aligned since the DMA hardware performs 32 bit word transfers.
152*
153* Mutual Exclusion
154*
155* The functions of the DMA channel are not thread safe such that the caller
156* of all DMA functions is responsible for ensuring mutual exclusion for a
157* DMA channel.  Mutual exclusion across multiple DMA channels is not
158* necessary.
159*
160* NOTES:
161*
162* Many of the provided functions which are register accessors don't provide
163* a lot of error detection. The caller is expected to understand the impact
164* of a function call based upon the current state of the DMA channel.  This
165* is done to minimize the overhead in this component.
166*
167******************************************************************************/
168
169#ifndef XDMA_CHANNEL_H          /* prevent circular inclusions */
170#define XDMA_CHANNEL_H          /* by using protection macros */
171
172/***************************** Include Files *********************************/
173
174#include "xdma_channel_i.h"     /* constants shared with buffer descriptor */
175#include "xbasic_types.h"
176#include "xstatus.h"
177#include "xversion.h"
178#include "xbuf_descriptor.h"
179
180/************************** Constant Definitions *****************************/
181
182/* the following constants provide access to the bit fields of the DMA control
183 * register (DMACR)
184 */
185#define XDC_DMACR_SOURCE_INCR_MASK      0x80000000UL    /* increment source address */
186#define XDC_DMACR_DEST_INCR_MASK        0x40000000UL    /* increment dest address */
187#define XDC_DMACR_SOURCE_LOCAL_MASK 0x20000000UL        /* local source address */
188#define XDC_DMACR_DEST_LOCAL_MASK       0x10000000UL    /* local dest address */
189#define XDC_DMACR_SG_DISABLE_MASK       0x08000000UL    /* scatter gather disable */
190#define XDC_DMACR_GEN_BD_INTR_MASK      0x04000000UL    /* descriptor interrupt */
191#define XDC_DMACR_LAST_BD_MASK          XDC_CONTROL_LAST_BD_MASK        /* last buffer */
192                                                                                                                         /*     descriptor  */
193
194/* the following constants provide access to the bit fields of the DMA status
195 * register (DMASR)
196 */
197#define XDC_DMASR_BUSY_MASK                     0x80000000UL    /* channel is busy */
198#define XDC_DMASR_BUS_ERROR_MASK        0x40000000UL    /* bus error occurred */
199#define XDC_DMASR_BUS_TIMEOUT_MASK      0x20000000UL    /* bus timeout occurred */
200#define XDC_DMASR_LAST_BD_MASK          XDC_STATUS_LAST_BD_MASK /* last buffer */
201                                                                                                                    /* descriptor  */
202#define XDC_DMASR_SG_BUSY_MASK          0x08000000UL    /* scatter gather is busy */
203
204/* the following constants provide access to the bit fields of the interrupt
205 * status register (ISR) and the interrupt enable register (IER), bit masks
206 * match for both registers such that they are named IXR
207 */
208#define XDC_IXR_DMA_DONE_MASK           0x1UL   /* dma operation done */
209#define XDC_IXR_DMA_ERROR_MASK      0x2UL       /* dma operation error */
210#define XDC_IXR_PKT_DONE_MASK       0x4UL       /* packet done */
211#define XDC_IXR_PKT_THRESHOLD_MASK      0x8UL   /* packet count threshold */
212#define XDC_IXR_PKT_WAIT_BOUND_MASK 0x10UL      /* packet wait bound reached */
213#define XDC_IXR_SG_DISABLE_ACK_MASK 0x20UL      /* scatter gather disable
214                                                   acknowledge occurred */
215#define XDC_IXR_SG_END_MASK                     0x40UL  /* last buffer descriptor
216                                                           disabled scatter gather */
217#define XDC_IXR_BD_MASK                         0x80UL  /* buffer descriptor done */
218
219/**************************** Type Definitions *******************************/
220
221/*
222 * the following structure contains data which is on a per instance basis
223 * for the XDmaChannel component
224 */
225typedef struct XDmaChannelTag {
226        XVersion Version;       /* version of the driver */
227        u32 RegBaseAddress;     /* base address of registers */
228        u32 IsReady;            /* device is initialized and ready */
229
230        XBufDescriptor *PutPtr; /* keep track of where to put into list */
231        XBufDescriptor *GetPtr; /* keep track of where to get from list */
232        XBufDescriptor *CommitPtr;      /* keep track of where to commit in list */
233        XBufDescriptor *LastPtr;        /* keep track of the last put in the list */
234        u32 TotalDescriptorCount;       /* total # of descriptors in the list */
235        u32 ActiveDescriptorCount;      /* # of descriptors pointing to buffers
236                                           * in the buffer descriptor list */
237} XDmaChannel;
238
239/***************** Macros (Inline Functions) Definitions *********************/
240
241/************************** Function Prototypes ******************************/
242
243XStatus XDmaChannel_Initialize(XDmaChannel * InstancePtr, u32 BaseAddress);
244u32 XDmaChannel_IsReady(XDmaChannel * InstancePtr);
245XVersion *XDmaChannel_GetVersion(XDmaChannel * InstancePtr);
246XStatus XDmaChannel_SelfTest(XDmaChannel * InstancePtr);
247void XDmaChannel_Reset(XDmaChannel * InstancePtr);
248
249/* Control functions */
250
251u32 XDmaChannel_GetControl(XDmaChannel * InstancePtr);
252void XDmaChannel_SetControl(XDmaChannel * InstancePtr, u32 Control);
253
254/* Status functions */
255
256u32 XDmaChannel_GetStatus(XDmaChannel * InstancePtr);
257void XDmaChannel_SetIntrStatus(XDmaChannel * InstancePtr, u32 Status);
258u32 XDmaChannel_GetIntrStatus(XDmaChannel * InstancePtr);
259void XDmaChannel_SetIntrEnable(XDmaChannel * InstancePtr, u32 Enable);
260u32 XDmaChannel_GetIntrEnable(XDmaChannel * InstancePtr);
261
262/* DMA without scatter gather functions */
263
264void XDmaChannel_Transfer(XDmaChannel * InstancePtr,
265                          u32 * SourcePtr, u32 * DestinationPtr, u32 ByteCount);
266
267/* Scatter gather functions */
268
269XStatus XDmaChannel_SgStart(XDmaChannel * InstancePtr);
270XStatus XDmaChannel_SgStop(XDmaChannel * InstancePtr,
271                           XBufDescriptor ** BufDescriptorPtr);
272XStatus XDmaChannel_CreateSgList(XDmaChannel * InstancePtr,
273                                 u32 * MemoryPtr, u32 ByteCount);
274u32 XDmaChannel_IsSgListEmpty(XDmaChannel * InstancePtr);
275
276XStatus XDmaChannel_PutDescriptor(XDmaChannel * InstancePtr,
277                                  XBufDescriptor * BufDescriptorPtr);
278XStatus XDmaChannel_CommitPuts(XDmaChannel * InstancePtr);
279XStatus XDmaChannel_GetDescriptor(XDmaChannel * InstancePtr,
280                                  XBufDescriptor ** BufDescriptorPtr);
281
282/* Packet functions for interrupt collescing */
283
284u32 XDmaChannel_GetPktCount(XDmaChannel * InstancePtr);
285void XDmaChannel_DecrementPktCount(XDmaChannel * InstancePtr);
286XStatus XDmaChannel_SetPktThreshold(XDmaChannel * InstancePtr, u8 Threshold);
287u8 XDmaChannel_GetPktThreshold(XDmaChannel * InstancePtr);
288void XDmaChannel_SetPktWaitBound(XDmaChannel * InstancePtr, u32 WaitBound);
289u32 XDmaChannel_GetPktWaitBound(XDmaChannel * InstancePtr);
290
291#endif                          /* end of protection macro */
Note: See TracBrowser for help on using the repository browser.