With the introduction of the new object and its infrastructure, update the
doc to reflect that and add a new graph.
Reviewed-by: Jason Gunthorpe
Reviewed-by: Kevin Tian
Signed-off-by: Nicolin Chen
---
Documentation/userspace-api/iommufd.rst | 69 -
1 file changed, 68 insertions(+), 1 deletion(-)
diff --git a/Documentation/userspace-api/iommufd.rst
b/Documentation/userspace-api/iommufd.rst
index 2deba93bf159..92d16efad5b0 100644
--- a/Documentation/userspace-api/iommufd.rst
+++ b/Documentation/userspace-api/iommufd.rst
@@ -63,6 +63,37 @@ Following IOMMUFD objects are exposed to userspace:
space usually has mappings from guest-level I/O virtual addresses to guest-
level physical addresses.
+ - IOMMUFD_OBJ_VIOMMU, representing a slice of the physical IOMMU instance,
+ passed to or shared with a VM. It may be some HW-accelerated virtualization
+ features and some SW resources used by the VM. For examples:
+ * Security namespace for guest owned ID, e.g. guest-controlled cache tags
+ * Access to a sharable nesting parent pagetable across physical IOMMUs
+ * Virtualization of various platforms IDs, e.g. RIDs and others
+ * Delivery of paravirtualized invalidation
+ * Direct assigned invalidation queues
+ * Direct assigned interrupts
+ * Non-affiliated event reporting
+ Such a vIOMMU object generally has the access to a nesting parent pagetable
+ to support some HW-accelerated virtualization features. So, a vIOMMU object
+ must be created given a nesting parent HWPT_PAGING object, and then it would
+ encapsulate that HWPT_PAGING object. Therefore, a vIOMMU object can be used
+ to allocate an HWPT_NESTED object in place of the encapsulated HWPT_PAGING.
+
+ .. note::
+
+ The name "vIOMMU" isn't necessarily identical to a virtualized IOMMU in a
+ VM. A VM can have one giant virtualized IOMMU running on a machine having
+ multiple physical IOMMUs, in which case the VMM will dispatch the
requests
+ or configurations from this single virtualized IOMMU instance to multiple
+ vIOMMU objects created for individual slices of different physical
IOMMUs.
+ In other words, a vIOMMU object is always a representation of one
physical
+ IOMMU, not necessarily of a virtualized IOMMU. For VMMs that want the
full
+ virtualization features from physical IOMMUs, it is suggested to build
the
+ same number of virtualized IOMMUs as the number of physical IOMMUs, so
the
+ passed-through devices would be connected to their own virtualized IOMMUs
+ backed by corresponding vIOMMU objects, in which case a guest OS would do
+ the "dispatch" naturally instead of VMM trappings.
+
All user-visible objects are destroyed via the IOMMU_DESTROY uAPI.
The diagrams below show relationships between user-visible objects and kernel
@@ -101,6 +132,28 @@ creating the objects and links::
|>|iommu_domain|<|iommu_domain|<|device|
|| || |__|
+ ___
+ | iommufd (with vIOMMU)|
+ | |
+ | [5] |
+ |_ |
+ | | | |
+ | ||vIOMMU | |
+ | || | |
+ | || | |
+ | | [1] | | [4] [2]|
+ | | __ | | _ |
+ | || || [3] || | || |
+ | || IOAS |<---|(HWPT_PAGING)|<---| HWPT_NESTED |<--| DEVICE | |
+ | ||__||_||_| || |
+ | || | | | |
+ |__||__|__|___|_|
+|| | | |
+ __v_ |__v_ __v_ ___v__
+ | struct | | PFN | (paging) | | (nested) | |struct|
+ |iommu_device| |-->|iommu_domain|<|iommu_domain|<|device|
+ || storage|| || |__|
+
1. IOMMUFD_OBJ_IOAS is created via the IOMMU_IOAS_ALLOC uAPI. An iommufd can
hold multiple IOAS objects. IOAS is the most generic object and does not
expose interfaces that are specific to single IOMMU drivers. All operations
@@ -132,7 +185,8 @@ creating the objects and links::
flag is set.
4. IOMMUFD_OBJ_HWPT_NESTED can be only m
