1.. SPDX-License-Identifier: GPL-2.0+ 2 3======= 4IOMMUFD 5======= 6 7:Author: Jason Gunthorpe 8:Author: Kevin Tian 9 10Overview 11======== 12 13IOMMUFD is the user API to control the IOMMU subsystem as it relates to managing 14IO page tables from userspace using file descriptors. It intends to be general 15and consumable by any driver that wants to expose DMA to userspace. These 16drivers are eventually expected to deprecate any internal IOMMU logic 17they may already/historically implement (e.g. vfio_iommu_type1.c). 18 19At minimum iommufd provides universal support of managing I/O address spaces and 20I/O page tables for all IOMMUs, with room in the design to add non-generic 21features to cater to specific hardware functionality. 22 23In this context the capital letter (IOMMUFD) refers to the subsystem while the 24small letter (iommufd) refers to the file descriptors created via /dev/iommu for 25use by userspace. 26 27Key Concepts 28============ 29 30User Visible Objects 31-------------------- 32 33Following IOMMUFD objects are exposed to userspace: 34 35- IOMMUFD_OBJ_IOAS, representing an I/O address space (IOAS), allowing map/unmap 36 of user space memory into ranges of I/O Virtual Address (IOVA). 37 38 The IOAS is a functional replacement for the VFIO container, and like the VFIO 39 container it copies an IOVA map to a list of iommu_domains held within it. 40 41- IOMMUFD_OBJ_DEVICE, representing a device that is bound to iommufd by an 42 external driver. 43 44- IOMMUFD_OBJ_HW_PAGETABLE, representing an actual hardware I/O page table 45 (i.e. a single struct iommu_domain) managed by the iommu driver. 46 47 The IOAS has a list of HW_PAGETABLES that share the same IOVA mapping and 48 it will synchronize its mapping with each member HW_PAGETABLE. 49 50All user-visible objects are destroyed via the IOMMU_DESTROY uAPI. 51 52The diagram below shows relationship between user-visible objects and kernel 53datastructures (external to iommufd), with numbers referred to operations 54creating the objects and links:: 55 56 _________________________________________________________ 57 | iommufd | 58 | [1] | 59 | _________________ | 60 | | | | 61 | | | | 62 | | | | 63 | | | | 64 | | | | 65 | | | | 66 | | | [3] [2] | 67 | | | ____________ __________ | 68 | | IOAS |<--| |<------| | | 69 | | | |HW_PAGETABLE| | DEVICE | | 70 | | | |____________| |__________| | 71 | | | | | | 72 | | | | | | 73 | | | | | | 74 | | | | | | 75 | | | | | | 76 | |_________________| | | | 77 | | | | | 78 |_________|___________________|___________________|_______| 79 | | | 80 | _____v______ _______v_____ 81 | PFN storage | | | | 82 |------------>|iommu_domain| |struct device| 83 |____________| |_____________| 84 851. IOMMUFD_OBJ_IOAS is created via the IOMMU_IOAS_ALLOC uAPI. An iommufd can 86 hold multiple IOAS objects. IOAS is the most generic object and does not 87 expose interfaces that are specific to single IOMMU drivers. All operations 88 on the IOAS must operate equally on each of the iommu_domains inside of it. 89 902. IOMMUFD_OBJ_DEVICE is created when an external driver calls the IOMMUFD kAPI 91 to bind a device to an iommufd. The driver is expected to implement a set of 92 ioctls to allow userspace to initiate the binding operation. Successful 93 completion of this operation establishes the desired DMA ownership over the 94 device. The driver must also set the driver_managed_dma flag and must not 95 touch the device until this operation succeeds. 96 973. IOMMUFD_OBJ_HW_PAGETABLE is created when an external driver calls the IOMMUFD 98 kAPI to attach a bound device to an IOAS. Similarly the external driver uAPI 99 allows userspace to initiate the attaching operation. If a compatible 100 pagetable already exists then it is reused for the attachment. Otherwise a 101 new pagetable object and iommu_domain is created. Successful completion of 102 this operation sets up the linkages among IOAS, device and iommu_domain. Once 103 this completes the device could do DMA. 104 105 Every iommu_domain inside the IOAS is also represented to userspace as a 106 HW_PAGETABLE object. 107 108 .. note:: 109 110 Future IOMMUFD updates will provide an API to create and manipulate the 111 HW_PAGETABLE directly. 112 113A device can only bind to an iommufd due to DMA ownership claim and attach to at 114most one IOAS object (no support of PASID yet). 115 116Kernel Datastructure 117-------------------- 118 119User visible objects are backed by following datastructures: 120 121- iommufd_ioas for IOMMUFD_OBJ_IOAS. 122- iommufd_device for IOMMUFD_OBJ_DEVICE. 123- iommufd_hw_pagetable for IOMMUFD_OBJ_HW_PAGETABLE. 124 125Several terminologies when looking at these datastructures: 126 127- Automatic domain - refers to an iommu domain created automatically when 128 attaching a device to an IOAS object. This is compatible to the semantics of 129 VFIO type1. 130 131- Manual domain - refers to an iommu domain designated by the user as the 132 target pagetable to be attached to by a device. Though currently there are 133 no uAPIs to directly create such domain, the datastructure and algorithms 134 are ready for handling that use case. 135 136- In-kernel user - refers to something like a VFIO mdev that is using the 137 IOMMUFD access interface to access the IOAS. This starts by creating an 138 iommufd_access object that is similar to the domain binding a physical device 139 would do. The access object will then allow converting IOVA ranges into struct 140 page * lists, or doing direct read/write to an IOVA. 141 142iommufd_ioas serves as the metadata datastructure to manage how IOVA ranges are 143mapped to memory pages, composed of: 144 145- struct io_pagetable holding the IOVA map 146- struct iopt_area's representing populated portions of IOVA 147- struct iopt_pages representing the storage of PFNs 148- struct iommu_domain representing the IO page table in the IOMMU 149- struct iopt_pages_access representing in-kernel users of PFNs 150- struct xarray pinned_pfns holding a list of pages pinned by in-kernel users 151 152Each iopt_pages represents a logical linear array of full PFNs. The PFNs are 153ultimately derived from userspace VAs via an mm_struct. Once they have been 154pinned the PFNs are stored in IOPTEs of an iommu_domain or inside the pinned_pfns 155xarray if they have been pinned through an iommufd_access. 156 157PFN have to be copied between all combinations of storage locations, depending 158on what domains are present and what kinds of in-kernel "software access" users 159exist. The mechanism ensures that a page is pinned only once. 160 161An io_pagetable is composed of iopt_areas pointing at iopt_pages, along with a 162list of iommu_domains that mirror the IOVA to PFN map. 163 164Multiple io_pagetable-s, through their iopt_area-s, can share a single 165iopt_pages which avoids multi-pinning and double accounting of page 166consumption. 167 168iommufd_ioas is shareable between subsystems, e.g. VFIO and VDPA, as long as 169devices managed by different subsystems are bound to a same iommufd. 170 171IOMMUFD User API 172================ 173 174.. kernel-doc:: include/uapi/linux/iommufd.h 175 176IOMMUFD Kernel API 177================== 178 179The IOMMUFD kAPI is device-centric with group-related tricks managed behind the 180scene. This allows the external drivers calling such kAPI to implement a simple 181device-centric uAPI for connecting its device to an iommufd, instead of 182explicitly imposing the group semantics in its uAPI as VFIO does. 183 184.. kernel-doc:: drivers/iommu/iommufd/device.c 185 :export: 186 187.. kernel-doc:: drivers/iommu/iommufd/main.c 188 :export: 189 190VFIO and IOMMUFD 191---------------- 192 193Connecting a VFIO device to iommufd can be done in two ways. 194 195First is a VFIO compatible way by directly implementing the /dev/vfio/vfio 196container IOCTLs by mapping them into io_pagetable operations. Doing so allows 197the use of iommufd in legacy VFIO applications by symlinking /dev/vfio/vfio to 198/dev/iommufd or extending VFIO to SET_CONTAINER using an iommufd instead of a 199container fd. 200 201The second approach directly extends VFIO to support a new set of device-centric 202user API based on aforementioned IOMMUFD kernel API. It requires userspace 203change but better matches the IOMMUFD API semantics and easier to support new 204iommufd features when comparing it to the first approach. 205 206Currently both approaches are still work-in-progress. 207 208There are still a few gaps to be resolved to catch up with VFIO type1, as 209documented in iommufd_vfio_check_extension(). 210 211Future TODOs 212============ 213 214Currently IOMMUFD supports only kernel-managed I/O page table, similar to VFIO 215type1. New features on the radar include: 216 217 - Binding iommu_domain's to PASID/SSID 218 - Userspace page tables, for ARM, x86 and S390 219 - Kernel bypass'd invalidation of user page tables 220 - Re-use of the KVM page table in the IOMMU 221 - Dirty page tracking in the IOMMU 222 - Runtime Increase/Decrease of IOPTE size 223 - PRI support with faults resolved in userspace 224