Documentation/core-api/swiotlb.rst

1 .. SPDX-License-Identifier: GPL-2.0
19 These APIs use the device DMA attributes and kernel-wide settings to determine
30 ---------------
33 only provide 32-bit DMA addresses. By allocating bounce buffer memory below
40 directed to guest memory that is unencrypted. CoCo VMs set a kernel-wide option
54 IOMMU access control is per-granule, the untrusted device can gain access to
60 ------------------
85 ------------------------------
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
102 on the I/O patterns of the workload in the VM. The dynamic swiotlb feature
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
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
193 Dynamic swiotlb
194 ---------------
195 When CONFIG_SWIOTLB_DYNAMIC is enabled, swiotlb can do on-demand expansion of
206 Creating a transient pool has relatively high cost, particularly in a CoCo VM
208 background task can add another non-transient pool.
210 Adding a dynamic pool has limitations. Like with the default pool, the memory
213 allocation may not be available. The dynamic pool allocator tries smaller sizes
217 The number of areas in a dynamic pool may be different from the number of areas
224 New pools added via dynamic swiotlb are linked together in a linear list.
227 large number of dynamic pools. The data structures could be improved for
230 Overall, dynamic swiotlb works best for small configurations with relatively
232 not wasted, with dynamic pools making more space available if needed (as long
236 ----------------------
239 which includes the default memory pool and any dynamic or transient pools
244 io_tlb_pool describes a memory pool, either the default pool, a dynamic pool,
251 entry for each area, and is accessed using a 0-based area index derived from the
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 ----------------