rt-thread/documentation/6.components/device-driver/dma/pool.md

@page page_device_dma_pool DMA memory pools

DMA coherent / CMA pools

Header: struct rt_dma_pool and rt_dma_pool_* in components/drivers/include/drivers/dma.h. Implementation: components/drivers/dma/dma_pool.c.

rt_dma_alloc / rt_dma_free (and default rt_dma_map_ops) allocate from installed pools instead of the generic heap when RT_USING_DMA and memblock reservations are configured. Controllers and slaves still use documentation/6.components/device-driver/dma/dma.md for channel programming; pools only back buffer memory.

Driver / BSP quick notes

Topic	Guidance
Boot reservation	Call rt_dma_pool_extract early (memblock dma-pool region) before drivers rt_dma_alloc.
Coherent vs CMA	coherent_pool is carved from the low end of the reserved region; CMA uses the remainder—cma_size must be ≥ coherent_pool_size.
32-bit DMA	Pools below 4 GiB set RT_DMA_F_32BITS on the pool—devices with limited addressing need buffers from these pools.
dma-coherent DT	rt_dma_device_is_coherent(dev) reads the property; map ops may skip flush on coherent devices.

struct rt_dma_pool

Field	Meaning
region	Physical start / end, optional name.
map / bits	Page bitmap (ARCH_PAGE_SIZE granule).
flags	e.g. RT_DMA_F_32BITS, RT_DMA_F_NOCACHE.
list	Global pool list (internal).

Public API

API	Role
rt_dma_pool_install(region)	Register a physical memory region as a pool; returns struct rt_dma_pool * or NULL on error.
rt_dma_pool_extract(cma_size, coherent_pool_size)	Find memblock region named dma-pool, split into coherent-pool + cma sub-regions, install both pools, mark memblock as consumed. Returns -RT_EEMPTY if no suitable region, -RT_EINVAL if sizes are inconsistent.

rt_dma_pool_install is also used directly when the BSP hands a fixed rt_region_t without going through memblock extract.

How allocation uses pools

1. rt_dma_alloc(dev, size, &handle, flags) walks installed pools (under dma_pools_lock), picks a pool matching flags (coherent, 32-bit, device, etc.).
2. Default rt_dma_map_ops:
   • Coherent: flush on sync_out_data, invalidate on sync_in_data.
   • Non-coherent: physical address via rt_kmem_v2p without cache maintenance on sync-in.
3. With RT_USING_OFW, rt_dma_device_set_ops may install ofw_dma_map_* that translates CPU ↔ DMA bus addresses via rt_ofw_translate_cpu2dma.

Slaves should use rt_dma_alloc_coherent for ring buffers the CPU and DMA both touch.

Boot flow (typical)

1. Bootloader or memblock code reserves dma-pool in device tree / memblock.
2. Early init calls rt_dma_pool_extract(SIZE_MB(8), SIZE_MB(2)) (example sizes).
3. Drivers probe and rt_dma_alloc for descriptor rings and payload buffers.

Debugging

With RT_USING_CONSOLE and RT_USING_MSH, list_dma_pool prints installed regions (name, size, base).

Pitfalls

• Pool exhausted: rt_dma_alloc returns NULL—size requests must fit contiguous free pages in a matching pool.
• CMA smaller than coherent: rt_dma_pool_extract rejects cma_size < coherent_pool_size.
• High memory only: if no sub-4G dma-pool chunk is large enough, extract may fall back with a warning—DMA to peripherals that cannot reach high memory will fail.
• Double extract: second call may find memblock already consumed—guard in BSP init.

See also

• DMA engine and channels: documentation/6.components/device-driver/dma/dma.md
• OFW DMA range: documentation/6.components/device-driver/ofw/ofw.md
• NUMA / affinity: documentation/6.components/device-driver/numa/numa.md
• Source: components/drivers/dma/dma_pool.c
• Header: components/drivers/include/drivers/dma.h