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>
---
 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 f7fddaf7510c..cd432996949c 100644
--- a/Documentation/core-api/dma-api.rst
+++ b/Documentation/core-api/dma-api.rst
@@ -90,13 +90,20 @@ description of the DMA pools API.
 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.
 
@@ -105,8 +112,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.
 
@@ -115,8 +121,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.
 
@@ -171,7 +176,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
@@ -205,16 +210,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

On Tue, Jun 24, 2025 at 03:39:21PM +0200, Petr Tesarik wrote:
> diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
> index f7fddaf7510c..cd432996949c 100644
> --- a/Documentation/core-api/dma-api.rst
> +++ b/Documentation/core-api/dma-api.rst
> @@ -90,13 +90,20 @@ description of the DMA pools API.
>  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.
>  
> @@ -105,8 +112,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.
>  
> @@ -115,8 +121,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.
>  
> @@ -171,7 +176,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
> @@ -205,16 +210,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
 
LGTM, thanks!

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

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