[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <20250627101015.1600042-7-ptesarik@suse.com>
Date: Fri, 27 Jun 2025 12:10:13 +0200
From: Petr Tesarik <ptesarik@...e.com>
To: Jonathan Corbet <corbet@....net>,
Randy Dunlap <rdunlap@...radead.org>,
Robin Murphy <robin.murphy@....com>,
Marek Szyprowski <m.szyprowski@...sung.com>
Cc: Andrew Morton <akpm@...ux-foundation.org>,
Keith Busch <kbusch@...nel.org>,
Jens Axboe <axboe@...nel.dk>,
Bagas Sanjaya <bagasdotme@...il.com>,
linux-doc@...r.kernel.org (open list:DOCUMENTATION),
linux-kernel@...r.kernel.org (open list),
linux-mm@...ck.org (open list:MEMORY MANAGEMENT),
Petr Tesarik <ptesarik@...e.com>
Subject: [PATCH v2 6/8] docs: dma-api: clarify DMA addressing limitations
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@...e.com>
Reviewed-by: Bagas Sanjaya <bagasdotme@...il.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
Powered by blists - more mailing lists