1 /** 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 */ 68 typedef 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 */ 85 typedef 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 */ 100 typedef 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 */ 115 typedef 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 */ 142 typedef 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 */ 162 typedef 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 /** 175 * @ingroup IxDmaAcc 176 * @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 */ 181 typedef void (*IxDmaAccDmaCompleteCallback) (IxDmaReturnStatus status); 182 183 /** 184 * @ingroup IxDmaAcc 185 * 186 * @fn ixDmaAccInit(IxNpeDlNpeId npeId) 187 * 188 * @brief Initialise the DMA Access component 189 * 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 */ 195 PUBLIC IX_STATUS 196 ixDmaAccInit(IxNpeDlNpeId npeId); 197 198 /** 199 * @ingroup IxDmaAcc 200 * 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 * 228 * @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 230 * @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 */ 235 PUBLIC IxDmaReturnStatus 236 ixDmaAccDmaTransfer( 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 */ 256 PUBLIC IX_STATUS 257 ixDmaAccShow(void); 258 259 #endif /* IXDMAACC_H */ 260 261