iommu.lists.linux-foundation.org archive mirror
 help / color / mirror / Atom feed
From: Christoph Hellwig <hch@lst.de>
To: Tony Luck <tony.luck@intel.com>,
	Fenghua Yu <fenghua.yu@intel.com>,
	Thomas Bogendoerfer <tsbogend@alpha.franken.de>,
	iommu@lists.linux-foundation.org
Cc: linux-ia64@vger.kernel.org, linux-doc@vger.kernel.org,
	linux-kernel@vger.kernel.org, linux-mips@vger.kernel.org,
	Robin Murphy <robin.murphy@arm.com>
Subject: [PATCH 12/12] dma-mapping: move the dma_declare_coherent_memory documentation
Date: Tue,  8 Sep 2020 18:47:58 +0200	[thread overview]
Message-ID: <20200908164758.3177341-13-hch@lst.de> (raw)
In-Reply-To: <20200908164758.3177341-1-hch@lst.de>

dma_declare_coherent_memory should not be in a DMA API guide aimed
at driver writers (that is consumers of the API).  Move it to a comment
near the function instead.

Signed-off-by: Christoph Hellwig <hch@lst.de>
---
 Documentation/core-api/dma-api.rst | 24 ------------------------
 kernel/dma/coherent.c              | 17 +++++++++++++++++
 2 files changed, 17 insertions(+), 24 deletions(-)

diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
index 3b3abbbb4b9a6f..90239348b30f6f 100644
--- a/Documentation/core-api/dma-api.rst
+++ b/Documentation/core-api/dma-api.rst
@@ -586,30 +586,6 @@ the DMA_ATTR_NON_CONSISTENT flag starting at virtual address vaddr and
 continuing on for size.  Again, you *must* observe the cache line
 boundaries when doing this.
 
-::
-
-	int
-	dma_declare_coherent_memory(struct device *dev, phys_addr_t phys_addr,
-				    dma_addr_t device_addr, size_t size);
-
-Declare region of memory to be handed out by dma_alloc_coherent() when
-it's asked for coherent memory for this device.
-
-phys_addr is the CPU physical address to which the memory is currently
-assigned (this will be ioremapped so the CPU can access the region).
-
-device_addr is the DMA address the device needs to be programmed
-with to actually address this memory (this will be handed out as the
-dma_addr_t in dma_alloc_coherent()).
-
-size is the size of the area (must be multiples of PAGE_SIZE).
-
-As a simplification for the platforms, only *one* such region of
-memory may be declared per device.
-
-For reasons of efficiency, most platforms choose to track the declared
-region only at the granularity of a page.  For smaller allocations,
-you should use the dma_pool() API.
 
 Part III - Debug drivers use of the DMA-API
 -------------------------------------------
diff --git a/kernel/dma/coherent.c b/kernel/dma/coherent.c
index 2a0c4985f38e41..f85d14bbfcbe03 100644
--- a/kernel/dma/coherent.c
+++ b/kernel/dma/coherent.c
@@ -107,6 +107,23 @@ static int dma_assign_coherent_memory(struct device *dev,
 	return 0;
 }
 
+/*
+ * Declare a region of memory to be handed out by dma_alloc_coherent() when it
+ * is asked for coherent memory for this device.  This shall only be used
+ * from platform code, usually based on the device tree description.
+ * 
+ * phys_addr is the CPU physical address to which the memory is currently
+ * assigned (this will be ioremapped so the CPU can access the region).
+ *
+ * device_addr is the DMA address the device needs to be programmed with to
+ * actually address this memory (this will be handed out as the dma_addr_t in
+ * dma_alloc_coherent()).
+ *
+ * size is the size of the area (must be a multiple of PAGE_SIZE).
+ *
+ * As a simplification for the platforms, only *one* such region of memory may
+ * be declared per device.
+ */
 int dma_declare_coherent_memory(struct device *dev, phys_addr_t phys_addr,
 				dma_addr_t device_addr, size_t size)
 {
-- 
2.28.0

_______________________________________________
iommu mailing list
iommu@lists.linux-foundation.org
https://lists.linuxfoundation.org/mailman/listinfo/iommu

  parent reply	other threads:[~2020-09-08 16:48 UTC|newest]

Thread overview: 27+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-09-08 16:47 dma-mapping cleanups Christoph Hellwig
2020-09-08 16:47 ` [PATCH 01/12] MIPS: make dma_sync_*_for_cpu a little less overzealous Christoph Hellwig
2020-09-08 16:47 ` [PATCH 02/12] MIPS/jazzdma: remove the unused vdma_remap function Christoph Hellwig
2020-09-08 16:47 ` [PATCH 03/12] MIPS/jazzdma: decouple from dma-direct Christoph Hellwig
2020-09-08 16:47 ` [PATCH 04/12] dma-mapping: fix DMA_OPS dependencies Christoph Hellwig
2020-09-08 18:04   ` Sergei Shtylyov
2020-09-11  7:10     ` Christoph Hellwig
2020-09-10 12:55   ` Robin Murphy
2020-09-11  7:09     ` Christoph Hellwig
2020-09-08 16:47 ` [PATCH 05/12] dma-mapping: add (back) arch_dma_mark_clean for ia64 Christoph Hellwig
2020-09-08 16:47 ` [PATCH 06/12] dma-direct: remove dma_direct_{alloc,free}_pages Christoph Hellwig
2020-09-10 12:57   ` Robin Murphy
2020-09-08 16:47 ` [PATCH 07/12] dma-direct: lift gfp_t manipulation out of__dma_direct_alloc_pages Christoph Hellwig
2020-09-10 13:02   ` Robin Murphy
2020-09-08 16:47 ` [PATCH 08/12] dma-direct: use phys_to_dma_direct in dma_direct_alloc Christoph Hellwig
2020-09-10 13:03   ` Robin Murphy
2020-09-08 16:47 ` [PATCH 09/12] dma-direct: remove __dma_to_phys Christoph Hellwig
2020-09-10 13:26   ` Robin Murphy
2020-09-11  7:14     ` Christoph Hellwig
2020-09-08 16:47 ` [PATCH 10/12] dma-direct: rename and cleanup __phys_to_dma Christoph Hellwig
2020-09-10 13:30   ` Robin Murphy
2020-09-08 16:47 ` [PATCH 11/12] dma-mapping: move dma_common_{mmap, get_sgtable} out of mapping.c Christoph Hellwig
2020-09-10 13:34   ` Robin Murphy
2020-09-11  7:15     ` [PATCH 11/12] dma-mapping: move dma_common_{mmap,get_sgtable} " Christoph Hellwig
2020-09-08 16:47 ` Christoph Hellwig [this message]
2020-09-10 13:51   ` [PATCH 12/12] dma-mapping: move the dma_declare_coherent_memory documentation Robin Murphy
2020-09-11  7:17     ` Christoph Hellwig

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200908164758.3177341-13-hch@lst.de \
    --to=hch@lst.de \
    --cc=fenghua.yu@intel.com \
    --cc=iommu@lists.linux-foundation.org \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-ia64@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-mips@vger.kernel.org \
    --cc=robin.murphy@arm.com \
    --cc=tony.luck@intel.com \
    --cc=tsbogend@alpha.franken.de \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).