| Message ID | a5025cbbd16f9c12dcaae7a14868419f17ce1d16.1733263737.git.nicolinc@nvidia.com |
|---|---|
| State | New |
| Headers | show |
| Series | None | expand |
> From: Nicolin Chen <nicolinc@nvidia.com> > Sent: Wednesday, December 4, 2024 6:10 AM > > With the introduction of the new objects, update the doc to reflect that. > > Signed-off-by: Nicolin Chen <nicolinc@nvidia.com> > --- > Documentation/userspace-api/iommufd.rst | 19 +++++++++++++++++++ > 1 file changed, 19 insertions(+) > > diff --git a/Documentation/userspace-api/iommufd.rst > b/Documentation/userspace-api/iommufd.rst > index 70289d6815d2..798520d9344d 100644 > --- a/Documentation/userspace-api/iommufd.rst > +++ b/Documentation/userspace-api/iommufd.rst > @@ -63,6 +63,14 @@ 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_EVENTQ_IOPF, representing a software queue for an > HWPT_NESTED now it can be used on paging hwpt too > + reporting IO Page Fault 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. An EVENTQ_IOPF object must be > created > + first to get a fault_id that could be then used to allocate an HWPT_NESTED > + via the IOMMU_HWPT_ALLOC command setting > IOMMU_HWPT_FAULT_ID_VALID set 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 +117,15 @@ 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_EVENTQ_VIRQ, representing a software queue for > IOMMUFD_OBJ_VIOMMU > + reporting its non-affiliated events, such as translation faults occurred to a non-affiliated is only mentioned here. It's not a standard term in this area. Sticking to the later examples in 'such as' is straightforward. > + nested stage-1 and HW-specific events/irqs e.g. events to invalidation > queues > + that are assigned to VMs via vIOMMUs. This queue object provides user vcmdq is not supported yet. add it later. > space an > + FD to poll the vIOMMU events. A vIOMMU object must be created first to > get its > + viommu_id that could be then used to allocate an EVENTQ_VIRQ. Each > vIOMMU can > + support multiple types of EVENTQ_VIRQs, but is confined to one > EVENTQ_VIRQ per > + vIRQ 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 +268,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_eventq_iopf for IOMMUFD_OBJ_EVENTQ_IOPF. > - iommufd_viommu for IOMMUFD_OBJ_VIOMMU. > - iommufd_vdevice for IOMMUFD_OBJ_VDEVICE. > +- iommufd_eventq_virq for IOMMUFD_OBJ_EVENTQ_VIRQ. > > Several terminologies when looking at these datastructures: > > -- > 2.43.0
On Wed, Dec 11, 2024 at 08:11:03AM +0000, Tian, Kevin wrote: > > From: Nicolin Chen <nicolinc@nvidia.com> > > Sent: Wednesday, December 4, 2024 6:10 AM > > > > With the introduction of the new objects, update the doc to reflect that. > > > > Signed-off-by: Nicolin Chen <nicolinc@nvidia.com> > > --- > > Documentation/userspace-api/iommufd.rst | 19 +++++++++++++++++++ > > 1 file changed, 19 insertions(+) > > > > diff --git a/Documentation/userspace-api/iommufd.rst > > b/Documentation/userspace-api/iommufd.rst > > index 70289d6815d2..798520d9344d 100644 > > --- a/Documentation/userspace-api/iommufd.rst > > +++ b/Documentation/userspace-api/iommufd.rst > > @@ -63,6 +63,14 @@ 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_EVENTQ_IOPF, representing a software queue for an > > HWPT_NESTED > > now it can be used on paging hwpt too Oh, that's why it's in the common path in the hwpt allocator... Seems that we are missing its selftest coverage for paging hwpt? > > + reporting IO Page Fault 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. An EVENTQ_IOPF object must be > > created > > + first to get a fault_id that could be then used to allocate an HWPT_NESTED > > + via the IOMMU_HWPT_ALLOC command setting > > IOMMU_HWPT_FAULT_ID_VALID set 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 +117,15 @@ 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_EVENTQ_VIRQ, representing a software queue for > > IOMMUFD_OBJ_VIOMMU > > + reporting its non-affiliated events, such as translation faults occurred to a > > non-affiliated is only mentioned here. It's not a standard term in this > area. Sticking to the later examples in 'such as' is straightforward. OK. > > + nested stage-1 and HW-specific events/irqs e.g. events to invalidation > > queues > > + that are assigned to VMs via vIOMMUs. This queue object provides user > > vcmdq is not supported yet. add it later. Ack. Thanks Nic
diff --git a/Documentation/userspace-api/iommufd.rst b/Documentation/userspace-api/iommufd.rst index 70289d6815d2..798520d9344d 100644 --- a/Documentation/userspace-api/iommufd.rst +++ b/Documentation/userspace-api/iommufd.rst @@ -63,6 +63,14 @@ 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_EVENTQ_IOPF, representing a software queue for an HWPT_NESTED + reporting IO Page Fault 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. An EVENTQ_IOPF object must be created + first to get a fault_id that could be then used to allocate an HWPT_NESTED + via the IOMMU_HWPT_ALLOC command setting IOMMU_HWPT_FAULT_ID_VALID set 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 +117,15 @@ 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_EVENTQ_VIRQ, representing a software queue for IOMMUFD_OBJ_VIOMMU + reporting its non-affiliated events, such as translation faults occurred to a + nested stage-1 and HW-specific events/irqs e.g. events to invalidation queues + that are assigned to VMs via vIOMMUs. This queue object provides user space an + FD to poll the vIOMMU events. A vIOMMU object must be created first to get its + viommu_id that could be then used to allocate an EVENTQ_VIRQ. Each vIOMMU can + support multiple types of EVENTQ_VIRQs, but is confined to one EVENTQ_VIRQ per + vIRQ 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 +268,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_eventq_iopf for IOMMUFD_OBJ_EVENTQ_IOPF. - iommufd_viommu for IOMMUFD_OBJ_VIOMMU. - iommufd_vdevice for IOMMUFD_OBJ_VDEVICE. +- iommufd_eventq_virq for IOMMUFD_OBJ_EVENTQ_VIRQ. Several terminologies when looking at these datastructures:
With the introduction of the new objects, update the doc to reflect that. Signed-off-by: Nicolin Chen <nicolinc@nvidia.com> --- Documentation/userspace-api/iommufd.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+)