Direct Memory Access Controller (DMAC)

Introduction

General Direct Memory Access (GDMA) Controller, also known as DMAC, is used to transfer data between memory and peripherals. The data transfer process does not require CPU intervention, thereby reducing the CPU workload. The architecture diagram of DMAC is shown below:

../../_images/dmac_arch.svg

DMAC supports the following features:

RTL8721Dx:

  • Supports up to 8 independent channels. The source and destination ports of each channel can be freely assigned to Memory or peripherals with DMAC capability.

  • Supports channel priority configuration.

  • Supports multiple transfer directions:

    • Peripheral to Memory

    • Peripheral to Peripheral

    • Memory to Peripheral

    • Memory to Memory

  • Each channel is equipped with an independent FIFO. The FIFO size varies across channels to suit different application scenarios.

  • Flexible flow control options: users can configure the transfer request and pacing to be controlled by the source peripheral, destination peripheral, or the DMAC itself.

  • Supports both single and burst transfer modes.

  • Supports single block and multiple block data transfers.

  • Supports secure transfer mode.

  • Supports low power consumption operation.

  • Supports pause, resume, and disable of channels during data transfers without data loss.

DMAC Configuration

The general DMA configuration process is as follows:

  1. Initialize clock: Enable DMA controller (DMAC) clock

  2. Configure relevant DMA channel

    1. Allocate a free DMA channel

    2. Set channel control parameters according to application requirements

      1. Transfer direction and flow control: such as memory-to-peripheral, peripheral-to-memory, and whether the source or destination peripheral or DMAC controls transfer requests and pace

      2. Source port and destination port addresses

      3. Transfer width (1/2/4 Bytes)

      4. Burst length msize (1/4/8/16)

      5. Transfer block size (Block Size)

      6. Priority setting

  3. Enable channel interrupt (for transfer complete/error notification, if needed)

  4. Start data transfer: Set channel enable bit, start DMA channel, peripheral/DMAC initiates DMA request, and begin data transfer

  5. Completion and post-processing

    1. DMA transfer generates an interrupt after completion

    2. Handle completion signal and release resources in the interrupt service routine

DMA parameter illustration:

../../_images/dmac_block_size_diagram.svg

Channel Allocation and Release

DMA implements channel allocation and release through the following two APIs:

  • GDMA_ChnlAlloc(): Allocates channels sequentially, starting from channel 0.

  • GDMA_ChnlFree(): Releases a channel according to the specified channel number.

During the channel allocation process, it is possible that two CPUs may request the same channel simultaneously, which can cause the program to run abnormally. To solve this issue, a hardware semaphore is used for protection during the channel allocation process.

Transfer Direction and Flow Controller

There are currently four transfer directions and two flow controller settings, resulting in eight available configurations.

  • When the peripheral is set as the flow controller, the DMA transfers data based on the single/burst requests from the peripheral.

  • When the DMAC is set as the flow controller, all requests from the peripheral will be processed according to the configured request type.

CTLx.TT_FC[2:0] (x is channel)

Direction

Flow Controller

000

Memory to Memory

DMAC

001

Memory to Peripheral

DMAC

010

Peripheral to Memory

DMAC

011

Peripheral to Peripheral

DMAC

100

Peripheral to Memory

Peripheral

101

Peripheral to Peripheral

Source Peripheral

110

Memory to Peripheral

Peripheral

111

Peripheral to Peripheral

Destination Peripheral

Principles of Flow Controller Configuration:

  • If the block_ts is known, use DMAC as the flow controller. For example: music playback, image display, and memory copy operations.

  • If the block_ts is unknown, use the peripheral as the flow controller. For example: when UART receives variable-length data, UART can be set as the flow controller so that a transfer is requested each time data arrives.

Warning

  • The block_ts parameter can only be set when DMAC is used as the flow controller.

  • When using a peripheral as the flow controller, make sure that the IP supports triggering DMA requests in the hardware design. For more details, please refer to the Handshake section.

Data Block Size

RTL8721Dx:

The above diagram illustrates the configuration of the DMAC transfer data size. block_ts specifies the amount of data to be transferred in a single data block and should be set to total data size/SRC_TR_WIDTH, with a maximum value of {{IC_PARAM_GDMA_BLOCK_SIZE}}.

Transaction Mode and Width

The transaction size for each DMAC transfer can be configured:

  • msize > 1: Burst transfer

  • msize = 1: Single transfer

CTLx.SRC_MSIZE[2:0]/DEST_MSIZE[2:0]

Transfer msize

000

1

001

4

010

8

011

16

100 and above

Not supported

DMAC supports the following transfer widths:

CTLx.SRC_TR_WIDTH[2:0]/DST_TR_WIDTH[2:0]

Transfer Width/Bytes

000

1

001

2

010

4

011 and above

Not supported

  • When DMAC acts as the flow controller, if the remaining data in a block is not enough for a Msize * Width transfer but is sufficient for a 1 * Width transfer, DMAC will initiate a single transfer request to complete the transfer.

  • When the peripheral is the flow controller, the peripheral decides whether to issue a single transfer or burst transfer request.

Note

  • When accessing peripheral: SRC_TR_WIDTH/DST_TR_WIDTH should be set according to the data width of the peripheral.

  • When accessing memory:

    • If cache is disabled, the memory address does not need to be aligned, but the total data must be divisible by SRC_TR_WIDTH to ensure block_ts remains an integer.

    • If cache is enabled, the memory address must meet the buffer boundary alignment and align to the cache line.

  • When the source or destination is memory (e.g., P2M, M2M modes): the hardware will force the memory side transfer width to 4 Bytes, and the configured DST_TR_WIDTH or SRC_TR_WIDTH parameter for memory will be ignored.

  • To prevent FIFO underflow or overflow, SRC_MSIZE * SRC_TR_WIDTH and DST_MSIZE * DST_TR_WIDTH must remain equal.

Transfer Types

DMAC supports the following transfer types:

  • Single Block: Contains only one data block

  • Multi-Block: Contains multiple data blocks

    • Auto-reloading mode

    • Link List mode

    • Continuous mode

The usage scenarios and features of each mode are as follows:

DMAC Modes Features

Mode

Sub-mode

Application Scenario

Features

Single Block

Continuous address space, single transfer

  • DMA stops immediately after the transfer is complete

Multi-Block

auto-reload

Continuous address space where the source or destination needs to repeatedly reload a particular data block

  • If block interrupt is enabled, DMA pauses after each block transfer until the interrupt is processed

Link List

Non-contiguous address space

  • If block interrupt is enabled, an interrupt is triggered after each block transfer, but the next block transfer starts immediately

  • In this mode, DMA data transfer is not blocked even during interrupts

continuous

Continuous data block in a single address space

  • Always uses address increment mode; if both source and destination are in continuous mode, the transfer is the same as single block mode.

  • Typically used when only one side is continuous and the other side uses auto-reload or Link List mode

Auto-reloading Mode

In auto-reloading mode, the source and destination can independently select which method to use.

Auto-reloading transfer types

Setting

Introduction

Src auto reload

PGDMA_InitTypeDef->GDMA_ReloadSrc = 1

PGDMA_InitTypeDef->GDMA_ReloadDst = 0

For multi-block transfers, the SAR register can be auto-reloaded from the initial value at the end of each block,

and DST address is contiguous, as shown in Multi-block DMA transfer with source address auto-reloaded and contiguous destination address..

Dst auto reload

PGDMA_InitTypeDef->GDMA_ReloadSrc = 0

PGDMA_InitTypeDef->GDMA_ReloadDst = 1

For multi-block transfers, the DAR register can be auto-reloaded from its initial value at

the end of each block, and the SRC address is contiguous.

Src & Dst auto reload

PGDMA_InitTypeDef->GDMA_ReloadSrc = 1

PGDMA_InitTypeDef->GDMA_ReloadDst = 1

For multi-block transfers, the SAR and DAR register can be auto-reloaded from its initial value at the end of each

block, as shown in Multi-block DMA transfer with source and destination address auto-reloaded..
../../_images/mbd_source_auto_dest_cont.png

Multi-block DMA transfer with source address auto-reloaded and contiguous destination address.

../../_images/mbd_source_dest_auto.png

Multi-block DMA transfer with source and destination address auto-reloaded.

Address Increment Type

Source Address Increment

There are two modes:

  • Increment: Indicates whether to increment the source address on every source transfer. Incrementing is done for alignment to the next CTLx.SRC_TR_WIDTH boundary.

  • No change: If the device is fetching data from a source peripheral FIFO with a fixed address, then set this field to No change.

Destination Address Increment

There are two modes:

  • Increment: indicates whether to increment destination address on every destination transfer. Incrementing is done for alignment to the next CTLx.DST_TR_WIDTH boundary.

  • No change: If the device is writing data to a destination peripheral FIFO with a fixed address, then set this field to No change.

Configuration Principles:

  • If the source or destination is Memory, the address mode is generally set to Increment.

  • If the source or destination is a Peripheral, the address mode is generally set to No Change.

FIFO

Each DMAC channel has its own independent FIFO, and the FIFO sizes of different channels are not the same.

RTL8721Dx:
FIFO Size

Channel Number

CH0

CH1

CH2~CH7

FIFO size/Bytes

128

128

32

Interrupt Type

There are several supported interrupt types, which can be used independently or in combination.

Interrupt type

Introduction

block interrupt

Triggered by the completion of a data block transfer

transfer interrupt

Occurs when all data blocks have been transferred

error interrupt

There was a transfer error

Note

  • In multi-block auto-reload mode, a block interrupt pauses the transfer after each block until the interrupt handler completes.

  • In Link List mode, the transfer-complete condition is that the last data block’s next-block pointer is null.

  • In Link List mode, a block interrupt does not pause the transfer; the next block transfer starts immediately.

Suspend and Abort

DMAC supports channel suspend resume and termination.

  • To suspend a channel, just configure CFGx.CH_SUSP, but there is no guarantee that the current data transaction is completed. Combined with CFGx.INACTIVE, the channel can be safely paused without losing data.

  • To resume data transmission after suspension, clear CFGx.CH_SUSP.

  • To terminate data transfer, CFGx.INACTIVE must be continuously polled until this bit is set to 1, then the data transfer can be aborted.

Note

CFGx.INACTIVE indicates whether the channel is idle on the AXI bus (1 = inactive, 0 = active). It can be used together with CFGx.CH_SUSP to cleanly disable a channel when the destination is a peripheral. The channel becomes inactive in the following situations:

  • After the DMAC has finished writing all pending data to memory, CFGx.INACTIVE is set to 1 automatically.

  • If the peripheral data width (e.g. 4 bytes) exceeds the remaining DMAC FIFO space (e.g. 2 bytes), no write can be initiated and CFGx.INACTIVE is set to 1 immediately.

Gather and Scatter

RTL8721Dx:

Not supported.

Priority

DMAC supports two kinds of channel priority:

  • Software: the priority of each channel can be configured in the CFGx.CH_PRIOR. The valid value is 0 ~ (DMAC_NUM_CHANNELS-1), where 0 is the highest priority value and (DMAC_NUM_CHANNELS-1) is the lowest priority value.

  • Hardware: if two channel requests have the same software priority level, or if no software priority is configured, the channel with the lower number takes priority over the channel with the higher number. For example, channel 2 takes priority over channel 4.

Handshake

DMAC supports only hardware handshake and does not support software handshake. The handshake interface needs to be configured only when transferring data between DMAC and peripherals. All hardware handshake interfaces are fixed during IC design and cannot be modified by users. The hardware handshake interfaces supported by the current IC and their corresponding IPs are listed in the following table:

RTL8721Dx:
DMAC Handshake Interface

Function

Handshake No.

Description

UART0 TX

0

UART0 RX

1

UART1 TX

2

UART1 RX

3

UART2 TX

4

UART2 RX

5

SPI0 TX

6

SPI0 RX

7

SPI1 TX

8

SPI1 RX

9

SPIC TX

10

SPIC RX

11

SPORT0 TX

12

Two FIFOs, occupies 12 & 13

SPORT0 RX

14

Two FIFOs, occupies 14 & 15

SPORT1 TX

16

Two FIFOs, occupies 16 & 17

SPORT1 RX

18

Two FIFOs, occupies 18 & 19

LEDC_TX

20

I2C0 TX

21

I2C0 RX

22

I2C1 TX

23

I2C1 RX

24

Real-time Status Acquisition

DMAC supports real-time acquisition of the current transmission source address, destination address and the data size that has been transmitted. Call the corresponding APIs to read.

Note

To get the amount of data that has been transferred, the block_ts must be greater than 768, and cannot be read in an interrupt function; otherwise, the value obtained is always 0.

Security Mechanism

By default, the secure transfer feature of DMAC is disabled. When users need to use this feature, they must first enable the Trustzone feature .

DMAC supports independent configuration of the secure transfer feature for each channel. Once this feature is enabled, the DMAC will initiate secure access requests through the AXI master interface. At this point, DMAC can transfer data between secure and non-secure peripherals (or memory).

  • Secure channels can only be configured within the secure world, and secure channels can access both secure peripherals (memory) and non-secure peripherals (memory).

  • Non-secure channels can only access non-secure peripherals (memory).

To enable the secure transfer feature for a specific channel, set the following structure member when configuring DMAC parameters in Secure code:

PGDMA_InitTypeDef->SecureTransfer = 1;

DMA and Cache

When using DMA to transfer data between memory regions or between memory and peripherals, if the cache is also enabled, attention must be paid to the problem of cache and memory data inconsistency.

DMA TX

When the DMA source is memory and you need to send data, the general process is as follows:

  1. Allocate a transmission buffer, ensuring that the starting address and size are aligned with the cache line.

  2. The CPU writes data into the memory buffer.

  3. Call the DCache_Clean() function to clean the data cache.

  4. Configure DMA transmission parameters.

  5. Start DMA transfer.

DMA RX

  1. The CPU allocates a receive buffer.

  2. Execute DCache_Clean() to ensure the receive buffer is in a clean state (if the receive buffer is already clean, this step can be skipped).

    Caution

    The reason for this step is:

    • For Cortex-A32, if the receive buffer in the cache is in a dirty state, executing step 5 DCache_Invalidate() will perform both clean and invalidate operations, which may lead to unexpected write actions.

    • If the receive buffer in the cache is dirty, when the CPU’s D-Cache is full, the CPU may write back dirty data in the receive buffer to memory, overwriting the content already written by DMA.

  3. Configure DMA Rx parameters.

  4. Configure and enable the DMA Rx interrupt handler.

  5. Execute DCache_Invalidate() to invalidate cache data and ensure that there is no residual old data from the receive buffer in the cache.

Caution

This step must be performed for the following reasons:

  • For CPUs with automatic data prefetch (such as Cortex-A32 and DSP), when the CPU reads addresses adjacent to the receive buffer, the CPU will perform a line fill operation in the background and automatically reload the old value of the receive buffer into the cache.

  • This prevents the CPU from reading old values into the cache during DMA processing.

  1. The CPU reads the receive buffer (the value returned by DMA Rx).

Note

Aligning the buffer address with the cache line will reduce the problem of inconsistent cache and memory data.

DMAC Demos

Single Block

  1. Allocate a free channel

    ch_num = GDMA_ChnlAlloc(gdma.index, (IRQ_FUN) Dma_memcpy_int, (u32)(&gdma), 3);

    This function also includes the following operation:

    • Register IRQ handler if using interrupt mode

    • Enable NVIC interrupt

    • Register the DMAC channel to use

  2. Configure the interrupt type

    PGDMA_InitTypeDef->GDMA_IsrType = (TransferType | ErrType);

  3. Configure interrupt handling function

    Clear the pending interrupt in the interrupt processing function.

    GDMA_ClearINT(0, PGDMA_InitTypeDef->GDMA_ChNum);

  4. Configure transfer settings

    PGDMA_InitTypeDef->GDMA_SrcMsize   = MsizeEight;
PGDMA_InitTypeDef->GDMA_SrcDataWidth = TrWidthFourBytes;
PGDMA_InitTypeDef->GDMA_DstMsize = MsizeEight;
PGDMA_InitTypeDef->GDMA_DstDataWidth = TrWidthFourBytes;
PGDMA_InitTypeDef->GDMA_BlockSize = DMA_CPY_LEN >> 2;
PGDMA_InitTypeDef->GDMA_DstInc = IncType; // if dst type is peripheral:no change
PGDMA_InitTypeDef->GDMA_SrcInc = IncType; // if src type is peripheral:no change

  5. Configure hardware handshake interface if slave is peripheral

    PGDMA_InitTypeDef->GDMA_SrcHandshakeInterface= GDMA_HANDSHAKE_INTERFACE_AUDIO_RX;

    or

    PGDMA_InitTypeDef->GDMA_DstHandshakeInterface = GDMA_HANDSHAKE_INTERFACE_AUDIO_TX;

  6. Configure the transfer address

    PGDMA_InitTypeDef->GDMA_SrcAddr = (u32)BDSrcTest;
PGDMA_InitTypeDef->GDMA_DstAddr = (u32)BDDstTest;

  7. Program DMAC index, DMAC channel, data width, msize, transfer direction, address increment mode, hardware handshake interface, reload control, interrupt type, block size, multi-block configuration and the source and destination address using the GDMA_Init() function.

    GDMA_Init(gdma.index, gdma.ch_num, PGDMA_InitTypeDef);

  8. Clean and invalidate Cache

    DCache_CleanInvalidate();

  9. Enable DMAC channel

    GDMA_Cmd(gdma.index, gdma.ch_num, ENABLE);

Multi-block

This example is SRC auto reload, compared with single block, multi-block is different in Step 2 to Step 4.

  1. Allocate a free channel

    ch_num = GDMA_ChnlAlloc(gdma.index, (IRQ_FUN) Dma_memcpy_int, (u32)(&gdma), 3);

    This function also includes the following operation:

    • Register IRQ handler if use interrupt mode

    • Enable NVIC interrupt

    • Register the DMAC channel to use

  1. Configure the interrupt type

    PGDMA_InitTypeDef->GDMA_IsrType = (BlockType | TransferType | ErrType);

  2. Configure interrupt handling function

    1. Clear the interrupt.

      GDMA_ClearINT(0, PGDMA_InitTypeDef->GDMA_ChNum);

    2. Clear the auto reload mode before the last block starts.

      GDMA_ChCleanAutoReload(0, PGDMA_InitTypeDef->GDMA_ChNum, CLEAN_RELOAD_SRC);

  1. Configure transfer settings

    PGDMA_InitTypeDef->GDMA_SrcMsize   = MsizeEight;
PGDMA_InitTypeDef->GDMA_SrcDataWidth = TrWidthFourBytes;
PGDMA_InitTypeDef->GDMA_DstMsize = MsizeEight;
PGDMA_InitTypeDef->GDMA_DstDataWidth = TrWidthFourBytes;
PGDMA_InitTypeDef->GDMA_BlockSize = DMA_CPY_LEN >> 2;
PGDMA_InitTypeDef->GDMA_DstInc = IncType; // If DST type is peripheral: no change
PGDMA_InitTypeDef->GDMA_SrcInc = IncType; // If SRC type is peripheral: no change
PGDMA_InitTypeDef->GDMA_ReloadSrc = 1;
PGDMA_InitTypeDef->GDMA_ReloadDst = 0;

  2. Configure hardware handshake interface if slave is peripheral.

    PGDMA_InitTypeDef->GDMA_SrcHandshakeInterface= GDMA_HANDSHAKE_INTERFACE_AUDIO_RX;

    or

    PGDMA_InitTypeDef->GDMA_DstHandshakeInterface = GDMA_HANDSHAKE_INTERFACE_AUDIO_TX;

  3. Configure the transfer address

    PGDMA_InitTypeDef->GDMA_SrcAddr = (u32)BDSrcTest;
PGDMA_InitTypeDef->GDMA_DstAddr = (u32)BDDstTest;

  4. Program DMAC index, DMAC channel, data width, msize, transfer direction, address increment mode, hardware handshake interface, reload control, interrupt type, block size, multi-block configuration and the source and destination address using the GDMA_Init() function.

    GDMA_Init(gdma.index, gdma.ch_num, PGDMA_InitTypeDef);

  5. Clean and invalidate Cache

    DCache_CleanInvalidate();

  6. Enable DMAC channel

    GDMA_Cmd(gdma.index, gdma.ch_num, ENABLE);

Raw API

GDMA Exported Types

struct GDMA_CH_LLI

GDMA CH LLI Structure Definition.

Public Members

GDMA_CH_LLI_ELE LliEle

Specifies the GDMA Linked List Item Element structure field of Linked List Item in block chaining. This structure variable stores the necessary parameters of a block descriptor.

u32 BlockSize

Specifies the GDMA block size of one block in block chaining. This parameter indicates the block size of the current block transfer.

struct GDMA_CH_LLI *pNextLli

Specifies the GDMA Linked List Item pointer. This parameter stores the address pointing to the next Linked List Item in block chaining.

struct GDMA_CH_LLI_ELE

GDMA LLI ELE Structure Definition.

Public Members

u32 Sarx

Specifies the GDMA channel x Source Address Register (SARx) value field of a block descriptor in block chaining. This parameter stores the source address of the current block transfer.

u32 Darx

Specifies the GDMA channel x Destination Address Register(DARx) value field of a block descriptor in block chaining. This parameter stores the destination address of the current block transfer.

u32 Llpx

Specifies the GDMA channel x Linked List Pointer Register(LLPx) value field of a block descriptor in block chaining. This parameter is a address, which points to the next block descriptor.

u32 CtlxLow

Specifies the GDMA channel x Control Register(CTRx) Low 32 bit value field of a block descriptor in block chaining. This parameter stores the DMA control parameters of the current block transfer.

u32 CtlxUp

Specifies the GDMA channel x Control Register(CTRx) High 32 bit value field of a block descriptor in block chaining. This parameter stores the DMA control parameters of the current block transfer.

u32 Temp

Specifies the reserved GDMA channel x register value field of a block descriptor in block chaining.

struct GDMA_InitTypeDef

GDMA Init Structure Definition.

Public Members

u8 GDMA_Index

Specifies the GDMA index. This parameter can be the value 0.

u8 GDMA_ChNum

Specifies the GDMA channel number. This parameter can be the value 0 ~ 7.

u8 GDMA_ChPrior

Specifies the GDMA channel priority. This parameter can be the value 0 ~ 7, while 0 for highest priority. If more than one channel are set with the same priority value, the channel with small channel number index has higher priority.

u32 GDMA_DIR

Specifies the GDMA transmission direction. This parameter can be a value of GDMA Data Transfer Direction.

u32 GDMA_DstDataWidth

Specifies the GDMA destination transfer width. This parameter can be a value of GDMA Data Size.

u32 GDMA_SrcDataWidth

Specifies the GDMA transfer width. This parameter can be a value of GDMA Data Size.

u32 GDMA_DstInc

Specifies the GDMA destination address increment mode. This parameter can be a value of GDMA Increment Mode.

u32 GDMA_SrcInc

Specifies the GDMA source address increment mode. This parameter can be a value of GDMA Increment Mode.

u32 GDMA_DstMsize

Specifies the GDMA destination burst transaction length. This parameter can be a value of GDMA Msize.

u32 GDMA_SrcMsize

Specifies the GDMA source burst transaction length. This parameter can be a value of GDMA Msize.

u32 GDMA_SrcAddr

Specifies the GDMA source address. This parameter can be a value of the memory or peripheral space address, depending on the GDMA data transfer direction.If this address is configured, GDMA will move data from here to the destination address space.

u32 GDMA_DstAddr

Specifies the GDMA destination address. This parameter can be a value of the memory or peripheral space address, depending on the GDMA data transfer direction.If this address is configured, GDMA will move data here from source address space.

u32 GDMA_BlockSize

Specifies the GDMA block transfer size. This parameter indicates the total number of single transactions for every block transfer.

u32 GDMA_IsrType

Specifies the GDMA interrupt types. This parameter can be a value of GDMA Interrupt Type.

u32 GDMA_ReloadSrc

Specifies the GDMA automatic source reload . This parameter can be the 0 or 1.(0 : disable / 1 : enable). If this value is set to 1, source address register can be automatically reloaded from its initial value at the end of every block for multi-block transfers. This parameter is only valid in multi block transmission mode.

u32 GDMA_ReloadDst

Specifies the GDMA automatic destination reload . This parameter can be the 0 or 1.(0 : disable / 1 : enable). If this parameter is set 1, destination address register can be automatically reloaded from its initial value at the end of every block for multi-block transfers. This parameter is only valid in multi block transmission mode.

u32 GDMA_LlpDstEn

Specifies the GDMA whether block chaining is enabled or disabled on the destination side only. This parameter is only valid in multi-block transmission mode.

u32 GDMA_LlpSrcEn

Specifies the GDMA whether block chaining is enabled or disabled on the source side only. This parameter is only valid in multi-block transmission mode.

u32 GDMA_SrcHandshakeInterface

Specifies the GDMA hardware handshaking interface for the source peripheral of a GDMA channel. This parameter can be a value of GDMA0 HS HandShake Interface.

u32 GDMA_DstHandshakeInterface

Specifies the GDMA hardware handshaking interface for the destination peripheral of a GDMA channel. This parameter can be a value of GDMA0 HS HandShake Interface.

u32 MuliBlockCunt

Specifies the GDMA Multi-block counter. This parameter is used in multi-block transmission.

u32 MaxMuliBlock

Specifies the GDMA Max block number in Multi-block transmission. This parameter is used in multi-block transmission.

u32 SecureTransfer

Specifies the GDMA secure transmission. This parameter is used in secure world of trustzone.

typedef struct GDMA_CH_LLI_ELE *PGDMA_CH_LLI_ELE
typedef struct GDMA_InitTypeDef *PGDMA_InitTypeDef

GDMA Exported Constants

GDMA0 HS HandShake Interface

/* Handshake interface for UART0 TX. */
#define GDMA_HANDSHAKE_INTERFACE_UART0_TX (0)

/* Handshake interface for UART0 RX. */
#define GDMA_HANDSHAKE_INTERFACE_UART0_RX (1)

/* Handshake interface for UART1 TX. */
#define GDMA_HANDSHAKE_INTERFACE_UART1_TX (2)

/* Handshake interface for UART1 RX. */
#define GDMA_HANDSHAKE_INTERFACE_UART1_RX (3)

/* Handshake interface for UART2 TX. */
#define GDMA_HANDSHAKE_INTERFACE_UART2_TX (4)

/* Handshake interface for UART2 RX. */
#define GDMA_HANDSHAKE_INTERFACE_UART2_RX (5)
RTL8721Dx: 
/* Handshake interface for SPI0 TX. */
#define GDMA_HANDSHAKE_INTERFACE_SPI0_TX (6)

/* Handshake interface for SPI0 RX. */
#define GDMA_HANDSHAKE_INTERFACE_SPI0_RX (7)

/* Handshake interface for SPI1 TX. */
#define GDMA_HANDSHAKE_INTERFACE_SPI1_TX (8)

/* Handshake interface for SPI1 RX. */
#define GDMA_HANDSHAKE_INTERFACE_SPI1_RX (9)

/* Handshake interface for SPIC TX. */
#define GDMA_HANDSHAKE_INTERFACE_SPIC_TX (10)

/* Handshake interface for SPIC RX. */
#define GDMA_HANDSHAKE_INTERFACE_SPIC_RX (11)

/* Handshake interface for SPORT0 FIFO0 TX. */
#define GDMA_HANDSHAKE_INTERFACE_SPORT0F0_TX (12)

/* Handshake interface for SPORT0 FIFO1 TX. */
#define GDMA_HANDSHAKE_INTERFACE_SPORT0F1_TX (13)

/* Handshake interface for SPORT0 FIFO0 RX. */
#define GDMA_HANDSHAKE_INTERFACE_SPORT0F0_RX (14)

/* Handshake interface for SPORT0 FIFO1 RX. */
#define GDMA_HANDSHAKE_INTERFACE_SPORT0F1_RX (15)

/* Handshake interface for SPORT1 FIFO0 TX. */
#define GDMA_HANDSHAKE_INTERFACE_SPORT1F0_TX (16)

/* Handshake interface for SPORT1 FIFO1 TX. */
#define GDMA_HANDSHAKE_INTERFACE_SPORT1F1_TX (17)

/* Handshake interface for SPORT1 FIFO0 RX. */
#define GDMA_HANDSHAKE_INTERFACE_SPORT1F0_RX (18)

/* Handshake interface for SPORT1 FIFO1 RX. */
#define GDMA_HANDSHAKE_INTERFACE_SPORT1F1_RX (19)

/* Handshake interface for LEDC TX. */
#define GDMA_HANDSHAKE_INTERFACE_LEDC_TX (20)

/* Handshake interface for I2C0 TX. */
#define GDMA_HANDSHAKE_INTERFACE_I2C0_TX (21)

/* Handshake interface for I2C0 RX. */
#define GDMA_HANDSHAKE_INTERFACE_I2C0_RX (22)

/* Handshake interface for I2C1 TX. */
#define GDMA_HANDSHAKE_INTERFACE_I2C1_TX (23)

/* Handshake interface for I2C1 RX. */
#define GDMA_HANDSHAKE_INTERFACE_I2C1_RX (24)

/* Handshake interface for Zigbee TX. */
#define GDMA_HANDSHAKE_INTERFACE_Zigbee_TX (NULL)

/* Handshake interface for Zigbee RX. */
#define GDMA_HANDSHAKE_INTERFACE_Zigbee_RX (NULL)

/* Handshake interface for ADC RX. */
#define GDMA_HANDSHAKE_INTERFACE_ADC_RX (NULL)

/* Handshake interface for Audio TX. */
#define GDMA_HANDSHAKE_INTERFACE_AUDIO_TX (NULL)

/* Handshake interface for Audio RX. */
#define GDMA_HANDSHAKE_INTERFACE_AUDIO_RX (NULL)

GDMA Data Size

/* Transfer width of one byte. */
#define TrWidthOneByte ((u32)0x00000000)

/* Transfer width of two bytes. */
#define TrWidthTwoBytes ((u32)0x00000001)

/* Transfer width of four bytes. */
#define TrWidthFourBytes ((u32)0x00000002)

/* Check if GDMA data size value is valid. */
#define IS_GDMA_DATA_SIZE (((SIZE) == TrWidthOneByte) || \
    ((SIZE) == TrWidthTwoBytes) || \
    ((SIZE) == TrWidthFourBytes))

GDMA Data Transfer Direction

/* Memory to memory transfer. */
#define TTFCMemToMem ((u32)0x00000000)

/* Memory to peripheral transfer. */
#define TTFCMemToPeri ((u32)0x00000001)

/* Peripheral to memory transfer. */
#define TTFCPeriToMem ((u32)0x00000002)

/* Peripheral to peripheral transfer. */
#define TTFCPeriToPeri ((u32)0x00000003)

/* Peripheral to memory, peripheral as flow controller. */
#define TTFCPeriToMem_PerCtrl ((u32)0x00000004)

/* Peripheral to peripheral, source peripheral as flow controller. */
#define TTFCPeriToPeri_SrcPerCtrl ((u32)0x00000005)

/* Memory to peripheral, peripheral as flow controller. */
#define TTFCMemToPeri_PerCtrl ((u32)0x00000006)

/* Peripheral to peripheral, destination peripheral as flow controller. */
#define TTFCPeriToPeri_DstPerCtrl ((u32)0x00000007)

/* Check if GDMA transfer direction value is valid. */
#define IS_GDMA_DIR (((DIR) == TTFCMemToMem) || \
    ((DIR) == TTFCMemToPeri) || \
    ((DIR) == TTFCPeriToMem) ||\
    ((DIR) == TTFCPeriToPeri) ||\
    ((DIR) == TTFCPeriToMem_PerCtrl) || \
    ((DIR) == TTFCPeriToPeri_SrcPerCtrl) || \
    ((DIR) == TTFCPeriToPeri_DstPerCtrl) || \
    ((DIR) == TTFCMemToPeri_PerCtrl))

GDMA Increment Mode

/* Address increment mode. */
#define IncType ((u32)0x00000000)

/* Address decrement mode. */
#define DecType ((u32)0x00000001)

/* Address no-change mode. */
#define NoChange ((u32)0x00000002)

/* Check if GDMA increment mode value is valid. */
#define IS_GDMA_IncMode (((STATE) == IncType) || \
    ((STATE) == DecType) || \
    ((STATE) == NoChange))

GDMA Index Channel Definition

/* Maximum GDMA index value. */
#define MAX_GDMA_INDX (0)

/* Maximum GDMA channel number. */
#define MAX_GDMA_CHNL (7)

/* Check if GDMA channel number is valid. */
#define IS_GDMA_ChannelNum ((NUM) <= MAX_GDMA_CHNL)

/* Check if GDMA index value is valid. */
#define IS_GDMA_Index ((NUM) <= MAX_GDMA_INDX)

GDMA Interrupt Type

/* DMA transfer complete interrupt type. */
#define TransferType ((u32)0x00000001)

/* DMA block transfer complete interrupt type. */
#define BlockType ((u32)0x00000002)

/* DMA transfer error interrupt type. */
#define ErrType ((u32)0x000000010)

/* Check if GDMA interrupt type configuration is valid. */
#define IS_GDMA_CONFIG_IT ((((IT) & 0xFFFFFFE0) == 0x00) && ((IT) != 0x00))

GDMA Msize

/* Burst transaction length of 1 item. */
#define MsizeOne ((u32)0x00000000)

/* Burst transaction length of 4 items. */
#define MsizeFour ((u32)0x00000001)

/* Burst transaction length of 8 items. */
#define MsizeEight ((u32)0x00000002)

/* Burst transaction length of 16 items. */
#define MsizeSixteen ((u32)0x00000003)

/* Burst transaction length of 32 items. */
#define Msize32 ((u32)0x00000004)

/* Burst transaction length of 64 items. */
#define Msize64 ((u32)0x00000005)

/* Burst transaction length of 128 items. */
#define Msize128 ((u32)0x00000006)

/* Burst transaction length of 256 items. */
#define Msize256 ((u32)0x00000007)

/* Check if GDMA Msize value is valid. */
#define IS_GDMA_MSIZE (((SIZE) == MsizeOne) || \
    ((SIZE) == MsizeFour) || \
    ((SIZE) == MsizeEight)|| \
    ((SIZE) == MsizeSixteen) || \
    ((SIZE) == Msize32) || \
    ((SIZE) == Msize64) || \
    ((SIZE) == Msize128) || \
    ((SIZE) == Msize256))

GDMA Reload Definition

/* Clean source auto-reload. */
#define CLEAN_RELOAD_SRC ((u32)0x00000001)

/* Clean destination auto-reload. */
#define CLEAN_RELOAD_DST ((u32)0x00000002)

/* Clean both source and destination auto-reload. */
#define CLEAN_RELOAD_SRC_DST ((u32)0x00000003)

GDMA Interrupt Status

RTL8721Dx:

Not supported.

GDMA Channel Status

RTL8721Dx:

Not supported.

GDMA Exported Functions

u8 GDMA_Abort(u8 GDMA_Index, u8 GDMA_ChNum)

Abort a channel.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

Returns:

TRUE if the channel is successfully aborted, FALSE otherwise.

void GDMA_ChCleanAutoReload(u8 GDMA_Index, u8 GDMA_ChNum, u32 CleanType)

Clear GDMA AutoReload bits for the specified channel.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

  • CleanType –

    This parameter can be any combination of the following values:

    • CLEAN_RELOAD_SRC

    • CLEAN_RELOAD_DST

u8 GDMA_ChnlAlloc(u32 GDMA_Index, IRQ_FUN IrqFun, u32 IrqData, u32 IrqPriority)

Allocate a free channel.

Parameters:

  • GDMA_Index – Always 0.

  • IrqFun – GDMA IRQ callback function.

  • IrqData – GDMA IRQ callback data.

  • IrqPriority – GDMA IrqPriority.

Returns:

Allocated GDMA channel number, or 0xFF if no free channel is available.

u8 GDMA_ChnlFIFOIsEmpty(u8 GDMA_Index, u8 GDMA_ChNum)

Get whether the FIFO is empty.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

Returns:

TRUE if the channel FIFO is empty, FALSE otherwise.

u8 GDMA_ChnlFree(u8 GDMA_Index, u8 GDMA_ChNum)

Free a channel, this channel will not be used.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

Returns:

TRUE if the channel is successfully freed, FALSE otherwise.

u32 GDMA_ClearINT(u8 GDMA_Index, u8 GDMA_ChNum)

Clear all the Pending Interrupt status.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

Returns:

Active interrupt types whose interrupt status is cleared, refer to GDMA Interrupt Type.

Note

Clear all the active interrupts status for the current GDMA channel.

u32 GDMA_ClearINTPendingBit(u8 GDMA_Index, u8 GDMA_ChNum, u32 GDMA_IT)

Clear the specified Pending Interrupt status.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

  • GDMA_IT –

    Specifies the GDMA interrupt sources whose interrupt status will be cleared. This parameter can be one or combinations of the following values:

    • TransferType

    • BlockType

    • ErrType

Returns:

Active interrupt types whose interrupt status is cleared, refer to GDMA Interrupt Type.

Note

This function completes clearing the specified type interrupt status. Which type interrupt status will be cleared, refer to the parameter “GDMA_IT”.

void GDMA_Cmd(u8 GDMA_Index, u8 GDMA_ChNum, u32 NewState)

GDMA channel Disable/Enable.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

  • NewState – Disable/Enable.

u32 GDMA_GetBlkSize(u8 GDMA_Index, u8 GDMA_ChNum)

Get the block transfer size configured for the specified GDMA channel.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

Returns:

Block size configured for the current GDMA channel.

u32 GDMA_GetDstAddr(u8 GDMA_Index, u8 GDMA_ChNum)

Get the destination writing address during DMA transmission.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

Returns:

Destination address.

u8 GDMA_GetIrqNum(u8 GDMA_Index, u8 GDMA_ChNum)

Get IRQ number for a channel.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

Returns:

IRQ number for the specified GDMA channel.

u32 GDMA_GetSrcAddr(u8 GDMA_Index, u8 GDMA_ChNum)

Get the source reading address during DMA transmission.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

Returns:

Source address.

void GDMA_INTConfig(u8 GDMA_Index, u8 GDMA_ChNum, u32 GDMA_IT, u32 NewState)

Enable or disable the specified GDMA interrupts.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

  • GDMA_IT –

    Specifies the GDMA interrupt sources to be enabled or disabled. This parameter can be one or combinations of the following values:

    • TransferType

    • BlockType

    • ErrType

  • NewState – DISABLE/ENABLE.

void GDMA_Init(u8 GDMA_Index, u8 GDMA_ChNum, PGDMA_InitTypeDef GDMA_InitStruct)

Initialize the GDMA registers according to the specified parameters in GDMA_InitStruct.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

  • GDMA_InitStruct – Pointer to a GDMA_InitTypeDef structure that contains the configuration information for the GDMA peripheral.

void GDMA_Resume(u8 GDMA_Index, u8 GDMA_ChNum)

Resume a channel.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

void GDMA_SetBlkSize(u8 GDMA_Index, u8 GDMA_ChNum, u32 BlkSize)

Set GDMA block size.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

  • BlkSize – Block transfer size.

void GDMA_SetChnlPriority(u8 GDMA_Index, u8 GDMA_ChNum, u32 ChnlPriority)

Set channel priority.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

  • ChnlPriority – Channel priority to set.

void GDMA_SetDstAddr(u8 GDMA_Index, u8 GDMA_ChNum, u32 DstAddr)

Set destination address.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

  • DstAddr – Destination address.

void GDMA_SetLLP(u8 GDMA_Index, u8 GDMA_ChNum, u32 MultiBlockCount, struct GDMA_CH_LLI *pGdmaChLli, u32 round)

Set LLP mode when use GDMA Linked List Pointer Register.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

  • MultiBlockCount – Block counts.

  • pGdmaChLli – LLP node list, point to a Linked List Item.

  • round –

    • 0 Linear list, last node id last one

    • 1 Last node is not the end.

void GDMA_SetSrcAddr(u8 GDMA_Index, u8 GDMA_ChNum, u32 SrcAddr)

Set source address.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

  • SrcAddr – Source address.

void GDMA_StructInit(PGDMA_InitTypeDef GDMA_InitStruct)

Fill each GDMA_InitStruct member with its default value.

Parameters:

  • GDMA_InitStruct – Pointer to a GDMA_InitTypeDef structure which will be initialized.

void GDMA_Suspend(u8 GDMA_Index, u8 GDMA_ChNum)

Suspend a channel.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

RTL8721Dx:
u8 GDMA_ChannelIsActive(u8 GDMA_Index, u8 GDMA_ChNum)

Check if the channel is active.

Parameters:

  • GDMA_Index – Always 0.

  • GDMA_ChNum – 0 ~ 7.

Returns:

TRUE if the channel is active, FALSE otherwise.

Mbed API

MBED_GDMA Exported Types

typedef u32 (*dma_irq_handler)(void *id)

DMA IRQ callback function type.

Structure Type

typedef struct gdma_s gdma_t

GDMA object type.

MBED_GDMA Exported Functions

void dma_memcpy(gdma_t *dma_obj, void *dst, void *src, uint32_t len)

Accomplish memory copy by DMA.

Parameters:

  • dma_obj – GDMA object defined in application software.

  • dst – Destination memory address.

  • src – Source memory address.

  • len – Copy data length.

void dma_memcpy_deinit(gdma_t *dma_obj)

Deinitialize the GDMA.

Parameters:

  • dma_obj – GDMA object defined in application software.

void dma_memcpy_init(gdma_t *dma_obj, dma_irq_handler handler, uint32_t id)

Initialize the GDMA.

Parameters:

  • dma_obj – GDMA object defined in application software.

  • handler – User-defined GDMA IRQ callback function.

  • id – User-defined GDMA IRQ callback parameter.