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

[Tian, Kevin]

> From: Nicolin Chen <nicolinc@xxxxxxxxxx>
> Sent: Wednesday, September 11, 2024 4:41 AM
> 
> +  feature flag. This can be either an UNMANAGED stage-1 domain for a
> device
> +  running in the user space, or a nesting parent stage-2 domain for
> mappings
> +  from guest-level physical addresses to host-level physical addresses.

the former part is inaccurate. It could be an UNMANAGED stage-2 domain.

> +
> +- 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.

s/can be/should be/

> 
> -3. IOMMUFD_OBJ_HW_PAGETABLE is created when an external driver calls
> the IOMMUFD
> +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.
> -
> -   Every iommu_domain inside the IOAS is also represented to userspace as
> a
> -   HW_PAGETABLE object.
> +   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.

the last sentence is redundant. here we are talking about how HWPT_PAGING
is created so it's implied. probably you can state that HWPT_PAGING object
is created when talking about "otherwise a new page table object and
iommu_domain is created".

> +
> +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
> +   to the corresponding HWPT_PAGING object. The associating
> HWPT_PAGING object
> +   must be a nesting parent manually allocated via the same uAPI previously
> with
> +   an IOMMU_HWPT_ALLOC_NEST_PARENT flag, otherwise the allocation
> will fail. The
> +   allocation will be further validated by the IOMMU driver of an IOMMU
> hardware
> +   that the given device (via @dev_id) is physically linked to, to ensure that
> +   the nesting parent domain and a nested domain being allocated are
> compatible.

just "validated by the IOMMU driver to ensure that ..."

> 
>     .. note::
> 
> -      Future IOMMUFD updates will provide an API to create and manipulate
> the
> -      HW_PAGETABLE directly.
> +      Either a manual IOMMUFD_OBJ_HWPT_PAGING or an
> IOMMUFD_OBJ_HWPT_NESTED is
> +      created via the same IOMMU_HWPT_ALLOC uAPI. The difference is at
> the type
> +      of the object passed in via the @pt_id field of struct
> iommufd_hwpt_alloc:
> +      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
> +      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'm not sure whether this note is still required. probably just one
sentence to highlight that it's @pt_id field to mark out the 
object type? most descriptions duplicate with the earlier words.