Re: [PATCH] Documentation: userspace-api: iommufd: Update HWPT_PAGING and HWPT_NESTED

[Bagas Sanjaya <bagasdotme@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 4741 bytes --]

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 #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]