The DMA pool API is documented in Memory Management APIs. Do not duplicate
it in DMA API documentation.

Signed-off-by: Petr Tesarik <ptesarik@suse.com>
---
 Documentation/core-api/dma-api.rst | 62 +-----------------------------
 Documentation/core-api/mm-api.rst  |  2 +
 2 files changed, 4 insertions(+), 60 deletions(-)

diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
index 3e89e3b0ecfd..f7fddaf7510c 100644
--- a/Documentation/core-api/dma-api.rst
+++ b/Documentation/core-api/dma-api.rst
@@ -83,66 +83,8 @@ much like a struct kmem_cache, except that they use the DMA-coherent allocator,
 not __get_free_pages().  Also, they understand common hardware constraints
 for alignment, like queue heads needing to be aligned on N-byte boundaries.
 
-
-::
-
-	struct dma_pool *
-	dma_pool_create(const char *name, struct device *dev,
-			size_t size, size_t align, size_t alloc);
-
-dma_pool_create() initializes a pool of DMA-coherent buffers
-for use with a given device.  It must be called in a context which
-can sleep.
-
-The "name" is for diagnostics (like a struct kmem_cache name); dev and size
-are like what you'd pass to dma_alloc_coherent().  The device's hardware
-alignment requirement for this type of data is "align" (which is expressed
-in bytes, and must be a power of two).  If your device has no boundary
-crossing restrictions, pass 0 for alloc; passing 4096 says memory allocated
-from this pool must not cross 4KByte boundaries.
-
-::
-
-	void *
-	dma_pool_zalloc(struct dma_pool *pool, gfp_t mem_flags,
-		        dma_addr_t *handle)
-
-Wraps dma_pool_alloc() and also zeroes the returned memory if the
-allocation attempt succeeded.
-
-
-::
-
-	void *
-	dma_pool_alloc(struct dma_pool *pool, gfp_t gfp_flags,
-		       dma_addr_t *dma_handle);
-
-This allocates memory from the pool; the returned memory will meet the
-size and alignment requirements specified at creation time.  Pass
-GFP_ATOMIC to prevent blocking, or if it's permitted (not
-in_interrupt, not holding SMP locks), pass GFP_KERNEL to allow
-blocking.  Like dma_alloc_coherent(), this returns two values:  an
-address usable by the CPU, and the DMA address usable by the pool's
-device.
-
-::
-
-	void
-	dma_pool_free(struct dma_pool *pool, void *vaddr,
-		      dma_addr_t addr);
-
-This puts memory back into the pool.  The pool is what was passed to
-dma_pool_alloc(); the CPU (vaddr) and DMA addresses are what
-were returned when that routine allocated the memory being freed.
-
-::
-
-	void
-	dma_pool_destroy(struct dma_pool *pool);
-
-dma_pool_destroy() frees the resources of the pool.  It must be
-called in a context which can sleep.  Make sure you've freed all allocated
-memory back to the pool before you destroy it.
+See :ref:`Documentation/core-api/mm-api.rst <dma_pools>` for a detailed
+description of the DMA pools API.
 
 
 Part Ic - DMA addressing limitations
diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst
index a61766328ac0..de0bab6e3fdd 100644
--- a/Documentation/core-api/mm-api.rst
+++ b/Documentation/core-api/mm-api.rst
@@ -91,6 +91,8 @@ Memory pools
 .. kernel-doc:: mm/mempool.c
    :export:
 
+.. _dma_pools:
+
 DMA pools
 =========
 
-- 
2.49.0

Hi,

On 6/24/25 6:39 AM, Petr Tesarik wrote:
> The DMA pool API is documented in Memory Management APIs. Do not duplicate
> it in DMA API documentation.
> 

This looks like it works (from just visual inspection), but I'm wondering
why not just move all DMA API interfaces to dma-api.rst and don't have any
in mm-api.rst... ?

Thanks.

> Signed-off-by: Petr Tesarik <ptesarik@suse.com>
> ---
>  Documentation/core-api/dma-api.rst | 62 +-----------------------------
>  Documentation/core-api/mm-api.rst  |  2 +
>  2 files changed, 4 insertions(+), 60 deletions(-)
> 
> diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
> index 3e89e3b0ecfd..f7fddaf7510c 100644
> --- a/Documentation/core-api/dma-api.rst
> +++ b/Documentation/core-api/dma-api.rst
> @@ -83,66 +83,8 @@ much like a struct kmem_cache, except that they use the DMA-coherent allocator,
>  not __get_free_pages().  Also, they understand common hardware constraints
>  for alignment, like queue heads needing to be aligned on N-byte boundaries.
>  
> -
> -::
> -
> -	struct dma_pool *
> -	dma_pool_create(const char *name, struct device *dev,
> -			size_t size, size_t align, size_t alloc);
> -
> -dma_pool_create() initializes a pool of DMA-coherent buffers
> -for use with a given device.  It must be called in a context which
> -can sleep.
> -
> -The "name" is for diagnostics (like a struct kmem_cache name); dev and size
> -are like what you'd pass to dma_alloc_coherent().  The device's hardware
> -alignment requirement for this type of data is "align" (which is expressed
> -in bytes, and must be a power of two).  If your device has no boundary
> -crossing restrictions, pass 0 for alloc; passing 4096 says memory allocated
> -from this pool must not cross 4KByte boundaries.
> -
> -::
> -
> -	void *
> -	dma_pool_zalloc(struct dma_pool *pool, gfp_t mem_flags,
> -		        dma_addr_t *handle)
> -
> -Wraps dma_pool_alloc() and also zeroes the returned memory if the
> -allocation attempt succeeded.
> -
> -
> -::
> -
> -	void *
> -	dma_pool_alloc(struct dma_pool *pool, gfp_t gfp_flags,
> -		       dma_addr_t *dma_handle);
> -
> -This allocates memory from the pool; the returned memory will meet the
> -size and alignment requirements specified at creation time.  Pass
> -GFP_ATOMIC to prevent blocking, or if it's permitted (not
> -in_interrupt, not holding SMP locks), pass GFP_KERNEL to allow
> -blocking.  Like dma_alloc_coherent(), this returns two values:  an
> -address usable by the CPU, and the DMA address usable by the pool's
> -device.
> -
> -::
> -
> -	void
> -	dma_pool_free(struct dma_pool *pool, void *vaddr,
> -		      dma_addr_t addr);
> -
> -This puts memory back into the pool.  The pool is what was passed to
> -dma_pool_alloc(); the CPU (vaddr) and DMA addresses are what
> -were returned when that routine allocated the memory being freed.
> -
> -::
> -
> -	void
> -	dma_pool_destroy(struct dma_pool *pool);
> -
> -dma_pool_destroy() frees the resources of the pool.  It must be
> -called in a context which can sleep.  Make sure you've freed all allocated
> -memory back to the pool before you destroy it.
> +See :ref:`Documentation/core-api/mm-api.rst <dma_pools>` for a detailed
> +description of the DMA pools API.
>  
>  
>  Part Ic - DMA addressing limitations
> diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst
> index a61766328ac0..de0bab6e3fdd 100644
> --- a/Documentation/core-api/mm-api.rst
> +++ b/Documentation/core-api/mm-api.rst
> @@ -91,6 +91,8 @@ Memory pools
>  .. kernel-doc:: mm/mempool.c
>     :export:
>  
> +.. _dma_pools:
> +
>  DMA pools
>  =========
>  

-- 
~Randy

On Tue, 24 Jun 2025 19:40:37 -0700
Randy Dunlap <rdunlap@infradead.org> wrote:

> Hi,
> 
> On 6/24/25 6:39 AM, Petr Tesarik wrote:
> > The DMA pool API is documented in Memory Management APIs. Do not duplicate
> > it in DMA API documentation.
> >   
> 
> This looks like it works (from just visual inspection), but I'm wondering
> why not just move all DMA API interfaces to dma-api.rst and don't have any
> in mm-api.rst... ?

That's also an option. As long as documentation is not repeated in more
than one place, I'm happy with the result. Now, seeing that it was you
who originally moved DMA pools from Drivers under Memory Management in
commit a80a438bd088 ("docbook: dmapool: fix fatal changed filename"), I
expect no complaints when I move it to dma-api.rst in v2.

Thanks for the idea!

Petr T