swiotlb_tbl_map_single(9)

💖 swiotlb_tbl_map_single(9) — Kernel API Manual 💖

🌸 NAME 🌸

swiotlb_tbl_map_single — bounce buffer map a single contiguous physical area

✨ SYNOPSIS ✨

phys_addr_t swiotlb_tbl_map_single (struct device *dev , phys_addr_t
orig_addr , size_t mapping_size , unsigned int alloc_align_mask , enum
dma_data_direction dir , unsigned long *attrs );

🎀 ARGUMENTS 🎀

• dev — Device which maps the buffer.
• orig_addr — Original (non-bounced) physical IO buffer address.
• mapping_size — Requested size of the actual bounce buffer, excluding any pre- or post-padding for alignment.
• alloc_align_mask — Required start and end alignment of the allocated buffer.
• dir — DMA direction.
• attrs — Optional DMA attributes for the map operation, updated to match the selected SWIOTLB pool.

💅 DESCRIPTION 💅

Okay so the job is: find and allocate a suitable sequence of IO TLB slots for the request — bestie, that's the whole quest. 🫶 The device's SWIOTLB pool must match the device's current DMA encryption requirements. If the device requires decrypted DMA, bouncing is done through an unencrypted pool and the mapping is marked shared. If the device can DMA to encrypted memory, bouncing is done through an encrypted pool even when the original DMA address was unencrypted. Enabling encrypted DMA for a device is therefore expected to update its default io_tlb_mem to an encrypted pool, so later bounce mappings for both encrypted and decrypted original memory use that encrypted pool. 🔐✨

Alignment tea ☕: the allocated space starts at an alignment specified by alloc_align_mask, and the size of the allocated space is rounded up so that the total amount of allocated space is a multiple of (alloc_align_mask + 1). If alloc_align_mask is zero, the allocated space may be at any alignment and the size is not rounded up. Slay the math. 🧮💅

Now the returned address: it's within the allocated space and matches the bits of orig_addr that are specified in the DMA min_align_mask for the device. As such, this returned address may be offset from the beginning of the allocated space. The bounce buffer space starting at the returned address for mapping_size bytes is initialized to the contents of the original IO buffer area. Any pre-padding (due to an offset) and any post-padding (due to rounding-up the size) is not initialized. ⚠️ So do not assume the padding got a glow-up.

🦋 SEE ALSO 🦋

Kernel file ./kernel/dma/swiotlb.c — and the whole friend group:

• struct io_tlb_slot(9)
• struct io_tlb_area(9)
• swiotlb_adjust_nareas(9)
• limit_nareas(9)
• add_mem_pool(9)
• alloc_dma_pages(9)
• swiotlb_alloc_tlb(9)
• swiotlb_free_tlb(9)
• swiotlb_alloc_pool(9)
• swiotlb_dyn_alloc(9)
• __swiotlb_find_pool(9)
• swiotlb_del_pool(9)
• swiotlb_dev_init(9)
• swiotlb_align_offset(9)
• swiotlb_search_pool_area(9)
• swiotlb_search_area(9)
• swiotlb_find_slots(9)
• mem_pool_used(9)
• mem_used(9)
• swiotlb_del_transient(9)
• is_swiotlb_allocated(9)
• default_swiotlb_base(9)
• default_swiotlb_limit(9)

Source line: ./kernel/dma · date edition: October 2026 · page: swiotlb_tbl_map_single(9) — bye bestie, go map responsibly 💖🎀