Re: [PATCH 8/8] docs: dma-api: clean up documentation of dma_map_sg()

[Bagas Sanjaya <bagasdotme@gmail.com>]

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

On Tue, Jun 24, 2025 at 03:39:23PM +0200, Petr Tesarik wrote:
> diff --git a/Documentation/core-api/dma-api.rst b/Documentation/core-api/dma-api.rst
> index 65132ec88104..f5aadb7f8626 100644
> --- a/Documentation/core-api/dma-api.rst
> +++ b/Documentation/core-api/dma-api.rst
> @@ -308,10 +308,10 @@ action (e.g. reduce current DMA mapping usage or delay and try again later).
>  	dma_map_sg(struct device *dev, struct scatterlist *sg,
>  		   int nents, enum dma_data_direction direction)
>  
> -Returns: the number of DMA address segments mapped (this may be shorter
> -than <nents> passed in if some elements of the scatter/gather list are
> -physically or virtually adjacent and an IOMMU maps them with a single
> -entry).
> +Maps a scatter/gather list for DMA. Returns the number of DMA address segments
> +mapped, which may be smaller than <nents> passed in if several consecutive
> +sglist entries are merged (e.g. with an IOMMU, or if some adjacent segments
> +just happen to be physically contiguous).
>  
>  Please note that the sg cannot be mapped again if it has been mapped once.
>  The mapping process is allowed to destroy information in the sg.
> @@ -335,9 +335,8 @@ With scatterlists, you use the resulting mapping like this::
>  where nents is the number of entries in the sglist.
>  
>  The implementation is free to merge several consecutive sglist entries
> -into one (e.g. with an IOMMU, or if several pages just happen to be
> -physically contiguous) and returns the actual number of sg entries it
> -mapped them to. On failure 0, is returned.
> +into one.  The returned number is the actual number of sg entries it
> +mapped them to. On failure, 0 is returned.
>  
>  Then you should loop count times (note: this can be less than nents times)
>  and use sg_dma_address() and sg_dma_len() macros where you previously

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 --]