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