kernel/Documentation/core-api/dma-api.rst, branch linux-6.19.y

dma-debug: refactor to use physical addresses for page mapping

2025-09-11T22:09:51Z

Convert the DMA debug infrastructure from page-based to physical address-based mapping as a preparation to rely on physical address for DMA mapping routines. The refactoring renames debug_dma_map_page() to debug_dma_map_phys() and changes its signature to accept a phys_addr_t parameter instead of struct page and offset. Similarly, debug_dma_unmap_page() becomes debug_dma_unmap_phys(). A new dma_debug_phy type is introduced to distinguish physical address mappings from other debug entry types. All callers throughout the codebase are updated to pass physical addresses directly, eliminating the need for page-to-physical conversion in the debug layer. This refactoring eliminates the need to convert between page pointers and physical addresses in the debug layer, making the code more efficient and consistent with the DMA mapping API's physical address focus. Reviewed-by: Jason Gunthorpe Signed-off-by: Leon Romanovsky [mszyprow: added a fixup] Signed-off-by: Marek Szyprowski Link: https://lore.kernel.org/r/56d1a6769b68dfcbf8b26a75a7329aeb8e3c3b6a.1757423202.git.leonro@nvidia.com Link: https://lore.kernel.org/all/20250910052618.GH341237@unreal/

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

2025-07-01T19:56:05Z

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 Reviewed-by: Bagas Sanjaya Tested-by: Randy Dunlap Acked-by: Marek Szyprowski Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250627101015.1600042-9-ptesarik@suse.com

docs: dma-api: update streaming DMA physical address constraints

2025-07-01T19:56:05Z

Add an introductory paragraph to Part Id - Streaming DMA mappings and move the explanation of address constraints there, because it applies to all map functions. Clarify that streaming DMA can be used with memory which does not meet the addressing constraints of a device, but it may fail in that case. Make a note about SWIOTLB and link to the detailed description of it. Do not mention platform-dependent allocation flags. The note may mislead device driver authors into thinking that they should poke into and try to second-guess the DMA API implementation. They definitely shouldn't. Remove the claim that platforms with an IOMMU may not require physically contiguous buffers. The current implementation explicitly rejects vmalloc addresses, regardless of IOMMU. Signed-off-by: Petr Tesarik Reviewed-by: Bagas Sanjaya Tested-by: Randy Dunlap Acked-by: Marek Szyprowski Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250627101015.1600042-8-ptesarik@suse.com

docs: dma-api: clarify DMA addressing limitations

2025-07-01T19:56:05Z

Move the description of DMA mask from the documentation of dma_map_single() to Part Ic - DMA addressing limitations and improve the wording. Explain when a mask setting function may fail, and do not repeat this explanation for each individual function. Clarify which device parameters are updated by each mask setting function. Signed-off-by: Petr Tesarik Reviewed-by: Bagas Sanjaya Tested-by: Randy Dunlap Acked-by: Marek Szyprowski Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250627101015.1600042-7-ptesarik@suse.com

docs: dma-api: remove duplicate description of the DMA pool API

2025-07-01T19:56:05Z

Move the DMA pool API documentation from Memory Management APIs to dma-api.rst, replacing the outdated duplicate description there. Signed-off-by: Petr Tesarik Tested-by: Randy Dunlap Acked-by: Marek Szyprowski Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250627101015.1600042-6-ptesarik@suse.com

docs: dma-api: remove remnants of PCI DMA API

2025-07-01T19:25:36Z

The wording sometimes suggests there are multiple functions for an operation. This was in fact the case before PCI DMA API was removed, but since there is only one API now, the documentation has become confusing. To improve readability: * Remove implicit references to the PCI DMA API (plurals, use of "both", etc.) * Where possible, refer to an actual function rather than a more generic description of the operation. Signed-off-by: Petr Tesarik Reviewed-by: Bagas Sanjaya Tested-by: Randy Dunlap Acked-by: Marek Szyprowski Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250627101015.1600042-4-ptesarik@suse.com

docs: dma-api: replace consistent with coherent

2025-07-01T19:25:36Z

For consistency, always use the term "coherent" when talking about memory that is not subject to CPU caching effects. The term "consistent" is a relic of a long-removed PCI DMA API (pci_alloc_consistent() and pci_free_consistent() functions). Signed-off-by: Petr Tesarik Tested-by: Randy Dunlap Acked-by: Marek Szyprowski Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250627101015.1600042-3-ptesarik@suse.com

docs: dma-api: use "DMA API" consistently throughout the document

2025-07-01T19:25:36Z

Make sure that all occurrences are spelled "DMA API" (all uppercase, no hyphen, no underscore). Signed-off-by: Petr Tesarik Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Acked-by: Marek Szyprowski Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250627101015.1600042-2-ptesarik@suse.com

doc: Include scatterlist APIs in htmldocs

2025-06-09T20:24:29Z

We have all this fine kernel-doc written, and it's not published anywhere. Expose it to public view. Signed-off-by: Matthew Wilcox (Oracle) Tested-by: Randy Dunlap Acked-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20250604195753.823742-1-willy@infradead.org

docs: core-api: document the IOVA-based API

2025-05-06T06:36:54Z

Add an explanation of the newly added IOVA-based mapping API. Signed-off-by: Christoph Hellwig Tested-by: Jens Axboe Signed-off-by: Leon Romanovsky Signed-off-by: Marek Szyprowski