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
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
153 Each pool is divided into "slots" of size IO_TLB_SIZE, which is 2 KiB with
154 current definitions. IO_TLB_SEGSIZE contiguous slots (128 slots) constitute
156 occupies one or more contiguous slots. A slot is never shared by multiple
159 IO_TLB_SEGSIZE. Multiple smaller bounce buffers may co-exist in a single slot
162 Slots are also grouped into "areas", with the constraint that a slot set exists
164 manipulate the slots in that area. The division into areas avoids contending
168 slots, it might be necessary to assign multiple CPUs to the same area. The
185 initial slots in each slot set might not meet the alloc_align_mask criterium.
187 those initial slots effectively reduces the max size of a bounce buffer.
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 ----------------------
250 serialize access to slots in the area. The io_tlb_area array for a pool has an
251 entry for each area, and is accessed using a 0-based area index derived from the
284 Third, the io_tlb_slot array is used to track available slots. The "list" field
285 in struct io_tlb_slot records how many contiguous available slots exist starting
291 available slots to use for a new bounce buffer. They are updated when allocating
292 a new bounce buffer and when freeing a bounce buffer. At pool creation time, the
293 "list" field is initialized to IO_TLB_SEGSIZE down to 1 for the slots in every
296 Fourth, the io_tlb_slot array keeps track of any "padding slots" allocated to
299 requirements, it may allocate pre-padding space across zero or more slots. But
302 allocation of any padding slots, is not known. The "pad_slots" field records
303 the number of padding slots so that swiotlb_tbl_unmap_single() can free them.
304 The "pad_slots" value is recorded only in the first non-padding slot allocated
308 ----------------
320 allocate/free slots from/to the restricted pool directly and do not go through