Re: [PATCH v8 08/15] iommupt: Add read_and_clear_dirty op

[Jason Gunthorpe <jgg@nvidia.com>]

On Tue, Nov 04, 2025 at 11:13:06AM -0800, Randy Dunlap wrote:
> 
> 
> On 11/4/25 10:30 AM, Jason Gunthorpe wrote:
> > +/**
> > + * read_and_clear_dirty() - Manipulate the HW set write dirty state
> > + * @domain: Domain to manipulate
> > + * @iova: IO virtual address to start
> > + * @size: Length of the IOVA
> > + * @flags: A bitmap of IOMMU_DIRTY_NO_CLEAR
> > + * @dirty: Place to store the dirty bits
> > + *
> > + * Iterate over all the entries in the mapped range and record their write dirty
> > + * status in iommu_dirty_bitmap. If IOMMU_DIRTY_NO_CLEAR is not specified then
> > + * the entries will be left dirty, otherwise they are returned to being not
> > + * write dirty.
> > + *
> > + * Context: The caller must hold a read range lock that includes @iova.
> > + *
> > + * Returns: -ERRNO on failure, 0 on success.
> > + */
> > +int DOMAIN_NS(read_and_clear_dirty)(struct iommu_domain *domain,
> > +				    unsigned long iova, size_t size,
> > +				    unsigned long flags,
> > +				    struct iommu_dirty_bitmap *dirty)
> > +{
> 
> Just FYI:
> 
> I guess that a function with DOMAIN_NS() is going to confuse
> scripts/kernel-doc.py.
> 
> From patch 3 of this series:
> 
> +#define DOMAIN_NS(op) CONCATENATE(CONCATENATE(pt_iommu_, PTPFX), op)

Yeah, I don't think kdoc is pointed at this file. Still need to
document the function though..

Thanks,
Jason