Documentation/core-api/swiotlb.rst

1 .. SPDX-License-Identifier: GPL-2.0
4 DMA and swiotlb
7 swiotlb is a memory buffer allocator used by the Linux kernel DMA layer. It is
8 typically used when a device doing DMA can't directly access the target memory
10 the DMA layer calls swiotlb to allocate a temporary memory buffer that conforms
11 to the limitations. The DMA is done to/from this temporary memory buffer, and
17 the DMA layer of the DMA attributes of the devices they are managing, and use
18 the normal DMA map, unmap, and sync APIs when programming a device to do DMA.
19 These APIs use the device DMA attributes and kernel-wide settings to determine
20 if bounce buffering is necessary. If so, the DMA layer manages the allocation,
21 freeing, and sync'ing of bounce buffers. Since the DMA attributes are per
25 memory buffer, doing bounce buffering is slower than doing DMA directly to the
27 when necessary for providing DMA functionality.
30 ---------------
31 swiotlb was originally created to handle DMA for devices with addressing
33 only provide 32-bit DMA addresses. By allocating bounce buffer memory below
35 do DMA.
40 directed to guest memory that is unencrypted. CoCo VMs set a kernel-wide option
41 to force all DMA I/O to use bounce buffers, and the bounce buffer memory is set
42 up as unencrypted. The host does DMA I/O to/from the bounce buffer memory, and
43 the Linux kernel DMA layer does "sync" operations to cause the CPU to copy the
50 mappings are set up for a DMA operation to/from a device that is considered
54 IOMMU access control is per-granule, the untrusted device can gain access to
55 the unrelated kernel data. This problem is solved by bounce buffering the DMA
60 ------------------
64 buffer memory is physically contiguous. The expectation is that the DMA layer
65 maps the physical memory address to a DMA address, and returns the DMA address
66 to the driver for programming into the device. If a DMA operation specifies
72 swiotlb_tbl_unmap_single() does the reverse. If the DMA operation might have
78 a driver may use when control of a buffer transitions between the CPU and the
85 ------------------------------
87 called by the corresponding DMA APIs which may run in contexts that cannot
89 pre-allocated at boot time (but see Dynamic swiotlb below). Because swiotlb
93 The need to pre-allocate the default swiotlb pool creates a boot-time tradeoff.
95 always be satisfied, as the non-blocking requirement means requests can't wait
97 this pre-allocated memory is not available for other uses in the system. The
98 tradeoff is particularly acute in CoCo VMs that use bounce buffers for all DMA
107 bytes, which is 256 KiB with current definitions. When a device's DMA settings
108 are such that the device might use swiotlb, the maximum size of a DMA segment
109 must be limited to that 256 KiB. This value is communicated to higher-level
111 higher-level code fails to account for this limit, it may make requests that
114 A key device DMA setting is "min_align_mask", which is a power of 2 minus 1
118 min_align_mask is non-zero, it may produce an "alignment offset" in the address
124 swiotlb, max_sectors_kb will be 256 KiB. When min_align_mask is non-zero,
130 bounce buffer might start at a larger address if min_align_mask is non-zero.
131 Hence there may be pre-padding space that is allocated prior to the start of
133 alloc_align_mask boundary, potentially resulting in post-padding space. Any
134 pre-padding or post-padding space is not initialized by swiotlb code. The
136 devices. It is set to the granule size - 1 so that the bounce buffer is
140 ------------------------
149 it works for devices that can only address 32-bits of physical memory (unless
150 architecture-specific code provides the SWIOTLB_ANY flag). In a CoCo VM, the
159 IO_TLB_SEGSIZE. Multiple smaller bounce buffers may co-exist in a single slot
194 ---------------
195 When CONFIG_SWIOTLB_DYNAMIC is enabled, swiotlb can do on-demand expansion of
208 background task can add another non-transient pool.
236 ----------------------
251 entry for each area, and is accessed using a 0-based area index derived from the
261 The io_tlb_slot array is designed to meet several requirements. First, the DMA
299 requirements, it may allocate pre-padding space across zero or more slots. But
304 The "pad_slots" value is recorded only in the first non-padding slot allocated
308 ----------------
310 memory separate from the default swiotlb pool, and that are dedicated for DMA
311 use by a particular device. Restricted pools provide a level of DMA memory
312 protection on systems with limited hardware protection capabilities, such as