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

[Zi Yan <ziy@nvidia.com>]

On 31 Oct 2025, at 19:36, Wei Yang wrote:

> On Fri, Oct 31, 2025 at 12:20:01PM -0400, Zi Yan wrote:
> [...]
>> diff --git a/mm/huge_memory.c b/mm/huge_memory.c
>> index 0e24bb7e90d0..ad2fc52651a6 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
>> @@ -3589,22 +3590,22 @@ static void __split_folio_to_order(struct folio *folio, int old_order,
>>  *    uniform_split is false.
>>  *
>>  * The high level flow for these two methods are:
>> - * 1. uniform split: a single __split_folio_to_order() is called to split the
>> - *    @folio into @new_order, then we traverse all the resulting folios one by
>> - *    one in PFN ascending order and perform stats, unfreeze, adding to list,
>> - *    and file mapping index operations.
>> - * 2. non-uniform split: in general, folio_order - @new_order calls to
>> - *    __split_folio_to_order() are made in a for loop to split the @folio
>> - *    to one lower order at a time. The resulting small folios are processed
>> - *    like what is done during the traversal in 1, except the one containing
>> - *    @page, which is split in next for loop.
>> + * 1. uniform split: @xas is split with no expectation of failure and a single
>> + *    __split_folio_to_order() is called to split the @folio into @new_order
>> + *    along with stats update.
>> + * 2. non-uniform split: folio_order - @new_order calls to
>> + *    __split_folio_to_order() are expected to be made in a for loop to split
>> + *    the @folio to one lower order at a time. The folio containing @page is
>
> Hope it is not annoying.
>
> The parameter's name is @split_at, maybe we misuse it?
>
> s/containing @page/containing @split_at/
>
>> + *    split in each iteration. @xas is split into half in each iteration and
>> + *    can fail. A failed @xas split leaves split folios as is without merging
>> + *    them back.
>>  *
>>  * After splitting, the caller's folio reference will be transferred to the
>>  * folio containing @page. The caller needs to unlock and/or free after-split
>
> The same above.
>
> And probably there is another one in above this comment(not shown here).

Hi Andrew,

Do you mind applying this fixup to address Wei's concerns?

Thanks.

From e1894a4e7ac95bdfe333cf5bee567f0ff90ddf5d Mon Sep 17 00:00:00 2001
From: Zi Yan <ziy@nvidia.com>
Date: Fri, 31 Oct 2025 19:50:55 -0400
Subject: [PATCH] mm/huge_memory: kernel-doc fixup

Signed-off-by: Zi Yan <ziy@nvidia.com>
---
 mm/huge_memory.c | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/mm/huge_memory.c b/mm/huge_memory.c
index ad2fc52651a6..a30fee2001b5 100644
--- a/mm/huge_memory.c
+++ b/mm/huge_memory.c
@@ -3586,7 +3586,7 @@ static void __split_folio_to_order(struct folio *folio, int old_order,
  *    uniform_split is true.
  * 2. buddy allocator like (non-uniform) split: the given @folio is split into
  *    half and one of the half (containing the given page) is split into half
- *    until the given @page's order becomes @new_order. This is done when
+ *    until the given @folio's order becomes @new_order. This is done when
  *    uniform_split is false.
  *
  * The high level flow for these two methods are:
@@ -3595,14 +3595,14 @@ static void __split_folio_to_order(struct folio *folio, int old_order,
  *    along with stats update.
  * 2. non-uniform split: folio_order - @new_order calls to
  *    __split_folio_to_order() are expected to be made in a for loop to split
- *    the @folio to one lower order at a time. The folio containing @page is
- *    split in each iteration. @xas is split into half in each iteration and
+ *    the @folio to one lower order at a time. The folio containing @split_at
+ *    is split in each iteration. @xas is split into half in each iteration and
  *    can fail. A failed @xas split leaves split folios as is without merging
  *    them back.
  *
  * After splitting, the caller's folio reference will be transferred to the
- * folio containing @page. The caller needs to unlock and/or free after-split
- * folios if necessary.
+ * folio containing @split_at. The caller needs to unlock and/or free
+ * after-split folios if necessary.
  *
  * Return: 0 - successful, <0 - failed (if -ENOMEM is returned, @folio might be
  * split but not to @new_order, the caller needs to check)
-- 
2.51.0





--
Best Regards,
Yan, Zi