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

[Nicolin Chen]

On Wed, Sep 11, 2024 at 07:09:15AM +0000, Tian, Kevin wrote:
> > 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/

Was thinking of the 2nd choice: HWPT_NESTED->vIOMMU (HWPT_PAGING)
Yet, I think "should" could fit that narrative too. Will change.

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

I don't quite get this part...where is the redundancy? And where
is "otherwise a new page table object .."?


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

OK.

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

I feel it's a nice summary though... I'll see how I can simplify it.

Thanks
Nicolin