RT-Thread RTOS
An open source embedded real-time operating system
DMA engine

DMA subsystem

1. DMA controller (<tt>rt_dma_controller</tt> / <tt>rt_dma_controller_ops</tt>)

Same style as **ata/ata.md**, for **rt_dma_controller_register / rt_dma_controller_unregister** (components/drivers/dma/dma.c).

<tt>struct rt_dma_controller</tt> (before register)

Member Rule Meaning
dev Non-NULL Bound **rt_device**; checked at register; may **rt_dm_dev_bind_fwdata**.
ops Non-NULL **rt_dma_controller_ops**.
dir_cap At least one bit **rt_dma_controller_add_direction**; register fails if no direction is set.
addr_mask Caller **RT_DMA_ADDR_MASK(n)**, DMA-visible physical range.
channels_nodes / mutex Core Initialized in **rt_dma_controller_register**.

<tt>struct rt_dma_controller_ops</tt>

Callback Role
**request_chan** Return **rt_dma_chan** for **slave** + **fw_data** (usually parsed **dmas/dma-names**).
**release_chan** Pair of **request_chan**.
**config / prep_* / start / pause / stop** Channel programming and run control.

Slaves use **rt_dma_chan_request(dev, name)**, then **rt_dma_chan_config**, **rt_dma_prep_***, **rt_dma_chan_start**, etc. (see **drivers/dma.h**).

Buffers and <tt>dma_map_ops</tt>

**rt_dma_alloc / rt_dma_free / rt_dma_alloc_coherent**, **rt_dma_sync_***, **rt_dma_device_set_ops** — see **drivers/dma.h**. Coherent/CMA pools are documented in **documentation/6.components/device-driver/dma/pool.md**.

When DMA framework vs memcpy

Prefer **rt_dma_chan_*** when… memcpy / PIO may be OK when…
SDIO / SPI / UART / MAC has **dmas** in DTS and high throughput. Bootloader-stage tiny transfers or debug-only paths.
You need scatter-gather or cyclic audio/I2S. Transfer is **< cache line** and latency matters more than CPU load.

Slave driver checklist

  1. **rt_dma_chan_request** in probe with **dma-names** matching DTS.
  2. **rt_dma_chan_config** with **src_addr_width**, **direction**, **dst_maxburst** aligned to FIFO depth—wrong burst causes underrun/overrun.
  3. **rt_dma_prep_* + rt_dma_chan_start**: pass physical or bus addresses per map_ops—never feed unrelated virtual pointers unless your dma_map_ops handles them.
  4. **rt_dma_chan_release** in remove even if request partially failed after cleanup.
  5. Completion: ISR or **rt_dma_chan_done**—do not sleep in ISR; wake thread for heavy post-processing.

Controller author pitfalls

  • **dir_cap empty** → register fails—set at least one **RT_DMA_DIR_*** before register.
  • **addr_mask too narrow** → peripherals above 4G cannot be targeted—set from SoC spec.

2. API index (symbols)

Quick index into **drivers/dma.h** (full definitions in the header).

Enums: enum rt_dma_slave_buswidth, enum rt_dma_transfer_direction.

Macros: RT_DMA_ADDR_MASK(n), RT_DMA_F_*, RT_DMA_PAGE_SIZE.

Structs: struct rt_dma_chan, struct rt_dma_controller, struct rt_dma_controller_ops, struct rt_dma_map_ops, struct rt_dma_pool, struct rt_dma_slave_config, struct rt_dma_slave_transfer.

Inlines: rt_dma_alloc_coherent, rt_dma_free_coherent, rt_dma_controller_add_direction, rt_dma_controller_set_addr_mask, rt_dma_device_is_coherent, rt_dma_device_set_ops.

Functions: rt_dma_alloc / rt_dma_free, rt_dma_chan_config / done / pause / start / stop, rt_dma_chan_request / release, rt_dma_controller_register / unregister, rt_dma_pool_extract / install, rt_dma_prep_cyclic / memcpy / single, rt_dma_sync_in_data / out_data.

See also