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
