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: clarify DMA addressing limitations

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

authored by

Petr Tesarik and committed by
Jonathan Corbet faa7c7eb 61043d09

+18 -17
+18 -17
Documentation/core-api/dma-api.rst
··· 92 92 Part Ic - DMA addressing limitations 93 93 ------------------------------------ 94 94 95 + DMA mask is a bit mask of the addressable region for the device. In other words, 96 + if applying the DMA mask (a bitwise AND operation) to the DMA address of a 97 + memory region does not clear any bits in the address, then the device can 98 + perform DMA to that memory region. 99 + 100 + All the below functions which set a DMA mask may fail if the requested mask 101 + cannot be used with the device, or if the device is not capable of doing DMA. 102 + 95 103 :: 96 104 97 105 int 98 106 dma_set_mask_and_coherent(struct device *dev, u64 mask) 99 107 100 - Checks to see if the mask is possible and updates the device 101 - streaming and coherent DMA mask parameters if it is. 108 + Updates both streaming and coherent DMA masks. 102 109 103 110 Returns: 0 if successful and a negative error if not. 104 111 ··· 114 107 int 115 108 dma_set_mask(struct device *dev, u64 mask) 116 109 117 - Checks to see if the mask is possible and updates the device 118 - parameters if it is. 110 + Updates only the streaming DMA mask. 119 111 120 112 Returns: 0 if successful and a negative error if not. 121 113 ··· 123 117 int 124 118 dma_set_coherent_mask(struct device *dev, u64 mask) 125 119 126 - Checks to see if the mask is possible and updates the device 127 - parameters if it is. 120 + Updates only the coherent DMA mask. 128 121 129 122 Returns: 0 if successful and a negative error if not. 130 123 ··· 178 173 unsigned long 179 174 dma_get_merge_boundary(struct device *dev); 180 175 181 - Returns the DMA merge boundary. If the device cannot merge any the DMA address 176 + Returns the DMA merge boundary. If the device cannot merge any DMA address 182 177 segments, the function returns 0. 183 178 184 179 Part Id - Streaming DMA mappings ··· 212 207 this API should be obtained from sources which guarantee it to be 213 208 physically contiguous (like kmalloc). 214 209 215 - Further, the DMA address of the memory must be within the 216 - dma_mask of the device (the dma_mask is a bit mask of the 217 - addressable region for the device, i.e., if the DMA address of 218 - the memory ANDed with the dma_mask is still equal to the DMA 219 - address, then the device can perform DMA to the memory). To 220 - ensure that the memory allocated by kmalloc is within the dma_mask, 221 - the driver may specify various platform-dependent flags to restrict 222 - the DMA address range of the allocation (e.g., on x86, GFP_DMA 223 - guarantees to be within the first 16MB of available DMA addresses, 224 - as required by ISA devices). 210 + Further, the DMA address of the memory must be within the dma_mask of 211 + the device. To ensure that the memory allocated by kmalloc is within 212 + the dma_mask, the driver may specify various platform-dependent flags 213 + to restrict the DMA address range of the allocation (e.g., on x86, 214 + GFP_DMA guarantees to be within the first 16MB of available DMA 215 + addresses, as required by ISA devices). 225 216 226 217 Note also that the above constraints on physical contiguity and 227 218 dma_mask may not apply if the platform has an IOMMU (a device which