Documentation/userspace-api/iommu.rst

1 .. SPDX-License-Identifier: GPL-2.0
8 IOMMU UAPI is used for virtualization cases where communications are
23 supported user-kernel APIs are as follows:
25 1. Bind/Unbind guest PASID (e.g. Intel VT-d)
35 1. Emulated and para-virtualised vIOMMUs
36 2. Multiple vendors (Intel VT-d, ARM SMMU, etc.)
37 3. Extensions to the UAPI shall not break existing userspace
41 Although the data structures defined in IOMMU UAPI are self-contained,
42 there are no user API functions introduced. Instead, IOMMU UAPI is
46 -----------------------------
47 When IOMMU UAPI gets extended, the data structures can *only* be
50 1. Adding new fields by re-purposing the padding[] field. No size change.
59 Version field is only reserved for the unlikely event of UAPI upgrade
70 ----------------------
71 When IOMMU UAPI extension results in some structure size increase,
72 IOMMU UAPI code shall handle the following cases:
75 2. An older user with older kernel header (smaller UAPI size) running on a
76    newer kernel (larger UAPI size)
77 3. A newer user with newer kernel header (larger UAPI size) running
83 ----------------
90 User applications such as QEMU are expected to import kernel UAPI
92 For example, an older QEMU (with older kernel header) can run on newer
93 kernel. Newer QEMU (with new kernel header) may refuse to initialize
95 kernel. Simply recompiling existing code with newer kernel header should
98 IOMMU vendor driver should report the below features to IOMMU UAPI
111 Documentation/driver-api/vfio.rst.
115 ------------------------------
119 to support IOMMU UAPI but it is outside the scope of this document.
121 In this tight-knit VFIO-IOMMU interface, the ultimate consumer of the
122 IOMMU UAPI data is the host IOMMU driver. VFIO facilitates user-kernel
135 Here data[] contains the IOMMU UAPI data structures. VFIO has the
139 and flags (or the equivalent) are also embedded in the IOMMU UAPI data
166 invokes appropriate IOMMU UAPI functions. The user pointers are passed
170 - Generic IOMMU layer checks argsz range based on UAPI data in the
173 - Generic IOMMU layer checks content of the UAPI data for non-zero
178 - Vendor IOMMU driver checks argsz based on vendor flags. UAPI data
185 IOMMU code treats UAPI data in two categories:
187 - structure contains vendor data
190 - structure contains only generic data
195 Sharing UAPI with in-kernel users
196 ---------------------------------
197 For UAPIs that are shared with in-kernel users, a wrapper function is
206 In-kernel caller ::