Re: updated documentation: Splitting pinned folios

[John Hubbard <jhubbard@nvidia.com>]

On 3/14/24 09:22, David Hildenbrand wrote:
> On 14.03.24 03:46, John Hubbard wrote:
>> On 3/13/24 2:20 AM, David Hildenbrand wrote:
>> ...
>>> The description is wrong. Whoever calls split_huge_page_to_list() 
>>> must hold a folio reference.
>>>
>>> That folio reference will be transferred to @page (not the head page) 
>>> once split. So @page can be used by the caller after the split 
>>> succeeded.
>>>
>>
>> David and all, does this updated draft comment look accurate?
>>
> 
> Note that in mm-unstable (maybe even mm-stable already), the function is 
> now called split_huge_page_to_list_to_order().

Aha, yes already in mm-stable, and the comment is quite heavily modified
there, too. But it's straightforward to merge in relevant parts of what
we're trying to say here.

I can send out an actual patch after the merge window finishes.

> 
>> /*
>>    * This function splits a huge page into normal pages. @page can 
>> point to any
>>    * subpage of the huge page to split. The split operation does not 
>> change the
>>    * position of @page.
>>    *
>>    * Prerequisites:
>>    *
>>    * 1) The caller must hold a reference on the @page's owning folio, 
>> also known as
>>    *    the huge page.
>>    *
>>    * 2) The huge page must be locked.
>>    *
>>    * 3) The folio must not be pinned. Pinned folios will not be split; 
>> instead,
>>    *    the caller will receive an -EBUSY.
> 
> Maybe focus on unexpected folio references:
> 
> 3) The folio must not be pinned. Any unexpected folio references, 
> including GUP pins, will result in the folio not getting split; instead ...

Yes, saying "unexpected" does make it clearer, agreed.

> 
>>    * >    * After splitting, the folio's refcount is transfered to @page 
> (not the head
> 
> s/transfered/transferred/
> 
>>    * page, unless @page is actually the head page). The other subpages 
>> may be
>>    * freed if they are not mapped.
> 
> "folio's refcount" might be a bit misleading. It's more like
> 
> "The caller's folio reference will be transferred to @page, resulting in 
> a raised refcount of @page after this call ... "

heh, my wording was actually wrong! Thanks for correcting it. I didn't
see where the @page picked up the folio's reference, so I thought I
must have misread your original explanation.


thanks,
-- 
John Hubbard
NVIDIA