[PATCH v8 19/29] Documentation: userspace-api: iommufd: Update HW QUEUE

Nicolin Chen
2025-07-05T01:14:44Z

With the introduction of the new object and its infrastructure, update the
doc to reflect that.

Reviewed-by: Jason Gunthorpe <jgg@nvidia.com>
Reviewed-by: Kevin Tian <kevin.tian@intel.com>
Reviewed-by: Lu Baolu <baolu.lu@linux.intel.com>
Signed-off-by: Nicolin Chen <nicolinc@nvidia.com>
---
Documentation/userspace-api/iommufd.rst | 12 ++++++++++++
1 file changed, 12 insertions(+)

diff --git a/Documentation/userspace-api/iommufd.rst b/Documentation/userspace-api/iommufd.rst
index b0df15865dec..03f7510384d2 100644
--- a/Documentation/userspace-api/iommufd.rst
+++ b/Documentation/userspace-api/iommufd.rst
@@ -124,6 +124,17 @@ Following IOMMUFD objects are exposed to userspace:
used to allocate a vEVENTQ. Each vIOMMU can support multiple types of vEVENTS,
but is confined to one vEVENTQ per vEVENTQ type.

+- IOMMUFD_OBJ_HW_QUEUE, representing a hardware accelerated queue, as a subset
+ of IOMMU's virtualization features, for the IOMMU HW to directly read or write
+ the virtual queue memory owned by a guest OS. This HW-acceleration feature can
+ allow VM to work with the IOMMU HW directly without a VM Exit, so as to reduce
+ overhead from the hypercalls. Along with the HW QUEUE object, iommufd provides
+ user space an mmap interface for VMM to mmap a physical MMIO region from the
+ host physical address space to the guest physical address space, allowing the
+ guest OS to directly control the allocated HW QUEUE. Thus, when allocating a
+ HW QUEUE, the VMM must request a pair of mmap info (offset/length) and pass in
+ exactly to an mmap syscall via its offset and length arguments.
+
All user-visible objects are destroyed via the IOMMU_DESTROY uAPI.

The diagrams below show relationships between user-visible objects and kernel
@@ -270,6 +281,7 @@ User visible objects are backed by following datastructures:
- iommufd_viommu for IOMMUFD_OBJ_VIOMMU.
- iommufd_vdevice for IOMMUFD_OBJ_VDEVICE.
- iommufd_veventq for IOMMUFD_OBJ_VEVENTQ.
+- iommufd_hw_queue for IOMMUFD_OBJ_HW_QUEUE.

Several terminologies when looking at these datastructures:

--
2.43.0