Re: [PATCH v4 3/3] mm/huge_memory: fix kernel-doc comments for folio_split() and related.

[Zi Yan <ziy@nvidia.com>]

On 30 Oct 2025, at 22:55, Wei Yang wrote:

> On Wed, Oct 29, 2025 at 09:40:20PM -0400, Zi Yan wrote:
>> try_folio_split_to_order(), folio_split, __folio_split(), and
>> __split_unmapped_folio() do not have correct kernel-doc comment format.
>> Fix them.
>>
>> Signed-off-by: Zi Yan <ziy@nvidia.com>
>> Reviewed-by: Lorenzo Stoakes <lorenzo.stoakes@oracle.com>
>> Acked-by: David Hildenbrand <david@redhat.com>
>
> Generally looks good, while some nit below.
>
>> ---
>> include/linux/huge_mm.h | 10 ++++++----
>> mm/huge_memory.c        | 27 +++++++++++++++------------
>> 2 files changed, 21 insertions(+), 16 deletions(-)
>>
>> diff --git a/include/linux/huge_mm.h b/include/linux/huge_mm.h
>> index 34f8d8453bf3..cbb2243f8e56 100644
>> --- a/include/linux/huge_mm.h
>> +++ b/include/linux/huge_mm.h
>> @@ -386,9 +386,9 @@ static inline int split_huge_page_to_order(struct page *page, unsigned int new_o
>> 	return split_huge_page_to_list_to_order(page, NULL, new_order);
>> }
>>
>> -/*
>> - * try_folio_split_to_order - try to split a @folio at @page to @new_order using
>> - * non uniform split.
>> +/**
>> + * try_folio_split_to_order() - try to split a @folio at @page to @new_order
>> + * using non uniform split.
>
> This looks try_folio_split_to_order() only perform non uniform split, while the
> following comment mentions it will try uniform split if non uniform split is
> not supported.
>
> Do you think this is a little confusing?

It says "try to", so it is possible that an alternative can be used.

>
>>  * @folio: folio to be split
>>  * @page: split to @new_order at the given page
>>  * @new_order: the target split order
>> @@ -398,7 +398,7 @@ static inline int split_huge_page_to_order(struct page *page, unsigned int new_o
>>  * folios are put back to LRU list. Use min_order_for_split() to get the lower
>>  * bound of @new_order.
>>  *
>> - * Return: 0: split is successful, otherwise split failed.
>> + * Return: 0 - split is successful, otherwise split failed.
>>  */
>> static inline int try_folio_split_to_order(struct folio *folio,
>> 		struct page *page, unsigned int new_order)
>> @@ -486,6 +486,8 @@ static inline spinlock_t *pud_trans_huge_lock(pud_t *pud,
>> /**
>>  * folio_test_pmd_mappable - Can we map this folio with a PMD?
>>  * @folio: The folio to test
>> + *
>> + * Return: true - @folio can be mapped, false - @folio cannot be mapped.
>>  */
>> static inline bool folio_test_pmd_mappable(struct folio *folio)
>> {
>> diff --git a/mm/huge_memory.c b/mm/huge_memory.c
>> index 0e24bb7e90d0..381a49c5ac3f 100644
>> --- a/mm/huge_memory.c
>> +++ b/mm/huge_memory.c
>> @@ -3567,8 +3567,9 @@ static void __split_folio_to_order(struct folio *folio, int old_order,
>> 		ClearPageCompound(&folio->page);
>> }
>>
>> -/*
>> - * It splits an unmapped @folio to lower order smaller folios in two ways.
>> +/**
>> + * __split_unmapped_folio() - splits an unmapped @folio to lower order folios in
>> + * two ways: uniform split or non-uniform split.
>>  * @folio: the to-be-split folio
>>  * @new_order: the smallest order of the after split folios (since buddy
>>  *             allocator like split generates folios with orders from @folio's
>
> In the comment of __split_unmapped_folio(), we have some description about the
> split behavior, e.g. update stat, unfreeze.
>
> Is this out-dated?

OK, I will update it.

--
Best Regards,
Yan, Zi