S32 SDK
edma_driver.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2013 - 2016, Freescale Semiconductor, Inc.
3  * Copyright 2016 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  ******************************************************************************/
58 #define STCD_SIZE(number) (((number) * 32U) - 1U)
59 #define STCD_ADDR(address) (((uint32_t)address + 31UL) & ~0x1FUL)
60 
67 #define EDMA_ERR_LSB_MASK 1U
68 
72 typedef enum {
77 
81 typedef enum {
85 
89 typedef enum {
108 
109 #if FEATURE_EDMA_CHANNEL_GROUP_COUNT > 0x1U
110 
113 typedef enum {
114  EDMA_GRP0_PRIO_LOW_GRP1_PRIO_HIGH = 0U,
115  EDMA_GRP0_PRIO_HIGH_GRP1_PRIO_LOW = 1U
116 } edma_group_priority_t;
117 #endif
118 
122 typedef enum {
155 } edma_modulo_t;
156 
160 typedef enum {
167 
175 typedef struct {
177 #if FEATURE_EDMA_CHANNEL_GROUP_COUNT > 0x1U
178  edma_arbitration_algorithm_t groupArbitration;
179  edma_group_priority_t groupPriority;
181 #endif
185 
193 typedef enum {
197 
204 typedef void (*edma_callback_t)(void *parameter, edma_chn_status_t status);
205 
209 typedef struct {
210  uint8_t channel;
214  void *parameter;
217 
225 typedef struct {
228  uint8_t channel;
231  void * callbackParam;
233 
237 typedef enum {
243 
247 typedef struct {
248  uint32_t address;
249  uint32_t length;
252 
262 typedef struct {
264 } edma_state_t;
265 
272 typedef struct {
278  int32_t minorLoopOffset;
287 
294 typedef struct {
295  uint32_t srcAddr;
296  uint32_t destAddr;
299  int16_t srcOffset;
302  int16_t destOffset;
324 
328 #if (defined(CORE_LITTLE_ENDIAN))
329 typedef struct {
330  uint32_t SADDR;
331  int16_t SOFF;
332  uint16_t ATTR;
333  uint32_t NBYTES;
334  int32_t SLAST;
335  uint32_t DADDR;
336  int16_t DOFF;
337  uint16_t CITER;
338  int32_t DLAST_SGA;
339  uint16_t CSR;
340  uint16_t BITER;
341 } edma_software_tcd_t;
342 #elif (defined(CORE_BIG_ENDIAN))
343 typedef struct {
344  uint32_t SADDR;
345  uint16_t ATTR;
346  int16_t SOFF;
347  uint32_t NBYTES;
348  int32_t SLAST;
349  uint32_t DADDR;
350  uint16_t CITER;
351  int16_t DOFF;
352  int32_t DLAST_SGA;
353  uint16_t BITER;
354  uint16_t CSR;
355 } edma_software_tcd_t;
356 #else
357  #error "Endianness not defined!"
358 #endif
359 
360 /*******************************************************************************
361  * API
362  ******************************************************************************/
363 
364 #if defined(__cplusplus)
365 extern "C" {
366 #endif
367 
397 status_t EDMA_DRV_Init(edma_state_t *edmaState, const edma_user_config_t *userConfig,
398  edma_chn_state_t * const chnStateArray[],
399  const edma_channel_config_t * const chnConfigArray[],
400  uint8_t chnCount);
401 
410 
434 status_t EDMA_DRV_ChannelInit(edma_chn_state_t *edmaChannelState, const edma_channel_config_t *edmaChannelConfig);
435 
446 status_t EDMA_DRV_ReleaseChannel(uint8_t channel);
447 
461 void EDMA_DRV_PushConfigToReg(uint8_t channel, const edma_transfer_config_t *tcd);
462 
473 void EDMA_DRV_PushConfigToSTCD(const edma_transfer_config_t *config, edma_software_tcd_t *stcd);
474 
504  uint32_t srcAddr, uint32_t destAddr,
505  edma_transfer_size_t transferSize, uint32_t dataBufferSize);
506 
540  uint32_t srcAddr, uint32_t destAddr,
541  edma_transfer_size_t transferSize, uint32_t blockSize,
542  uint32_t blockCount, bool disableReqOnCompletion);
543 
558 status_t EDMA_DRV_ConfigLoopTransfer(uint8_t channel, const edma_transfer_config_t * transferConfig);
559 
590 status_t EDMA_DRV_ConfigScatterGatherTransfer(uint8_t channel, edma_software_tcd_t *stcd,
591  edma_transfer_size_t transferSize, uint32_t bytesOnEachRequest,
592  const edma_scatter_gather_list_t *srcList,
593  const edma_scatter_gather_list_t *destList, uint8_t tcdCount);
594 
602 void EDMA_DRV_CancelTransfer(bool error);
603 
619 status_t EDMA_DRV_StartChannel(uint8_t channel);
620 
630 status_t EDMA_DRV_StopChannel(uint8_t channel);
631 
643 status_t EDMA_DRV_SetChannelRequest(uint8_t channel, uint8_t req);
644 
650 void EDMA_DRV_ClearTCD(uint8_t channel);
651 
658 void EDMA_DRV_SetSrcAddr(uint8_t channel, uint32_t address);
659 
669 void EDMA_DRV_SetSrcOffset(uint8_t channel, int16_t offset);
670 
679 void EDMA_DRV_SetSrcReadChunkSize(uint8_t channel, edma_transfer_size_t size);
680 
691 void EDMA_DRV_SetSrcLastAddrAdjustment(uint8_t channel, int32_t adjust);
692 
699 void EDMA_DRV_SetDestAddr(uint8_t channel, uint32_t address);
700 
710 void EDMA_DRV_SetDestOffset(uint8_t channel, int16_t offset);
711 
720 void EDMA_DRV_SetDestWriteChunkSize(uint8_t channel, edma_transfer_size_t size);
721 
732 void EDMA_DRV_SetDestLastAddrAdjustment(uint8_t channel, int32_t adjust);
733 
744 void EDMA_DRV_SetMinorLoopBlockSize(uint8_t channel, uint32_t nbytes);
745 
755 void EDMA_DRV_SetMajorLoopIterationCount(uint8_t channel, uint32_t majorLoopCount);
756 
765 uint32_t EDMA_DRV_GetRemainingMajorIterationsCount(uint8_t channel);
766 
779 void EDMA_DRV_SetScatterGatherLink(uint8_t channel, uint32_t nextTCDAddr);
780 
790 void EDMA_DRV_DisableRequestsOnTransferComplete(uint8_t channel, bool disable);
791 
802 void EDMA_DRV_ConfigureInterrupt(uint8_t channel, edma_channel_interrupt_t intSrc, bool enable);
803 
811 void EDMA_DRV_TriggerSwRequest(uint8_t channel);
812 
837 status_t EDMA_DRV_InstallCallback(uint8_t channel, edma_callback_t callback, void *parameter);
838 
853 
858 #if defined(__cplusplus)
859 }
860 #endif
861 
864 #endif /* EDMA_DRIVER_H */
865 /*******************************************************************************
866  * EOF
867  ******************************************************************************/
868 
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:1302
edma_arbitration_algorithm_t
eDMA channel arbitration algorithm used for selection among channels. Implements : edma_arbitration_a...
Definition: edma_driver.h:81
void EDMA_DRV_SetDestLastAddrAdjustment(uint8_t channel, int32_t adjust)
Configures the destination address last adjustment.
Definition: edma_driver.c:1003
edma_modulo_t
eDMA modulo configuration Implements : edma_modulo_t_Class
Definition: edma_driver.h:122
uint32_t minorByteTransferCount
Definition: edma_driver.h:310
void EDMA_DRV_SetSrcReadChunkSize(uint8_t channel, edma_transfer_size_t size)
Configures the source data chunk size (transferred in a read sequence).
Definition: edma_driver.c:957
edma_modulo_t destModulo
Definition: edma_driver.h:309
uint32_t EDMA_DRV_GetRemainingMajorIterationsCount(uint8_t channel)
Returns the remaining major loop iteration count.
Definition: edma_driver.c:1141
edma_callback_t callback
Definition: edma_driver.h:230
The user configuration structure for the eDMA driver.
Definition: edma_driver.h:175
edma_transfer_type_t
A type for the DMA transfer. Implements : edma_transfer_type_t_Class.
Definition: edma_driver.h:237
The user configuration structure for the an eDMA driver channel.
Definition: edma_driver.h:225
status_t EDMA_DRV_ReleaseChannel(uint8_t channel)
Releases an eDMA channel.
Definition: edma_driver.c:367
status_t EDMA_DRV_StopChannel(uint8_t channel)
Stops the eDMA channel.
Definition: edma_driver.c:838
void EDMA_DRV_SetDestOffset(uint8_t channel, int16_t offset)
Configures the destination address signed offset for the eDMA channel.
Definition: edma_driver.c:1049
status_t EDMA_DRV_Deinit(void)
De-initializes the eDMA module.
Definition: edma_driver.c:207
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[], uint8_t chnCount)
Initializes the eDMA module.
Definition: edma_driver.c:99
edma_channel_priority_t priority
Definition: edma_driver.h:226
void EDMA_DRV_SetMinorLoopBlockSize(uint8_t channel, uint32_t nbytes)
Configures the number of bytes to be transferred in each service request of the channel.
Definition: edma_driver.c:1095
status_t EDMA_DRV_SetChannelRequest(uint8_t channel, uint8_t req)
Configures the DMA request for the eDMA channel.
Definition: edma_driver.c:863
dma_request_source_t
Structure for the DMA hardware request.
void EDMA_DRV_DisableRequestsOnTransferComplete(uint8_t channel, bool disable)
Disables/Enables the DMA request after the major loop completes for the TCD.
Definition: edma_driver.c:1191
void EDMA_DRV_SetSrcLastAddrAdjustment(uint8_t channel, int32_t adjust)
Configures the source address last adjustment.
Definition: edma_driver.c:980
void EDMA_DRV_SetScatterGatherLink(uint8_t channel, uint32_t nextTCDAddr)
Configures the memory address of the next TCD, in scatter/gather mode.
Definition: edma_driver.c:1168
edma_channel_interrupt_t
eDMA channel interrupts. Implements : edma_channel_interrupt_t_Class
Definition: edma_driver.h:72
uint32_t scatterGatherNextDescAddr
Definition: edma_driver.h:313
status_t EDMA_DRV_ConfigLoopTransfer(uint8_t channel, const edma_transfer_config_t *transferConfig)
Configures the DMA transfer in loop mode.
Definition: edma_driver.c:619
status_t EDMA_DRV_ChannelInit(edma_chn_state_t *edmaChannelState, const edma_channel_config_t *edmaChannelConfig)
Initializes an eDMA channel.
Definition: edma_driver.c:254
Runtime state structure for the eDMA driver.
Definition: edma_driver.h:262
edma_chn_status_t
Channel status for eDMA channel.
Definition: edma_driver.h:193
edma_transfer_size_t destTransferSize
Definition: edma_driver.h:298
edma_callback_t callback
Definition: edma_driver.h:211
edma_transfer_size_t
eDMA transfer configuration Implements : edma_transfer_size_t_Class
Definition: edma_driver.h:160
void EDMA_DRV_PushConfigToReg(uint8_t channel, const edma_transfer_config_t *tcd)
Copies the channel configuration to the TCD registers.
Definition: edma_driver.c:1340
void EDMA_DRV_SetSrcAddr(uint8_t channel, uint32_t address)
Configures the source address for the eDMA channel.
Definition: edma_driver.c:911
edma_channel_priority_t
eDMA channel priority setting Implements : edma_channel_priority_t_Class
Definition: edma_driver.h:89
edma_arbitration_algorithm_t chnArbitration
Definition: edma_driver.h:176
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:308
status_t EDMA_DRV_ConfigScatterGatherTransfer(uint8_t channel, 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:656
edma_transfer_size_t srcTransferSize
Definition: edma_driver.h:297
Data structure for configuring a discrete memory transfer. Implements : edma_scatter_gather_list_t_Cl...
Definition: edma_driver.h:247
void EDMA_DRV_SetMajorLoopIterationCount(uint8_t channel, uint32_t majorLoopCount)
Configures the number of major loop iterations.
Definition: edma_driver.c:1118
volatile edma_chn_status_t status
Definition: edma_driver.h:215
void EDMA_DRV_SetDestAddr(uint8_t channel, uint32_t address)
Configures the destination address for the eDMA channel.
Definition: edma_driver.c:1026
edma_chn_status_t EDMA_DRV_GetChannelStatus(uint8_t channel)
Gets the eDMA channel status.
Definition: edma_driver.c:1440
edma_transfer_type_t type
Definition: edma_driver.h:250
void EDMA_DRV_SetDestWriteChunkSize(uint8_t channel, edma_transfer_size_t size)
Configures the destination data chunk size (transferred in a write sequence).
Definition: edma_driver.c:1072
status_t EDMA_DRV_StartChannel(uint8_t channel)
Starts an eDMA channel.
Definition: edma_driver.c:813
void EDMA_DRV_SetSrcOffset(uint8_t channel, int16_t offset)
Configures the source address signed offset for the eDMA channel.
Definition: edma_driver.c:934
void EDMA_DRV_TriggerSwRequest(uint8_t channel)
Triggers a sw request for the current channel.
Definition: edma_driver.c:1279
void EDMA_DRV_ClearTCD(uint8_t channel)
Clears all registers to 0 for the channel's TCD.
Definition: edma_driver.c:888
void EDMA_DRV_CancelTransfer(bool error)
Cancel the running transfer.
Definition: edma_driver.c:1254
void(* edma_callback_t)(void *parameter, edma_chn_status_t status)
Definition for the eDMA channel callback function.
Definition: edma_driver.h:204
dma_request_source_t source
Definition: edma_driver.h:229
status_t EDMA_DRV_ConfigSingleBlockTransfer(uint8_t channel, 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:495
eDMA loop transfer configuration.
Definition: edma_driver.h:272
void EDMA_DRV_ConfigureInterrupt(uint8_t channel, edma_channel_interrupt_t intSrc, bool enable)
Disables/Enables the channel interrupt requests.
Definition: edma_driver.c:1214
eDMA transfer size configuration.
Definition: edma_driver.h:294
edma_loop_transfer_config_t * loopTransferConfig
Definition: edma_driver.h:319
status_t EDMA_DRV_ConfigMultiBlockTransfer(uint8_t channel, 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:589
status_t EDMA_DRV_InstallCallback(uint8_t channel, edma_callback_t callback, void *parameter)
Registers the callback function and the parameter for eDMA channel.
Definition: edma_driver.c:293
#define FEATURE_EDMA_MODULE_CHANNELS
Data structure for the eDMA channel state. Implements : edma_chn_state_t_Class.
Definition: edma_driver.h:209