tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

docs: dma-api: clean up documentation of dma_map_sg()

Describe in one sentence what the function does.

Do not repeat example situations when the returned number is lower than
the number of segments on input.

Signed-off-by: Petr Tesarik <ptesarik@suse.com>
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Marek Szyprowski <m.szyprowski@samsung.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250627101015.1600042-9-ptesarik@suse.com

authored by

Petr Tesarik and committed by
Jonathan Corbet f304c259 0ebbc69e

+6 -7
+6 -7
Documentation/core-api/dma-api.rst
··· 322 322 dma_map_sg(struct device *dev, struct scatterlist *sg, 323 323 int nents, enum dma_data_direction direction) 324 324 325 - Returns: the number of DMA address segments mapped (this may be shorter 326 - than <nents> passed in if some elements of the scatter/gather list are 327 - physically or virtually adjacent and an IOMMU maps them with a single 328 - entry). 325 + Maps a scatter/gather list for DMA. Returns the number of DMA address segments 326 + mapped, which may be smaller than <nents> passed in if several consecutive 327 + sglist entries are merged (e.g. with an IOMMU, or if some adjacent segments 328 + just happen to be physically contiguous). 329 329 330 330 Please note that the sg cannot be mapped again if it has been mapped once. 331 331 The mapping process is allowed to destroy information in the sg. ··· 349 349 where nents is the number of entries in the sglist. 350 350 351 351 The implementation is free to merge several consecutive sglist entries 352 - into one (e.g. with an IOMMU, or if several pages just happen to be 353 - physically contiguous) and returns the actual number of sg entries it 354 - mapped them to. On failure 0, is returned. 352 + into one. The returned number is the actual number of sg entries it 353 + mapped them to. On failure, 0 is returned. 355 354 356 355 Then you should loop count times (note: this can be less than nents times) 357 356 and use sg_dma_address() and sg_dma_len() macros where you previously