Re: updated documentation: Splitting pinned folios

[David Hildenbrand <david@redhat.com>]

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

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

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

>    *
>    * If @list is null, tail pages will be added to LRU list, otherwise, to @list.
>    *
>    * Both head page and tail pages will inherit mapping, flags, and so on from the
>    * hugepage.
>    *
>    * Returns 0 if the hugepage was split successfully.
>    *
>    * Returns -EBUSY if @page's folio is pinned, or if the anon_vma disappeared
>    * from under us.
>    */
> int split_huge_page_to_list(struct page *page, struct list_head *list)
>    

-- 
Cheers,

David / dhildenb