Commit 2ec0458e authored by Nicolin Chen's avatar Nicolin Chen Committed by Jason Gunthorpe
Browse files

Documentation: userspace-api: iommufd: Update FAULT and VEVENTQ 

With the introduction of the new objects, update the doc to reflect that.

Link: https://patch.msgid.link/r/09829fbc218872d242323d8834da4bec187ce6f4.1741719725.git.nicolinc@nvidia.com


Reviewed-by: default avatarLu Baolu <baolu.lu@linux.intel.com>
Reviewed-by: default avatarKevin Tian <kevin.tian@intel.com>
Reviewed-by: default avatarBagas Sanjaya <bagasdotme@gmail.com>
Reviewed-by: default avatarJason Gunthorpe <jgg@nvidia.com>
Signed-off-by: default avatarNicolin Chen <nicolinc@nvidia.com>
Signed-off-by: default avatarJason Gunthorpe <jgg@nvidia.com>
parent 97717a1f

Documentation/userspace-api/iommufd.rst

+17 −0
Original line number Diff line number Diff line
@@ -63,6 +63,13 @@ Following IOMMUFD objects are exposed to userspace: 
  space usually has mappings from guest-level I/O virtual addresses to guest-

  level physical addresses.



- IOMMUFD_FAULT, representing a software queue for an HWPT reporting IO page

  faults using the IOMMU HW's PRI (Page Request Interface). This queue object

  provides user space an FD to poll the page fault events and also to respond

  to those events. A FAULT object must be created first to get a fault_id that

  could be then used to allocate a fault-enabled HWPT via the IOMMU_HWPT_ALLOC

  command by setting the IOMMU_HWPT_FAULT_ID_VALID bit in its flags field.



- 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:
@@ -109,6 +116,14 @@ Following IOMMUFD objects are exposed to userspace: 
  vIOMMU, which is a separate ioctl call from attaching the same device to an

  HWPT_PAGING that the vIOMMU holds.



- IOMMUFD_OBJ_VEVENTQ, representing a software queue for a vIOMMU to report its

  events such as translation faults occurred to a nested stage-1 (excluding I/O

  page faults that should go through IOMMUFD_OBJ_FAULT) and HW-specific events.

  This queue object provides user space an FD to poll/read the vIOMMU events. A

  vIOMMU object must be created first to get its viommu_id, which could be then

  used to allocate a vEVENTQ. Each vIOMMU can support multiple types of vEVENTS,

  but is confined to one vEVENTQ per vEVENTQ type.



All user-visible objects are destroyed via the IOMMU_DESTROY uAPI.



The diagrams below show relationships between user-visible objects and kernel
@@ -251,8 +266,10 @@ User visible objects are backed by following datastructures: 
- iommufd_device for IOMMUFD_OBJ_DEVICE.

- iommufd_hwpt_paging for IOMMUFD_OBJ_HWPT_PAGING.

- iommufd_hwpt_nested for IOMMUFD_OBJ_HWPT_NESTED.

- iommufd_fault for IOMMUFD_OBJ_FAULT.

- iommufd_viommu for IOMMUFD_OBJ_VIOMMU.

- iommufd_vdevice for IOMMUFD_OBJ_VDEVICE.

- iommufd_veventq for IOMMUFD_OBJ_VEVENTQ.



Several terminologies when looking at these datastructures: