tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

mm/huge_memory: fix kernel-doc comments for folio_split() and related

try_folio_split_to_order(), folio_split, __folio_split(), and
__split_unmapped_folio() do not have correct kernel-doc comment format.
Fix them.

[ziy@nvidia.com: kernel-doc fixup]
Link: https://lkml.kernel.org/r/BE7AC5F3-9E64-4923-861D-C2C4E0CB91EB@nvidia.com
[ziy@nvidia.com: add newline to fix an error and a warning from docutils]
Link: https://lkml.kernel.org/r/040B38C0-23C6-4AEA-B069-69AE6DAA828B@nvidia.com
Link: https://lkml.kernel.org/r/20251031162001.670503-4-ziy@nvidia.com
Signed-off-by: Zi Yan <ziy@nvidia.com>
Reviewed-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
Reviewed-by: Lance Yang <lance.yang@linux.dev>
Reviewed-by: Barry Song <baohua@kernel.org>
Reviewed-by: Miaohe Lin <linmiaohe@huawei.com>
Acked-by: David Hildenbrand (Red Hat) <david@kernel.org>
Reviewed-by: Wei Yang <richard.weiyang@gmail.com>
Cc: Baolin Wang <baolin.wang@linux.alibaba.com>
Cc: Dev Jain <dev.jain@arm.com>
Cc: Jane Chu <jane.chu@oracle.com>
Cc: Liam Howlett <liam.howlett@oracle.com>
Cc: Luis Chamberalin <mcgrof@kernel.org>
Cc: Matthew Wilcox (Oracle) <willy@infradead.org>
Cc: Naoya Horiguchi <nao.horiguchi@gmail.com>
Cc: Nico Pache <npache@redhat.com>
Cc: Pankaj Raghav <kernel@pankajraghav.com>
Cc: Ryan Roberts <ryan.roberts@arm.com>
Cc: Yang Shi <shy828301@gmail.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>

authored by

Zi Yan and committed by
Andrew Morton 50d0598c 689b8986

+34 -28
+6 -4
include/linux/huge_mm.h
··· 386 386 return split_huge_page_to_list_to_order(page, NULL, new_order); 387 387 } 388 388 389 - /* 390 - * try_folio_split_to_order - try to split a @folio at @page to @new_order using 391 - * non uniform split. 389 + /** 390 + * try_folio_split_to_order() - try to split a @folio at @page to @new_order 391 + * using non uniform split. 392 392 * @folio: folio to be split 393 393 * @page: split to @new_order at the given page 394 394 * @new_order: the target split order ··· 398 398 * folios are put back to LRU list. Use min_order_for_split() to get the lower 399 399 * bound of @new_order. 400 400 * 401 - * Return: 0: split is successful, otherwise split failed. 401 + * Return: 0 - split is successful, otherwise split failed. 402 402 */ 403 403 static inline int try_folio_split_to_order(struct folio *folio, 404 404 struct page *page, unsigned int new_order) ··· 483 483 /** 484 484 * folio_test_pmd_mappable - Can we map this folio with a PMD? 485 485 * @folio: The folio to test 486 + * 487 + * Return: true - @folio can be mapped, false - @folio cannot be mapped. 486 488 */ 487 489 static inline bool folio_test_pmd_mappable(struct folio *folio) 488 490 {
+28 -24
mm/huge_memory.c
··· 3493 3493 ClearPageCompound(&folio->page); 3494 3494 } 3495 3495 3496 - /* 3497 - * It splits an unmapped @folio to lower order smaller folios in two ways. 3496 + /** 3497 + * __split_unmapped_folio() - splits an unmapped @folio to lower order folios in 3498 + * two ways: uniform split or non-uniform split. 3498 3499 * @folio: the to-be-split folio 3499 3500 * @new_order: the smallest order of the after split folios (since buddy 3500 3501 * allocator like split generates folios with orders from @folio's ··· 3512 3511 * uniform_split is true. 3513 3512 * 2. buddy allocator like (non-uniform) split: the given @folio is split into 3514 3513 * half and one of the half (containing the given page) is split into half 3515 - * until the given @page's order becomes @new_order. This is done when 3514 + * until the given @folio's order becomes @new_order. This is done when 3516 3515 * uniform_split is false. 3517 3516 * 3518 3517 * The high level flow for these two methods are: 3519 - * 1. uniform split: a single __split_folio_to_order() is called to split the 3520 - * @folio into @new_order, then we traverse all the resulting folios one by 3521 - * one in PFN ascending order and perform stats, unfreeze, adding to list, 3522 - * and file mapping index operations. 3523 - * 2. non-uniform split: in general, folio_order - @new_order calls to 3524 - * __split_folio_to_order() are made in a for loop to split the @folio 3525 - * to one lower order at a time. The resulting small folios are processed 3526 - * like what is done during the traversal in 1, except the one containing 3527 - * @page, which is split in next for loop. 3518 + * 3519 + * 1. uniform split: @xas is split with no expectation of failure and a single 3520 + * __split_folio_to_order() is called to split the @folio into @new_order 3521 + * along with stats update. 3522 + * 2. non-uniform split: folio_order - @new_order calls to 3523 + * __split_folio_to_order() are expected to be made in a for loop to split 3524 + * the @folio to one lower order at a time. The folio containing @split_at 3525 + * is split in each iteration. @xas is split into half in each iteration and 3526 + * can fail. A failed @xas split leaves split folios as is without merging 3527 + * them back. 3528 3528 * 3529 3529 * After splitting, the caller's folio reference will be transferred to the 3530 - * folio containing @page. The caller needs to unlock and/or free after-split 3531 - * folios if necessary. 3530 + * folio containing @split_at. The caller needs to unlock and/or free 3531 + * after-split folios if necessary. 3532 3532 * 3533 - * For !uniform_split, when -ENOMEM is returned, the original folio might be 3534 - * split. The caller needs to check the input folio. 3533 + * Return: 0 - successful, <0 - failed (if -ENOMEM is returned, @folio might be 3534 + * split but not to @new_order, the caller needs to check) 3535 3535 */ 3536 3536 static int __split_unmapped_folio(struct folio *folio, int new_order, 3537 3537 struct page *split_at, struct xa_state *xas, ··· 3652 3650 return true; 3653 3651 } 3654 3652 3655 - /* 3656 - * __folio_split: split a folio at @split_at to a @new_order folio 3653 + /** 3654 + * __folio_split() - split a folio at @split_at to a @new_order folio 3657 3655 * @folio: folio to split 3658 3656 * @new_order: the order of the new folio 3659 3657 * @split_at: a page within the new folio ··· 3671 3669 * 1. for uniform split, @lock_at points to one of @folio's subpages; 3672 3670 * 2. for buddy allocator like (non-uniform) split, @lock_at points to @folio. 3673 3671 * 3674 - * return: 0: successful, <0 failed (if -ENOMEM is returned, @folio might be 3672 + * Return: 0 - successful, <0 - failed (if -ENOMEM is returned, @folio might be 3675 3673 * split but not to @new_order, the caller needs to check) 3676 3674 */ 3677 3675 static int __folio_split(struct folio *folio, unsigned int new_order, ··· 4049 4047 unmapped); 4050 4048 } 4051 4049 4052 - /* 4053 - * folio_split: split a folio at @split_at to a @new_order folio 4050 + /** 4051 + * folio_split() - split a folio at @split_at to a @new_order folio 4054 4052 * @folio: folio to split 4055 4053 * @new_order: the order of the new folio 4056 4054 * @split_at: a page within the new folio 4057 - * 4058 - * return: 0: successful, <0 failed (if -ENOMEM is returned, @folio might be 4059 - * split but not to @new_order, the caller needs to check) 4055 + * @list: after-split folios are added to @list if not null, otherwise to LRU 4056 + * list 4060 4057 * 4061 4058 * It has the same prerequisites and returns as 4062 4059 * split_huge_page_to_list_to_order(). ··· 4069 4068 * [order-4, {order-3}, order-3, order-5, order-6, order-7, order-8]. 4070 4069 * 4071 4070 * After split, folio is left locked for caller. 4071 + * 4072 + * Return: 0 - successful, <0 - failed (if -ENOMEM is returned, @folio might be 4073 + * split but not to @new_order, the caller needs to check) 4072 4074 */ 4073 4075 int folio_split(struct folio *folio, unsigned int new_order, 4074 4076 struct page *split_at, struct list_head *list)