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

[Bagas Sanjaya <bagasdotme@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 3019 bytes --]

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

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]