From: Christoph Hellwig <hch@lst.de>
To: Mauro Carvalho Chehab <mchehab@kernel.org>,
Marek Szyprowski <m.szyprowski@samsung.com>,
Tomasz Figa <tfiga@chromium.org>,
iommu@lists.linux-foundation.org
Cc: Robin Murphy <robin.murphy@arm.com>,
linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
linux-media@vger.kernel.org
Subject: [PATCH 2/8] dma-mapping: document dma_{alloc,free}_pages
Date: Wed, 30 Sep 2020 18:09:11 +0200 [thread overview]
Message-ID: <20200930160917.1234225-3-hch@lst.de> (raw)
In-Reply-To: <20200930160917.1234225-1-hch@lst.de>
Document the new dma_alloc_pages and dma_free_pages APIs, and fix
up the documentation for dma_alloc_noncoherent and dma_free_noncoherent.
Reported-by: Robin Murphy <robin.murphy@arm.com>
Signed-off-by: Christoph Hellwig <hch@lst.de>
---
Documentation/core-api/dma-api.rst | 45 ++++++++++++++++++++++++++----
1 file changed, 40 insertions(+), 5 deletions(-)
diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
index ea0413276ddb70..a75c469dbcaa7c 100644
--- a/Documentation/core-api/dma-api.rst
+++ b/Documentation/core-api/dma-api.rst
@@ -534,11 +534,9 @@ an I/O device, you should not be using this part of the API.
dma_addr_t *dma_handle, enum dma_data_direction dir,
gfp_t gfp)
-This routine allocates a region of <size> bytes of consistent memory. It
+This routine allocates a region of <size> bytes of non-coherent memory. It
returns a pointer to the allocated region (in the processor's virtual address
-space) or NULL if the allocation failed. The returned memory may or may not
-be in the kernels direct mapping. Drivers must not call virt_to_page on
-the returned memory region.
+space) or NULL if the allocation failed.
It also returns a <dma_handle> which may be cast to an unsigned integer the
same width as the bus and given to the device as the DMA address base of
@@ -565,7 +563,44 @@ reused.
Free a region of memory previously allocated using dma_alloc_noncoherent().
dev, size and dma_handle and dir must all be the same as those passed into
dma_alloc_noncoherent(). cpu_addr must be the virtual address returned by
-the dma_alloc_noncoherent().
+dma_alloc_noncoherent().
+
+::
+
+ struct page *
+ dma_alloc_pages(struct device *dev, size_t size, dma_addr_t *dma_handle,
+ enum dma_data_direction dir, gfp_t gfp)
+
+This routine allocates a region of <size> bytes of non-coherent memory. It
+returns a pointer to first struct page for the region, or NULL if the
+allocation failed.
+
+It also returns a <dma_handle> which may be cast to an unsigned integer the
+same width as the bus and given to the device as the DMA address base of
+the region.
+
+The dir parameter specified if data is read and/or written by the device,
+see dma_map_single() for details.
+
+The gfp parameter allows the caller to specify the ``GFP_`` flags (see
+kmalloc()) for the allocation, but rejects flags used to specify a memory
+zone such as GFP_DMA or GFP_HIGHMEM.
+
+Before giving the memory to the device, dma_sync_single_for_device() needs
+to be called, and before reading memory written by the device,
+dma_sync_single_for_cpu(), just like for streaming DMA mappings that are
+reused.
+
+::
+
+ void
+ dma_free_pages(struct device *dev, size_t size, struct page *page,
+ dma_addr_t dma_handle, enum dma_data_direction dir)
+
+Free a region of memory previously allocated using dma_alloc_pages().
+dev, size and dma_handle and dir must all be the same as those passed into
+dma_alloc_noncoherent(). page must be the pointer returned by
+dma_alloc_pages().
::
--
2.28.0
next prev parent reply other threads:[~2020-09-30 16:10 UTC|newest]
Thread overview: 28+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-09-30 16:09 dma_alloc_pages / dma_alloc_noncoherent fixups Christoph Hellwig
2020-09-30 16:09 ` [PATCH 1/8] dma-mapping: remove the {alloc,free}_noncoherent methods Christoph Hellwig
2020-09-30 16:09 ` Christoph Hellwig [this message]
2020-09-30 16:09 ` [PATCH 3/8] dma-direct check for highmem pages in dma_direct_alloc_pages Christoph Hellwig
2020-09-30 16:09 ` [PATCH 4/8] dma-direct: use __GFP_ZERO " Christoph Hellwig
2020-09-30 16:09 ` [PATCH 5/8] dma-direct: factor out a dma_direct_alloc_from_pool helper Christoph Hellwig
2020-09-30 16:09 ` [PATCH 6/8] dma-direct: simplify the DMA_ATTR_NO_KERNEL_MAPPING handling Christoph Hellwig
2020-09-30 16:09 ` [PATCH 7/8] dma-iommu: remove __iommu_dma_mmap Christoph Hellwig
2020-09-30 16:09 ` [PATCH 8/8] WIP: add a dma_alloc_contiguous API Christoph Hellwig
2020-10-02 17:50 ` Tomasz Figa
2020-10-05 8:26 ` Christoph Hellwig
2020-10-06 20:56 ` Tomasz Figa
2020-10-07 6:21 ` Christoph Hellwig
2020-10-07 12:21 ` Tomasz Figa
2020-10-07 12:24 ` Christoph Hellwig
2020-10-14 13:20 ` Tomasz Figa
2020-10-14 15:03 ` David Laight
2020-11-09 14:53 ` Ricardo Ribalda
2020-11-10 9:25 ` Christoph Hellwig
2020-11-10 9:33 ` Ricardo Ribalda
2020-11-10 9:41 ` Christoph Hellwig
2020-11-10 9:50 ` Tomasz Figa
2020-11-10 9:57 ` Christoph Hellwig
2020-11-17 21:21 ` Ricardo Ribalda
2020-11-18 14:25 ` [PATCH] WIP! media: uvcvideo: Use dma_alloc_noncontiguos API Ricardo Ribalda
2020-11-24 11:35 ` Christoph Hellwig
2020-11-24 12:01 ` Ricardo Ribalda
2020-11-24 13:33 ` 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=20200930160917.1234225-3-hch@lst.de \
--to=hch@lst.de \
--cc=iommu@lists.linux-foundation.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-media@vger.kernel.org \
--cc=m.szyprowski@samsung.com \
--cc=mchehab@kernel.org \
--cc=robin.murphy@arm.com \
--cc=tfiga@chromium.org \
/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).