mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
From: Zi Yan <ziy@nvidia.com>
To: akpm@linux-foundation.org, linmiaohe@huawei.com,
	david@redhat.com, jane.chu@oracle.com
Cc: kernel@pankajraghav.com, ziy@nvidia.com, mcgrof@kernel.org,
	nao.horiguchi@gmail.com,
	Lorenzo Stoakes <lorenzo.stoakes@oracle.com>,
	Baolin Wang <baolin.wang@linux.alibaba.com>,
	"Liam R. Howlett" <Liam.Howlett@oracle.com>,
	Nico Pache <npache@redhat.com>,
	Ryan Roberts <ryan.roberts@arm.com>, Dev Jain <dev.jain@arm.com>,
	Barry Song <baohua@kernel.org>, Lance Yang <lance.yang@linux.dev>,
	"Matthew Wilcox (Oracle)" <willy@infradead.org>,
	Wei Yang <richard.weiyang@gmail.com>,
	Yang Shi <shy828301@gmail.com>,
	linux-fsdevel@vger.kernel.org, linux-kernel@vger.kernel.org,
	linux-mm@kvack.org
Subject: Re: [PATCH v5 3/3] mm/huge_memory: fix kernel-doc comments for folio_split() and related.
Date: Wed, 05 Nov 2025 11:10:24 -0500	[thread overview]
Message-ID: <040B38C0-23C6-4AEA-B069-69AE6DAA828B@nvidia.com> (raw)
In-Reply-To: <20251031162001.670503-4-ziy@nvidia.com>

On 31 Oct 2025, at 12:20, 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.
>
> 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>
> Signed-off-by: Zi Yan <ziy@nvidia.com>
> ---
>  include/linux/huge_mm.h | 10 +++++----
>  mm/huge_memory.c        | 45 ++++++++++++++++++++++-------------------
>  2 files changed, 30 insertions(+), 25 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.
>   * @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..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
> + *    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.
>   *

This change caused an error and a warning from docutils[1].
The following patch fixed the issue.

Hi Andrew,

Do you mind folding this in? This fixup can just go after[2]. And both
can be folded into this patch.

Thanks.


From c49e940cc23e051e3f4faf0bca002a05bb6b0dc1 Mon Sep 17 00:00:00 2001
From: Zi Yan <ziy@nvidia.com>
Date: Wed, 5 Nov 2025 11:01:09 -0500
Subject: [PATCH] mm/huge_memory: fix an error and a warning from docutils

Add a newline to fix the following error and warning:

Documentation/core-api/mm-api:134: mm/huge_memory.c:3593: ERROR: Unexpected indentation. [docutils]
Documentation/core-api/mm-api:134: mm/huge_memory.c:3595: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]

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

diff --git a/mm/huge_memory.c b/mm/huge_memory.c
index a30fee2001b5..36fc4ff002c9 100644
--- a/mm/huge_memory.c
+++ b/mm/huge_memory.c
@@ -3590,6 +3590,7 @@ 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: @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.51.0





[1] https://lore.kernel.org/all/20251105162314.004e2764@canb.auug.org.au/
[2] https://lore.kernel.org/all/BE7AC5F3-9E64-4923-861D-C2C4E0CB91EB@nvidia.com/

Best Regards,
Yan, Zi

      parent reply	other threads:[~2025-11-05 16:10 UTC|newest]

Thread overview: 9+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2025-10-31 16:19 [PATCH v5 0/3] Optimize folio split in memory failure Zi Yan
2025-10-31 16:19 ` [PATCH v5 1/3] mm/huge_memory: add split_huge_page_to_order() Zi Yan
2025-10-31 16:20 ` [PATCH v5 2/3] mm/memory-failure: improve large block size folio handling Zi Yan
2025-10-31 16:20 ` [PATCH v5 3/3] mm/huge_memory: fix kernel-doc comments for folio_split() and related Zi Yan
2025-10-31 23:36   ` Wei Yang
2025-10-31 23:52     ` Zi Yan
2025-11-01  0:08       ` Wei Yang
2025-11-03 16:38       ` David Hildenbrand (Red Hat)
2025-11-05 16:10   ` Zi Yan [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=040B38C0-23C6-4AEA-B069-69AE6DAA828B@nvidia.com \
    --to=ziy@nvidia.com \
    --cc=Liam.Howlett@oracle.com \
    --cc=akpm@linux-foundation.org \
    --cc=baohua@kernel.org \
    --cc=baolin.wang@linux.alibaba.com \
    --cc=david@redhat.com \
    --cc=dev.jain@arm.com \
    --cc=jane.chu@oracle.com \
    --cc=kernel@pankajraghav.com \
    --cc=lance.yang@linux.dev \
    --cc=linmiaohe@huawei.com \
    --cc=linux-fsdevel@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-mm@kvack.org \
    --cc=lorenzo.stoakes@oracle.com \
    --cc=mcgrof@kernel.org \
    --cc=nao.horiguchi@gmail.com \
    --cc=npache@redhat.com \
    --cc=richard.weiyang@gmail.com \
    --cc=ryan.roberts@arm.com \
    --cc=shy828301@gmail.com \
    --cc=willy@infradead.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox

all inboxes | Powered by JetHome®