edma_driver.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2013 - 2016, Freescale Semiconductor, Inc.
3  * Copyright 2016 - 2018 NXP
4  * All rights reserved.
5  *
6  * THIS SOFTWARE IS PROVIDED BY NXP "AS IS" AND ANY EXPRESSED OR
7  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
8  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
9  * IN NO EVENT SHALL NXP OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
10  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
11  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
12  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
13  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
14  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
15  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
16  * THE POSSIBILITY OF SUCH DAMAGE.
17  */
18 
35 #if !defined(EDMA_DRIVER_H)
36 #define EDMA_DRIVER_H
37 
38 #include "device_registers.h"
39 #include "status.h"
40 #include <stddef.h>
41 
47 /*******************************************************************************
48  * Definitions
49  ******************************************************************************/
50 
59 #define STCD_SIZE(number) (((number) * 32U) - 1U)
60 #define STCD_ADDR(address) (((uint32_t)address + 31UL) & ~0x1FUL)
61 
68 #define EDMA_ERR_LSB_MASK 1U
69 
73 typedef enum {
78 
82 typedef enum {
86 
90 typedef enum {
95 #ifndef FEATURE_DMA_4_CH_PRIORITIES
96  EDMA_CHN_PRIORITY_4 = 4U,
97  EDMA_CHN_PRIORITY_5 = 5U,
98  EDMA_CHN_PRIORITY_6 = 6U,
99  EDMA_CHN_PRIORITY_7 = 7U,
100 #ifndef FEATURE_DMA_8_CH_PRIORITIES
101  EDMA_CHN_PRIORITY_8 = 8U,
102  EDMA_CHN_PRIORITY_9 = 9U,
103  EDMA_CHN_PRIORITY_10 = 10U,
104  EDMA_CHN_PRIORITY_11 = 11U,
105  EDMA_CHN_PRIORITY_12 = 12U,
106  EDMA_CHN_PRIORITY_13 = 13U,
107  EDMA_CHN_PRIORITY_14 = 14U,
108  EDMA_CHN_PRIORITY_15 = 15U,
109 #endif
110 #endif
113 
114 #if FEATURE_DMA_CHANNEL_GROUP_COUNT > 0x1U
115 
118 typedef enum {
119 #ifdef FEATURE_DMA_HWV3
120  EDMA_CHN_GROUP_0 = 0U,
121  EDMA_CHN_GROUP_1 = 1U,
122  EDMA_CHN_GROUP_2 = 2U,
123  EDMA_CHN_GROUP_3 = 3U,
124  EDMA_CHN_GROUP_4 = 4U,
125  EDMA_CHN_GROUP_5 = 5U,
126  EDMA_CHN_GROUP_6 = 6U,
127  EDMA_CHN_GROUP_7 = 7U,
128  EDMA_CHN_GROUP_8 = 8U,
129  EDMA_CHN_GROUP_9 = 9U,
130  EDMA_CHN_GROUP_10 = 10U,
131  EDMA_CHN_GROUP_11 = 11U,
132  EDMA_CHN_GROUP_12 = 12U,
133  EDMA_CHN_GROUP_13 = 13U,
134  EDMA_CHN_GROUP_14 = 14U,
135  EDMA_CHN_GROUP_15 = 15U,
136  EDMA_CHN_GROUP_16 = 16U,
137  EDMA_CHN_GROUP_17 = 17U,
138  EDMA_CHN_GROUP_18 = 18U,
139  EDMA_CHN_GROUP_19 = 19U,
140  EDMA_CHN_GROUP_20 = 20U,
141  EDMA_CHN_GROUP_21 = 21U,
142  EDMA_CHN_GROUP_22 = 22U,
143  EDMA_CHN_GROUP_23 = 23U,
144  EDMA_CHN_GROUP_24 = 24U,
145  EDMA_CHN_GROUP_25 = 25U,
146  EDMA_CHN_GROUP_26 = 26U,
147  EDMA_CHN_GROUP_27 = 27U,
148  EDMA_CHN_GROUP_28 = 28U,
149  EDMA_CHN_GROUP_29 = 29U,
150  EDMA_CHN_GROUP_30 = 30U,
151  EDMA_CHN_GROUP_31 = 31U
152 #else
153  EDMA_GRP0_PRIO_LOW_GRP1_PRIO_HIGH = 0U,
154  EDMA_GRP0_PRIO_HIGH_GRP1_PRIO_LOW = 1U
155 #endif
156 } edma_group_priority_t;
157 #endif
158 
162 typedef enum {
195 } edma_modulo_t;
196 
200 typedef enum {
201 #ifdef FEATURE_DMA_HWV3
202  EDMA_TRANSFER_SIZE_1B = 0x0U,
203  EDMA_TRANSFER_SIZE_2B = 0x1U,
204  EDMA_TRANSFER_SIZE_4B = 0x2U,
205  EDMA_TRANSFER_SIZE_8B = 0x3U,
206  EDMA_TRANSFER_SIZE_16B = 0x4U,
207  EDMA_TRANSFER_SIZE_32B = 0x5U,
208  EDMA_TRANSFER_SIZE_64B = 0x6U
209 #else
211  EDMA_TRANSFER_SIZE_2B = 0x1U,
212  EDMA_TRANSFER_SIZE_4B = 0x2U,
213 #ifdef FEATURE_DMA_TRANSFER_SIZE_8B
214  EDMA_TRANSFER_SIZE_8B = 0x3U,
215 #endif
216 #ifdef FEATURE_DMA_TRANSFER_SIZE_16B
217  EDMA_TRANSFER_SIZE_16B = 0x4U,
218 #endif
219 #ifdef FEATURE_DMA_TRANSFER_SIZE_32B
220  EDMA_TRANSFER_SIZE_32B = 0x5U,
221 #endif
222 #ifdef FEATURE_DMA_TRANSFER_SIZE_64B
223  EDMA_TRANSFER_SIZE_64B = 0x6U
224 #endif
225 #endif
227 
235 typedef struct {
237 #if FEATURE_DMA_CHANNEL_GROUP_COUNT > 0x1U
238 #ifndef FEATURE_DMA_HWV3
239  edma_arbitration_algorithm_t groupArbitration;
240  edma_group_priority_t groupPriority;
242 #endif
243 #endif
244  bool haltOnError;
247 
255 typedef enum {
259 
266 typedef void (*edma_callback_t)(void *parameter, edma_chn_status_t status);
267 
271 typedef struct {
272  uint8_t virtChn;
276  void *parameter;
279 
287 typedef struct {
288 #if FEATURE_DMA_CHANNEL_GROUP_COUNT > 0x1U
289 #ifdef FEATURE_DMA_HWV3
290  edma_group_priority_t groupPriority;
292 #endif
293 #endif
296  uint8_t virtChnConfig;
299  void * callbackParam;
301 
305 typedef enum {
311 
315 typedef struct {
316  uint32_t address;
317  uint32_t length;
320 
330 typedef struct {
331  edma_chn_state_t * volatile virtChnState[(uint32_t)FEATURE_DMA_VIRTUAL_CHANNELS];
332 } edma_state_t;
333 
340 typedef struct {
346  int32_t minorLoopOffset;
355 
362 typedef struct {
363  uint32_t srcAddr;
364  uint32_t destAddr;
367  int16_t srcOffset;
370  int16_t destOffset;
392 
396 #if (defined(CORE_LITTLE_ENDIAN))
397 typedef struct {
398  uint32_t SADDR;
399  int16_t SOFF;
400  uint16_t ATTR;
401  uint32_t NBYTES;
402  int32_t SLAST;
403  uint32_t DADDR;
404  int16_t DOFF;
405  uint16_t CITER;
406  int32_t DLAST_SGA;
407  uint16_t CSR;
408  uint16_t BITER;
410 #elif (defined(CORE_BIG_ENDIAN))
411 typedef struct {
412  uint32_t SADDR;
413  uint16_t ATTR;
414  int16_t SOFF;
415  uint32_t NBYTES;
416  int32_t SLAST;
417  uint32_t DADDR;
418  uint16_t CITER;
419  int16_t DOFF;
420  int32_t DLAST_SGA;
421  uint16_t BITER;
422  uint16_t CSR;
424 #else
425  #error "Endianness not defined!"
426 #endif
427 
428 /*******************************************************************************
429  * API
430  ******************************************************************************/
431 
432 #if defined(__cplusplus)
433 extern "C" {
434 #endif
435 
466  const edma_user_config_t *userConfig,
467  edma_chn_state_t * const chnStateArray[],
468  const edma_channel_config_t * const chnConfigArray[],
469  uint32_t chnCount);
470 
479 
504  const edma_channel_config_t *edmaChannelConfig);
505 
516 status_t EDMA_DRV_ReleaseChannel(uint8_t virtualChannel);
517 
531 void EDMA_DRV_PushConfigToReg(uint8_t virtualChannel,
532  const edma_transfer_config_t *tcd);
533 
544  edma_software_tcd_t *stcd);
545 
574 status_t EDMA_DRV_ConfigSingleBlockTransfer(uint8_t virtualChannel,
576  uint32_t srcAddr,
577  uint32_t destAddr,
578  edma_transfer_size_t transferSize,
579  uint32_t dataBufferSize);
580 
613 status_t EDMA_DRV_ConfigMultiBlockTransfer(uint8_t virtualChannel,
615  uint32_t srcAddr,
616  uint32_t destAddr,
617  edma_transfer_size_t transferSize,
618  uint32_t blockSize,
619  uint32_t blockCount,
620  bool disableReqOnCompletion);
621 
636 status_t EDMA_DRV_ConfigLoopTransfer(uint8_t virtualChannel,
637  const edma_transfer_config_t *transferConfig);
638 
669 status_t EDMA_DRV_ConfigScatterGatherTransfer(uint8_t virtualChannel,
670  edma_software_tcd_t *stcd,
671  edma_transfer_size_t transferSize,
672  uint32_t bytesOnEachRequest,
673  const edma_scatter_gather_list_t *srcList,
674  const edma_scatter_gather_list_t *destList,
675  uint8_t tcdCount);
676 
684 void EDMA_DRV_CancelTransfer(bool error);
685 
701 status_t EDMA_DRV_StartChannel(uint8_t virtualChannel);
702 
712 status_t EDMA_DRV_StopChannel(uint8_t virtualChannel);
713 
725 status_t EDMA_DRV_SetChannelRequest(uint8_t virtualChannel,
726  uint8_t req);
727 
733 void EDMA_DRV_ClearTCD(uint8_t virtualChannel);
734 
741 void EDMA_DRV_SetSrcAddr(uint8_t virtualChannel,
742  uint32_t address);
743 
753 void EDMA_DRV_SetSrcOffset(uint8_t virtualChannel,
754  int16_t offset);
755 
764 void EDMA_DRV_SetSrcReadChunkSize(uint8_t virtualChannel,
765  edma_transfer_size_t size);
766 
777 void EDMA_DRV_SetSrcLastAddrAdjustment(uint8_t virtualChannel,
778  int32_t adjust);
779 
786 void EDMA_DRV_SetDestAddr(uint8_t virtualChannel,
787  uint32_t address);
788 
798 void EDMA_DRV_SetDestOffset(uint8_t virtualChannel,
799  int16_t offset);
800 
809 void EDMA_DRV_SetDestWriteChunkSize(uint8_t virtualChannel,
810  edma_transfer_size_t size);
811 
822 void EDMA_DRV_SetDestLastAddrAdjustment(uint8_t virtualChannel,
823  int32_t adjust);
824 
835 void EDMA_DRV_SetMinorLoopBlockSize(uint8_t virtualChannel,
836  uint32_t nbytes);
837 
847 void EDMA_DRV_SetMajorLoopIterationCount(uint8_t virtualChannel,
848  uint32_t majorLoopCount);
849 
858 uint32_t EDMA_DRV_GetRemainingMajorIterationsCount(uint8_t virtualChannel);
859 
872 void EDMA_DRV_SetScatterGatherLink(uint8_t virtualChannel,
873  uint32_t nextTCDAddr);
874 
884 void EDMA_DRV_DisableRequestsOnTransferComplete(uint8_t virtualChannel,
885  bool disable);
886 
897 void EDMA_DRV_ConfigureInterrupt(uint8_t virtualChannel,
899  bool enable);
900 
908 void EDMA_DRV_TriggerSwRequest(uint8_t virtualChannel);
909 
934 status_t EDMA_DRV_InstallCallback(uint8_t virtualChannel,
935  edma_callback_t callback,
936  void *parameter);
937 
951 edma_chn_status_t EDMA_DRV_GetChannelStatus(uint8_t virtualChannel);
952 
957 #if defined(__cplusplus)
958 }
959 #endif
960 
963 #endif /* EDMA_DRIVER_H */
964 /*******************************************************************************
965  * EOF
966  ******************************************************************************/
967 
void EDMA_DRV_PushConfigToSTCD(const edma_transfer_config_t *config, edma_software_tcd_t *stcd)
Copies the channel configuration to the software TCD structure.
Definition: edma_driver.c:1543
edma_arbitration_algorithm_t
eDMA channel arbitration algorithm used for selection among channels. Implements : edma_arbitration_a...
Definition: edma_driver.h:82
void EDMA_DRV_SetMajorLoopIterationCount(uint8_t virtualChannel, uint32_t majorLoopCount)
Configures the number of major loop iterations.
Definition: edma_driver.c:1316
eDMA TCD Implements : edma_software_tcd_t_Class
Definition: edma_driver.h:397
edma_modulo_t
eDMA modulo configuration Implements : edma_modulo_t_Class
Definition: edma_driver.h:162
uint32_t EDMA_DRV_GetRemainingMajorIterationsCount(uint8_t virtualChannel)
Returns the remaining major loop iteration count.
Definition: edma_driver.c:1346
uint32_t minorByteTransferCount
Definition: edma_driver.h:378
status_t EDMA_DRV_InstallCallback(uint8_t virtualChannel, edma_callback_t callback, void *parameter)
Registers the callback function and the parameter for eDMA channel.
Definition: edma_driver.c:336
edma_modulo_t destModulo
Definition: edma_driver.h:377
status_t EDMA_DRV_ConfigLoopTransfer(uint8_t virtualChannel, const edma_transfer_config_t *transferConfig)
Configures the DMA transfer in loop mode.
Definition: edma_driver.c:708
status_t EDMA_DRV_ConfigMultiBlockTransfer(uint8_t virtualChannel, edma_transfer_type_t type, uint32_t srcAddr, uint32_t destAddr, edma_transfer_size_t transferSize, uint32_t blockSize, uint32_t blockCount, bool disableReqOnCompletion)
Configures a multiple block data transfer with DMA.
Definition: edma_driver.c:662
edma_callback_t callback
Definition: edma_driver.h:298
The user configuration structure for the eDMA driver.
Definition: edma_driver.h:235
edma_transfer_type_t
A type for the DMA transfer. Implements : edma_transfer_type_t_Class.
Definition: edma_driver.h:305
void EDMA_DRV_SetDestWriteChunkSize(uint8_t virtualChannel, edma_transfer_size_t size)
Configures the destination data chunk size (transferred in a write sequence).
Definition: edma_driver.c:1256
status_t EDMA_DRV_ConfigSingleBlockTransfer(uint8_t virtualChannel, edma_transfer_type_t type, uint32_t srcAddr, uint32_t destAddr, edma_transfer_size_t transferSize, uint32_t dataBufferSize)
Configures a simple single block data transfer with DMA.
Definition: edma_driver.c:554
void EDMA_DRV_PushConfigToReg(uint8_t virtualChannel, const edma_transfer_config_t *tcd)
Copies the channel configuration to the TCD registers.
Definition: edma_driver.c:1587
The user configuration structure for the an eDMA driver channel.
Definition: edma_driver.h:287
status_t EDMA_DRV_Deinit(void)
De-initializes the eDMA module.
Definition: edma_driver.c:239
void EDMA_DRV_SetScatterGatherLink(uint8_t virtualChannel, uint32_t nextTCDAddr)
Configures the memory address of the next TCD, in scatter/gather mode.
Definition: edma_driver.c:1377
void EDMA_DRV_SetSrcLastAddrAdjustment(uint8_t virtualChannel, int32_t adjust)
Configures the source address last adjustment.
Definition: edma_driver.c:1136
void EDMA_DRV_ConfigureInterrupt(uint8_t virtualChannel, edma_channel_interrupt_t intSrc, bool enable)
Disables/Enables the channel interrupt requests.
Definition: edma_driver.c:1437
void EDMA_DRV_TriggerSwRequest(uint8_t virtualChannel)
Triggers a sw request for the current channel.
Definition: edma_driver.c:1514
void EDMA_DRV_SetDestOffset(uint8_t virtualChannel, int16_t offset)
Configures the destination address signed offset for the eDMA channel.
Definition: edma_driver.c:1226
status_t EDMA_DRV_StopChannel(uint8_t virtualChannel)
Stops the eDMA channel.
Definition: edma_driver.c:952
edma_channel_interrupt_t
eDMA channel interrupts. Implements : edma_channel_interrupt_t_Class
Definition: edma_driver.h:73
uint32_t scatterGatherNextDescAddr
Definition: edma_driver.h:381
void EDMA_DRV_DisableRequestsOnTransferComplete(uint8_t virtualChannel, bool disable)
Disables/Enables the DMA request after the major loop completes for the TCD.
Definition: edma_driver.c:1407
status_t EDMA_DRV_ChannelInit(edma_chn_state_t *edmaChannelState, const edma_channel_config_t *edmaChannelConfig)
Initializes an eDMA channel.
Definition: edma_driver.c:287
Runtime state structure for the eDMA driver.
Definition: edma_driver.h:330
edma_chn_status_t
Channel status for eDMA channel.
Definition: edma_driver.h:255
edma_chn_status_t EDMA_DRV_GetChannelStatus(uint8_t virtualChannel)
Gets the eDMA channel status.
Definition: edma_driver.c:1710
edma_transfer_size_t destTransferSize
Definition: edma_driver.h:366
edma_callback_t callback
Definition: edma_driver.h:273
edma_transfer_size_t
eDMA transfer configuration Implements : edma_transfer_size_t_Class
Definition: edma_driver.h:200
void EDMA_DRV_SetDestAddr(uint8_t virtualChannel, uint32_t address)
Configures the destination address for the eDMA channel.
Definition: edma_driver.c:1196
edma_channel_priority_t
eDMA channel priority setting Implements : edma_channel_priority_t_Class
Definition: edma_driver.h:90
edma_arbitration_algorithm_t chnArbitration
Definition: edma_driver.h:236
status_t
Status return codes. Common error codes will be a unified enumeration (C enum) that will contain all ...
Definition: status.h:44
edma_modulo_t srcModulo
Definition: edma_driver.h:376
edma_channel_priority_t channelPriority
Definition: edma_driver.h:294
status_t EDMA_DRV_ReleaseChannel(uint8_t virtualChannel)
Releases an eDMA channel.
Definition: edma_driver.c:421
void EDMA_DRV_SetSrcOffset(uint8_t virtualChannel, int16_t offset)
Configures the source address signed offset for the eDMA channel.
Definition: edma_driver.c:1076
edma_transfer_size_t srcTransferSize
Definition: edma_driver.h:365
Data structure for configuring a discrete memory transfer. Implements : edma_scatter_gather_list_t_Cl...
Definition: edma_driver.h:315
volatile edma_chn_status_t status
Definition: edma_driver.h:277
void EDMA_DRV_SetSrcReadChunkSize(uint8_t virtualChannel, edma_transfer_size_t size)
Configures the source data chunk size (transferred in a read sequence).
Definition: edma_driver.c:1106
edma_transfer_type_t type
Definition: edma_driver.h:318
void EDMA_DRV_SetSrcAddr(uint8_t virtualChannel, uint32_t address)
Configures the source address for the eDMA channel.
Definition: edma_driver.c:1046
status_t EDMA_DRV_ConfigScatterGatherTransfer(uint8_t virtualChannel, edma_software_tcd_t *stcd, edma_transfer_size_t transferSize, uint32_t bytesOnEachRequest, const edma_scatter_gather_list_t *srcList, const edma_scatter_gather_list_t *destList, uint8_t tcdCount)
Configures the DMA transfer in a scatter-gather mode.
Definition: edma_driver.c:761
void EDMA_DRV_SetMinorLoopBlockSize(uint8_t virtualChannel, uint32_t nbytes)
Configures the number of bytes to be transferred in each service request of the channel.
Definition: edma_driver.c:1286
status_t EDMA_DRV_Init(edma_state_t *edmaState, const edma_user_config_t *userConfig, edma_chn_state_t *const chnStateArray[], const edma_channel_config_t *const chnConfigArray[], uint32_t chnCount)
Initializes the eDMA module.
Definition: edma_driver.c:119
status_t EDMA_DRV_StartChannel(uint8_t virtualChannel)
Starts an eDMA channel.
Definition: edma_driver.c:921
status_t EDMA_DRV_SetChannelRequest(uint8_t virtualChannel, uint8_t req)
Configures the DMA request for the eDMA channel.
Definition: edma_driver.c:983
#define FEATURE_DMA_VIRTUAL_CHANNELS
void EDMA_DRV_CancelTransfer(bool error)
Cancel the running transfer.
Definition: edma_driver.c:1485
void(* edma_callback_t)(void *parameter, edma_chn_status_t status)
Definition for the eDMA channel callback function.
Definition: edma_driver.h:266
dma_request_source_t source
Definition: edma_driver.h:297
void EDMA_DRV_SetDestLastAddrAdjustment(uint8_t virtualChannel, int32_t adjust)
Configures the destination address last adjustment.
Definition: edma_driver.c:1166
void EDMA_DRV_ClearTCD(uint8_t virtualChannel)
Clears all registers to 0 for the channel's TCD.
Definition: edma_driver.c:1017
eDMA loop transfer configuration.
Definition: edma_driver.h:340
eDMA transfer size configuration.
Definition: edma_driver.h:362
edma_loop_transfer_config_t * loopTransferConfig
Definition: edma_driver.h:387
dma_request_source_t
Structure for the DMA hardware request.
Data structure for the eDMA channel state. Implements : edma_chn_state_t_Class.
Definition: edma_driver.h:271