[PATCH v2 0/8] update DMA API documentation

[PATCH v2 0/8] update DMA API documentation

[Petr Tesarik]

A few documentation updates:

* remove outdated and confusing parts
* reduce duplicates
* update streaming DMA API expectations

Changes from v1:

* move DMA Pools to dma-api.rst
* improve streaming DMA addressing constraints

Petr Tesarik (8):
  docs: dma-api: use "DMA API" consistently throughout the document
  docs: dma-api: replace consistent with coherent
  docs: dma-api: remove remnants of PCI DMA API
  docs: dma-api: add a kernel-doc comment for dma_pool_zalloc()
  docs: dma-api: remove duplicate description of the DMA pool API
  docs: dma-api: clarify DMA addressing limitations
  docs: dma-api: update streaming DMA physical address constraints
  docs: dma-api: clean up documentation of dma_map_sg()

 Documentation/core-api/dma-api-howto.rst |  36 ++---
 Documentation/core-api/dma-api.rst       | 191 ++++++++---------------
 Documentation/core-api/mm-api.rst        |   6 -
 include/linux/dmapool.h                  |   8 +
 mm/dmapool.c                             |   6 +-
 5 files changed, 97 insertions(+), 150 deletions(-)

-- 
2.49.0

[PATCH v2 1/8] docs: dma-api: use "DMA API" consistently throughout the document

[Petr Tesarik]

Make sure that all occurrences are spelled "DMA API" (all uppercase, no
hyphen, no underscore).

Signed-off-by: Petr Tesarik <ptesarik@suse.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
---
 Documentation/core-api/dma-api.rst | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
index 2ad08517e626e..97f42c15f5e43 100644
--- a/Documentation/core-api/dma-api.rst
+++ b/Documentation/core-api/dma-api.rst
@@ -13,10 +13,10 @@ machines.  Unless you know that your driver absolutely has to support
 non-consistent platforms (this is usually only legacy platforms) you
 should only use the API described in part I.
 
-Part I - dma_API
+Part I - DMA API
 ----------------
 
-To get the dma_API, you must #include <linux/dma-mapping.h>.  This
+To get the DMA API, you must #include <linux/dma-mapping.h>.  This
 provides dma_addr_t and the interfaces described below.
 
 A dma_addr_t can hold any valid DMA address for the platform.  It can be
@@ -76,7 +76,7 @@ may only be called with IRQs enabled.
 Part Ib - Using small DMA-coherent buffers
 ------------------------------------------
 
-To get this part of the dma_API, you must #include <linux/dmapool.h>
+To get this part of the DMA API, you must #include <linux/dmapool.h>
 
 Many drivers need lots of small DMA-coherent memory regions for DMA
 descriptors or I/O buffers.  Rather than allocating in units of a page
@@ -247,7 +247,7 @@ Maps a piece of processor virtual memory so it can be accessed by the
 device and returns the DMA address of the memory.
 
 The direction for both APIs may be converted freely by casting.
-However the dma_API uses a strongly typed enumerator for its
+However the DMA API uses a strongly typed enumerator for its
 direction:
 
 ======================= =============================================
@@ -775,19 +775,19 @@ memory or doing partial flushes.
 	of two for easy alignment.
 
 
-Part III - Debug drivers use of the DMA-API
+Part III - Debug drivers use of the DMA API
 -------------------------------------------
 
-The DMA-API as described above has some constraints. DMA addresses must be
+The DMA API as described above has some constraints. DMA addresses must be
 released with the corresponding function with the same size for example. With
 the advent of hardware IOMMUs it becomes more and more important that drivers
 do not violate those constraints. In the worst case such a violation can
 result in data corruption up to destroyed filesystems.
 
-To debug drivers and find bugs in the usage of the DMA-API checking code can
+To debug drivers and find bugs in the usage of the DMA API checking code can
 be compiled into the kernel which will tell the developer about those
 violations. If your architecture supports it you can select the "Enable
-debugging of DMA-API usage" option in your kernel configuration. Enabling this
+debugging of DMA API usage" option in your kernel configuration. Enabling this
 option has a performance impact. Do not enable it in production kernels.
 
 If you boot the resulting kernel will contain code which does some bookkeeping
@@ -826,7 +826,7 @@ example warning message may look like this::
 	<EOI> <4>---[ end trace f6435a98e2a38c0e ]---
 
 The driver developer can find the driver and the device including a stacktrace
-of the DMA-API call which caused this warning.
+of the DMA API call which caused this warning.
 
 Per default only the first error will result in a warning message. All other
 errors will only silently counted. This limitation exist to prevent the code
@@ -834,7 +834,7 @@ from flooding your kernel log. To support debugging a device driver this can
 be disabled via debugfs. See the debugfs interface documentation below for
 details.
 
-The debugfs directory for the DMA-API debugging code is called dma-api/. In
+The debugfs directory for the DMA API debugging code is called dma-api/. In
 this directory the following files can currently be found:
 
 =============================== ===============================================
@@ -882,7 +882,7 @@ dma-api/driver_filter		You can write a name of a driver into this file
 
 If you have this code compiled into your kernel it will be enabled by default.
 If you want to boot without the bookkeeping anyway you can provide
-'dma_debug=off' as a boot parameter. This will disable DMA-API debugging.
+'dma_debug=off' as a boot parameter. This will disable DMA API debugging.
 Notice that you can not enable it again at runtime. You have to reboot to do
 so.
 
-- 
2.49.0

[PATCH v2 2/8] docs: dma-api: replace consistent with coherent

[Petr Tesarik]

For consistency, always use the term "coherent" when talking about memory
that is not subject to CPU caching effects. The term "consistent" is a
relic of a long-removed PCI DMA API (pci_alloc_consistent() and
pci_free_consistent() functions).

Signed-off-by: Petr Tesarik <ptesarik@suse.com>
---
 Documentation/core-api/dma-api-howto.rst | 36 ++++++++++++------------
 Documentation/core-api/dma-api.rst       | 14 ++++-----
 mm/dmapool.c                             |  6 ++--
 3 files changed, 28 insertions(+), 28 deletions(-)

diff --git a/Documentation/core-api/dma-api-howto.rst b/Documentation/core-api/dma-api-howto.rst
index 0bf31b6c4383c..96fce2a9aa901 100644
--- a/Documentation/core-api/dma-api-howto.rst
+++ b/Documentation/core-api/dma-api-howto.rst
@@ -155,7 +155,7 @@ a device with limitations, it needs to be decreased.
 
 Special note about PCI: PCI-X specification requires PCI-X devices to support
 64-bit addressing (DAC) for all transactions.  And at least one platform (SGI
-SN2) requires 64-bit consistent allocations to operate correctly when the IO
+SN2) requires 64-bit coherent allocations to operate correctly when the IO
 bus is in PCI-X mode.
 
 For correct operation, you must set the DMA mask to inform the kernel about
@@ -174,7 +174,7 @@ used instead:
 
 		int dma_set_mask(struct device *dev, u64 mask);
 
-	The setup for consistent allocations is performed via a call
+	The setup for coherent allocations is performed via a call
 	to dma_set_coherent_mask()::
 
 		int dma_set_coherent_mask(struct device *dev, u64 mask);
@@ -241,7 +241,7 @@ it would look like this::
 
 The coherent mask will always be able to set the same or a smaller mask as
 the streaming mask. However for the rare case that a device driver only
-uses consistent allocations, one would have to check the return value from
+uses coherent allocations, one would have to check the return value from
 dma_set_coherent_mask().
 
 Finally, if your device can only drive the low 24-bits of
@@ -298,20 +298,20 @@ Types of DMA mappings
 
 There are two types of DMA mappings:
 
-- Consistent DMA mappings which are usually mapped at driver
+- Coherent DMA mappings which are usually mapped at driver
   initialization, unmapped at the end and for which the hardware should
   guarantee that the device and the CPU can access the data
   in parallel and will see updates made by each other without any
   explicit software flushing.
 
-  Think of "consistent" as "synchronous" or "coherent".
+  Think of "coherent" as "synchronous".
 
-  The current default is to return consistent memory in the low 32
+  The current default is to return coherent memory in the low 32
   bits of the DMA space.  However, for future compatibility you should
-  set the consistent mask even if this default is fine for your
+  set the coherent mask even if this default is fine for your
   driver.
 
-  Good examples of what to use consistent mappings for are:
+  Good examples of what to use coherent mappings for are:
 
 	- Network card DMA ring descriptors.
 	- SCSI adapter mailbox command data structures.
@@ -320,13 +320,13 @@ There are two types of DMA mappings:
 
   The invariant these examples all require is that any CPU store
   to memory is immediately visible to the device, and vice
-  versa.  Consistent mappings guarantee this.
+  versa.  Coherent mappings guarantee this.
 
   .. important::
 
-	     Consistent DMA memory does not preclude the usage of
+	     Coherent DMA memory does not preclude the usage of
 	     proper memory barriers.  The CPU may reorder stores to
-	     consistent memory just as it may normal memory.  Example:
+	     coherent memory just as it may normal memory.  Example:
 	     if it is important for the device to see the first word
 	     of a descriptor updated before the second, you must do
 	     something like::
@@ -365,10 +365,10 @@ Also, systems with caches that aren't DMA-coherent will work better
 when the underlying buffers don't share cache lines with other data.
 
 
-Using Consistent DMA mappings
-=============================
+Using Coherent DMA mappings
+===========================
 
-To allocate and map large (PAGE_SIZE or so) consistent DMA regions,
+To allocate and map large (PAGE_SIZE or so) coherent DMA regions,
 you should do::
 
 	dma_addr_t dma_handle;
@@ -385,10 +385,10 @@ __get_free_pages() (but takes size instead of a page order).  If your
 driver needs regions sized smaller than a page, you may prefer using
 the dma_pool interface, described below.
 
-The consistent DMA mapping interfaces, will by default return a DMA address
+The coherent DMA mapping interfaces, will by default return a DMA address
 which is 32-bit addressable.  Even if the device indicates (via the DMA mask)
-that it may address the upper 32-bits, consistent allocation will only
-return > 32-bit addresses for DMA if the consistent DMA mask has been
+that it may address the upper 32-bits, coherent allocation will only
+return > 32-bit addresses for DMA if the coherent DMA mask has been
 explicitly changed via dma_set_coherent_mask().  This is true of the
 dma_pool interface as well.
 
@@ -497,7 +497,7 @@ program address space.  Such platforms can and do report errors in the
 kernel logs when the DMA controller hardware detects violation of the
 permission setting.
 
-Only streaming mappings specify a direction, consistent mappings
+Only streaming mappings specify a direction, coherent mappings
 implicitly have a direction attribute setting of
 DMA_BIDIRECTIONAL.
 
diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
index 97f42c15f5e43..c0a2cc7d0b959 100644
--- a/Documentation/core-api/dma-api.rst
+++ b/Documentation/core-api/dma-api.rst
@@ -8,9 +8,9 @@ This document describes the DMA API.  For a more gentle introduction
 of the API (and actual examples), see Documentation/core-api/dma-api-howto.rst.
 
 This API is split into two pieces.  Part I describes the basic API.
-Part II describes extensions for supporting non-consistent memory
+Part II describes extensions for supporting non-coherent memory
 machines.  Unless you know that your driver absolutely has to support
-non-consistent platforms (this is usually only legacy platforms) you
+non-coherent platforms (this is usually only legacy platforms) you
 should only use the API described in part I.
 
 Part I - DMA API
@@ -33,13 +33,13 @@ Part Ia - Using large DMA-coherent buffers
 	dma_alloc_coherent(struct device *dev, size_t size,
 			   dma_addr_t *dma_handle, gfp_t flag)
 
-Consistent memory is memory for which a write by either the device or
+Coherent memory is memory for which a write by either the device or
 the processor can immediately be read by the processor or device
 without having to worry about caching effects.  (You may however need
 to make sure to flush the processor's write buffers before telling
 devices to read that memory.)
 
-This routine allocates a region of <size> bytes of consistent memory.
+This routine allocates a region of <size> bytes of coherent memory.
 
 It returns a pointer to the allocated region (in the processor's virtual
 address space) or NULL if the allocation failed.
@@ -48,9 +48,9 @@ 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.
 
-Note: consistent memory can be expensive on some platforms, and the
+Note: coherent memory can be expensive on some platforms, and the
 minimum allocation length may be as big as a page, so you should
-consolidate your requests for consistent memory as much as possible.
+consolidate your requests for coherent memory as much as possible.
 The simplest way to do that is to use the dma_pool calls (see below).
 
 The flag parameter (dma_alloc_coherent() only) allows the caller to
@@ -64,7 +64,7 @@ the returned memory, like GFP_DMA).
 	dma_free_coherent(struct device *dev, size_t size, void *cpu_addr,
 			  dma_addr_t dma_handle)
 
-Free a region of consistent memory you previously allocated.  dev,
+Free a region of coherent memory you previously allocated.  dev,
 size and dma_handle must all be the same as those passed into
 dma_alloc_coherent().  cpu_addr must be the virtual address returned by
 the dma_alloc_coherent().
diff --git a/mm/dmapool.c b/mm/dmapool.c
index 5be8cc1c65292..5d8af6e291276 100644
--- a/mm/dmapool.c
+++ b/mm/dmapool.c
@@ -200,7 +200,7 @@ static void pool_block_push(struct dma_pool *pool, struct dma_block *block,
 
 
 /**
- * dma_pool_create_node - Creates a pool of consistent memory blocks, for dma.
+ * dma_pool_create_node - Creates a pool of coherent DMA memory blocks.
  * @name: name of pool, for diagnostics
  * @dev: device that will be doing the DMA
  * @size: size of the blocks in this pool.
@@ -210,7 +210,7 @@ static void pool_block_push(struct dma_pool *pool, struct dma_block *block,
  * Context: not in_interrupt()
  *
  * Given one of these pools, dma_pool_alloc()
- * may be used to allocate memory.  Such memory will all have "consistent"
+ * may be used to allocate memory.  Such memory will all have coherent
  * 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.
@@ -395,7 +395,7 @@ void dma_pool_destroy(struct dma_pool *pool)
 EXPORT_SYMBOL(dma_pool_destroy);
 
 /**
- * dma_pool_alloc - get a block of consistent memory
+ * dma_pool_alloc - get a block of coherent memory
  * @pool: dma pool that will produce the block
  * @mem_flags: GFP_* bitmask
  * @handle: pointer to dma address of block
-- 
2.49.0

[PATCH v2 3/8] docs: dma-api: remove remnants of PCI DMA API

[Petr Tesarik]

The wording sometimes suggests there are multiple functions for an
operation. This was in fact the case before PCI DMA API was removed, but
since there is only one API now, the documentation has become confusing.

To improve readability:

* Remove implicit references to the PCI DMA API (plurals, use of "both",
  etc.)

* Where possible, refer to an actual function rather than a more generic
  description of the operation.

Signed-off-by: Petr Tesarik <ptesarik@suse.com>
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/core-api/dma-api.rst | 25 ++++++++++---------------
 1 file changed, 10 insertions(+), 15 deletions(-)

diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
index c0a2cc7d0b959..3e89e3b0ecfd2 100644
--- a/Documentation/core-api/dma-api.rst
+++ b/Documentation/core-api/dma-api.rst
@@ -53,10 +53,9 @@ minimum allocation length may be as big as a page, so you should
 consolidate your requests for coherent memory as much as possible.
 The simplest way to do that is to use the dma_pool calls (see below).
 
-The flag parameter (dma_alloc_coherent() only) allows the caller to
-specify the ``GFP_`` flags (see kmalloc()) for the allocation (the
-implementation may choose to ignore flags that affect the location of
-the returned memory, like GFP_DMA).
+The flag parameter allows the caller to specify the ``GFP_`` flags (see
+kmalloc()) for the allocation (the implementation may ignore flags that affect
+the location of the returned memory, like GFP_DMA).
 
 ::
 
@@ -64,13 +63,12 @@ the returned memory, like GFP_DMA).
 	dma_free_coherent(struct device *dev, size_t size, void *cpu_addr,
 			  dma_addr_t dma_handle)
 
-Free a region of coherent memory you previously allocated.  dev,
-size and dma_handle must all be the same as those passed into
-dma_alloc_coherent().  cpu_addr must be the virtual address returned by
-the dma_alloc_coherent().
+Free a previously allocated region of coherent memory.  dev, size and dma_handle
+must all be the same as those passed into dma_alloc_coherent().  cpu_addr must
+be the virtual address returned by dma_alloc_coherent().
 
-Note that unlike their sibling allocation calls, these routines
-may only be called with IRQs enabled.
+Note that unlike the sibling allocation call, this routine may only be called
+with IRQs enabled.
 
 
 Part Ib - Using small DMA-coherent buffers
@@ -246,9 +244,7 @@ Part Id - Streaming DMA mappings
 Maps a piece of processor virtual memory so it can be accessed by the
 device and returns the DMA address of the memory.
 
-The direction for both APIs may be converted freely by casting.
-However the DMA API uses a strongly typed enumerator for its
-direction:
+The DMA API uses a strongly typed enumerator for its direction:
 
 ======================= =============================================
 DMA_NONE		no direction (used for debugging)
@@ -325,8 +321,7 @@ DMA_BIDIRECTIONAL	direction isn't known
 			 enum dma_data_direction direction)
 
 Unmaps the region previously mapped.  All the parameters passed in
-must be identical to those passed in (and returned) by the mapping
-API.
+must be identical to those passed to (and returned by) dma_map_single().
 
 ::
 
-- 
2.49.0

[PATCH v2 4/8] docs: dma-api: add a kernel-doc comment for dma_pool_zalloc()

[Petr Tesarik]

Document the dma_pool_zalloc() wrapper.

Signed-off-by: Petr Tesarik <ptesarik@suse.com>
---
 Documentation/core-api/mm-api.rst | 2 ++
 include/linux/dmapool.h           | 8 ++++++++
 2 files changed, 10 insertions(+)

diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst
index af8151db88b28..a61766328ac06 100644
--- a/Documentation/core-api/mm-api.rst
+++ b/Documentation/core-api/mm-api.rst
@@ -97,6 +97,8 @@ DMA pools
 .. kernel-doc:: mm/dmapool.c
    :export:
 
+.. kernel-doc:: include/linux/dmapool.h
+
 More Memory Management Functions
 ================================
 
diff --git a/include/linux/dmapool.h b/include/linux/dmapool.h
index 06c4de602b2f3..c0c7717d3ae7b 100644
--- a/include/linux/dmapool.h
+++ b/include/linux/dmapool.h
@@ -60,6 +60,14 @@ static inline struct dma_pool *dma_pool_create(const char *name,
 				    NUMA_NO_NODE);
 }
 
+/**
+ * dma_pool_zalloc - Get a zero-initialized block of DMA coherent memory.
+ * @pool: dma pool that will produce the block
+ * @mem_flags: GFP_* bitmask
+ * @handle: pointer to dma address of block
+ *
+ * Same as @dma_pool_alloc, but the returned memory is zeroed.
+ */
 static inline void *dma_pool_zalloc(struct dma_pool *pool, gfp_t mem_flags,
 				    dma_addr_t *handle)
 {
-- 
2.49.0

[PATCH v2 5/8] docs: dma-api: remove duplicate description of the DMA pool API

[Petr Tesarik]

Move the DMA pool API documentation from Memory Management APIs to
dma-api.rst, replacing the outdated duplicate description there.

Signed-off-by: Petr Tesarik <ptesarik@suse.com>
---
 Documentation/core-api/dma-api.rst | 62 ++----------------------------
 Documentation/core-api/mm-api.rst  |  8 ----
 2 files changed, 3 insertions(+), 67 deletions(-)

diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
index 3e89e3b0ecfd2..bed6e8fdf56e2 100644
--- a/Documentation/core-api/dma-api.rst
+++ b/Documentation/core-api/dma-api.rst
@@ -83,66 +83,10 @@ much like a struct kmem_cache, except that they use the DMA-coherent allocator,
 not __get_free_pages().  Also, they understand common hardware constraints
 for alignment, like queue heads needing to be aligned on N-byte boundaries.
 
+.. kernel-doc:: mm/dmapool.c
+   :export:
 
-::
-
-	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.
-
-
-::
-
-	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.
-
-::
-
-	void
-	dma_pool_free(struct dma_pool *pool, void *vaddr,
-		      dma_addr_t addr);
-
-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.
-
-::
-
-	void
-	dma_pool_destroy(struct dma_pool *pool);
-
-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:: include/linux/dmapool.h
 
 
 Part Ic - DMA addressing limitations
diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst
index a61766328ac06..50cfc78429304 100644
--- a/Documentation/core-api/mm-api.rst
+++ b/Documentation/core-api/mm-api.rst
@@ -91,14 +91,6 @@ Memory pools
 .. kernel-doc:: mm/mempool.c
    :export:
 
-DMA pools
-=========
-
-.. kernel-doc:: mm/dmapool.c
-   :export:
-
-.. kernel-doc:: include/linux/dmapool.h
-
 More Memory Management Functions
 ================================
 
-- 
2.49.0

[PATCH v2 6/8] docs: dma-api: clarify DMA addressing limitations

[Petr Tesarik]

Move the description of DMA mask from the documentation of dma_map_single()
to Part Ic - DMA addressing limitations and improve the wording.

Explain when a mask setting function may fail, and do not repeat this
explanation for each individual function.

Clarify which device parameters are updated by each mask setting function.

Signed-off-by: Petr Tesarik <ptesarik@suse.com>
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/core-api/dma-api.rst | 35 +++++++++++++++---------------
 1 file changed, 18 insertions(+), 17 deletions(-)

diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
index bed6e8fdf56e2..9fcdb160638e0 100644
--- a/Documentation/core-api/dma-api.rst
+++ b/Documentation/core-api/dma-api.rst
@@ -92,13 +92,20 @@ for alignment, like queue heads needing to be aligned on N-byte boundaries.
 Part Ic - DMA addressing limitations
 ------------------------------------
 
+DMA mask is a bit mask of the addressable region for the device. In other words,
+if applying the DMA mask (a bitwise AND operation) to the DMA address of a
+memory region does not clear any bits in the address, then the device can
+perform DMA to that memory region.
+
+All the below functions which set a DMA mask may fail if the requested mask
+cannot be used with the device, or if the device is not capable of doing DMA.
+
 ::
 
 	int
 	dma_set_mask_and_coherent(struct device *dev, u64 mask)
 
-Checks to see if the mask is possible and updates the device
-streaming and coherent DMA mask parameters if it is.
+Updates both streaming and coherent DMA masks.
 
 Returns: 0 if successful and a negative error if not.
 
@@ -107,8 +114,7 @@ Returns: 0 if successful and a negative error if not.
 	int
 	dma_set_mask(struct device *dev, u64 mask)
 
-Checks to see if the mask is possible and updates the device
-parameters if it is.
+Updates only the streaming DMA mask.
 
 Returns: 0 if successful and a negative error if not.
 
@@ -117,8 +123,7 @@ Returns: 0 if successful and a negative error if not.
 	int
 	dma_set_coherent_mask(struct device *dev, u64 mask)
 
-Checks to see if the mask is possible and updates the device
-parameters if it is.
+Updates only the coherent DMA mask.
 
 Returns: 0 if successful and a negative error if not.
 
@@ -173,7 +178,7 @@ transfer memory ownership.  Returns %false if those calls can be skipped.
 	unsigned long
 	dma_get_merge_boundary(struct device *dev);
 
-Returns the DMA merge boundary. If the device cannot merge any the DMA address
+Returns the DMA merge boundary. If the device cannot merge any DMA address
 segments, the function returns 0.
 
 Part Id - Streaming DMA mappings
@@ -207,16 +212,12 @@ DMA_BIDIRECTIONAL	direction isn't known
 	this API should be obtained from sources which guarantee it to be
 	physically contiguous (like kmalloc).
 
-	Further, the DMA address of the memory must be within the
-	dma_mask of the device (the dma_mask is a bit mask of the
-	addressable region for the device, i.e., if the DMA address of
-	the memory ANDed with the dma_mask is still equal to the DMA
-	address, then the device can perform DMA to the memory).  To
-	ensure that the memory allocated by kmalloc is within the dma_mask,
-	the driver may specify various platform-dependent flags to restrict
-	the DMA address range of the allocation (e.g., on x86, GFP_DMA
-	guarantees to be within the first 16MB of available DMA addresses,
-	as required by ISA devices).
+	Further, the DMA address of the memory must be within the dma_mask of
+	the device.  To ensure that the memory allocated by kmalloc is within
+	the dma_mask, the driver may specify various platform-dependent flags
+	to restrict the DMA address range of the allocation (e.g., on x86,
+	GFP_DMA guarantees to be within the first 16MB of available DMA
+	addresses, as required by ISA devices).
 
 	Note also that the above constraints on physical contiguity and
 	dma_mask may not apply if the platform has an IOMMU (a device which
-- 
2.49.0

[PATCH v2 7/8] docs: dma-api: update streaming DMA physical address constraints

[Petr Tesarik]

Add an introductory paragraph to Part Id - Streaming DMA mappings and move
the explanation of address constraints there, because it applies to all map
functions.

Clarify that streaming DMA can be used with memory which does not meet the
addressing constraints of a device, but it may fail in that case.

Make a note about SWIOTLB and link to the detailed description of it.

Do not mention platform-dependent allocation flags. The note may mislead
device driver authors into thinking that they should poke into and try to
second-guess the DMA API implementation. They definitely shouldn't.

Remove the claim that platforms with an IOMMU may not require physically
contiguous buffers. The current implementation explicitly rejects vmalloc
addresses, regardless of IOMMU.

Signed-off-by: Petr Tesarik <ptesarik@suse.com>
---
 Documentation/core-api/dma-api.rst | 36 +++++++++++++++++-------------
 1 file changed, 21 insertions(+), 15 deletions(-)

diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
index 9fcdb160638e0..a075550ebbb54 100644
--- a/Documentation/core-api/dma-api.rst
+++ b/Documentation/core-api/dma-api.rst
@@ -184,6 +184,26 @@ segments, the function returns 0.
 Part Id - Streaming DMA mappings
 --------------------------------
 
+Streaming DMA allows to map an existing buffer for DMA transfers and then
+unmap it when finished.  Map functions are not guaranteed to succeed, so the
+return value must be checked.
+
+.. note::
+
+	In particular, mapping may fail for memory not addressable by the
+	device, e.g. if it is not within the DMA mask of the device and/or a
+	connecting bus bridge.  Streaming DMA functions try to overcome such
+	addressing constraints, either by using an IOMMU (a device which maps
+	I/O DMA addresses to physical memory addresses), or by copying the
+	data to/from a bounce buffer if the kernel is configured with a
+	:doc:`SWIOTLB <swiotlb>`.  However, these methods are not always
+	available, and even if they are, they may still fail for a number of
+	reasons.
+
+	In short, a device driver may need to be wary of where buffers are
+	located in physical memory, especially if the DMA mask is less than 32
+	bits.
+
 ::
 
 	dma_addr_t
@@ -204,27 +224,13 @@ DMA_BIDIRECTIONAL	direction isn't known
 
 .. note::
 
-	Not all memory regions in a machine can be mapped by this API.
-	Further, contiguous kernel virtual space may not be contiguous as
+	Contiguous kernel virtual space may not be contiguous as
 	physical memory.  Since this API does not provide any scatter/gather
 	capability, it will fail if the user tries to map a non-physically
 	contiguous piece of memory.  For this reason, memory to be mapped by
 	this API should be obtained from sources which guarantee it to be
 	physically contiguous (like kmalloc).
 
-	Further, the DMA address of the memory must be within the dma_mask of
-	the device.  To ensure that the memory allocated by kmalloc is within
-	the dma_mask, the driver may specify various platform-dependent flags
-	to restrict the DMA address range of the allocation (e.g., on x86,
-	GFP_DMA guarantees to be within the first 16MB of available DMA
-	addresses, as required by ISA devices).
-
-	Note also that the above constraints on physical contiguity and
-	dma_mask may not apply if the platform has an IOMMU (a device which
-	maps an I/O DMA address to a physical memory address).  However, to be
-	portable, device driver writers may *not* assume that such an IOMMU
-	exists.
-
 .. warning::
 
 	Memory coherency operates at a granularity called the cache
-- 
2.49.0

[PATCH v2 8/8] docs: dma-api: clean up documentation of dma_map_sg()

[Petr Tesarik]

Describe in one sentence what the function does.

Do not repeat example situations when the returned number is lower than
the number of segments on input.

Signed-off-by: Petr Tesarik <ptesarik@suse.com>
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/core-api/dma-api.rst | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
index a075550ebbb54..6a57618118fd4 100644
--- a/Documentation/core-api/dma-api.rst
+++ b/Documentation/core-api/dma-api.rst
@@ -322,10 +322,10 @@ action (e.g. reduce current DMA mapping usage or delay and try again later).
 	dma_map_sg(struct device *dev, struct scatterlist *sg,
 		   int nents, enum dma_data_direction direction)
 
-Returns: the number of DMA address segments mapped (this may be shorter
-than <nents> passed in if some elements of the scatter/gather list are
-physically or virtually adjacent and an IOMMU maps them with a single
-entry).
+Maps a scatter/gather list for DMA. Returns the number of DMA address segments
+mapped, which may be smaller than <nents> passed in if several consecutive
+sglist entries are merged (e.g. with an IOMMU, or if some adjacent segments
+just happen to be physically contiguous).
 
 Please note that the sg cannot be mapped again if it has been mapped once.
 The mapping process is allowed to destroy information in the sg.
@@ -349,9 +349,8 @@ With scatterlists, you use the resulting mapping like this::
 where nents is the number of entries in the sglist.
 
 The implementation is free to merge several consecutive sglist entries
-into one (e.g. with an IOMMU, or if several pages just happen to be
-physically contiguous) and returns the actual number of sg entries it
-mapped them to. On failure 0, is returned.
+into one.  The returned number is the actual number of sg entries it
+mapped them to. On failure, 0 is returned.
 
 Then you should loop count times (note: this can be less than nents times)
 and use sg_dma_address() and sg_dma_len() macros where you previously
-- 
2.49.0

Re: [PATCH v2 0/8] update DMA API documentation

[Marek Szyprowski]

On 27.06.2025 12:10, Petr Tesarik wrote:
> A few documentation updates:
>
> * remove outdated and confusing parts
> * reduce duplicates
> * update streaming DMA API expectations

Thanks for this cleanup and documentation clarification! Feel free to 
add for the whole patchset:

Acked-by: Marek Szyprowski <m.szyprowski@samsung.com>


> Changes from v1:
>
> * move DMA Pools to dma-api.rst
> * improve streaming DMA addressing constraints
>
> Petr Tesarik (8):
>    docs: dma-api: use "DMA API" consistently throughout the document
>    docs: dma-api: replace consistent with coherent
>    docs: dma-api: remove remnants of PCI DMA API
>    docs: dma-api: add a kernel-doc comment for dma_pool_zalloc()
>    docs: dma-api: remove duplicate description of the DMA pool API
>    docs: dma-api: clarify DMA addressing limitations
>    docs: dma-api: update streaming DMA physical address constraints
>    docs: dma-api: clean up documentation of dma_map_sg()
>
>   Documentation/core-api/dma-api-howto.rst |  36 ++---
>   Documentation/core-api/dma-api.rst       | 191 ++++++++---------------
>   Documentation/core-api/mm-api.rst        |   6 -
>   include/linux/dmapool.h                  |   8 +
>   mm/dmapool.c                             |   6 +-
>   5 files changed, 97 insertions(+), 150 deletions(-)
>
Best regards
-- 
Marek Szyprowski, PhD
Samsung R&D Institute Poland

Re: [PATCH v2 1/8] docs: dma-api: use "DMA API" consistently throughout the document

[Randy Dunlap]

On 6/27/25 3:10 AM, Petr Tesarik wrote:
> Make sure that all occurrences are spelled "DMA API" (all uppercase, no
> hyphen, no underscore).
> 
> Signed-off-by: Petr Tesarik <ptesarik@suse.com>
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> ---
>  Documentation/core-api/dma-api.rst | 22 +++++++++++-----------
>  1 file changed, 11 insertions(+), 11 deletions(-)


-- 
~Randy

Re: [PATCH v2 2/8] docs: dma-api: replace consistent with coherent

[Randy Dunlap]

On 6/27/25 3:10 AM, Petr Tesarik wrote:
> For consistency, always use the term "coherent" when talking about memory
> that is not subject to CPU caching effects. The term "consistent" is a
> relic of a long-removed PCI DMA API (pci_alloc_consistent() and
> pci_free_consistent() functions).
> 
> Signed-off-by: Petr Tesarik <ptesarik@suse.com>

Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> ---
>  Documentation/core-api/dma-api-howto.rst | 36 ++++++++++++------------
>  Documentation/core-api/dma-api.rst       | 14 ++++-----
>  mm/dmapool.c                             |  6 ++--
>  3 files changed, 28 insertions(+), 28 deletions(-)

-- 
~Randy

Re: [PATCH v2 3/8] docs: dma-api: remove remnants of PCI DMA API

[Randy Dunlap]

On 6/27/25 3:10 AM, Petr Tesarik wrote:
> The wording sometimes suggests there are multiple functions for an
> operation. This was in fact the case before PCI DMA API was removed, but
> since there is only one API now, the documentation has become confusing.
> 
> To improve readability:
> 
> * Remove implicit references to the PCI DMA API (plurals, use of "both",
>   etc.)
> 
> * Where possible, refer to an actual function rather than a more generic
>   description of the operation.
> 
> Signed-off-by: Petr Tesarik <ptesarik@suse.com>
> Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> ---
>  Documentation/core-api/dma-api.rst | 25 ++++++++++---------------
>  1 file changed, 10 insertions(+), 15 deletions(-)

-- 
~Randy

Re: [PATCH v2 6/8] docs: dma-api: clarify DMA addressing limitations

[Randy Dunlap]

On 6/27/25 3:10 AM, Petr Tesarik wrote:
> Move the description of DMA mask from the documentation of dma_map_single()
> to Part Ic - DMA addressing limitations and improve the wording.
> 
> Explain when a mask setting function may fail, and do not repeat this
> explanation for each individual function.
> 
> Clarify which device parameters are updated by each mask setting function.
> 
> Signed-off-by: Petr Tesarik <ptesarik@suse.com>
> Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> ---
>  Documentation/core-api/dma-api.rst | 35 +++++++++++++++---------------
>  1 file changed, 18 insertions(+), 17 deletions(-)

-- 
~Randy

Re: [PATCH v2 7/8] docs: dma-api: update streaming DMA physical address constraints

[Randy Dunlap]

On 6/27/25 3:10 AM, Petr Tesarik wrote:
> Add an introductory paragraph to Part Id - Streaming DMA mappings and move
> the explanation of address constraints there, because it applies to all map
> functions.
> 
> Clarify that streaming DMA can be used with memory which does not meet the
> addressing constraints of a device, but it may fail in that case.
> 
> Make a note about SWIOTLB and link to the detailed description of it.
> 
> Do not mention platform-dependent allocation flags. The note may mislead
> device driver authors into thinking that they should poke into and try to
> second-guess the DMA API implementation. They definitely shouldn't.
> 
> Remove the claim that platforms with an IOMMU may not require physically
> contiguous buffers. The current implementation explicitly rejects vmalloc
> addresses, regardless of IOMMU.
> 
> Signed-off-by: Petr Tesarik <ptesarik@suse.com>

Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> ---
>  Documentation/core-api/dma-api.rst | 36 +++++++++++++++++-------------
>  1 file changed, 21 insertions(+), 15 deletions(-)

-- 
~Randy

Re: [PATCH v2 8/8] docs: dma-api: clean up documentation of dma_map_sg()

[Randy Dunlap]

On 6/27/25 3:10 AM, Petr Tesarik wrote:
> Describe in one sentence what the function does.
> 
> Do not repeat example situations when the returned number is lower than
> the number of segments on input.
> 
> Signed-off-by: Petr Tesarik <ptesarik@suse.com>
> Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> ---
>  Documentation/core-api/dma-api.rst | 13 ++++++-------
>  1 file changed, 6 insertions(+), 7 deletions(-)

-- 
~Randy

Re: [PATCH v2 5/8] docs: dma-api: remove duplicate description of the DMA pool API

[Randy Dunlap]

On 6/27/25 3:10 AM, Petr Tesarik wrote:
> Move the DMA pool API documentation from Memory Management APIs to
> dma-api.rst, replacing the outdated duplicate description there.
> 
> Signed-off-by: Petr Tesarik <ptesarik@suse.com>

Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> ---
>  Documentation/core-api/dma-api.rst | 62 ++----------------------------
>  Documentation/core-api/mm-api.rst  |  8 ----
>  2 files changed, 3 insertions(+), 67 deletions(-)

-- 
~Randy

Re: [PATCH v2 4/8] docs: dma-api: add a kernel-doc comment for dma_pool_zalloc()

[Randy Dunlap]

On 6/27/25 3:10 AM, Petr Tesarik wrote:
> Document the dma_pool_zalloc() wrapper.
> 
> Signed-off-by: Petr Tesarik <ptesarik@suse.com>
> ---
>  Documentation/core-api/mm-api.rst | 2 ++
>  include/linux/dmapool.h           | 8 ++++++++
>  2 files changed, 10 insertions(+)
> 
> diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst
> index af8151db88b28..a61766328ac06 100644
> --- a/Documentation/core-api/mm-api.rst
> +++ b/Documentation/core-api/mm-api.rst
> @@ -97,6 +97,8 @@ DMA pools
>  .. kernel-doc:: mm/dmapool.c
>     :export:
>  
> +.. kernel-doc:: include/linux/dmapool.h
> +
>  More Memory Management Functions
>  ================================
>  
> diff --git a/include/linux/dmapool.h b/include/linux/dmapool.h
> index 06c4de602b2f3..c0c7717d3ae7b 100644
> --- a/include/linux/dmapool.h
> +++ b/include/linux/dmapool.h
> @@ -60,6 +60,14 @@ static inline struct dma_pool *dma_pool_create(const char *name,
>  				    NUMA_NO_NODE);
>  }
>  
> +/**
> + * dma_pool_zalloc - Get a zero-initialized block of DMA coherent memory.
> + * @pool: dma pool that will produce the block
> + * @mem_flags: GFP_* bitmask
> + * @handle: pointer to dma address of block
> + *
> + * Same as @dma_pool_alloc, but the returned memory is zeroed.

    * Same as dma_pool_alloc(), but ...

'@' is for function arguments.

With that change:

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.


> + */
>  static inline void *dma_pool_zalloc(struct dma_pool *pool, gfp_t mem_flags,
>  				    dma_addr_t *handle)
>  {

-- 
~Randy

Re: [PATCH v2 7/8] docs: dma-api: update streaming DMA physical address constraints

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 3019 bytes --]

On Fri, Jun 27, 2025 at 12:10:14PM +0200, Petr Tesarik wrote:
> diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
> index 9fcdb160638e0..a075550ebbb54 100644
> --- a/Documentation/core-api/dma-api.rst
> +++ b/Documentation/core-api/dma-api.rst
> @@ -184,6 +184,26 @@ segments, the function returns 0.
>  Part Id - Streaming DMA mappings
>  --------------------------------
>  
> +Streaming DMA allows to map an existing buffer for DMA transfers and then
> +unmap it when finished.  Map functions are not guaranteed to succeed, so the
> +return value must be checked.
> +
> +.. note::
> +
> +	In particular, mapping may fail for memory not addressable by the
> +	device, e.g. if it is not within the DMA mask of the device and/or a
> +	connecting bus bridge.  Streaming DMA functions try to overcome such
> +	addressing constraints, either by using an IOMMU (a device which maps
> +	I/O DMA addresses to physical memory addresses), or by copying the
> +	data to/from a bounce buffer if the kernel is configured with a
> +	:doc:`SWIOTLB <swiotlb>`.  However, these methods are not always
> +	available, and even if they are, they may still fail for a number of
> +	reasons.
> +
> +	In short, a device driver may need to be wary of where buffers are
> +	located in physical memory, especially if the DMA mask is less than 32
> +	bits.
> +
>  ::
>  
>  	dma_addr_t
> @@ -204,27 +224,13 @@ DMA_BIDIRECTIONAL	direction isn't known
>  
>  .. note::
>  
> -	Not all memory regions in a machine can be mapped by this API.
> -	Further, contiguous kernel virtual space may not be contiguous as
> +	Contiguous kernel virtual space may not be contiguous as
>  	physical memory.  Since this API does not provide any scatter/gather
>  	capability, it will fail if the user tries to map a non-physically
>  	contiguous piece of memory.  For this reason, memory to be mapped by
>  	this API should be obtained from sources which guarantee it to be
>  	physically contiguous (like kmalloc).
>  
> -	Further, the DMA address of the memory must be within the dma_mask of
> -	the device.  To ensure that the memory allocated by kmalloc is within
> -	the dma_mask, the driver may specify various platform-dependent flags
> -	to restrict the DMA address range of the allocation (e.g., on x86,
> -	GFP_DMA guarantees to be within the first 16MB of available DMA
> -	addresses, as required by ISA devices).
> -
> -	Note also that the above constraints on physical contiguity and
> -	dma_mask may not apply if the platform has an IOMMU (a device which
> -	maps an I/O DMA address to a physical memory address).  However, to be
> -	portable, device driver writers may *not* assume that such an IOMMU
> -	exists.
> -
>  .. warning::
>  
>  	Memory coherency operates at a granularity called the cache

The wording looks good, thanks!

Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH v2 4/8] docs: dma-api: add a kernel-doc comment for dma_pool_zalloc()

[Petr Tesarik]

On Sat, 28 Jun 2025 12:04:04 -0700
Randy Dunlap <rdunlap@infradead.org> wrote:

> On 6/27/25 3:10 AM, Petr Tesarik wrote:
> > Document the dma_pool_zalloc() wrapper.
> > 
> > Signed-off-by: Petr Tesarik <ptesarik@suse.com>
> > ---
> >  Documentation/core-api/mm-api.rst | 2 ++
> >  include/linux/dmapool.h           | 8 ++++++++
> >  2 files changed, 10 insertions(+)
> > 
> > diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst
> > index af8151db88b28..a61766328ac06 100644
> > --- a/Documentation/core-api/mm-api.rst
> > +++ b/Documentation/core-api/mm-api.rst
> > @@ -97,6 +97,8 @@ DMA pools
> >  .. kernel-doc:: mm/dmapool.c
> >     :export:
> >  
> > +.. kernel-doc:: include/linux/dmapool.h
> > +
> >  More Memory Management Functions
> >  ================================
> >  
> > diff --git a/include/linux/dmapool.h b/include/linux/dmapool.h
> > index 06c4de602b2f3..c0c7717d3ae7b 100644
> > --- a/include/linux/dmapool.h
> > +++ b/include/linux/dmapool.h
> > @@ -60,6 +60,14 @@ static inline struct dma_pool *dma_pool_create(const char *name,
> >  				    NUMA_NO_NODE);
> >  }
> >  
> > +/**
> > + * dma_pool_zalloc - Get a zero-initialized block of DMA coherent memory.
> > + * @pool: dma pool that will produce the block
> > + * @mem_flags: GFP_* bitmask
> > + * @handle: pointer to dma address of block
> > + *
> > + * Same as @dma_pool_alloc, but the returned memory is zeroed.  
> 
>     * Same as dma_pool_alloc(), but ...
> 
> '@' is for function arguments.

Oops. Somehow sneaked in...

> With that change:
> 
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> Tested-by: Randy Dunlap <rdunlap@infradead.org>

Do I have to submit a v3 then?

Petr T

Re: [PATCH v2 4/8] docs: dma-api: add a kernel-doc comment for dma_pool_zalloc()

[Jonathan Corbet]

Petr Tesarik <ptesarik@suse.com> writes:

> Do I have to submit a v3 then?

What path were you planning for this to go upstream?  If it goes through
docs, I can apply that tweak on the way in.

Thanks,

jon

Re: [PATCH v2 4/8] docs: dma-api: add a kernel-doc comment for dma_pool_zalloc()

[Petr Tesarik]

On Tue, 01 Jul 2025 06:54:47 -0600
Jonathan Corbet <corbet@lwn.net> wrote:

> Petr Tesarik <ptesarik@suse.com> writes:
> 
> > Do I have to submit a v3 then?  
> 
> What path were you planning for this to go upstream?  If it goes through
> docs, I can apply that tweak on the way in.

There's a reason I put docs: in the Subject prefix. ;-)

This specific patch touches an include file outside Documentation/, but
since it merely adds a kernel-doc comment, I believe it's still good to
go through docs.

Thanks
Petr T

Re: [PATCH v2 0/8] update DMA API documentation

[Jonathan Corbet]

Petr Tesarik <ptesarik@suse.com> writes:

> A few documentation updates:
>
> * remove outdated and confusing parts
> * reduce duplicates
> * update streaming DMA API expectations
>
> Changes from v1:
>
> * move DMA Pools to dma-api.rst
> * improve streaming DMA addressing constraints
>
> Petr Tesarik (8):
>   docs: dma-api: use "DMA API" consistently throughout the document
>   docs: dma-api: replace consistent with coherent
>   docs: dma-api: remove remnants of PCI DMA API
>   docs: dma-api: add a kernel-doc comment for dma_pool_zalloc()
>   docs: dma-api: remove duplicate description of the DMA pool API
>   docs: dma-api: clarify DMA addressing limitations
>   docs: dma-api: update streaming DMA physical address constraints
>   docs: dma-api: clean up documentation of dma_map_sg()

OK, I have applied these - thanks.

jon