From: Nicolin Chen <nicolinc@nvidia.com>
To: <jgg@nvidia.com>, <kevin.tian@intel.com>, <corbet@lwn.net>,
<will@kernel.org>
Cc: <joro@8bytes.org>, <suravee.suthikulpanit@amd.com>,
<robin.murphy@arm.com>, <dwmw2@infradead.org>,
<baolu.lu@linux.intel.com>, <shuah@kernel.org>,
<linux-kernel@vger.kernel.org>, <iommu@lists.linux.dev>,
<linux-arm-kernel@lists.infradead.org>,
<linux-kselftest@vger.kernel.org>, <linux-doc@vger.kernel.org>,
<eric.auger@redhat.com>, <jean-philippe@linaro.org>,
<mdf@kernel.org>, <mshavit@google.com>,
<shameerali.kolothum.thodi@huawei.com>, <smostafa@google.com>,
<ddutile@redhat.com>, <yi.l.liu@intel.com>,
<patches@lists.linux.dev>
Subject: [PATCH v6 11/14] Documentation: userspace-api: iommufd: Update FAULT and VEVENTQ
Date: Fri, 24 Jan 2025 16:30:40 -0800 [thread overview]
Message-ID: <300d03449b9420d756c1589e1c24bb8b4d508293.1737754129.git.nicolinc@nvidia.com> (raw)
In-Reply-To: <cover.1737754129.git.nicolinc@nvidia.com>
With the introduction of the new objects, update the doc to reflect that.
Reviewed-by: Lu Baolu <baolu.lu@linux.intel.com>
Reviewed-by: Kevin Tian <kevin.tian@intel.com>
Signed-off-by: Nicolin Chen <nicolinc@nvidia.com>
---
Documentation/userspace-api/iommufd.rst | 17 +++++++++++++++++
1 file changed, 17 insertions(+)
diff --git a/Documentation/userspace-api/iommufd.rst b/Documentation/userspace-api/iommufd.rst
index 70289d6815d2..b0df15865dec 100644
--- a/Documentation/userspace-api/iommufd.rst
+++ b/Documentation/userspace-api/iommufd.rst
@@ -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:
--
2.43.0
next prev parent reply other threads:[~2025-01-25 0:31 UTC|newest]
Thread overview: 60+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-01-25 0:30 [PATCH v6 00/14] iommufd: Add vIOMMU infrastructure (Part-3: vEVENTQ) Nicolin Chen
2025-01-25 0:30 ` [PATCH v6 01/14] iommufd/fault: Move two fault functions out of the header Nicolin Chen
2025-02-14 20:15 ` Jason Gunthorpe
2025-02-18 5:05 ` Tian, Kevin
2025-01-25 0:30 ` [PATCH v6 02/14] iommufd/fault: Add an iommufd_fault_init() helper Nicolin Chen
2025-01-25 0:30 ` [PATCH v6 03/14] iommufd: Abstract an iommufd_eventq from iommufd_fault Nicolin Chen
2025-02-14 20:23 ` Jason Gunthorpe
2025-01-25 0:30 ` [PATCH v6 04/14] iommufd: Rename fault.c to eventq.c Nicolin Chen
2025-01-25 0:30 ` [PATCH v6 05/14] iommufd: Add IOMMUFD_OBJ_VEVENTQ and IOMMUFD_CMD_VEVENTQ_ALLOC Nicolin Chen
2025-02-18 5:13 ` Tian, Kevin
2025-02-18 17:53 ` Nicolin Chen
2025-02-18 15:29 ` Jason Gunthorpe
2025-02-18 17:47 ` Nicolin Chen
2025-02-18 18:08 ` Jason Gunthorpe
2025-02-18 18:15 ` Nicolin Chen
2025-01-25 0:30 ` [PATCH v6 06/14] iommufd/viommu: Add iommufd_viommu_get_vdev_id helper Nicolin Chen
2025-02-18 15:31 ` Jason Gunthorpe
2025-02-20 5:17 ` Nicolin Chen
2025-02-20 16:19 ` Jason Gunthorpe
2025-01-25 0:30 ` [PATCH v6 07/14] iommufd/viommu: Add iommufd_viommu_report_event helper Nicolin Chen
2025-02-18 5:14 ` Tian, Kevin
2025-02-18 15:35 ` Jason Gunthorpe
2025-02-19 6:58 ` Tian, Kevin
2025-02-20 21:16 ` Nicolin Chen
2025-02-21 4:27 ` Tian, Kevin
2025-02-21 13:39 ` Jason Gunthorpe
2025-01-25 0:30 ` [PATCH v6 08/14] iommufd/selftest: Require vdev_id when attaching to a nested domain Nicolin Chen
2025-02-18 5:15 ` Tian, Kevin
2025-01-25 0:30 ` [PATCH v6 09/14] iommufd/selftest: Add IOMMU_TEST_OP_TRIGGER_VEVENT for vEVENTQ coverage Nicolin Chen
2025-02-18 5:16 ` Tian, Kevin
2025-01-25 0:30 ` [PATCH v6 10/14] iommufd/selftest: Add IOMMU_VEVENTQ_ALLOC test coverage Nicolin Chen
2025-02-18 5:19 ` Tian, Kevin
2025-01-25 0:30 ` Nicolin Chen [this message]
2025-01-28 8:21 ` [PATCH v6 11/14] Documentation: userspace-api: iommufd: Update FAULT and VEVENTQ Bagas Sanjaya
2025-02-18 17:02 ` Jason Gunthorpe
2025-01-25 0:30 ` [PATCH v6 12/14] iommu/arm-smmu-v3: Introduce struct arm_smmu_vmaster Nicolin Chen
2025-02-18 17:08 ` Jason Gunthorpe
2025-02-20 7:16 ` Nicolin Chen
2025-01-25 0:30 ` [PATCH v6 13/14] iommu/arm-smmu-v3: Report events that belong to devices attached to vIOMMU Nicolin Chen
2025-02-18 5:21 ` Tian, Kevin
2025-02-18 17:18 ` Jason Gunthorpe
2025-02-18 18:28 ` Nicolin Chen
2025-02-18 18:50 ` Jason Gunthorpe
2025-02-18 19:02 ` Nicolin Chen
2025-02-18 19:08 ` Jason Gunthorpe
2025-02-18 19:27 ` Nicolin Chen
2025-02-20 20:45 ` Nicolin Chen
2025-02-20 23:24 ` Jason Gunthorpe
2025-02-21 8:10 ` Nicolin Chen
2025-01-25 0:30 ` [PATCH v6 14/14] iommu/arm-smmu-v3: Set MEV bit in nested STE for DoS mitigations Nicolin Chen
2025-02-18 5:24 ` Tian, Kevin
2025-02-18 18:17 ` Pranjal Shrivastava
2025-02-18 18:52 ` Jason Gunthorpe
2025-02-20 7:12 ` Nicolin Chen
2025-02-18 18:53 ` Nicolin Chen
2025-02-20 16:15 ` Pranjal Shrivastava
2025-02-18 17:21 ` Jason Gunthorpe
2025-02-18 18:14 ` Nicolin Chen
2025-02-20 9:09 ` Nicolin Chen
2025-02-14 8:03 ` [PATCH v6 00/14] iommufd: Add vIOMMU infrastructure (Part-3: vEVENTQ) Nicolin Chen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=300d03449b9420d756c1589e1c24bb8b4d508293.1737754129.git.nicolinc@nvidia.com \
--to=nicolinc@nvidia.com \
--cc=baolu.lu@linux.intel.com \
--cc=corbet@lwn.net \
--cc=ddutile@redhat.com \
--cc=dwmw2@infradead.org \
--cc=eric.auger@redhat.com \
--cc=iommu@lists.linux.dev \
--cc=jean-philippe@linaro.org \
--cc=jgg@nvidia.com \
--cc=joro@8bytes.org \
--cc=kevin.tian@intel.com \
--cc=linux-arm-kernel@lists.infradead.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-kselftest@vger.kernel.org \
--cc=mdf@kernel.org \
--cc=mshavit@google.com \
--cc=patches@lists.linux.dev \
--cc=robin.murphy@arm.com \
--cc=shameerali.kolothum.thodi@huawei.com \
--cc=shuah@kernel.org \
--cc=smostafa@google.com \
--cc=suravee.suthikulpanit@amd.com \
--cc=will@kernel.org \
--cc=yi.l.liu@intel.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.