Re: [PATCH v2 2/4] mm: Add file_operations.get_mapping_order()

[Peter Xu <peterx@redhat.com>]

On Tue, Dec 16, 2025 at 02:58:50PM -0400, Jason Gunthorpe wrote:
> On Tue, Dec 16, 2025 at 12:36:13PM -0500, Peter Xu wrote:
> > On Tue, Dec 16, 2025 at 01:19:44PM -0400, Jason Gunthorpe wrote:
> > > On Tue, Dec 16, 2025 at 10:42:39AM -0500, Peter Xu wrote:
> > > > Also see __thp_get_unmapped_area() processed such pgoff, it allocates VA
> > > > with len_pad (not len), and pad the retval at last.
> > > > 
> > > > Please let me know if it didn't work like it, then it might be a bug.
> > > 
> > > It should all be documented then in the kdoc for the new ops, in this
> > > kind of language that the resulting VA flows from pgoff
> > 
> > IMHO that's one of the major benefits of this API, so that there's no need
> > to mention impl details like this.
> 
> It needs to be clearly explained exactly how pgoff and the returned
> order are related because it impacts how the drivers need to manage
> their pgoff space.

Here "pgoff" plays two roles:

  (1) as a range, (pgoff, len) on top of the fd, decides which device blob
      to be mapped.  This is relevant to the driver, for sure..

  (2) as an offset, pgoff is relevant when we want to make sure mmap()
      request's VA will be aligned in a way so that we can maximize huge
      mappings.  This has, IMHO, nothing to do with the driver, and that's
      what I want to make the new API transparent of.

I agree drivers need to know pgoff for (1) in terms of get_mapping_order(),
not (2).

> 
> > Here the point is, the driver should only care about the size of mapping,
> > nothing else like how exactly the alignments will be calculated, and how
> > that interacts with pgoff.  The kernel mm manages that. It's done exactly
> > like what anon thp does already when len is pmd aligned.
> 
> The driver owns the pgoff number space, it has to care about how that
> relates to the PTEs.
> 
> > Or maybe I misunderstood what you're suggesting to document?  If so, please
> > let me know; some example would be greatly helpful.
> 
> Just document the 'VA % order = pgoff % order' equation in the kdoc
> for the new op.

When it's "related to PTEs", it's talking about (2) above, so that's really
what I want to avoid mentioning.

Docuemnt anything about VA is just confusing on its own especially when
"int get_mapping_order(fd, pgoff, len)" doesn't even have anything in param
or retval that is relevant to the virtual address space..

If you think missing such info is harder for reviews, I can definitely add
a rich comment when repost explaining how __thp_get_unmapped_area() works
here.

We can also pause this a bit and wait for Matthew's review on the API,
where he showed concerns.  If there's major reason this API is rejected, we
don't need to bother this part of detail either.

Thanks,

-- 
Peter Xu