blob: 45c7527de9d63acc909965fc0cc73c88aa296634 [file] [log] [blame]
Wolfgang Denkba94a1b2006-05-30 15:56:48 +02001/**
2 * @file IxDmaAcc.h
3 *
4 * @date 15 October 2002
5 *
6 * @brief API of the IXP400 DMA Access Driver Component (IxDma)
7 *
8 *
9 * @par
10 * IXP400 SW Release version 2.0
11 *
12 * -- Copyright Notice --
13 *
14 * @par
15 * Copyright 2001-2005, Intel Corporation.
16 * All rights reserved.
17 *
18 * @par
19 * Redistribution and use in source and binary forms, with or without
20 * modification, are permitted provided that the following conditions
21 * are met:
22 * 1. Redistributions of source code must retain the above copyright
23 * notice, this list of conditions and the following disclaimer.
24 * 2. Redistributions in binary form must reproduce the above copyright
25 * notice, this list of conditions and the following disclaimer in the
26 * documentation and/or other materials provided with the distribution.
27 * 3. Neither the name of the Intel Corporation nor the names of its contributors
28 * may be used to endorse or promote products derived from this software
29 * without specific prior written permission.
30 *
31 * @par
32 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
33 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
34 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
35 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
36 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
37 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
38 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
39 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
40 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
41 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
42 * SUCH DAMAGE.
43 *
44 * @par
45 * -- End of Copyright Notice --
46 */
47
48/*---------------------------------------------------------------------
49 Doxygen group definitions
50 ---------------------------------------------------------------------*/
51
52#ifndef IXDMAACC_H
53#define IXDMAACC_H
54
55#include "IxOsal.h"
56#include "IxNpeDl.h"
57/**
58 * @defgroup IxDmaTypes IXP400 DMA Types (IxDmaTypes)
59 * @brief The common set of types used in the DMA component
60 * @{
61 */
62
63/**
64 * @ingroup IxDmaTypes
65 * @enum IxDmaReturnStatus
66 * @brief Dma return status definitions
67 */
68typedef enum
69{
70 IX_DMA_SUCCESS = IX_SUCCESS, /**< DMA Transfer Success */
71 IX_DMA_FAIL = IX_FAIL, /**< DMA Transfer Fail */
72 IX_DMA_INVALID_TRANSFER_WIDTH, /**< Invalid transfer width */
73 IX_DMA_INVALID_TRANSFER_LENGTH, /**< Invalid transfer length */
74 IX_DMA_INVALID_TRANSFER_MODE, /**< Invalid transfer mode */
75 IX_DMA_INVALID_ADDRESS_MODE, /**< Invalid address mode */
76 IX_DMA_REQUEST_FIFO_FULL /**< DMA request queue is full */
77} IxDmaReturnStatus;
78
79/**
80 * @ingroup IxDmaTypes
81 * @enum IxDmaTransferMode
82 * @brief Dma transfer mode definitions
83 * @note Copy and byte swap, and copy and reverse modes only support multiples of word data length.
84 */
85typedef enum
86{
87 IX_DMA_COPY_CLEAR = 0, /**< copy and clear source*/
88 IX_DMA_COPY, /**< copy */
89 IX_DMA_COPY_BYTE_SWAP, /**< copy and byte swap (endian) */
90 IX_DMA_COPY_REVERSE, /**< copy and reverse */
91 IX_DMA_TRANSFER_MODE_INVALID /**< Invalid transfer mode */
92} IxDmaTransferMode;
93
94/**
95 * @ingroup IxDmaTypes
96 * @enum IxDmaAddressingMode
97 * @brief Dma addressing mode definitions
98 * @note Fixed source address to fixed destination address addressing mode is not supported.
99 */
100typedef enum
101{
102 IX_DMA_INC_SRC_INC_DST = 0, /**< Incremental source address to incremental destination address */
103 IX_DMA_INC_SRC_FIX_DST, /**< Incremental source address to incremental destination address */
104 IX_DMA_FIX_SRC_INC_DST, /**< Incremental source address to incremental destination address */
105 IX_DMA_FIX_SRC_FIX_DST, /**< Incremental source address to incremental destination address */
106 IX_DMA_ADDRESSING_MODE_INVALID /**< Invalid Addressing Mode */
107} IxDmaAddressingMode;
108
109/**
110 * @ingroup IxDmaTypes
111 * @enum IxDmaTransferWidth
112 * @brief Dma transfer width definitions
113 * @Note Fixed addresses (either source or destination) do not support burst transfer width.
114 */
115typedef enum
116{
117 IX_DMA_32_SRC_32_DST = 0, /**< 32-bit src to 32-bit dst */
118 IX_DMA_32_SRC_16_DST, /**< 32-bit src to 16-bit dst */
119 IX_DMA_32_SRC_8_DST, /**< 32-bit src to 8-bit dst */
120 IX_DMA_16_SRC_32_DST, /**< 16-bit src to 32-bit dst */
121 IX_DMA_16_SRC_16_DST, /**< 16-bit src to 16-bit dst */
122 IX_DMA_16_SRC_8_DST, /**< 16-bit src to 8-bit dst */
123 IX_DMA_8_SRC_32_DST, /**< 8-bit src to 32-bit dst */
124 IX_DMA_8_SRC_16_DST, /**< 8-bit src to 16-bit dst */
125 IX_DMA_8_SRC_8_DST, /**< 8-bit src to 8-bit dst */
126 IX_DMA_8_SRC_BURST_DST, /**< 8-bit src to burst dst - Not supported for fixed destination address */
127 IX_DMA_16_SRC_BURST_DST, /**< 16-bit src to burst dst - Not supported for fixed destination address */
128 IX_DMA_32_SRC_BURST_DST, /**< 32-bit src to burst dst - Not supported for fixed destination address */
129 IX_DMA_BURST_SRC_8_DST, /**< burst src to 8-bit dst - Not supported for fixed source address */
130 IX_DMA_BURST_SRC_16_DST, /**< burst src to 16-bit dst - Not supported for fixed source address */
131 IX_DMA_BURST_SRC_32_DST, /**< burst src to 32-bit dst - Not supported for fixed source address*/
132 IX_DMA_BURST_SRC_BURST_DST, /**< burst src to burst dst - Not supported for fixed source and destination address
133*/
134 IX_DMA_TRANSFER_WIDTH_INVALID /**< Invalid transfer width */
135} IxDmaTransferWidth;
136
137/**
138 * @ingroup IxDmaTypes
139 * @enum IxDmaNpeId
140 * @brief NpeId numbers to identify NPE A, B or C
141 */
142typedef enum
143{
144 IX_DMA_NPEID_NPEA = 0, /**< Identifies NPE A */
145 IX_DMA_NPEID_NPEB, /**< Identifies NPE B */
146 IX_DMA_NPEID_NPEC, /**< Identifies NPE C */
147 IX_DMA_NPEID_MAX /**< Total Number of NPEs */
148} IxDmaNpeId;
149/* @} */
150/**
151 * @defgroup IxDmaAcc IXP400 DMA Access Driver (IxDmaAcc) API
152 *
153 * @brief The public API for the IXP400 IxDmaAcc component
154 *
155 * @{
156 */
157
158/**
159 * @ingroup IxDmaAcc
160 * @brief DMA Request Id type
161 */
162typedef UINT32 IxDmaAccRequestId;
163
164/**
165 * @ingroup IxDmaAcc
166 * @def IX_DMA_REQUEST_FULL
167 * @brief DMA request queue is full
168 * This constant is a return value used to tell the user that the IxDmaAcc
169 * queue is full.
170 *
171 */
172#define IX_DMA_REQUEST_FULL 16
173
174/**
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200175 * @ingroup IxDmaAcc
Wolfgang Denkba94a1b2006-05-30 15:56:48 +0200176 * @brief DMA completion notification
177 * This function is called to notify a client that the DMA has been completed
178 * @param status @ref IxDmaReturnStatus [out] - reporting to client
179 *
180 */
181typedef void (*IxDmaAccDmaCompleteCallback) (IxDmaReturnStatus status);
182
183/**
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200184 * @ingroup IxDmaAcc
Wolfgang Denkba94a1b2006-05-30 15:56:48 +0200185 *
186 * @fn ixDmaAccInit(IxNpeDlNpeId npeId)
187 *
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200188 * @brief Initialise the DMA Access component
Wolfgang Denkba94a1b2006-05-30 15:56:48 +0200189 * This function will initialise the DMA Access component internals
190 * @param npeId @ref IxNpeDlNpeId [in] - NPE to use for Dma Transfer
191 * @return @li IX_SUCCESS succesfully initialised the component
192 * @return @li IX_FAIL Initialisation failed for some unspecified
193 * internal reason.
194 */
195PUBLIC IX_STATUS
196ixDmaAccInit(IxNpeDlNpeId npeId);
197
198/**
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200199 * @ingroup IxDmaAcc
Wolfgang Denkba94a1b2006-05-30 15:56:48 +0200200 *
201 * @fn ixDmaAccDmaTransfer(
202 IxDmaAccDmaCompleteCallback callback,
203 UINT32 SourceAddr,
204 UINT32 DestinationAddr,
205 UINT16 TransferLength,
206 IxDmaTransferMode TransferMode,
207 IxDmaAddressingMode AddressingMode,
208 IxDmaTransferWidth TransferWidth)
209 *
210 * @brief Perform DMA transfer
211 * This function will perform DMA transfer between devices within the
212 * IXP400 memory map.
213 * @note The following are restrictions for IxDmaAccDmaTransfer:
214 * @li The function is non re-entrant.
215 * @li The function assumes host devices are operating in big-endian mode.
216 * @li Fixed address does not suport burst transfer width
217 * @li Fixed source address to fixed destinatiom address mode is not suported
218 * @li The incrementing source address for expansion bus will not support a burst transfer width and copy and clear mode
219 *
220 * @param callback @ref IxDmaAccDmaCompleteCallback [in] - function pointer to be stored and called when the DMA transfer is completed. This cannot be NULL.
221 * @param SourceAddr UINT32 [in] - Starting address of DMA source. Must be a valid IXP400 memory map address.
222 * @param DestinationAddr UINT32 [in] - Starting address of DMA destination. Must be a valid IXP400 memory map address.
223 * @param TransferLength UINT16 [in] - The size of DMA data transfer. The range must be from 1-64Kbyte
224 * @param TransferMode @ref IxDmaTransferMode [in] - The DMA transfer mode
225 * @param AddressingMode @ref IxDmaAddressingMode [in] - The DMA addressing mode
226 * @param TransferWidth @ref IxDmaTransferWidth [in] - The DMA transfer width
227 *
Wolfgang Denk53677ef2008-05-20 16:00:29 +0200228 * @return @li IX_DMA_SUCCESS Notification that the DMA request is succesful
229 * @return @li IX_DMA_FAIL IxDmaAcc not yet initialised or some internal error has occured
Wolfgang Denkba94a1b2006-05-30 15:56:48 +0200230 * @return @li IX_DMA_INVALID_TRANSFER_WIDTH Transfer width is nit valid
231 * @return @li IX_DMA_INVALID_TRANSFER_LENGTH Transfer length outside of valid range
232 * @return @li IX_DMA_INVALID_TRANSFER_MODE Transfer Mode not valid
233 * @return @li IX_DMA_REQUEST_FIFO_FULL IxDmaAcc request queue is full
234 */
235PUBLIC IxDmaReturnStatus
236ixDmaAccDmaTransfer(
237 IxDmaAccDmaCompleteCallback callback,
238 UINT32 SourceAddr,
239 UINT32 DestinationAddr,
240 UINT16 TransferLength,
241 IxDmaTransferMode TransferMode,
242 IxDmaAddressingMode AddressingMode,
243 IxDmaTransferWidth TransferWidth);
244/**
245 * @ingroup IxDmaAcc
246 *
247 * @fn ixDmaAccShow(void)
248 *
249 * @brief Display some component information for debug purposes
250 * Show some internal operation information relating to the DMA service.
251 * At a minimum the following will show.
252 * - the number of the DMA pend (in queue)
253 * @param None
254 * @return @li None
255 */
256PUBLIC IX_STATUS
257ixDmaAccShow(void);
258
259#endif /* IXDMAACC_H */
260