IxDmaAcc.h 8.3 KB

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