docs: dma-api: update streaming DMA physical address constraints

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>
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Marek Szyprowski <m.szyprowski@samsung.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250627101015.1600042-8-ptesarik@suse.com

diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
index f5129a4a001505ea76fa52057985243c8e00e6bb..c1ba2a967dbfba0ba12a28e26b1409f28d723ef8 100644 (file)
--- 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