Document the dma_pool_zalloc() wrapper.

Signed-off-by: Petr Tesarik <ptesarik@suse.com>
---
 Documentation/core-api/mm-api.rst | 2 ++
 include/linux/dmapool.h           | 8 ++++++++
 2 files changed, 10 insertions(+)

diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst
index af8151db88b28..a61766328ac06 100644
--- a/Documentation/core-api/mm-api.rst
+++ b/Documentation/core-api/mm-api.rst
@@ -97,6 +97,8 @@ DMA pools
 .. kernel-doc:: mm/dmapool.c
    :export:
 
+.. kernel-doc:: include/linux/dmapool.h
+
 More Memory Management Functions
 ================================
 
diff --git a/include/linux/dmapool.h b/include/linux/dmapool.h
index 06c4de602b2f3..c0c7717d3ae7b 100644
--- a/include/linux/dmapool.h
+++ b/include/linux/dmapool.h
@@ -60,6 +60,14 @@ static inline struct dma_pool *dma_pool_create(const char *name,
 				    NUMA_NO_NODE);
 }
 
+/**
+ * dma_pool_zalloc - Get a zero-initialized block of DMA coherent memory.
+ * @pool: dma pool that will produce the block
+ * @mem_flags: GFP_* bitmask
+ * @handle: pointer to dma address of block
+ *
+ * Same as @dma_pool_alloc, but the returned memory is zeroed.
+ */
 static inline void *dma_pool_zalloc(struct dma_pool *pool, gfp_t mem_flags,
 				    dma_addr_t *handle)
 {
-- 
2.49.0

On 6/27/25 3:10 AM, Petr Tesarik wrote:
> Document the dma_pool_zalloc() wrapper.
> 
> Signed-off-by: Petr Tesarik <ptesarik@suse.com>
> ---
>  Documentation/core-api/mm-api.rst | 2 ++
>  include/linux/dmapool.h           | 8 ++++++++
>  2 files changed, 10 insertions(+)
> 
> diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst
> index af8151db88b28..a61766328ac06 100644
> --- a/Documentation/core-api/mm-api.rst
> +++ b/Documentation/core-api/mm-api.rst
> @@ -97,6 +97,8 @@ DMA pools
>  .. kernel-doc:: mm/dmapool.c
>     :export:
>  
> +.. kernel-doc:: include/linux/dmapool.h
> +
>  More Memory Management Functions
>  ================================
>  
> diff --git a/include/linux/dmapool.h b/include/linux/dmapool.h
> index 06c4de602b2f3..c0c7717d3ae7b 100644
> --- a/include/linux/dmapool.h
> +++ b/include/linux/dmapool.h
> @@ -60,6 +60,14 @@ static inline struct dma_pool *dma_pool_create(const char *name,
>  				    NUMA_NO_NODE);
>  }
>  
> +/**
> + * dma_pool_zalloc - Get a zero-initialized block of DMA coherent memory.
> + * @pool: dma pool that will produce the block
> + * @mem_flags: GFP_* bitmask
> + * @handle: pointer to dma address of block
> + *
> + * Same as @dma_pool_alloc, but the returned memory is zeroed.

    * Same as dma_pool_alloc(), but ...

'@' is for function arguments.

With that change:

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.


> + */
>  static inline void *dma_pool_zalloc(struct dma_pool *pool, gfp_t mem_flags,
>  				    dma_addr_t *handle)
>  {

-- 
~Randy

On Sat, 28 Jun 2025 12:04:04 -0700
Randy Dunlap <rdunlap@infradead.org> wrote:

> On 6/27/25 3:10 AM, Petr Tesarik wrote:
> > Document the dma_pool_zalloc() wrapper.
> > 
> > Signed-off-by: Petr Tesarik <ptesarik@suse.com>
> > ---
> >  Documentation/core-api/mm-api.rst | 2 ++
> >  include/linux/dmapool.h           | 8 ++++++++
> >  2 files changed, 10 insertions(+)
> > 
> > diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst
> > index af8151db88b28..a61766328ac06 100644
> > --- a/Documentation/core-api/mm-api.rst
> > +++ b/Documentation/core-api/mm-api.rst
> > @@ -97,6 +97,8 @@ DMA pools
> >  .. kernel-doc:: mm/dmapool.c
> >     :export:
> >  
> > +.. kernel-doc:: include/linux/dmapool.h
> > +
> >  More Memory Management Functions
> >  ================================
> >  
> > diff --git a/include/linux/dmapool.h b/include/linux/dmapool.h
> > index 06c4de602b2f3..c0c7717d3ae7b 100644
> > --- a/include/linux/dmapool.h
> > +++ b/include/linux/dmapool.h
> > @@ -60,6 +60,14 @@ static inline struct dma_pool *dma_pool_create(const char *name,
> >  				    NUMA_NO_NODE);
> >  }
> >  
> > +/**
> > + * dma_pool_zalloc - Get a zero-initialized block of DMA coherent memory.
> > + * @pool: dma pool that will produce the block
> > + * @mem_flags: GFP_* bitmask
> > + * @handle: pointer to dma address of block
> > + *
> > + * Same as @dma_pool_alloc, but the returned memory is zeroed.  
> 
>     * Same as dma_pool_alloc(), but ...
> 
> '@' is for function arguments.

Oops. Somehow sneaked in...

> With that change:
> 
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> Tested-by: Randy Dunlap <rdunlap@infradead.org>

Do I have to submit a v3 then?

Petr T

Petr Tesarik <ptesarik@suse.com> writes:

> Do I have to submit a v3 then?

What path were you planning for this to go upstream?  If it goes through
docs, I can apply that tweak on the way in.

Thanks,

jon

On Tue, 01 Jul 2025 06:54:47 -0600
Jonathan Corbet <corbet@lwn.net> wrote:

> Petr Tesarik <ptesarik@suse.com> writes:
> 
> > Do I have to submit a v3 then?  
> 
> What path were you planning for this to go upstream?  If it goes through
> docs, I can apply that tweak on the way in.

There's a reason I put docs: in the Subject prefix. ;-)

This specific patch touches an include file outside Documentation/, but
since it merely adds a kernel-doc comment, I believe it's still good to
go through docs.

Thanks
Petr T