Detailed Description

This module covers the functionality of the Enhanced Direct Memory Access (eDMA) peripheral driver.

The eDMA driver implements direct memory access functionality with multiple features: (single block/multi block/loop/scatter-gather transfers); the main usage of this module is to offload the bus read/write accesses from the core to the eDMA engine.

Features

Functionality

Initialization

In order to use the eDMA driver, the module must be first initialized, using EDMA_DRV_Init() function. Once initialized, it cannot be initialized again until it is de-initialized, using EDMA_DRV_Deinit(). The initialization function does the following operations:

Upon module initialization, the application must initialize the channel(s) to be used, using EDMA_DRV_ChannelInit() function. This operation means enabling an eDMA channel number (or dynamically allocating one), selecting a source trigger (eDMA request multiplexed via DMAMUX) and setting the channel priority. Additionally, a user callback can be installed for each channel, which will be called when the corresponding interrupt is triggered.

Transfer Configuration

After initialization, the transfer control descriptor for the selected channel must be configured before use. Depending on the application use-case, on of the three transfer configuration methods should be called.

Single-block transfer

For the simplest use-case where a contiguous chunk of data must be transferred, the most suitable function is EDMA_DRV_ConfigSingleBlockTransfer(). This takes the source/destination addresses as parameters, as well as transfer type/size and data buffer size, and configures the channel TCD to read/write the data in a single request. The looping and scatter/gather features are not used in this scenario. The driver computes the appropriate offsets for source/destination addresses and set the other TCD fields.

Multi-block transfer

This type of transfer can be seen as a sequence of single-block transfers, as described above, which are triggered by subsequent requests. This configuration is suitable for contiguous chunks of data which need to be transferred in multiple steps (e.g. writing one/several bytes from a memory buffer to a peripheral data register each time the module is free - eDMA-based communication). In order to configure this kind of transfer, EDMA_DRV_ConfigMultiBlockTransfer function should be used; aside from the EDMA_DRV_ConfigSingleBlockTransfer parameters, this function also takes two additional parameters: the number of transfer loops (expected number of requests to finish the data) and a boolean variable configuring whether requests should be disabled for the current channel upon transfer completion.

Loop transfer

The eDMA IP supports complex addressing modes. One of the methods to configure complex transfers in multiple requests is using the minor/major loop support. The EDMA_DRV_ConfigLoopTransfer() function sets up the transfer control descriptor for subsequent requests to trigger multiple transfers. The addresses are adjusted after each minor/major loop, according to user setup. This method takes a transfer configuration structure as parameter, with settings for all the fields that control addressing mode (source/destination offsets, minor loop offset, channel linking, minor/major loop count, address last adjustments). It is the responsibility of the application to correctly initialize the configuration structure passed to this function, according to the addressed use-case.

Scatter/gather

The eDMA driver also supports scatter/gather feature, which allows various transfer scenarios. When scatter/gather is enabled, a new TCD structure is automatically loaded in the current channel's TCD registers when a transfer is complete, allowing the application to define multiple different subsequent transfers. The EDMA_DRV_ConfigScatterGatherTransfer() function sets up a list of TCD structures based on the parameters received and configures the eDMA channel for the first transfer; upon completion, the second TCD from the list will be loaded and the channel will be ready to start the new transfer when a new request is received.
The application must allocate memory for the TCD list passed to this function (with an extra 32-bytes buffer, as the TCD structures need to be 32 bytes aligned); nevertheless, the driver will take care of initializing the array of descriptors, based on the other parameters passed. The function also received two lists of scatter/gather configuration structures (for source and destination, respectively), which define the address, length and type for each transfer. Besides these, the other parameters received are the transfer size, the number of bytes to be transferred on each request and the number of TCD structures to be used. This method will initialize all the descriptors according to user input and link them together; the linkage is done by writing the address of the next descriptor in the appropriate field of each one, similar to a linked-list data structure. The first descriptor is also copied to the TCD registers of the selected channel; if no errors are returned, after calling this function the channel is configured for the transfer defined by the first descriptor.

Virtual Channel Definition

The virtual channel is used to map multiple hardware channels across multiple eDMA instances. If only one eDMA instance is available, then the virtual channels will map one-on-one with the hardware channels. If more than one eDMA instance is available, then the virtual channels will map continuously and linearly over all of the harware channels. Example: If the SOC has 4 eDMAs modules each with 32 channels, then the user will be able to address a total of 128 virtual channels, that seamlessly map onto the hardware channels.

Virtual Channel Control

The eDMA driver provides functions that allow the user to start, stop, allocate and release an eDMA virtual channel.
The EDMA_DRV_StartChannel() enables the eDMA requests for a virtual channel; this function should be called when the virtual channel is already initialized, as the first request received after the function call will trigger the transfer based on the current values of the virtual channel's TCD registers.
The EDMA_DRV_StopChannel() function disables requests for the selected virtual channel; this function should be called whenever the application needs to ignore eDMA requests for a virtual channel. It is automatically called when the virtual channel is released.
The EDMA_DRV_RequestChannel() function selects a virtual channel to be used by application and updates the driver state structure accordingly. Two types of virtual channel allocation are available:

The EDMA_DRV_ReleaseChannel() function frees the hardware and software resources allocated for that virtual channel; it clears the virtual channel state structure, updates the driver state and disables requests for that virtual channel.

Important Notes

Data Structures

struct  edma_user_config_t
 The user configuration structure for the eDMA driver. More...
 
struct  edma_chn_state_t
 Data structure for the eDMA channel state. Implements : edma_chn_state_t_Class. More...
 
struct  edma_channel_config_t
 The user configuration structure for the an eDMA driver channel. More...
 
struct  edma_scatter_gather_list_t
 Data structure for configuring a discrete memory transfer. Implements : edma_scatter_gather_list_t_Class. More...
 
struct  edma_state_t
 Runtime state structure for the eDMA driver. More...
 
struct  edma_loop_transfer_config_t
 eDMA loop transfer configuration. More...
 
struct  edma_transfer_config_t
 eDMA transfer size configuration. More...
 
struct  edma_software_tcd_t
 eDMA TCD Implements : edma_software_tcd_t_Class More...
 

Macros

#define STCD_SIZE(number)    (((number) * 32U) - 1U)
 Macro for the memory size needed for the software TCD. More...
 
#define STCD_ADDR(address)    (((uint32_t)address + 31UL) & ~0x1FUL)
 
#define EDMA_ERR_LSB_MASK   1U
 Macro for accessing the least significant bit of the ERR register. More...
 

Typedefs

typedef void(* edma_callback_t) (void *parameter, edma_chn_status_t status)
 Definition for the eDMA channel callback function. More...
 

Enumerations

enum  edma_channel_interrupt_t { EDMA_CHN_ERR_INT = 0U, EDMA_CHN_HALF_MAJOR_LOOP_INT, EDMA_CHN_MAJOR_LOOP_INT }
 eDMA channel interrupts. Implements : edma_channel_interrupt_t_Class More...
 
enum  edma_arbitration_algorithm_t { EDMA_ARBITRATION_FIXED_PRIORITY = 0U, EDMA_ARBITRATION_ROUND_ROBIN }
 eDMA channel arbitration algorithm used for selection among channels. Implements : edma_arbitration_algorithm_t_Class More...
 
enum  edma_channel_priority_t {
  EDMA_CHN_PRIORITY_0 = 0U, EDMA_CHN_PRIORITY_1 = 1U, EDMA_CHN_PRIORITY_2 = 2U, EDMA_CHN_PRIORITY_3 = 3U,
  EDMA_CHN_DEFAULT_PRIORITY = 255U
}
 eDMA channel priority setting Implements : edma_channel_priority_t_Class More...
 
enum  edma_modulo_t {
  EDMA_MODULO_OFF = 0U, EDMA_MODULO_2B, EDMA_MODULO_4B, EDMA_MODULO_8B,
  EDMA_MODULO_16B, EDMA_MODULO_32B, EDMA_MODULO_64B, EDMA_MODULO_128B,
  EDMA_MODULO_256B, EDMA_MODULO_512B, EDMA_MODULO_1KB, EDMA_MODULO_2KB,
  EDMA_MODULO_4KB, EDMA_MODULO_8KB, EDMA_MODULO_16KB, EDMA_MODULO_32KB,
  EDMA_MODULO_64KB, EDMA_MODULO_128KB, EDMA_MODULO_256KB, EDMA_MODULO_512KB,
  EDMA_MODULO_1MB, EDMA_MODULO_2MB, EDMA_MODULO_4MB, EDMA_MODULO_8MB,
  EDMA_MODULO_16MB, EDMA_MODULO_32MB, EDMA_MODULO_64MB, EDMA_MODULO_128MB,
  EDMA_MODULO_256MB, EDMA_MODULO_512MB, EDMA_MODULO_1GB, EDMA_MODULO_2GB
}
 eDMA modulo configuration Implements : edma_modulo_t_Class More...
 
enum  edma_transfer_size_t { EDMA_TRANSFER_SIZE_1B = 0x0U, EDMA_TRANSFER_SIZE_2B = 0x1U, EDMA_TRANSFER_SIZE_4B = 0x2U }
 eDMA transfer configuration Implements : edma_transfer_size_t_Class More...
 
enum  edma_chn_status_t { EDMA_CHN_NORMAL = 0U, EDMA_CHN_ERROR }
 Channel status for eDMA channel. More...
 
enum  edma_transfer_type_t { EDMA_TRANSFER_PERIPH2MEM = 0U, EDMA_TRANSFER_MEM2PERIPH, EDMA_TRANSFER_MEM2MEM, EDMA_TRANSFER_PERIPH2PERIPH }
 A type for the DMA transfer. Implements : edma_transfer_type_t_Class. More...
 

eDMA peripheral driver module level functions

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. More...
 
status_t EDMA_DRV_Deinit (void)
 De-initializes the eDMA module. More...
 

eDMA peripheral driver channel management functions

status_t EDMA_DRV_ChannelInit (edma_chn_state_t *edmaChannelState, const edma_channel_config_t *edmaChannelConfig)
 Initializes an eDMA channel. More...
 
status_t EDMA_DRV_ReleaseChannel (uint8_t virtualChannel)
 Releases an eDMA channel. More...
 

eDMA peripheral driver transfer setup functions

void EDMA_DRV_PushConfigToReg (uint8_t virtualChannel, const edma_transfer_config_t *tcd)
 Copies the channel configuration to the TCD registers. More...
 
void EDMA_DRV_PushConfigToSTCD (const edma_transfer_config_t *config, edma_software_tcd_t *stcd)
 Copies the channel configuration to the software TCD structure. More...
 
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. More...
 
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. More...
 
status_t EDMA_DRV_ConfigLoopTransfer (uint8_t virtualChannel, const edma_transfer_config_t *transferConfig)
 Configures the DMA transfer in loop mode. More...
 
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. More...
 
void EDMA_DRV_CancelTransfer (bool error)
 Cancel the running transfer. More...
 

eDMA Peripheral driver channel operation functions

status_t EDMA_DRV_StartChannel (uint8_t virtualChannel)
 Starts an eDMA channel. More...
 
status_t EDMA_DRV_StopChannel (uint8_t virtualChannel)
 Stops the eDMA channel. More...
 
status_t EDMA_DRV_SetChannelRequest (uint8_t virtualChannel, uint8_t req)
 Configures the DMA request for the eDMA channel. More...
 
void EDMA_DRV_ClearTCD (uint8_t virtualChannel)
 Clears all registers to 0 for the channel's TCD. More...
 
void EDMA_DRV_SetSrcAddr (uint8_t virtualChannel, uint32_t address)
 Configures the source address for the eDMA channel. More...
 
void EDMA_DRV_SetSrcOffset (uint8_t virtualChannel, int16_t offset)
 Configures the source address signed offset for the eDMA channel. More...
 
void EDMA_DRV_SetSrcReadChunkSize (uint8_t virtualChannel, edma_transfer_size_t size)
 Configures the source data chunk size (transferred in a read sequence). More...
 
void EDMA_DRV_SetSrcLastAddrAdjustment (uint8_t virtualChannel, int32_t adjust)
 Configures the source address last adjustment. More...
 
void EDMA_DRV_SetDestAddr (uint8_t virtualChannel, uint32_t address)
 Configures the destination address for the eDMA channel. More...
 
void EDMA_DRV_SetDestOffset (uint8_t virtualChannel, int16_t offset)
 Configures the destination address signed offset for the eDMA channel. More...
 
void EDMA_DRV_SetDestWriteChunkSize (uint8_t virtualChannel, edma_transfer_size_t size)
 Configures the destination data chunk size (transferred in a write sequence). More...
 
void EDMA_DRV_SetDestLastAddrAdjustment (uint8_t virtualChannel, int32_t adjust)
 Configures the destination address last adjustment. More...
 
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. More...
 
void EDMA_DRV_SetMajorLoopIterationCount (uint8_t virtualChannel, uint32_t majorLoopCount)
 Configures the number of major loop iterations. More...
 
uint32_t EDMA_DRV_GetRemainingMajorIterationsCount (uint8_t virtualChannel)
 Returns the remaining major loop iteration count. More...
 
void EDMA_DRV_SetScatterGatherLink (uint8_t virtualChannel, uint32_t nextTCDAddr)
 Configures the memory address of the next TCD, in scatter/gather mode. More...
 
void EDMA_DRV_DisableRequestsOnTransferComplete (uint8_t virtualChannel, bool disable)
 Disables/Enables the DMA request after the major loop completes for the TCD. More...
 
void EDMA_DRV_ConfigureInterrupt (uint8_t virtualChannel, edma_channel_interrupt_t intSrc, bool enable)
 Disables/Enables the channel interrupt requests. More...
 
void EDMA_DRV_TriggerSwRequest (uint8_t virtualChannel)
 Triggers a sw request for the current channel. More...
 

eDMA Peripheral callback and interrupt functions

status_t EDMA_DRV_InstallCallback (uint8_t virtualChannel, edma_callback_t callback, void *parameter)
 Registers the callback function and the parameter for eDMA channel. More...
 

eDMA Peripheral driver miscellaneous functions

edma_chn_status_t EDMA_DRV_GetChannelStatus (uint8_t virtualChannel)
 Gets the eDMA channel status. More...
 

Macro Definition Documentation

#define EDMA_ERR_LSB_MASK   1U

Macro for accessing the least significant bit of the ERR register.

The erroneous channels are retrieved from ERR register by subsequently right shifting all the ERR bits + "AND"-ing the result with this mask.

Definition at line 68 of file edma_driver.h.

#define STCD_ADDR (   address)    (((uint32_t)address + 31UL) & ~0x1FUL)

Definition at line 60 of file edma_driver.h.

#define STCD_SIZE (   number)    (((number) * 32U) - 1U)

Macro for the memory size needed for the software TCD.

Software TCD is aligned to 32 bytes. We don't need a software TCD structure for the first descriptor, since the configuration is pushed directly to registers. To make sure the software TCD can meet the eDMA module requirement regarding alignment, allocate memory for the remaining descriptors with extra 31 bytes.

Definition at line 59 of file edma_driver.h.

Typedef Documentation

typedef void(* edma_callback_t) (void *parameter, edma_chn_status_t status)

Definition for the eDMA channel callback function.

Prototype for the callback function registered in the eDMA driver. Implements : edma_callback_t_Class

Definition at line 266 of file edma_driver.h.

Enumeration Type Documentation

eDMA channel arbitration algorithm used for selection among channels. Implements : edma_arbitration_algorithm_t_Class

Enumerator
EDMA_ARBITRATION_FIXED_PRIORITY 

Fixed Priority

EDMA_ARBITRATION_ROUND_ROBIN 

Round-Robin arbitration

Definition at line 82 of file edma_driver.h.

eDMA channel interrupts. Implements : edma_channel_interrupt_t_Class

Enumerator
EDMA_CHN_ERR_INT 

Error interrupt

EDMA_CHN_HALF_MAJOR_LOOP_INT 

Half major loop interrupt.

EDMA_CHN_MAJOR_LOOP_INT 

Complete major loop interrupt.

Definition at line 73 of file edma_driver.h.

eDMA channel priority setting Implements : edma_channel_priority_t_Class

Enumerator
EDMA_CHN_PRIORITY_0 
EDMA_CHN_PRIORITY_1 
EDMA_CHN_PRIORITY_2 
EDMA_CHN_PRIORITY_3 
EDMA_CHN_DEFAULT_PRIORITY 

Definition at line 90 of file edma_driver.h.

Channel status for eDMA channel.

A structure describing the eDMA channel status. The user can get the status by callback parameter or by calling EDMA_DRV_getStatus() function. Implements : edma_chn_status_t_Class

Enumerator
EDMA_CHN_NORMAL 

eDMA channel normal state.

EDMA_CHN_ERROR 

An error occurred in the eDMA channel.

Definition at line 255 of file edma_driver.h.

eDMA modulo configuration Implements : edma_modulo_t_Class

Enumerator
EDMA_MODULO_OFF 
EDMA_MODULO_2B 
EDMA_MODULO_4B 
EDMA_MODULO_8B 
EDMA_MODULO_16B 
EDMA_MODULO_32B 
EDMA_MODULO_64B 
EDMA_MODULO_128B 
EDMA_MODULO_256B 
EDMA_MODULO_512B 
EDMA_MODULO_1KB 
EDMA_MODULO_2KB 
EDMA_MODULO_4KB 
EDMA_MODULO_8KB 
EDMA_MODULO_16KB 
EDMA_MODULO_32KB 
EDMA_MODULO_64KB 
EDMA_MODULO_128KB 
EDMA_MODULO_256KB 
EDMA_MODULO_512KB 
EDMA_MODULO_1MB 
EDMA_MODULO_2MB 
EDMA_MODULO_4MB 
EDMA_MODULO_8MB 
EDMA_MODULO_16MB 
EDMA_MODULO_32MB 
EDMA_MODULO_64MB 
EDMA_MODULO_128MB 
EDMA_MODULO_256MB 
EDMA_MODULO_512MB 
EDMA_MODULO_1GB 
EDMA_MODULO_2GB 

Definition at line 162 of file edma_driver.h.

eDMA transfer configuration Implements : edma_transfer_size_t_Class

Enumerator
EDMA_TRANSFER_SIZE_1B 
EDMA_TRANSFER_SIZE_2B 
EDMA_TRANSFER_SIZE_4B 

Definition at line 200 of file edma_driver.h.

A type for the DMA transfer. Implements : edma_transfer_type_t_Class.

Enumerator
EDMA_TRANSFER_PERIPH2MEM 

Transfer from peripheral to memory

EDMA_TRANSFER_MEM2PERIPH 

Transfer from memory to peripheral

EDMA_TRANSFER_MEM2MEM 

Transfer from memory to memory

EDMA_TRANSFER_PERIPH2PERIPH 

Transfer from peripheral to peripheral

Definition at line 305 of file edma_driver.h.

Function Documentation

void EDMA_DRV_CancelTransfer ( bool  error)

Cancel the running transfer.

This function cancels the current transfer, optionally signalling an error.

Parameters
boolerror If true, an error will be logged for the current transfer.

Definition at line 1485 of file edma_driver.c.

status_t EDMA_DRV_ChannelInit ( edma_chn_state_t edmaChannelState,
const edma_channel_config_t edmaChannelConfig 
)

Initializes an eDMA channel.

This function initializes the run-time state structure for a eDMA channel, based on user configuration. It will request the channel, set up the channel priority and install the callback.

Parameters
edmaChannelStatePointer to the eDMA channel state structure. The user passes the memory for this run-time state structure and the eDMA peripheral driver populates the members. This run-time state structure keeps track of the eDMA channel status. The memory must be kept valid before calling the EDMA_DRV_ReleaseChannel.
edmaChannelConfigUser configuration structure for eDMA channel. The user populates the members of this structure and passes the pointer of this structure into the function.
Returns
STATUS_ERROR or STATUS_SUCCESS.

Definition at line 287 of file edma_driver.c.

void EDMA_DRV_ClearTCD ( uint8_t  virtualChannel)

Clears all registers to 0 for the channel's TCD.

Parameters
virtualChanneleDMA virtual channel number.

Definition at line 1017 of file edma_driver.c.

status_t EDMA_DRV_ConfigLoopTransfer ( uint8_t  virtualChannel,
const edma_transfer_config_t transferConfig 
)

Configures the DMA transfer in loop mode.

This function configures the DMA transfer in a loop chain. The user passes a block of memory into this function that configures the loop transfer properties (minor/major loop count, address offsets, channel linking). The DMA driver copies the configuration to TCD registers, only when the loop properties are set up correctly and minor loop mapping is enabled for the eDMA module.

Parameters
virtualChanneleDMA virtual channel number.
transferConfigPointer to the transfer configuration strucutre; this structure defines fields for setting up the basic transfer and also a pointer to a memory strucure that defines the loop chain properties (minor/major).
Returns
STATUS_ERROR or STATUS_SUCCESS

Definition at line 708 of file edma_driver.c.

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.

This function configures the descriptor for a multi-block transfer. The function considers contiguous memory blocks, thus it configures the TCD source/destination offset fields to cover the data buffer without gaps, according to "transferSize" parameter (the offset is equal to the number of bytes transferred in a source read/destination write). The buffer is divided in multiple block, each block being transferred upon a single DMA request.

NOTE: For transfers to/from peripherals, make sure the transfer size is equal to the data buffer size of the peripheral used, otherwise only truncated chunks of data may be transferred (e.g. for a communication IP with an 8-bit data register the transfer size should be 1B, whereas for a 32-bit data register, the transfer size should be 4B). The rationale of this constraint is that, on the peripheral side, the address offset is set to zero, allowing to read/write data from/to the peripheral in a single source read/destination write operation.

Parameters
virtualChanneleDMA virtual channel number.
typeTransfer type (M->M, P->M, M->P, P->P).
srcAddrA source register address or a source memory address.
destAddrA destination register address or a destination memory address.
transferSizeThe number of bytes to be transferred on every DMA write/read. Source/Dest share the same write/read size.
blockSizeThe total number of bytes inside a block.
blockCountThe total number of data blocks (one block is transferred upon a DMA request).
disableReqOnCompletionThis parameter specifies whether the DMA channel should be disabled when the transfer is complete (further requests will remain untreated).
Returns
STATUS_ERROR or STATUS_SUCCESS

Definition at line 662 of file edma_driver.c.

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.

This function configures the descriptors into a single-ended chain. The user passes blocks of memory into this function. The interrupt is triggered only when the last memory block is completed. The memory block information is passed with the edma_scatter_gather_list_t data structure, which can tell the memory address and length. The DMA driver configures the descriptor for each memory block, transfers the descriptor from the first one to the last one, and stops.

Parameters
virtualChanneleDMA virtual channel number.
stcdArray of empty software TCD structures. The user must prepare this memory block. We don't need a software TCD structure for the first descriptor, since the configuration is pushed directly to registers.The "stcd" buffer must align with 32 bytes; if not, an error occurs in the eDMA driver. Thus, the required memory size for "stcd" is equal to tcdCount * size_of(edma_software_tcd_t) - 1; the driver will take care of the memory alignment if the provided memory buffer is big enough. For proper allocation of the "stcd" buffer it is recommended to use STCD_SIZE macro.
transferSizeThe number of bytes to be transferred on every DMA write/read.
bytesOnEachRequestBytes to be transferred in each DMA request.
srcListData structure storing the address, length and type of transfer (M->M, M->P, P->M, P->P) for the bytes to be transferred for source memory blocks. If the source memory is peripheral, the length is not used.
destListData structure storing the address, length and type of transfer (M->M, M->P, P->M, P->P) for the bytes to be transferred for destination memory blocks. In the memory-to-memory transfer mode, the user must ensure that the length of the destination scatter gather list is equal to the source scatter gather list. If the destination memory is a peripheral register, the length is not used.
tcdCountThe number of TCD memory blocks contained in the scatter gather list.
Returns
STATUS_ERROR or STATUS_SUCCESS

Definition at line 761 of file edma_driver.c.

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.

This function configures the descriptor for a single block transfer. The function considers contiguous memory blocks, thus it configures the TCD source/destination offset fields to cover the data buffer without gaps, according to "transferSize" parameter (the offset is equal to the number of bytes transferred in a source read/destination write).

NOTE: For memory-to-peripheral or peripheral-to-memory transfers, make sure the transfer size is equal to the data buffer size of the peripheral used, otherwise only truncated chunks of data may be transferred (e.g. for a communication IP with an 8-bit data register the transfer size should be 1B, whereas for a 32-bit data register, the transfer size should be 4B). The rationale of this constraint is that, on the peripheral side, the address offset is set to zero, allowing to read/write data from/to the peripheral in a single source read/destination write operation.

Parameters
virtualChanneleDMA virtual channel number.
typeTransfer type (M->M, P->M, M->P, P->P).
srcAddrA source register address or a source memory address.
destAddrA destination register address or a destination memory address.
transferSizeThe number of bytes to be transferred on every DMA write/read. Source/Dest share the same write/read size.
dataBufferSizeThe total number of bytes to be transferred.
Returns
STATUS_ERROR or STATUS_SUCCESS

Definition at line 554 of file edma_driver.c.

void EDMA_DRV_ConfigureInterrupt ( uint8_t  virtualChannel,
edma_channel_interrupt_t  intSrc,
bool  enable 
)

Disables/Enables the channel interrupt requests.

This function enables/disables error, half major loop and complete major loop interrupts for the current channel.

Parameters
virtualChanneleDMA virtual channel number.
interruptInterrupt event (error/half major loop/complete major loop).
enableEnable (true)/Disable (false) interrupts for the current channel.

Definition at line 1437 of file edma_driver.c.

status_t EDMA_DRV_Deinit ( void  )

De-initializes the eDMA module.

This function resets the eDMA module to reset state and disables the interrupt to the core.

Returns
STATUS_ERROR or STATUS_SUCCESS.

Definition at line 239 of file edma_driver.c.

void EDMA_DRV_DisableRequestsOnTransferComplete ( uint8_t  virtualChannel,
bool  disable 
)

Disables/Enables the DMA request after the major loop completes for the TCD.

If disabled, the eDMA hardware automatically clears the corresponding DMA request when the current major iteration count reaches zero.

Parameters
virtualChanneleDMA virtual channel number.
disableDisable (true)/Enable (false) DMA request after TCD complete.

Definition at line 1407 of file edma_driver.c.

edma_chn_status_t EDMA_DRV_GetChannelStatus ( uint8_t  virtualChannel)

Gets the eDMA channel status.

Parameters
virtualChanneleDMA virtual channel number.
Returns
Channel status.

Definition at line 1710 of file edma_driver.c.

uint32_t EDMA_DRV_GetRemainingMajorIterationsCount ( uint8_t  virtualChannel)

Returns the remaining major loop iteration count.

Gets the number minor loops yet to be triggered (major loop iterations).

Parameters
virtualChanneleDMA virtual channel number.
Returns
number of major loop iterations yet to be triggered

Definition at line 1346 of file edma_driver.c.

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.

This function initializes the run-time state structure to provide the eDMA channel allocation release, protect, and track the state for channels. This function also resets the eDMA modules, initializes the module to user-defined settings and default settings.

Parameters
edmaStateThe pointer to the eDMA peripheral driver state structure. The user passes the memory for this run-time state structure and the eDMA peripheral driver populates the members. This run-time state structure keeps track of the eDMA channels status. The memory must be kept valid before calling the EDMA_DRV_DeInit.
userConfigUser configuration structure for eDMA peripheral drivers. The user populates the members of this structure and passes the pointer of this structure into the function.
chnStateArrayArray of pointers to run-time state structures for eDMA channels; will populate the state structures inside the eDMA driver state structure.
chnConfigArrayArray of pointers to channel initialization structures.
chnCountThe number of eDMA channels to be initialized.
Returns
STATUS_ERROR or STATUS_SUCCESS.

Definition at line 119 of file edma_driver.c.

status_t EDMA_DRV_InstallCallback ( uint8_t  virtualChannel,
edma_callback_t  callback,
void *  parameter 
)

Registers the callback function and the parameter for eDMA channel.

This function registers the callback function and the parameter into the eDMA channel state structure. The callback function is called when the channel is complete or a channel error occurs. The eDMA driver passes the channel status to this callback function to indicate whether it is caused by the channel complete event or the channel error event.

To un-register the callback function, set the callback function to "NULL" and call this function.

Parameters
virtualChanneleDMA virtual channel number.
callbackThe pointer to the callback function.
parameterThe pointer to the callback function's parameter.
Returns
STATUS_ERROR or STATUS_SUCCESS.

Definition at line 336 of file edma_driver.c.

void EDMA_DRV_PushConfigToReg ( uint8_t  virtualChannel,
const edma_transfer_config_t tcd 
)

Copies the channel configuration to the TCD registers.

Parameters
virtualChanneleDMA virtual channel number.
tcdPointer to the channel configuration structure.

Definition at line 1587 of file edma_driver.c.

void EDMA_DRV_PushConfigToSTCD ( const edma_transfer_config_t config,
edma_software_tcd_t stcd 
)

Copies the channel configuration to the software TCD structure.

This function copies the properties from the channel configuration to the software TCD structure; the address of the software TCD can be used to enable scatter/gather operation (pointer to the next TCD).

Parameters
configPointer to the channel configuration structure.
stcdPointer to the software TCD structure.

Definition at line 1543 of file edma_driver.c.

status_t EDMA_DRV_ReleaseChannel ( uint8_t  virtualChannel)

Releases an eDMA channel.

This function stops the eDMA channel and disables the interrupt of this channel. The channel state structure can be released after this function is called.

Parameters
virtualChanneleDMA virtual channel number.
Returns
STATUS_ERROR or STATUS_SUCCESS.

Definition at line 421 of file edma_driver.c.

status_t EDMA_DRV_SetChannelRequest ( uint8_t  virtualChannel,
uint8_t  req 
)

Configures the DMA request for the eDMA channel.

Selects which DMA source is routed to a DMA channel. The DMA sources are defined in the file <MCU>_Features.h

Parameters
virtualChanneleDMA virtual channel number.
reqDMA request source.
Returns
STATUS_SUCCESS.

Definition at line 983 of file edma_driver.c.

void EDMA_DRV_SetDestAddr ( uint8_t  virtualChannel,
uint32_t  address 
)

Configures the destination address for the eDMA channel.

Parameters
virtualChanneleDMA virtual channel number.
addressThe pointer to the destination memory address.

Definition at line 1196 of file edma_driver.c.

void EDMA_DRV_SetDestLastAddrAdjustment ( uint8_t  virtualChannel,
int32_t  adjust 
)

Configures the destination address last adjustment.

Adjustment value added to the destination address at the completion of the major iteration count. This value can be applied to restore the destination address to the initial value, or adjust the address to reference the next data structure.

Parameters
virtualChanneleDMA virtual channel number.
adjustAdjustment value.

Definition at line 1166 of file edma_driver.c.

void EDMA_DRV_SetDestOffset ( uint8_t  virtualChannel,
int16_t  offset 
)

Configures the destination address signed offset for the eDMA channel.

Sign-extended offset applied to the current destination address to form the next-state value as each destination write is complete.

Parameters
virtualChanneleDMA virtual channel number.
offsetsigned-offset

Definition at line 1226 of file edma_driver.c.

void EDMA_DRV_SetDestWriteChunkSize ( uint8_t  virtualChannel,
edma_transfer_size_t  size 
)

Configures the destination data chunk size (transferred in a write sequence).

Destination data write transfer size (1/2/4/16/32 bytes).

Parameters
virtualChanneleDMA virtual channel number.
sizeDestination transfer size.

Definition at line 1256 of file edma_driver.c.

void EDMA_DRV_SetMajorLoopIterationCount ( uint8_t  virtualChannel,
uint32_t  majorLoopCount 
)

Configures the number of major loop iterations.

Sets the number of major loop iterations; each major loop iteration will be served upon a request for the current channel, transferring the data block configured for the minor loop (NBYTES).

Parameters
virtualChanneleDMA virtual channel number.
majorLoopCountNumber of major loop iterations.

Definition at line 1316 of file edma_driver.c.

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.

Sets the number of bytes to be transferred each time a request is received (one major loop iteration). This number needs to be a multiple of the source/destination transfer size, as the data block will be transferred within multiple read/write sequences (minor loops).

Parameters
virtualChanneleDMA virtual channel number.
nbytesNumber of bytes to be transferred in each service request of the channel

Definition at line 1286 of file edma_driver.c.

void EDMA_DRV_SetScatterGatherLink ( uint8_t  virtualChannel,
uint32_t  nextTCDAddr 
)

Configures the memory address of the next TCD, in scatter/gather mode.

This function configures the address of the next TCD to be loaded form memory, when scatter/gather feature is enabled. This address points to the beginning of a 0-modulo-32 byte region containing the next transfer TCD to be loaded into this channel. The channel reload is performed as the major iteration count completes. The scatter/gather address must be 0-modulo-32-byte. Otherwise, a configuration error is reported.

Parameters
virtualChanneleDMA virtual channel number.
nextTCDAddrThe address of the next TCD to be linked to this TCD.

Definition at line 1377 of file edma_driver.c.

void EDMA_DRV_SetSrcAddr ( uint8_t  virtualChannel,
uint32_t  address 
)

Configures the source address for the eDMA channel.

Parameters
virtualChanneleDMA virtual channel number.
addressThe pointer to the source memory address.

Definition at line 1046 of file edma_driver.c.

void EDMA_DRV_SetSrcLastAddrAdjustment ( uint8_t  virtualChannel,
int32_t  adjust 
)

Configures the source address last adjustment.

Adjustment value added to the source address at the completion of the major iteration count. This value can be applied to restore the source address to the initial value, or adjust the address to reference the next data structure.

Parameters
virtualChanneleDMA virtual channel number.
adjustAdjustment value.

Definition at line 1136 of file edma_driver.c.

void EDMA_DRV_SetSrcOffset ( uint8_t  virtualChannel,
int16_t  offset 
)

Configures the source address signed offset for the eDMA channel.

Sign-extended offset applied to the current source address to form the next-state value as each source read is complete.

Parameters
virtualChanneleDMA virtual channel number.
offsetSigned-offset for source address.

Definition at line 1076 of file edma_driver.c.

void EDMA_DRV_SetSrcReadChunkSize ( uint8_t  virtualChannel,
edma_transfer_size_t  size 
)

Configures the source data chunk size (transferred in a read sequence).

Source data read transfer size (1/2/4/16/32 bytes).

Parameters
virtualChanneleDMA virtual channel number.
sizeSource transfer size.

Definition at line 1106 of file edma_driver.c.

status_t EDMA_DRV_StartChannel ( uint8_t  virtualChannel)

Starts an eDMA channel.

This function enables the eDMA channel DMA request.

Parameters
virtualChanneleDMA virtual channel number.
Returns
STATUS_ERROR or STATUS_SUCCESS.

Definition at line 921 of file edma_driver.c.

status_t EDMA_DRV_StopChannel ( uint8_t  virtualChannel)

Stops the eDMA channel.

This function disables the eDMA channel DMA request.

Parameters
virtualChanneleDMA virtual channel number.
Returns
STATUS_ERROR or STATUS_SUCCESS.

Definition at line 952 of file edma_driver.c.

void EDMA_DRV_TriggerSwRequest ( uint8_t  virtualChannel)

Triggers a sw request for the current channel.

This function starts a transfer using the current channel (sw request).

Parameters
virtualChanneleDMA virtual channel number.

Definition at line 1514 of file edma_driver.c.