Re: dma-coherent: add documentation to new interfaces

Re: dma-coherent: add documentation to new interfaces

[Randy Dunlap]

On Tue, 29 Jul 2008 03:01:07 GMT Linux Kernel Mailing List wrote:

> Gitweb:     http://git.kernel.org/git/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=b6d4f7e3ef25beb8c658c97867d98883e69dc544
> Commit:     b6d4f7e3ef25beb8c658c97867d98883e69dc544
> Parent:     8fa8b9fbab90c74139e8e868fe5b30b6a9f6be65
> Author:     Dmitry Baryshkov <dbaryshkov@gmail.com>
> AuthorDate: Sun Jul 20 15:01:10 2008 +0400
> Committer:  Ingo Molnar <mingo@elte.hu>
> CommitDate: Sun Jul 20 21:22:00 2008 +0200
> 
>     dma-coherent: add documentation to new interfaces

Hi,
Please fix these to be proper kernel-doc notation, as described in
Documentation/kernel-doc-nano-HOWTO.txt ...

>     Signed-off-by: Dmitry Baryshkov <dbaryshkov@gmail.com>
>     Cc: Jesse Barnes <jbarnes@virtuousgeek.org>
>     Signed-off-by: Ingo Molnar <mingo@elte.hu>
> ---
>  kernel/dma-coherent.c |   28 ++++++++++++++++++++++++++++
>  1 files changed, 28 insertions(+), 0 deletions(-)
> 
> diff --git a/kernel/dma-coherent.c b/kernel/dma-coherent.c
> index 56dff5c..7517115 100644
> --- a/kernel/dma-coherent.c
> +++ b/kernel/dma-coherent.c
> @@ -92,6 +92,21 @@ void *dma_mark_declared_memory_occupied(struct device *dev,
>  }
>  EXPORT_SYMBOL(dma_mark_declared_memory_occupied);
>  
> +/**
> + * Try to allocate memory from the per-device coherent area.

Missing function name -

> + *
> + * @dev:	device from which we allocate memory
> + * @size:	size of requested memory area
> + * @dma_handle:	This will be filled with the correct dma handle
> + * @ret:	This pointer will be filled with the virtual address
> + * 		to allocated area.
> + *
> + * This function should be only called from per-arch %dma_alloc_coherent()
> + * to support allocation from per-device coherent memory pools.
> + *
> + * Returns 0 if dma_alloc_coherent should continue with allocating from
> + * generic memory areas, or !0 if dma_alloc_coherent should return %ret.

'%' is a constant-value prefix in kernel-doc.

> + */
>  int dma_alloc_from_coherent(struct device *dev, ssize_t size,
>  				       dma_addr_t *dma_handle, void **ret)
>  {
> @@ -111,6 +126,19 @@ int dma_alloc_from_coherent(struct device *dev, ssize_t size,
>  	return (mem != NULL);
>  }
>  
> +/**
> + * Try to free the memory allocated from per-device coherent memory pool.

Missing function name -

> + * @dev:	device from which the memory was allocated
> + * @order:	the order of pages allocated
> + * @vaddr:	virtual address of allocated pages
> + *
> + * This checks whether the memory was allocated from the per-device
> + * coherent memory pool and if so, releases that memory.
> + *
> + * Returns 1 if we correctly released the memory, or 0 if
> + * %dma_release_coherent() should proceed with releasing memory from

Drop the '%'.

> + * generic pools.
> + */
>  int dma_release_from_coherent(struct device *dev, int order, void *vaddr)
>  {
>  	struct dma_coherent_mem *mem = dev ? dev->dma_mem : NULL;
> --


Thanks.

---
~Randy
Linux Plumbers Conference, 17-19 September 2008, Portland, Oregon USA
http://linuxplumbersconf.org/

Re: dma-coherent: add documentation to new interfaces

[Dmitry Baryshkov]

On Tue, Jul 29, 2008 at 01:17:57PM -0700, Randy Dunlap wrote:
> On Tue, 29 Jul 2008 03:01:07 GMT Linux Kernel Mailing List wrote:
> 
> > Gitweb:     http://git.kernel.org/git/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=b6d4f7e3ef25beb8c658c97867d98883e69dc544
> > Commit:     b6d4f7e3ef25beb8c658c97867d98883e69dc544
> > Parent:     8fa8b9fbab90c74139e8e868fe5b30b6a9f6be65
> > Author:     Dmitry Baryshkov <dbaryshkov@gmail.com>
> > AuthorDate: Sun Jul 20 15:01:10 2008 +0400
> > Committer:  Ingo Molnar <mingo@elte.hu>
> > CommitDate: Sun Jul 20 21:22:00 2008 +0200
> > 
> >     dma-coherent: add documentation to new interfaces
> 
> Hi,
> Please fix these to be proper kernel-doc notation, as described in
> Documentation/kernel-doc-nano-HOWTO.txt ...

Please consider this patch:

>From 766159161001e2e118cc840e7aca4b8d500b1ebf Mon Sep 17 00:00:00 2001
From: Dmitry Baryshkov <dbaryshkov@gmail.com>
Date: Wed, 30 Jul 2008 01:41:58 +0400
Subject: [PATCH] dma-coherent: fix kernel-doc comments

Signed-off-by: Dmitry Baryshkov <dbaryshkov@gmail.com>
---
 kernel/dma-coherent.c |   10 +++++-----
 1 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/kernel/dma-coherent.c b/kernel/dma-coherent.c
index 7517115..9ef28a0 100644
--- a/kernel/dma-coherent.c
+++ b/kernel/dma-coherent.c
@@ -93,7 +93,7 @@ void *dma_mark_declared_memory_occupied(struct device *dev,
 EXPORT_SYMBOL(dma_mark_declared_memory_occupied);
 
 /**
- * Try to allocate memory from the per-device coherent area.
+ * dma_alloc_from_coherent() - try to allocate memory from the per-device coherent area
  *
  * @dev:	device from which we allocate memory
  * @size:	size of requested memory area
@@ -101,11 +101,11 @@ EXPORT_SYMBOL(dma_mark_declared_memory_occupied);
  * @ret:	This pointer will be filled with the virtual address
  * 		to allocated area.
  *
- * This function should be only called from per-arch %dma_alloc_coherent()
+ * This function should be only called from per-arch dma_alloc_coherent()
  * to support allocation from per-device coherent memory pools.
  *
  * Returns 0 if dma_alloc_coherent should continue with allocating from
- * generic memory areas, or !0 if dma_alloc_coherent should return %ret.
+ * generic memory areas, or !0 if dma_alloc_coherent should return @ret.
  */
 int dma_alloc_from_coherent(struct device *dev, ssize_t size,
 				       dma_addr_t *dma_handle, void **ret)
@@ -127,7 +127,7 @@ int dma_alloc_from_coherent(struct device *dev, ssize_t size,
 }
 
 /**
- * Try to free the memory allocated from per-device coherent memory pool.
+ * dma_release_from_coherent() - try to free the memory allocated from per-device coherent memory pool
  * @dev:	device from which the memory was allocated
  * @order:	the order of pages allocated
  * @vaddr:	virtual address of allocated pages
@@ -136,7 +136,7 @@ int dma_alloc_from_coherent(struct device *dev, ssize_t size,
  * coherent memory pool and if so, releases that memory.
  *
  * Returns 1 if we correctly released the memory, or 0 if
- * %dma_release_coherent() should proceed with releasing memory from
+ * dma_release_coherent() should proceed with releasing memory from
  * generic pools.
  */
 int dma_release_from_coherent(struct device *dev, int order, void *vaddr)
-- 
1.5.6.3

-- 
With best wishes
Dmitry

Re: dma-coherent: add documentation to new interfaces

[Randy Dunlap]

On Wed, 30 Jul 2008 14:46:50 +0400 Dmitry Baryshkov wrote:

> On Tue, Jul 29, 2008 at 01:17:57PM -0700, Randy Dunlap wrote:
> > On Tue, 29 Jul 2008 03:01:07 GMT Linux Kernel Mailing List wrote:
> > 
> > > Gitweb:     http://git.kernel.org/git/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=b6d4f7e3ef25beb8c658c97867d98883e69dc544
> > > Commit:     b6d4f7e3ef25beb8c658c97867d98883e69dc544
> > > Parent:     8fa8b9fbab90c74139e8e868fe5b30b6a9f6be65
> > > Author:     Dmitry Baryshkov <dbaryshkov@gmail.com>
> > > AuthorDate: Sun Jul 20 15:01:10 2008 +0400
> > > Committer:  Ingo Molnar <mingo@elte.hu>
> > > CommitDate: Sun Jul 20 21:22:00 2008 +0200
> > > 
> > >     dma-coherent: add documentation to new interfaces
> > 
> > Hi,
> > Please fix these to be proper kernel-doc notation, as described in
> > Documentation/kernel-doc-nano-HOWTO.txt ...
> 
> Please consider this patch:

Looks good.  Thanks.

Jesse or Ingo:  will one of you merge this, please?


> >From 766159161001e2e118cc840e7aca4b8d500b1ebf Mon Sep 17 00:00:00 2001
> From: Dmitry Baryshkov <dbaryshkov@gmail.com>
> Date: Wed, 30 Jul 2008 01:41:58 +0400
> Subject: [PATCH] dma-coherent: fix kernel-doc comments
> 
> Signed-off-by: Dmitry Baryshkov <dbaryshkov@gmail.com>
> ---
>  kernel/dma-coherent.c |   10 +++++-----
>  1 files changed, 5 insertions(+), 5 deletions(-)
> 
> diff --git a/kernel/dma-coherent.c b/kernel/dma-coherent.c
> index 7517115..9ef28a0 100644
> --- a/kernel/dma-coherent.c
> +++ b/kernel/dma-coherent.c
> @@ -93,7 +93,7 @@ void *dma_mark_declared_memory_occupied(struct device *dev,
>  EXPORT_SYMBOL(dma_mark_declared_memory_occupied);
>  
>  /**
> - * Try to allocate memory from the per-device coherent area.
> + * dma_alloc_from_coherent() - try to allocate memory from the per-device coherent area
>   *
>   * @dev:	device from which we allocate memory
>   * @size:	size of requested memory area
> @@ -101,11 +101,11 @@ EXPORT_SYMBOL(dma_mark_declared_memory_occupied);
>   * @ret:	This pointer will be filled with the virtual address
>   * 		to allocated area.
>   *
> - * This function should be only called from per-arch %dma_alloc_coherent()
> + * This function should be only called from per-arch dma_alloc_coherent()
>   * to support allocation from per-device coherent memory pools.
>   *
>   * Returns 0 if dma_alloc_coherent should continue with allocating from
> - * generic memory areas, or !0 if dma_alloc_coherent should return %ret.
> + * generic memory areas, or !0 if dma_alloc_coherent should return @ret.
>   */
>  int dma_alloc_from_coherent(struct device *dev, ssize_t size,
>  				       dma_addr_t *dma_handle, void **ret)
> @@ -127,7 +127,7 @@ int dma_alloc_from_coherent(struct device *dev, ssize_t size,
>  }
>  
>  /**
> - * Try to free the memory allocated from per-device coherent memory pool.
> + * dma_release_from_coherent() - try to free the memory allocated from per-device coherent memory pool
>   * @dev:	device from which the memory was allocated
>   * @order:	the order of pages allocated
>   * @vaddr:	virtual address of allocated pages
> @@ -136,7 +136,7 @@ int dma_alloc_from_coherent(struct device *dev, ssize_t size,
>   * coherent memory pool and if so, releases that memory.
>   *
>   * Returns 1 if we correctly released the memory, or 0 if
> - * %dma_release_coherent() should proceed with releasing memory from
> + * dma_release_coherent() should proceed with releasing memory from
>   * generic pools.
>   */
>  int dma_release_from_coherent(struct device *dev, int order, void *vaddr)
> -- 

---
~Randy
Linux Plumbers Conference, 17-19 September 2008, Portland, Oregon USA
http://linuxplumbersconf.org/

Re: dma-coherent: add documentation to new interfaces

[Jesse Barnes]

On Wednesday, July 30, 2008 7:28 am Randy Dunlap wrote:
> On Wed, 30 Jul 2008 14:46:50 +0400 Dmitry Baryshkov wrote:
> > On Tue, Jul 29, 2008 at 01:17:57PM -0700, Randy Dunlap wrote:
> > > On Tue, 29 Jul 2008 03:01:07 GMT Linux Kernel Mailing List wrote:
> > > > Gitweb:    
> > > > http://git.kernel.org/git/?p=linux/kernel/git/torvalds/linux-2.6.git;
> > > >a=commit;h=b6d4f7e3ef25beb8c658c97867d98883e69dc544 Commit:    
> > > > b6d4f7e3ef25beb8c658c97867d98883e69dc544
> > > > Parent:     8fa8b9fbab90c74139e8e868fe5b30b6a9f6be65
> > > > Author:     Dmitry Baryshkov <dbaryshkov@gmail.com>
> > > > AuthorDate: Sun Jul 20 15:01:10 2008 +0400
> > > > Committer:  Ingo Molnar <mingo@elte.hu>
> > > > CommitDate: Sun Jul 20 21:22:00 2008 +0200
> > > >
> > > >     dma-coherent: add documentation to new interfaces
> > >
> > > Hi,
> > > Please fix these to be proper kernel-doc notation, as described in
> > > Documentation/kernel-doc-nano-HOWTO.txt ...
> >
> > Please consider this patch:
>
> Looks good.  Thanks.
>
> Jesse or Ingo:  will one of you merge this, please?

Just pushed it into my for-linus branch.  I added your "Acked-by" too, thanks 
for checking it out.

Jesse