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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <aFymwvL5vcfWBy73@archie.me>
Date: Thu, 26 Jun 2025 08:47:46 +0700
From: Bagas Sanjaya <bagasdotme@...il.com>
To: Petr Tesarik <ptesarik@...e.com>, Jonathan Corbet <corbet@....net>,
	Morton <akpm@...ux-foundation.org>
Cc: Marek Szyprowski <m.szyprowski@...sung.com>,
	Leon Romanovsky <leon@...nel.org>, Keith Busch <kbusch@...nel.org>,
	Caleb Sander Mateos <csander@...estorage.com>,
	Sagi Grimberg <sagi@...mberg.me>, Jens Axboe <axboe@...nel.dk>,
	John Garry <john.g.garry@...cle.com>,
	"open list:DOCUMENTATION" <linux-doc@...r.kernel.org>,
	open list <linux-kernel@...r.kernel.org>,
	"open list:MEMORY MANAGEMENT" <linux-mm@...ck.org>
Subject: Re: [PATCH 6/8] docs: dma-api: clarify DMA addressing limitations

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@...il.com>

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

Download attachment "signature.asc" of type "application/pgp-signature" (229 bytes)