linux-kernel - Re: [PATCH v4 3/3] mm/huge_memory: fix kernel-doc comments for folio

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20251031025551.bmt4wh6e6tmhcr4i@master>
Date: Fri, 31 Oct 2025 02:55:51 +0000
From: Wei Yang <richard.weiyang@...il.com>
To: Zi Yan <ziy@...dia.com>
Cc: linmiaohe@...wei.com, david@...hat.com, jane.chu@...cle.com,
	kernel@...kajraghav.com, akpm@...ux-foundation.org,
	mcgrof@...nel.org, nao.horiguchi@...il.com,
	Lorenzo Stoakes <lorenzo.stoakes@...cle.com>,
	Baolin Wang <baolin.wang@...ux.alibaba.com>,
	"Liam R. Howlett" <Liam.Howlett@...cle.com>,
	Nico Pache <npache@...hat.com>, Ryan Roberts <ryan.roberts@....com>,
	Dev Jain <dev.jain@....com>, Barry Song <baohua@...nel.org>,
	Lance Yang <lance.yang@...ux.dev>,
	"Matthew Wilcox (Oracle)" <willy@...radead.org>,
	Wei Yang <richard.weiyang@...il.com>,
	Yang Shi <shy828301@...il.com>, linux-fsdevel@...r.kernel.org,
	linux-kernel@...r.kernel.org, linux-mm@...ck.org
Subject: Re: [PATCH v4 3/3] mm/huge_memory: fix kernel-doc comments for
 folio_split() and related.

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@...dia.com>
>Reviewed-by: Lorenzo Stoakes <lorenzo.stoakes@...cle.com>
>Acked-by: David Hildenbrand <david@...hat.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?

>  * @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?

-- 
Wei Yang
Help you, Help me