Skip to contentSkip to conversation

dma-coherent: add documentation to new interfaces

DISCUSSION Randy Dunlap 3 participants 4 messages Jul 29, 2008 – Jul 31, 2008 1 message not in the archive

lore
Share & tools
lore

A message that is not in the archive (sent off-list or not yet received): [email protected]

#1 lore raw
Quoted 9 lines · 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 <[email protected]>
AuthorDate: Sun Jul 20 15:01:10 2008 +0400
Committer:  Ingo Molnar <[email protected]>
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 ...

Quoted 12 lines
---
 kernel/dma-coherent.c |   28 ++++++++++++++++++++++++++++
 1 files changed, 28 insertions(+), 0 deletions(-)
kernel/dma-coherent.c +0 -0
index 56dff5c..7517115 100644

kernel/dma-coherent.c void *dma_mark_declared_memory_occupied(struct device *dev, · line 96

Quoted 5 lines
kernel/dma-coherent.c +2 -0
@@ -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 -

kernel/dma-coherent.c void *dma_mark_declared_memory_occupied(struct device *dev, · line 108

Quoted 12 lines
kernel/dma-coherent.c +12 -0
+ *
+ * @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.

kernel/dma-coherent.c int dma_alloc_from_coherent(struct device *dev, ssize_t size, · line 130

Quoted 10 lines
kernel/dma-coherent.c +3 -0
+ */
 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 -

kernel/dma-coherent.c int dma_alloc_from_coherent(struct device *dev, ssize_t size, · line 139

Quoted 9 lines
kernel/dma-coherent.c +9 -0
+ * @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 '%'.

kernel/dma-coherent.c int dma_alloc_from_coherent(struct device *dev, ssize_t size,

Quoted 6 lines
kernel/dma-coherent.c +2 -1
+ * 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/

#2 lore raw
Quoted 10 lines · Randy Dunlap
Quoted 8 lines · 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 <[email protected]>
AuthorDate: Sun Jul 20 15:01:10 2008 +0400
Committer:  Ingo Molnar <[email protected]>
CommitDate: Sun Jul 20 21:22:00 2008 +0200
Quoted 5 lines
Quoted 1 line

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:

Quoted 1 line

From 766159161001e2e118cc840e7aca4b8d500b1ebf Mon Sep 17 00:00:00 2001

From: Dmitry Baryshkov <[email protected]>
Date: Wed, 30 Jul 2008 01:41:58 +0400
Subject: [PATCH] dma-coherent: fix kernel-doc comments

---
 kernel/dma-coherent.c |   10 +++++-----
 1 files changed, 5 insertions(+), 5 deletions(-)
kernel/dma-coherent.c +5 -5
index 7517115..9ef28a0 100644
@@ -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)
Signature · 5 lines
1.5.6.3

-- 
With best wishes
Dmitry
#3 lore raw
Quoted 11 lines · On Wed, 30 Jul 2008 14:46:50 +0400 Dmitry Baryshkov wrote:
Quoted 10 lines · Randy Dunlap
Quoted 8 lines · 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 <[email protected]>
AuthorDate: Sun Jul 20 15:01:10 2008 +0400
Committer:  Ingo Molnar <[email protected]>
CommitDate: Sun Jul 20 21:22:00 2008 +0200
Quoted 7 lines
Quoted 5 lines
Quoted 1 line

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?

Quoted 48 lines
Quoted 1 line

From 766159161001e2e118cc840e7aca4b8d500b1ebf Mon Sep 17 00:00:00 2001

From: Dmitry Baryshkov <[email protected]>
Date: Wed, 30 Jul 2008 01:41:58 +0400
Subject: [PATCH] dma-coherent: fix kernel-doc comments

---
 kernel/dma-coherent.c |   10 +++++-----
 1 files changed, 5 insertions(+), 5 deletions(-)
kernel/dma-coherent.c +4 -4
index 7517115..9ef28a0 100644
@@ -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

kernel/dma-coherent.c int dma_alloc_from_coherent(struct device *dev, ssize_t size, · line 142

Quoted 8 lines
kernel/dma-coherent.c +1 -1
@@ -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/

#4 lore raw
Quoted 19 lines · Randy Dunlap
Quoted 18 lines · On Wed, 30 Jul 2008 14:46:50 +0400 Dmitry Baryshkov wrote:
Quoted 16 lines · Randy Dunlap
Quoted 11 lines · 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 <[email protected]>
AuthorDate: Sun Jul 20 15:01:10 2008 +0400
Committer:  Ingo Molnar <[email protected]>
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 ...

Quoted 5 lines
Quoted 1 line

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