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

[Nicolin Chen]

Hi Bagas,

On Wed, Sep 11, 2024 at 09:13:10AM +0700, Bagas Sanjaya wrote:
> ---- >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.

I've applied the diff to my local version and will respin another
version after collecting remarks from others.

Thanks!
Nicolin