[RFC PATCH 0/2] modernize DMA api documentation

[RFC PATCH 0/2] modernize DMA api documentation

[anish kumar]

Dear maintainers,

This patch series is inspired by the ongoing discussion in the following thread:
https://lore.kernel.org/lkml/20241111063847.GB23992@lst.de/

As part of an effort to modernize the documentation, the first patch in
this series converts the relevant document to use kernel-doc comments directly
within the source code, replacing the previous method of manually adding
documentation. This change will help streamline the documentation workflow and
ensure it remains synchronized with the code.

I am still getting below errors and wondering if there is a better
way to write this patch.

/home/ANT.AMAZON.COM/anishkmr/Downloads/linux/Documentation/core-api/dma-api:89:  
    ./mm/dmapool.c:229: WARNING: Duplicate C declaration, also defined at  
    core-api/mm-api:224. Declaration is:  
    '.. c:function:: struct dma_pool *dma_pool_create (const char *name,  
    struct device *dev, size_t size, size_t align, size_t boundary)'.

/home/ANT.AMAZON.COM/anishkmr/Downloads/linux/Documentation/core-api/dma-api:92:  
    ./mm/dmapool.c:420: WARNING: Duplicate C declaration, also defined at  
    core-api/mm-api:404. Declaration is:  
    '.. c:function:: void *dma_pool_alloc (struct dma_pool *pool, gfp_t mem_flags,  
    dma_addr_t *handle)'.

/home/ANT.AMAZON.COM/anishkmr/Downloads/linux/Documentation/core-api/dma-api:98:  
    ./mm/dmapool.c:229: WARNING: Duplicate C declaration, also defined at  
    core-api/mm-api:224. Declaration is:  
    '.. c:function:: struct dma_pool *dma_pool_create (const char *name,  
    struct device *dev, size_t size, size_t align, size_t boundary)'.

/home/ANT.AMAZON.COM/anishkmr/Downloads/linux/Documentation/core-api/dma-api:101:  
    ./mm/dmapool.c:466: WARNING: Duplicate C declaration, also defined at  
    core-api/mm-api:450. Declaration is:  
    '.. c:function:: void dma_pool_free (struct dma_pool *pool, void *vaddr,  
    dma_addr_t dma)'.

/home/ANT.AMAZON.COM/anishkmr/Downloads/linux/Documentation/core-api/dma-api:104:  
    ./mm/dmapool.c:366: WARNING: Duplicate C declaration, also defined at  
    core-api/mm-api:360.

Thank you for considering this patch. I look forward to your feedback.

anish kumar (2):
  dmapool: Improve dma api kernel-doc comments
  dmapool: Documentation: use the kernel-doc comment

 Documentation/core-api/dma-api.rst | 66 ++++++------------------------
 mm/dmapool.c                       | 40 ++++++++++++------
 2 files changed, 40 insertions(+), 66 deletions(-)

-- 
2.39.5 (Apple Git-154)

[RFC PATCH 1/2] dmapool: Improve dma api kernel-doc comments

[anish kumar]

Move explanatory content from the documentation
to source code comment written in kernel-doc format.
This allows kernel-doc to generate more comprehensive
and accurate documentation. Additionally, improving
the kernel-doc comment describes the api behaviour
and usage better.

Signed-off-by: anish kumar <yesanishhere@gmail.com>
---
 mm/dmapool.c | 40 ++++++++++++++++++++++++++++------------
 1 file changed, 28 insertions(+), 12 deletions(-)

diff --git a/mm/dmapool.c b/mm/dmapool.c
index f0bfc6c490f4..8b32a52becd6 100644
--- a/mm/dmapool.c
+++ b/mm/dmapool.c
@@ -207,11 +207,16 @@ static void pool_block_push(struct dma_pool *pool, struct dma_block *block,
  * @boundary: returned blocks won't cross this power of two boundary
  * Context: not in_interrupt()
  *
- * Given one of these pools, dma_pool_alloc()
- * may be used to allocate memory.  Such memory will all have "consistent"
- * DMA mappings, accessible by the device and its driver without using
- * cache flushing primitives.  The actual size of blocks allocated may be
- * larger than requested because of alignment.
+ * This api initializes a pool of DMA-coherent buffers for use with a given
+ * device. It must be called in a context which can sleep. The device's
+ * hardware alignment requirement for this type of data is "align". 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.
+ *
+ * Given one of these pools, dma_pool_alloc() may be used to allocate memory.
+ * Such memory will all have "consistent" DMA mappings, accessible by the
+ * device and its driver without using cache flushing primitives.  The actual
+ * size of blocks allocated may be larger than requested because of alignment.
  *
  * If @boundary is nonzero, objects returned from dma_pool_alloc() won't
  * cross that size boundary.  This is useful for devices which have
@@ -356,6 +361,7 @@ static struct dma_page *pool_alloc_page(struct dma_pool *pool, gfp_t mem_flags)
  *
  * Caller guarantees that no more memory from the pool is in use,
  * and that nothing will try to use the pool after this call.
+ * It must be called in a context which can sleep.
  */
 void dma_pool_destroy(struct dma_pool *pool)
 {
@@ -392,14 +398,24 @@ void dma_pool_destroy(struct dma_pool *pool)
 EXPORT_SYMBOL(dma_pool_destroy);
 
 /**
- * dma_pool_alloc - get a block of consistent memory
- * @pool: dma pool that will produce the block
- * @mem_flags: GFP_* bitmask
- * @handle: pointer to dma address of block
+ * dma_pool_alloc - Get a block of consistent memory from a DMA pool
+ * @pool:       DMA pool that will produce the block
+ * @mem_flags:  GFP_* bitmask specifying memory allocation flags
+ * @handle:     Pointer to a DMA address that will hold the address of the block
+ *
+ * Return: The kernel virtual address of a currently unused block of memory,
+ *         and reports its DMA address through the handle. If such a memory
+ *         block can't be allocated, %NULL is returned.
+ *
+ * This function allocates memory from the specified DMA pool. The returned
+ * memory will meet the size and alignment requirements specified when the
+ * pool was created. Pass GFP_ATOMIC to prevent blocking, or if permitted
+ * (not in interrupt context, and not holding SMP locks), pass GFP_KERNEL
+ * to allow blocking.
  *
- * Return: the kernel virtual address of a currently unused block,
- * and reports its dma address through the handle.
- * If such a memory block can't be allocated, %NULL is returned.
+ * Similar to dma_alloc_coherent(), this function returns two addresses:
+ *  - A CPU-accessible virtual address
+ *  - A DMA address usable by the pool's associated device.
  */
 void *dma_pool_alloc(struct dma_pool *pool, gfp_t mem_flags,
 		     dma_addr_t *handle)
-- 
2.39.5 (Apple Git-154)

[RFC PATCH 2/2] dmapool: Documentation: use the kernel-doc comment

[anish kumar]

In an effort to modernize the documentation for
dma api, move the api explanation to kernel-doc comment
in the source code and use the kernel-doc here in
the documentation.

Signed-off-by: anish kumar <yesanishhere@gmail.com>
---
 Documentation/core-api/dma-api.rst | 66 ++++++------------------------
 1 file changed, 12 insertions(+), 54 deletions(-)

diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
index 8e3cce3d0a23..8e89f328ba54 100644
--- a/Documentation/core-api/dma-api.rst
+++ b/Documentation/core-api/dma-api.rst
@@ -86,65 +86,23 @@ 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.
-
+.. kernel-doc:: mm/dmapool.c
+    :identifiers: dma_pool_create
 
-::
-
-	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.
-
-::
+.. kernel-doc:: mm/dmapool.c
+    :identifiers: dma_pool_alloc
 
-	void
-	dma_pool_free(struct dma_pool *pool, void *vaddr,
-		      dma_addr_t addr);
+dma_pool_zalloc wraps dma_pool_alloc() and also zeroes the returned memory
+if the allocation attempt succeeded.
 
-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.
+.. kernel-doc:: mm/dmapool.c
+    :identifiers: dma_pool_create
 
-::
-
-	void
-	dma_pool_destroy(struct dma_pool *pool);
+.. kernel-doc:: mm/dmapool.c
+    :identifiers: dma_pool_free
 
-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.
+.. kernel-doc:: mm/dmapool.c
+    :identifiers: dma_pool_destroy
 
 
 Part Ic - DMA addressing limitations
-- 
2.39.5 (Apple Git-154)

Re: [RFC PATCH 0/2] modernize DMA api documentation

[Randy Dunlap]

Hi--

On 11/12/24 10:34 PM, anish kumar wrote:
> Dear maintainers,
> 
> This patch series is inspired by the ongoing discussion in the following thread:
> https://lore.kernel.org/lkml/20241111063847.GB23992@lst.de/
> 
> As part of an effort to modernize the documentation, the first patch in
> this series converts the relevant document to use kernel-doc comments directly
> within the source code, replacing the previous method of manually adding
> documentation. This change will help streamline the documentation workflow and
> ensure it remains synchronized with the code.
> 
> I am still getting below errors and wondering if there is a better
> way to write this patch.
> 
> /home/ANT.AMAZON.COM/anishkmr/Downloads/linux/Documentation/core-api/dma-api:89:  
>     ./mm/dmapool.c:229: WARNING: Duplicate C declaration, also defined at  
>     core-api/mm-api:224. Declaration is:  
>     '.. c:function:: struct dma_pool *dma_pool_create (const char *name,  
>     struct device *dev, size_t size, size_t align, size_t boundary)'.
> 
> /home/ANT.AMAZON.COM/anishkmr/Downloads/linux/Documentation/core-api/dma-api:92:  
>     ./mm/dmapool.c:420: WARNING: Duplicate C declaration, also defined at  
>     core-api/mm-api:404. Declaration is:  
>     '.. c:function:: void *dma_pool_alloc (struct dma_pool *pool, gfp_t mem_flags,  
>     dma_addr_t *handle)'.
> 
> /home/ANT.AMAZON.COM/anishkmr/Downloads/linux/Documentation/core-api/dma-api:98:  
>     ./mm/dmapool.c:229: WARNING: Duplicate C declaration, also defined at  
>     core-api/mm-api:224. Declaration is:  
>     '.. c:function:: struct dma_pool *dma_pool_create (const char *name,  
>     struct device *dev, size_t size, size_t align, size_t boundary)'.
> 
> /home/ANT.AMAZON.COM/anishkmr/Downloads/linux/Documentation/core-api/dma-api:101:  
>     ./mm/dmapool.c:466: WARNING: Duplicate C declaration, also defined at  
>     core-api/mm-api:450. Declaration is:  
>     '.. c:function:: void dma_pool_free (struct dma_pool *pool, void *vaddr,  
>     dma_addr_t dma)'.
> 
> /home/ANT.AMAZON.COM/anishkmr/Downloads/linux/Documentation/core-api/dma-api:104:  
>     ./mm/dmapool.c:366: WARNING: Duplicate C declaration, also defined at  
>     core-api/mm-api:360.
> 

If you are going to add these APIs in dma-api.rst, you need to remove them from
mm-api.rst (IMO). That should remove these Duplicate warnings.


> Thank you for considering this patch. I look forward to your feedback.
> 
> anish kumar (2):
>   dmapool: Improve dma api kernel-doc comments
>   dmapool: Documentation: use the kernel-doc comment
> 
>  Documentation/core-api/dma-api.rst | 66 ++++++------------------------
>  mm/dmapool.c                       | 40 ++++++++++++------
>  2 files changed, 40 insertions(+), 66 deletions(-)
> 

-- 
~Randy