drivers/net/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  * SPDX-License-Identifier:     BSD-3-Clause
  20  * @par
  21  * -- End of Copyright Notice --
  22  */
  23
  24 /*---------------------------------------------------------------------
  25    Doxygen group definitions
  26   ---------------------------------------------------------------------*/
  27
  28 #ifndef IXDMAACC_H
  29 #define IXDMAACC_H
  30
  31 #include "IxOsal.h"
  32 #include "IxNpeDl.h"
  33 /**
  34  * @defgroup IxDmaTypes IXP400 DMA Types (IxDmaTypes)
  35  * @brief The common set of types used in the DMA component
  36  * @{
  37  */
  38
  39 /**
  40  * @ingroup IxDmaTypes
  41  * @enum IxDmaReturnStatus
  42  * @brief Dma return status definitions
  43  */
  44 typedef enum
  45 {
  46     IX_DMA_SUCCESS = IX_SUCCESS,  /**< DMA Transfer Success */
  47     IX_DMA_FAIL = IX_FAIL,        /**< DMA Transfer Fail */
  48     IX_DMA_INVALID_TRANSFER_WIDTH, /**< Invalid transfer width */
  49     IX_DMA_INVALID_TRANSFER_LENGTH, /**< Invalid transfer length */
  50     IX_DMA_INVALID_TRANSFER_MODE, /**< Invalid transfer mode */
  51     IX_DMA_INVALID_ADDRESS_MODE, /**< Invalid address mode */
  52     IX_DMA_REQUEST_FIFO_FULL  /**< DMA request queue is full */
  53 } IxDmaReturnStatus;
  54
  55 /**
  56  * @ingroup IxDmaTypes
  57  * @enum IxDmaTransferMode
  58  * @brief Dma transfer mode definitions
  59  * @note Copy and byte swap, and copy and reverse modes only support multiples of word data length.
  60  */
  61 typedef enum
  62 {
  63     IX_DMA_COPY_CLEAR = 0,      /**< copy and clear source*/
  64     IX_DMA_COPY,                /**< copy */
  65     IX_DMA_COPY_BYTE_SWAP,      /**< copy and byte swap (endian) */
  66     IX_DMA_COPY_REVERSE,        /**< copy and reverse */
  67     IX_DMA_TRANSFER_MODE_INVALID /**< Invalid transfer mode */
  68 } IxDmaTransferMode;
  69
  70 /**
  71  * @ingroup IxDmaTypes
  72  * @enum IxDmaAddressingMode
  73  * @brief Dma addressing mode definitions
  74  * @note Fixed source address to fixed destination address addressing mode is not supported.
  75  */
  76 typedef enum
  77 {
  78     IX_DMA_INC_SRC_INC_DST = 0, /**< Incremental source address to incremental destination address */
  79     IX_DMA_INC_SRC_FIX_DST,     /**< Incremental source address to incremental destination address */
  80     IX_DMA_FIX_SRC_INC_DST,     /**< Incremental source address to incremental destination address */
  81     IX_DMA_FIX_SRC_FIX_DST,     /**< Incremental source address to incremental destination address */
  82     IX_DMA_ADDRESSING_MODE_INVALID /**< Invalid Addressing Mode */
  83 } IxDmaAddressingMode;
  84
  85 /**
  86  * @ingroup IxDmaTypes
  87  * @enum IxDmaTransferWidth
  88  * @brief Dma transfer width definitions
  89  * @Note Fixed addresses (either source or destination) do not support burst transfer width.
  90  */
  91 typedef enum
  92 {
  93     IX_DMA_32_SRC_32_DST = 0,  /**< 32-bit src to 32-bit dst */
  94     IX_DMA_32_SRC_16_DST,      /**< 32-bit src to 16-bit dst */
  95     IX_DMA_32_SRC_8_DST,       /**< 32-bit src to 8-bit dst */
  96     IX_DMA_16_SRC_32_DST,      /**< 16-bit src to 32-bit dst */
  97     IX_DMA_16_SRC_16_DST,      /**< 16-bit src to 16-bit dst */
  98     IX_DMA_16_SRC_8_DST,       /**< 16-bit src to 8-bit dst */
  99     IX_DMA_8_SRC_32_DST,       /**< 8-bit src to 32-bit dst */
 100     IX_DMA_8_SRC_16_DST,       /**< 8-bit src to 16-bit dst */
 101     IX_DMA_8_SRC_8_DST,        /**< 8-bit src to 8-bit dst */
 102     IX_DMA_8_SRC_BURST_DST,    /**< 8-bit src to burst dst - Not supported for fixed destination address */
 103     IX_DMA_16_SRC_BURST_DST,   /**< 16-bit src to burst dst - Not supported for fixed destination address */
 104     IX_DMA_32_SRC_BURST_DST,   /**< 32-bit src to burst dst - Not supported for fixed destination address */
 105     IX_DMA_BURST_SRC_8_DST,    /**< burst src to 8-bit dst  - Not supported for fixed source address */
 106     IX_DMA_BURST_SRC_16_DST,   /**< burst src to 16-bit dst - Not supported for fixed source address */
 107     IX_DMA_BURST_SRC_32_DST,   /**< burst src to 32-bit dst - Not supported for fixed source address*/
 108     IX_DMA_BURST_SRC_BURST_DST, /**< burst src to burst dst  - Not supported for fixed source and destination address
 109 */
 110     IX_DMA_TRANSFER_WIDTH_INVALID /**< Invalid transfer width */
 111 } IxDmaTransferWidth;
 112
 113 /**
 114  * @ingroup IxDmaTypes
 115  * @enum IxDmaNpeId
 116  * @brief NpeId numbers to identify NPE A, B or C
 117  */
 118 typedef enum
 119 {
 120     IX_DMA_NPEID_NPEA = 0, /**< Identifies NPE A */
 121     IX_DMA_NPEID_NPEB,     /**< Identifies NPE B */
 122     IX_DMA_NPEID_NPEC,     /**< Identifies NPE C */
 123     IX_DMA_NPEID_MAX       /**< Total Number of NPEs */
 124 } IxDmaNpeId;
 125 /* @} */
 126 /**
 127  * @defgroup IxDmaAcc IXP400 DMA Access Driver (IxDmaAcc) API
 128  *
 129  * @brief The public API for the IXP400 IxDmaAcc component
 130  *
 131  * @{
 132  */
 133
 134 /**
 135  * @ingroup IxDmaAcc
 136  * @brief DMA Request Id type
 137  */
 138 typedef UINT32 IxDmaAccRequestId;
 139
 140 /**
 141  * @ingroup IxDmaAcc
 142  * @def IX_DMA_REQUEST_FULL
 143  * @brief DMA request queue is full
 144  * This constant is a return value used to tell the user that the IxDmaAcc
 145  * queue is full.
 146  *
 147  */
 148 #define IX_DMA_REQUEST_FULL 16
 149
 150 /**
 151  * @ingroup     IxDmaAcc
 152  * @brief       DMA completion notification
 153  * This function is called to notify a client that the DMA has been completed
 154  * @param status @ref IxDmaReturnStatus [out] - reporting to client
 155  *
 156  */
 157 typedef void (*IxDmaAccDmaCompleteCallback) (IxDmaReturnStatus status);
 158
 159 /**
 160  * @ingroup     IxDmaAcc
 161  *
 162  * @fn ixDmaAccInit(IxNpeDlNpeId npeId)
 163  *
 164  * @brief       Initialise the DMA Access component
 165  * This function will initialise the DMA Access component internals
 166  * @param npeId @ref IxNpeDlNpeId [in] - NPE to use for Dma Transfer
 167  * @return @li IX_SUCCESS succesfully initialised the component
 168  * @return @li IX_FAIL Initialisation failed for some unspecified
 169  * internal reason.
 170  */
 171 PUBLIC IX_STATUS
 172 ixDmaAccInit(IxNpeDlNpeId npeId);
 173
 174 /**
 175  * @ingroup     IxDmaAcc
 176  *
 177  * @fn ixDmaAccDmaTransfer(
 178     IxDmaAccDmaCompleteCallback callback,
 179     UINT32 SourceAddr,
 180     UINT32 DestinationAddr,
 181     UINT16 TransferLength,
 182     IxDmaTransferMode TransferMode,
 183     IxDmaAddressingMode AddressingMode,
 184     IxDmaTransferWidth TransferWidth)
 185  *
 186  * @brief       Perform DMA transfer
 187  * This function will perform DMA transfer between devices within the
 188  * IXP400 memory map.
 189  * @note The following are restrictions for IxDmaAccDmaTransfer:
 190  *      @li The function is non re-entrant.
 191  *      @li The function assumes host devices are operating in big-endian mode.
 192  *      @li Fixed address does not suport burst transfer width
 193  *      @li Fixed source address to fixed destinatiom address mode is not suported
 194  *      @li The incrementing source address for expansion bus will not support a burst transfer width and copy and clear mode
 195  *
 196  * @param callback @ref IxDmaAccDmaCompleteCallback [in] - function pointer to be stored and called when the DMA transfer is completed. This cannot be NULL.
 197  * @param SourceAddr UINT32 [in] -      Starting address of DMA source. Must be a valid IXP400 memory map address.
 198  * @param DestinationAddr UINT32 [in] - Starting address of DMA destination. Must be a valid IXP400 memory map address.
 199  * @param TransferLength UINT16 [in] - The size of DMA data transfer. The range must be from 1-64Kbyte
 200  * @param TransferMode @ref IxDmaTransferMode [in] - The DMA transfer mode
 201  * @param AddressingMode @ref IxDmaAddressingMode [in] - The DMA addressing mode
 202  * @param TransferWidth @ref IxDmaTransferWidth [in] - The DMA transfer width
 203  *
 204  * @return @li IX_DMA_SUCCESS   Notification that the DMA request is succesful
 205  * @return @li IX_DMA_FAIL      IxDmaAcc not yet initialised or some internal error has occured
 206  * @return @li IX_DMA_INVALID_TRANSFER_WIDTH Transfer width is nit valid
 207  * @return @li IX_DMA_INVALID_TRANSFER_LENGTH Transfer length outside of valid range
 208  * @return @li IX_DMA_INVALID_TRANSFER_MODE Transfer Mode not valid
 209  * @return @li IX_DMA_REQUEST_FIFO_FULL IxDmaAcc request queue is full
 210  */
 211 PUBLIC IxDmaReturnStatus
 212 ixDmaAccDmaTransfer(
 213     IxDmaAccDmaCompleteCallback callback,
 214     UINT32 SourceAddr,
 215     UINT32 DestinationAddr,
 216     UINT16 TransferLength,
 217     IxDmaTransferMode TransferMode,
 218     IxDmaAddressingMode AddressingMode,
 219     IxDmaTransferWidth TransferWidth);
 220 /**
 221  * @ingroup IxDmaAcc
 222  *
 223  * @fn ixDmaAccShow(void)
 224  *
 225  * @brief Display some component information for debug purposes
 226  * Show some internal operation information relating to the DMA service.
 227  * At a minimum the following will show.
 228  * - the number of the DMA pend (in queue)
 229  * @param None
 230  * @return @li None
 231  */
 232 PUBLIC IX_STATUS
 233 ixDmaAccShow(void);
 234
 235 #endif /* IXDMAACC_H */
 236