updated documentation: Splitting pinned folios

[John Hubbard <jhubbard@nvidia.com>]

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?

/*
  * 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.
  *
  * After splitting, the folio's refcount is transfered to @page (not the head
  * page, unless @page is actually the head page). The other subpages may be
  * freed if they are not mapped.
  *
  * 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)
  

thanks,
-- 
John Hubbard
NVIDIA