Patchwork [RFC,v3,21/21] vfio: Document nested stage control

mail settings
Submitter Auger Eric
Date Jan. 8, 2019, 10:26 a.m.
Message ID <>
Download mbox | patch
Permalink /patch/694659/
State New
Headers show


Auger Eric - Jan. 8, 2019, 10:26 a.m.
New iotcls were introduced to pass information about guest stage1
to the host through VFIO. Let's document the nested stage control.

Signed-off-by: Eric Auger <>


v2 -> v3:
- document the new fault API

v1 -> v2:
- use the new ioctl names
- add doc related to fault handling
 Documentation/vfio.txt | 62 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)


diff --git a/Documentation/vfio.txt b/Documentation/vfio.txt
index f1a4d3c3ba0b..620e38ed0c4a 100644
--- a/Documentation/vfio.txt
+++ b/Documentation/vfio.txt
@@ -239,6 +239,68 @@  group and can access them as follows::
 	/* Gratuitous device reset and go... */
 	ioctl(device, VFIO_DEVICE_RESET);
+IOMMU Dual Stage Control
+Some IOMMUs support 2 stages/levels of translation. "Stage" corresponds to
+the ARM terminology while "level" corresponds to Intel's VTD terminology. In
+the following text we use either without distinction.
+This is useful when the guest is exposed with a virtual IOMMU and some
+devices are assigned to the guest through VFIO. Then the guest OS can use
+stage 1 (IOVA -> GPA), while the hypervisor uses stage 2 for VM isolation
+(GPA -> HPA).
+The guest gets ownership of the stage 1 page tables and also owns stage 1
+configuration structures. The hypervisor owns the root configuration structure
+(for security reason), including stage 2 configuration. This works as long
+configuration structures and page table format are compatible between the
+virtual IOMMU and the physical IOMMU.
+Assuming the HW supports it, this nested mode is selected by choosing the
+This forces the hypervisor to use the stage 2, leaving stage 1 available for
+guest usage.
+Once groups are attached to the container, the guest stage 1 translation
+configuration data can be passed to VFIO by using
+ioctl(container, VFIO_IOMMU_BIND_PASID_TABLE, &pasid_table_info);
+This allows to combine guest stage 1 configuration structure along with
+hypervisor stage 2 configuration structure. stage 1 configuration structures
+are dependent on the IOMMU type.
+As the stage 1 translation is fully delegated to the HW, physical events that
+may occur (especially translation faults), need to be propagated up to
+the virtualizer and re-injected into the guest.
+index, the virtualizer can register an eventfd signalled whenever a
+fault is observed at physical level. The actual faults can be retrieved
+from the device fault region whose type/subtype is:
+This region can be mmapped. When a fault is consumed, the user must increment
+the consumer index.
+When the guest invalidates stage 1 related caches, invalidations must be
+forwarded to the host through
+ioctl(container, VFIO_IOMMU_CACHE_INVALIDATE, &inv_data);
+Those invalidations can happen at various granularity levels, page, context, ...
+The ARM SMMU specification introduces another challenge: MSIs are translated by
+both the virtual SMMU and the physical SMMU. To build a nested mapping for the
+IOVA programmed into the assigned device, the guest needs to pass its IOVA/MSI
+doorbell GPA binding to the host. Then the hypervisor can build a nested stage 2
+binding eventually translating into the physical MSI doorbell.
+This is achieved by
+ioctl(container, VFIO_IOMMU_BIND_MSI, &guest_binding);