efm32_dma.h 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372
  1. /***************************************************************************//**
  2. * @file
  3. * @brief Direct memory access (DMA) API for EFM32.
  4. * @author Energy Micro AS
  5. * @version 1.3.0
  6. *******************************************************************************
  7. * @section License
  8. * <b>(C) Copyright 2010 Energy Micro AS, http://www.energymicro.com</b>
  9. *******************************************************************************
  10. *
  11. * This source code is the property of Energy Micro AS. The source and compiled
  12. * code may only be used on Energy Micro "EFM32" microcontrollers.
  13. *
  14. * This copyright notice may not be removed from the source code nor changed.
  15. *
  16. * DISCLAIMER OF WARRANTY/LIMITATION OF REMEDIES: Energy Micro AS has no
  17. * obligation to support this Software. Energy Micro AS is providing the
  18. * Software "AS IS", with no express or implied warranties of any kind,
  19. * including, but not limited to, any implied warranties of merchantability
  20. * or fitness for any particular purpose or warranties against infringement
  21. * of any proprietary rights of a third party.
  22. *
  23. * Energy Micro AS will not be liable for any consequential, incidental, or
  24. * special damages, or any other relief, or for any claim by any third party,
  25. * arising from your use of this Software.
  26. *
  27. ******************************************************************************/
  28. #ifndef __EFM32_DMA_H
  29. #define __EFM32_DMA_H
  30. #include <stdio.h>
  31. #include <stdbool.h>
  32. #include "efm32.h"
  33. #ifdef __cplusplus
  34. extern "C" {
  35. #endif
  36. /***************************************************************************//**
  37. * @addtogroup EFM32_Library
  38. * @{
  39. ******************************************************************************/
  40. /***************************************************************************//**
  41. * @addtogroup DMA
  42. * @{
  43. ******************************************************************************/
  44. /*******************************************************************************
  45. ******************************** ENUMS ************************************
  46. ******************************************************************************/
  47. /**
  48. * Amount source/destination address should be incremented for each data
  49. * transfer.
  50. */
  51. typedef enum
  52. {
  53. dmaDataInc1 = _DMA_CTRL_SRC_INC_BYTE, /**< Increment address 1 byte. */
  54. dmaDataInc2 = _DMA_CTRL_SRC_INC_HALFWORD, /**< Increment address 2 bytes. */
  55. dmaDataInc4 = _DMA_CTRL_SRC_INC_WORD, /**< Increment address 4 bytes. */
  56. dmaDataIncNone = _DMA_CTRL_SRC_INC_NONE /**< Do not increment address. */
  57. } DMA_DataInc_TypeDef;
  58. /** Data sizes (in number of bytes) to be read/written by DMA transfer. */
  59. typedef enum
  60. {
  61. dmaDataSize1 = _DMA_CTRL_SRC_SIZE_BYTE, /**< 1 byte DMA transfer size. */
  62. dmaDataSize2 = _DMA_CTRL_SRC_SIZE_HALFWORD, /**< 2 byte DMA transfer size. */
  63. dmaDataSize4 = _DMA_CTRL_SRC_SIZE_WORD /**< 4 byte DMA transfer size. */
  64. } DMA_DataSize_TypeDef;
  65. /** Type of DMA transfer. */
  66. typedef enum
  67. {
  68. /** Basic DMA cycle. */
  69. dmaCycleCtrlBasic = _DMA_CTRL_CYCLE_CTRL_BASIC,
  70. /** Auto-request DMA cycle. */
  71. dmaCycleCtrlAuto = _DMA_CTRL_CYCLE_CTRL_AUTO,
  72. /** Ping-pong DMA cycle. */
  73. dmaCycleCtrlPingPong = _DMA_CTRL_CYCLE_CTRL_PINGPONG,
  74. /** Memory scatter-gather DMA cycle. */
  75. dmaCycleCtrlMemScatterGather = _DMA_CTRL_CYCLE_CTRL_MEM_SCATTER_GATHER,
  76. /** Peripheral scatter-gather DMA cycle. */
  77. dmaCycleCtrlPerScatterGather = _DMA_CTRL_CYCLE_CTRL_PER_SCATTER_GATHER
  78. } DMA_CycleCtrl_TypeDef;
  79. /** Number of transfers before controller does new arbitration. */
  80. typedef enum
  81. {
  82. dmaArbitrate1 = _DMA_CTRL_R_POWER_1, /**< Arbitrate after 1 DMA transfer. */
  83. dmaArbitrate2 = _DMA_CTRL_R_POWER_2, /**< Arbitrate after 2 DMA transfers. */
  84. dmaArbitrate4 = _DMA_CTRL_R_POWER_4, /**< Arbitrate after 4 DMA transfers. */
  85. dmaArbitrate8 = _DMA_CTRL_R_POWER_8, /**< Arbitrate after 8 DMA transfers. */
  86. dmaArbitrate16 = _DMA_CTRL_R_POWER_16, /**< Arbitrate after 16 DMA transfers. */
  87. dmaArbitrate32 = _DMA_CTRL_R_POWER_32, /**< Arbitrate after 32 DMA transfers. */
  88. dmaArbitrate64 = _DMA_CTRL_R_POWER_64, /**< Arbitrate after 64 DMA transfers. */
  89. dmaArbitrate128 = _DMA_CTRL_R_POWER_128, /**< Arbitrate after 128 DMA transfers. */
  90. dmaArbitrate256 = _DMA_CTRL_R_POWER_256, /**< Arbitrate after 256 DMA transfers. */
  91. dmaArbitrate512 = _DMA_CTRL_R_POWER_512, /**< Arbitrate after 512 DMA transfers. */
  92. dmaArbitrate1024 = _DMA_CTRL_R_POWER_1024 /**< Arbitrate after 1024 DMA transfers. */
  93. } DMA_ArbiterConfig_TypeDef;
  94. /*******************************************************************************
  95. ******************************* STRUCTS ***********************************
  96. ******************************************************************************/
  97. /**
  98. * @brief
  99. * DMA interrupt callback function pointer.
  100. * @details
  101. * Parameters:
  102. * @li channel - The DMA channel the callback function is invoked for.
  103. * @li primary - Indicates if callback is invoked for completion of primary
  104. * (true) or alternate (false) descriptor. This is mainly useful for
  105. * ping-pong DMA cycles, in order to know which descriptor to refresh.
  106. * @li user - User definable reference that may be used to pass information
  107. * to be used by the callback handler. If used, the referenced data must be
  108. * valid at the point when the interrupt handler invokes the callback.
  109. * If callback changes any data in the provided user structure, remember
  110. * that those changes are done in interrupt context, and proper protection
  111. * of data may be required.
  112. */
  113. typedef void (*DMA_FuncPtr_TypeDef)(unsigned int channel, bool primary, void *user);
  114. /**
  115. * @brief
  116. * Callback structure that can be used to define DMA complete actions.
  117. * @details
  118. * A reference to this structure is only stored in the primary descriptor
  119. * for a channel (if callback feature is used). If callback is required
  120. * for both primary and alternate descriptor completion, this must be
  121. * handled by one common callback, using the provided 'primary' parameter
  122. * with the callback function.
  123. */
  124. typedef struct
  125. {
  126. /**
  127. * Pointer to callback function to invoke when DMA transfer cycle done.
  128. * Notice that this function is invoked in interrupt context, and therefore
  129. * should be short and non-blocking.
  130. */
  131. DMA_FuncPtr_TypeDef cbFunc;
  132. /** User defined pointer to provide with callback function. */
  133. void *userPtr;
  134. /**
  135. * For internal use only: Indicates if next callback applies to primary
  136. * or alternate descriptor completion. Mainly useful for ping-pong DMA
  137. * cycles. Set this value to 0 prior to configuring callback handling.
  138. */
  139. uint8_t primary;
  140. } DMA_CB_TypeDef;
  141. /** Configuration structure for a channel. */
  142. typedef struct
  143. {
  144. /**
  145. * Select if channel priority is in the high or default priority group
  146. * with respect to arbitration. Within a priority group, lower numbered
  147. * channels have higher priority than higher numbered channels.
  148. */
  149. bool highPri;
  150. /**
  151. * Select if interrupt shall be enabled for channel (triggering interrupt
  152. * handler when dma_done signal is asserted). It should normally be
  153. * enabled if using the callback feature for a channel, and disabled if
  154. * not using the callback feature.
  155. */
  156. bool enableInt;
  157. /**
  158. * Channel control specifying the source of DMA signals. If accessing
  159. * peripherals, use one of the DMAREQ_nnn defines available for the
  160. * peripheral. Set it to 0 for memory-to-memory DMA cycles.
  161. */
  162. uint32_t select;
  163. /**
  164. * @brief
  165. * User definable callback handling configuration.
  166. * @details
  167. * Please refer to structure definition for details. The callback
  168. * is invoked when the specified DMA cycle is complete (when dma_done
  169. * signal asserted). The callback is invoked in interrupt context,
  170. * and should be efficient and non-blocking. Set to NULL to not
  171. * use the callback feature.
  172. * @note
  173. * The referenced structure is used by the interrupt handler, and must
  174. * be available until no longer used. Thus, in most cases it should
  175. * not be located on the stack.
  176. */
  177. DMA_CB_TypeDef *cb;
  178. } DMA_CfgChannel_TypeDef;
  179. /**
  180. * Configuration structure for primary or alternate descriptor
  181. * (not used for scatter-gather DMA cycles).
  182. */
  183. typedef struct
  184. {
  185. /** Destination increment size for each DMA transfer */
  186. DMA_DataInc_TypeDef dstInc;
  187. /** Source increment size for each DMA transfer */
  188. DMA_DataInc_TypeDef srcInc;
  189. /** DMA transfer unit size. */
  190. DMA_DataSize_TypeDef size;
  191. /**
  192. * Arbitration rate, ie number of DMA transfers done before rearbitration
  193. * takes place.
  194. */
  195. DMA_ArbiterConfig_TypeDef arbRate;
  196. /**
  197. * HPROT signal state, please refer to reference manual, DMA chapter for
  198. * further details. Normally set to 0 if protection is not an issue.
  199. * The following bits are available:
  200. * @li bit 0 - HPROT[1] control for source read accesses,
  201. * privileged/non-privileged access
  202. * @li bit 3 - HPROT[1] control for destination write accesses,
  203. * privileged/non-privileged access
  204. */
  205. uint8_t hprot;
  206. } DMA_CfgDescr_TypeDef;
  207. /** Configuration structure for alternate scatter-gather descriptor. */
  208. typedef struct
  209. {
  210. /** Pointer to location to transfer data from. */
  211. void *src;
  212. /** Pointer to location to transfer data to. */
  213. void *dst;
  214. /** Destination increment size for each DMA transfer */
  215. DMA_DataInc_TypeDef dstInc;
  216. /** Source increment size for each DMA transfer */
  217. DMA_DataInc_TypeDef srcInc;
  218. /** DMA transfer unit size. */
  219. DMA_DataSize_TypeDef size;
  220. /**
  221. * Arbitration rate, ie number of DMA transfers done before rearbitration
  222. * takes place.
  223. */
  224. DMA_ArbiterConfig_TypeDef arbRate;
  225. /** Number of DMA transfers minus 1 to do. Must be <= 1023. */
  226. uint16_t nMinus1;
  227. /**
  228. * HPROT signal state, please refer to reference manual, DMA chapter for
  229. * further details. Normally set to 0 if protection is not an issue.
  230. * The following bits are available:
  231. * @li bit 0 - HPROT[1] control for source read accesses,
  232. * privileged/non-privileged access
  233. * @li bit 3 - HPROT[1] control for destination write accesses,
  234. * privileged/non-privileged access
  235. */
  236. uint8_t hprot;
  237. /** Specify if a memory or peripheral scatter-gather DMA cycle. Notice
  238. * that this parameter should be the same for all alternate
  239. * descriptors.
  240. * @li true - this is a peripheral scatter-gather cycle
  241. * @li false - this is a memory scatter-gather cycle
  242. */
  243. bool peripheral;
  244. } DMA_CfgDescrSGAlt_TypeDef;
  245. /** DMA init structure */
  246. typedef struct
  247. {
  248. /**
  249. * HPROT signal state when accessing the primary/alternate
  250. * descriptors. Normally set to 0 if protection is not an issue.
  251. * The following bits are available:
  252. * @li bit 0 - HPROT[1] control for descriptor accesses (ie when
  253. * the DMA controller accesses the channel control block itself),
  254. * privileged/non-privileged access
  255. */
  256. uint8_t hprot;
  257. /**
  258. * Pointer to the controlblock in memory holding descriptors (channel
  259. * control data structures). This memory must be properly aligned
  260. * according to requirements. Please refer to the reference manual,
  261. * DMA chapter for details.
  262. *
  263. * It is possible to provide a smaller memory block, only covering
  264. * those channels actually used, if not all available channels are used.
  265. * Ie, if only using 4 channels (0-3), both primary and alternate
  266. * structures, then only 16*2*4 = 128 bytes must be provided. This
  267. * implementation has however no check if later exceeding such a limit
  268. * by configuring for instance channel 4, in which case memory overwrite
  269. * of some other data will occur.
  270. */
  271. DMA_DESCRIPTOR_TypeDef *controlBlock;
  272. } DMA_Init_TypeDef;
  273. /*******************************************************************************
  274. ***************************** PROTOTYPES **********************************
  275. ******************************************************************************/
  276. void DMA_ActivateAuto(unsigned int channel,
  277. bool primary,
  278. void *dst,
  279. void *src,
  280. unsigned int nMinus1);
  281. void DMA_ActivateBasic(unsigned int channel,
  282. bool primary,
  283. bool useBurst,
  284. void *dst,
  285. void *src,
  286. unsigned int nMinus1);
  287. void DMA_ActivatePingPong(unsigned int channel,
  288. bool useBurst,
  289. void *primDst,
  290. void *primSrc,
  291. unsigned int primNMinus1,
  292. void *altDst,
  293. void *altSrc,
  294. unsigned int altNMinus1);
  295. void DMA_ActivateScatterGather(unsigned int channel,
  296. bool useBurst,
  297. DMA_DESCRIPTOR_TypeDef *altDescr,
  298. unsigned int count);
  299. void DMA_CfgChannel(unsigned int channel, DMA_CfgChannel_TypeDef *cfg);
  300. void DMA_CfgDescr(unsigned int channel,
  301. bool primary,
  302. DMA_CfgDescr_TypeDef *cfg);
  303. void DMA_CfgDescrScatterGather(DMA_DESCRIPTOR_TypeDef *descr,
  304. unsigned int indx,
  305. DMA_CfgDescrSGAlt_TypeDef *cfg);
  306. bool DMA_ChannelEnabled(unsigned int channel);
  307. void DMA_Init(DMA_Init_TypeDef *init);
  308. void DMA_IRQHandler(void);
  309. void DMA_RefreshPingPong(unsigned int channel,
  310. bool primary,
  311. bool useBurst,
  312. void *dst,
  313. void *src,
  314. unsigned int nMinus1,
  315. bool last);
  316. void DMA_Reset(void);
  317. /** @} (end addtogroup DMA) */
  318. /** @} (end addtogroup EFM32_Library) */
  319. #ifdef __cplusplus
  320. }
  321. #endif
  322. #endif /* __EFM32_DMA_H */