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

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: <aGHpIiKWDr0T-FLN@archie.me>
Date: Mon, 30 Jun 2025 08:32:18 +0700
From: Bagas Sanjaya <bagasdotme@...il.com>
To: Petr Tesarik <ptesarik@...e.com>, 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>,
	"open list:DOCUMENTATION" <linux-doc@...r.kernel.org>,
	open list <linux-kernel@...r.kernel.org>,
	"open list:MEMORY MANAGEMENT" <linux-mm@...ck.org>,
	iommu@...ts.linux.dev
Subject: Re: [PATCH v2 7/8] docs: dma-api: update streaming DMA physical
 address constraints

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

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

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