On Tue, Sep 10, 2024 at 01:41:11PM -0700, Nicolin Chen wrote:
> +- IOMMUFD_OBJ_HWPT_NESTED, representing an actual hardware I/O page table
> + (i.e. a single struct iommu_domain) managed by user space (e.g. guest OS).
> + "NESTED" indicates that this type of HWPT can be linked to an HWPT_PAGING.
> + It also indicates that it is backed by an iommu_domain that has a type of
> + IOMMU_DOMAIN_NESTED. This must be a stage-1 domain for a device running in
> + the user space (e.g. in a guest VM enabling the IOMMU nested translation
> + feature.) So it must be created with a given nesting parent stage-2 domain
"As such, it must be ..."
> + to associate to. This nested stage-1 page table managed by the user space
> + usually has mappings from guest-level I/O virtual addresses to guest-level
> + physical addresses.
>
> <snipped>...
> + this completes the device could do DMA. Note that every iommu_domain inside
> + the IOAS is also represented to userspace as an IOMMUFD_OBJ_HWPT_PAGING.
> +
> + IOMMUFD_OBJ_HWPT_PAGING can be also manually created via the IOMMU_HWPT_ALLOC
> + uAPI, provided an ioas_id via @pt_id to associate the new HWPT_PAGING object
> + to the corresponding IOAS object. The benefit of this manual allocation is to
> + provide allocation flags (defined in enum iommufd_hwpt_alloc_flags), e.g. it
> + allocates a nesting parent HWPT_PAGING, if the IOMMU_HWPT_ALLOC_NEST_PARENT
> + flag is set.
Nested bullet list fits:
---- >8 ---
diff --git a/Documentation/userspace-api/iommufd.rst b/Documentation/userspace-api/iommufd.rst
index 3b0e46017dce22..e3ff476aba097e 100644
--- a/Documentation/userspace-api/iommufd.rst
+++ b/Documentation/userspace-api/iommufd.rst
@@ -115,21 +115,21 @@ creating the objects and links::
3. IOMMUFD_OBJ_HWPT_PAGING can be created in two ways:
- IOMMUFD_OBJ_HWPT_PAGING is created when an external driver calls the IOMMUFD
- kAPI to attach a bound device to an IOAS. Similarly the external driver uAPI
- allows userspace to initiate the attaching operation. If a compatible
- pagetable already exists then it is reused for the attachment. Otherwise a
- new pagetable object and iommu_domain is created. Successful completion of
- this operation sets up the linkages among IOAS, device and iommu_domain. Once
- this completes the device could do DMA. Note that every iommu_domain inside
- the IOAS is also represented to userspace as an IOMMUFD_OBJ_HWPT_PAGING.
+ * IOMMUFD_OBJ_HWPT_PAGING is created when an external driver calls the IOMMUFD
+ kAPI to attach a bound device to an IOAS. Similarly the external driver uAPI
+ allows userspace to initiate the attaching operation. If a compatible
+ pagetable already exists then it is reused for the attachment. Otherwise a
+ new pagetable object and iommu_domain is created. Successful completion of
+ this operation sets up the linkages among IOAS, device and iommu_domain. Once
+ this completes the device could do DMA. Note that every iommu_domain inside
+ the IOAS is also represented to userspace as an IOMMUFD_OBJ_HWPT_PAGING.
- IOMMUFD_OBJ_HWPT_PAGING can be also manually created via the IOMMU_HWPT_ALLOC
- uAPI, provided an ioas_id via @pt_id to associate the new HWPT_PAGING object
- to the corresponding IOAS object. The benefit of this manual allocation is to
- provide allocation flags (defined in enum iommufd_hwpt_alloc_flags), e.g. it
- allocates a nesting parent HWPT_PAGING, if the IOMMU_HWPT_ALLOC_NEST_PARENT
- flag is set.
+ * IOMMUFD_OBJ_HWPT_PAGING can be also manually created via the IOMMU_HWPT_ALLOC
+ uAPI, provided an ioas_id via @pt_id to associate the new HWPT_PAGING object
+ to the corresponding IOAS object. The benefit of this manual allocation is to
+ provide allocation flags (defined in enum iommufd_hwpt_alloc_flags), e.g. it
+ allocates a nesting parent HWPT_PAGING, if the IOMMU_HWPT_ALLOC_NEST_PARENT
+ flag is set.
4. IOMMUFD_OBJ_HWPT_NESTED can be only manually created via the IOMMU_HWPT_ALLOC
uAPI, provided an hwpt_id via @pt_id to associate the new HWPT_NESTED object
> <snipped>...
> + When @pt_id carries an ioas_id to an IOAS object, the IOMMU_HWPT_ALLOC
> + call is instructed to allocate an HWPT_PAGING object only.
> + When @pt_id carries an hwpt_id to an HWPT_PAGING object, the uAPI call
"If instead @pt_id ..."
> + is instructed to allocate an HWPT_NESTED object only.
> + If any other type of object is passed in via the @pt_id, the uAPI call
> + will fail.
Thanks.
--
An old man doll... just what I always wanted! - Clara
Attachment:
signature.asc
Description: PGP signature
