cpu/ixp/npe/include/IxDmaAcc.h

   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