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: update streaming DMA physical address constraints

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 <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-8-ptesarik@suse.com

authored by

Petr Tesarik and committed by
Jonathan Corbet 0ebbc69e faa7c7eb

+21 -15
+21 -15
Documentation/core-api/dma-api.rst
··· 184 184 Part Id - Streaming DMA mappings 185 185 -------------------------------- 186 186 187 + Streaming DMA allows to map an existing buffer for DMA transfers and then 188 + unmap it when finished. Map functions are not guaranteed to succeed, so the 189 + return value must be checked. 190 + 191 + .. note:: 192 + 193 + In particular, mapping may fail for memory not addressable by the 194 + device, e.g. if it is not within the DMA mask of the device and/or a 195 + connecting bus bridge. Streaming DMA functions try to overcome such 196 + addressing constraints, either by using an IOMMU (a device which maps 197 + I/O DMA addresses to physical memory addresses), or by copying the 198 + data to/from a bounce buffer if the kernel is configured with a 199 + :doc:`SWIOTLB <swiotlb>`. However, these methods are not always 200 + available, and even if they are, they may still fail for a number of 201 + reasons. 202 + 203 + In short, a device driver may need to be wary of where buffers are 204 + located in physical memory, especially if the DMA mask is less than 32 205 + bits. 206 + 187 207 :: 188 208 189 209 dma_addr_t ··· 224 204 225 205 .. note:: 226 206 227 - Not all memory regions in a machine can be mapped by this API. 228 - Further, contiguous kernel virtual space may not be contiguous as 207 + Contiguous kernel virtual space may not be contiguous as 229 208 physical memory. Since this API does not provide any scatter/gather 230 209 capability, it will fail if the user tries to map a non-physically 231 210 contiguous piece of memory. For this reason, memory to be mapped by 232 211 this API should be obtained from sources which guarantee it to be 233 212 physically contiguous (like kmalloc). 234 - 235 - Further, the DMA address of the memory must be within the dma_mask of 236 - the device. To ensure that the memory allocated by kmalloc is within 237 - the dma_mask, the driver may specify various platform-dependent flags 238 - to restrict the DMA address range of the allocation (e.g., on x86, 239 - GFP_DMA guarantees to be within the first 16MB of available DMA 240 - addresses, as required by ISA devices). 241 - 242 - Note also that the above constraints on physical contiguity and 243 - dma_mask may not apply if the platform has an IOMMU (a device which 244 - maps an I/O DMA address to a physical memory address). However, to be 245 - portable, device driver writers may *not* assume that such an IOMMU 246 - exists. 247 213 248 214 .. warning:: 249 215