docs: dma-api: remove duplicate description of the DMA pool API

Move the DMA pool API documentation from Memory Management APIs to
dma-api.rst, replacing the outdated duplicate description there.

Signed-off-by: Petr Tesarik <ptesarik@suse.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Marek Szyprowski <m.szyprowski@samsung.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250627101015.1600042-6-ptesarik@suse.com

authored by

Petr Tesarik and committed by

Jonathan Corbet 1 year ago 61043d09 fc9a0995

+3 -67

2 changed files

expand all

Documentation

core-api

dma-api.rst

mm-api.rst

+3 -59

Documentation/core-api/dma-api.rst

··· 83 83 not __get_free_pages(). Also, they understand common hardware constraints 84 84 for alignment, like queue heads needing to be aligned on N-byte boundaries. 85 85 86 + .. kernel-doc:: mm/dmapool.c 87 + :export: 86 88 87 - :: 88 - 89 - struct dma_pool * 90 - dma_pool_create(const char *name, struct device *dev, 91 - size_t size, size_t align, size_t alloc); 92 - 93 - dma_pool_create() initializes a pool of DMA-coherent buffers 94 - for use with a given device. It must be called in a context which 95 - can sleep. 96 - 97 - The "name" is for diagnostics (like a struct kmem_cache name); dev and size 98 - are like what you'd pass to dma_alloc_coherent(). The device's hardware 99 - alignment requirement for this type of data is "align" (which is expressed 100 - in bytes, and must be a power of two). If your device has no boundary 101 - crossing restrictions, pass 0 for alloc; passing 4096 says memory allocated 102 - from this pool must not cross 4KByte boundaries. 103 - 104 - :: 105 - 106 - void * 107 - dma_pool_zalloc(struct dma_pool *pool, gfp_t mem_flags, 108 - dma_addr_t *handle) 109 - 110 - Wraps dma_pool_alloc() and also zeroes the returned memory if the 111 - allocation attempt succeeded. 112 - 113 - 114 - :: 115 - 116 - void * 117 - dma_pool_alloc(struct dma_pool *pool, gfp_t gfp_flags, 118 - dma_addr_t *dma_handle); 119 - 120 - This allocates memory from the pool; the returned memory will meet the 121 - size and alignment requirements specified at creation time. Pass 122 - GFP_ATOMIC to prevent blocking, or if it's permitted (not 123 - in_interrupt, not holding SMP locks), pass GFP_KERNEL to allow 124 - blocking. Like dma_alloc_coherent(), this returns two values: an 125 - address usable by the CPU, and the DMA address usable by the pool's 126 - device. 127 - 128 - :: 129 - 130 - void 131 - dma_pool_free(struct dma_pool *pool, void *vaddr, 132 - dma_addr_t addr); 133 - 134 - This puts memory back into the pool. The pool is what was passed to 135 - dma_pool_alloc(); the CPU (vaddr) and DMA addresses are what 136 - were returned when that routine allocated the memory being freed. 137 - 138 - :: 139 - 140 - void 141 - dma_pool_destroy(struct dma_pool *pool); 142 - 143 - dma_pool_destroy() frees the resources of the pool. It must be 144 - called in a context which can sleep. Make sure you've freed all allocated 145 - memory back to the pool before you destroy it. 89 + .. kernel-doc:: include/linux/dmapool.h 146 90 147 91 148 92 Part Ic - DMA addressing limitations

-8

Documentation/core-api/mm-api.rst

··· 91 91 .. kernel-doc:: mm/mempool.c 92 92 :export: 93 93 94 - DMA pools 95 - ========= 96 - 97 - .. kernel-doc:: mm/dmapool.c 98 - :export: 99 - 100 - .. kernel-doc:: include/linux/dmapool.h 101 - 102 94 More Memory Management Functions 103 95 ================================ 104 96

Configure Feed

Configure Feed