linux-kernel - Re: [PATCH 8/8] docs: dma-api: clean up documentation of dma_map

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: <aFynUS7nVnlhvlv8@archie.me>
Date: Thu, 26 Jun 2025 08:50:09 +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 8/8] docs: dma-api: clean up documentation of dma_map_sg()

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

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

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