[PATCH mm-new] mm/mglru: clarify the generation placement in lru_gen_folio_seq()

[PATCH mm-new] mm/mglru: clarify the generation placement in lru_gen_folio_seq()

[Ridong Chen]

From: Ridong Chen <chenridong@xiaomi.com>

lru_gen_folio_seq() computes how many generations below max_seq a
folio should be added to, but stores it in a variable named "gen".
Elsewhere in MGLRU "gen" means an index into lrugen->folios[], i.e.
seq % MAX_NR_GENS, so reusing the name for a relative offset is
confusing.

The comment table above the code also no longer matches it. It only
covers the PG_active and the final branch, leaving out the reclaiming
and "can't evict yet" cases, and it lists LRU_REFS_FLAGS as an input
although lru_gen_folio_seq() never looks at it.

Rename the local variable to "age", redraw the table so that each
branch maps to the age and seq it produces, and note that the result
is clamped to min_seq[type].

No functional change.

Assisted-by: LLM
Signed-off-by: Ridong Chen <chenridong@xiaomi.com>
---
 include/linux/mm_inline.h | 48 ++++++++++++++++++++++++++-------------
 1 file changed, 32 insertions(+), 16 deletions(-)

diff --git a/include/linux/mm_inline.h b/include/linux/mm_inline.h
index ab69b9930893..a933d8c14558 100644
--- a/include/linux/mm_inline.h
+++ b/include/linux/mm_inline.h
@@ -302,34 +302,50 @@ static inline unsigned long lru_gen_folio_seq(const struct lruvec *lruvec,
 					      const struct folio *folio,
 					      bool reclaiming)
 {
-	int gen;
+	int age;
 	int type = folio_is_file_lru(folio);
 	const struct lru_gen_folio *lrugen = &lruvec->lrugen;
 
 	/*
-	 * +-----------------------------------+-----------------------------------+
-	 * | Accessed through page tables and  | Accessed through file descriptors |
-	 * | promoted by folio_update_gen()    | and protected by folio_inc_gen()  |
-	 * +-----------------------------------+-----------------------------------+
-	 * | PG_active (set while isolated)    |                                   |
-	 * +-----------------+-----------------+-----------------+-----------------+
-	 * |  PG_workingset  |  PG_referenced  |  PG_workingset  |  LRU_REFS_FLAGS |
-	 * +-----------------------------------+-----------------------------------+
-	 * |<---------- MIN_NR_GENS ---------->|                                   |
-	 * |<---------------------------- MAX_NR_GENS ---------------------------->|
+	 *            +-----------------+-----------------+-----------------+-----------------+
+	 * age        |        1        |        2        |        3        |        4        |
+	 *            +-----------------+-----------------+-----------------+-----------------+
+	 * seq        |     max_seq     |    max_seq-1    |    max_seq-2    |    max_seq-3    |
+	 *            +-----------------------------------+-----------------------------------+
+	 *            |<---------- MIN_NR_GENS ---------->|                                   |
+	 *            |<---------------------------- MAX_NR_GENS ---------------------------->|
+	 *            +-----------------------------------+-----------------------------------+
+	 *            | Accessed through page tables and  | Accessed through file descriptors |
+	 *            | promoted by folio_update_gen()    | and protected by folio_inc_gen()  |
+	 *            +-----------------+-----------------+-----------------+-----------------+
+	 * PG_active  |  PG_workingset  | !PG_workingset  |                 |                 |
+	 *            +-----------------+-----------------+-----------------+-----------------+
+	 * reclaiming |                 |                 |                 |     always      |
+	 *            +-----------------+-----------------+-----------------+-----------------+
+	 * can't      |                 |  anon && not in |                 |                 |
+	 * evict yet  |                 |  swapcache, or  |                 |                 |
+	 *            |                 |  PG_reclaim &&  |                 |                 |
+	 *            |                 | dirty/writeback |                 |                 |
+	 *            +-----------------+-----------------+-----------------+-----------------+
+	 * else       |                 |                 |  PG_workingset  | !PG_workingset  |
+	 *            |                 |                 |       or        |       &&        |
+	 *            |                 |                 |  PG_referenced  | !PG_referenced  |
+	 *            +-----------------+-----------------+-----------------+-----------------+
+	 *
+	 * The resulting seq is clamped to min_seq[type].
 	 */
 	if (folio_test_active(folio))
-		gen = MIN_NR_GENS - folio_test_workingset(folio);
+		age = MIN_NR_GENS - folio_test_workingset(folio);
 	else if (reclaiming)
-		gen = MAX_NR_GENS;
+		age = MAX_NR_GENS;
 	else if ((!folio_is_file_lru(folio) && !folio_test_swapcache(folio)) ||
 		 (folio_test_reclaim(folio) &&
 		  (folio_test_dirty(folio) || folio_test_writeback(folio))))
-		gen = MIN_NR_GENS;
+		age = MIN_NR_GENS;
 	else
-		gen = MAX_NR_GENS - (folio_test_workingset(folio) || folio_test_referenced(folio));
+		age = MAX_NR_GENS - (folio_test_workingset(folio) || folio_test_referenced(folio));
 
-	return max(READ_ONCE(lrugen->max_seq) - gen + 1, READ_ONCE(lrugen->min_seq[type]));
+	return max(READ_ONCE(lrugen->max_seq) - age + 1, READ_ONCE(lrugen->min_seq[type]));
 }
 
 static inline bool lru_gen_add_folio(struct lruvec *lruvec, struct folio *folio, bool reclaiming)
-- 
2.34.1

Re: [PATCH mm-new] mm/mglru: clarify the generation placement in lru_gen_folio_seq()

[Barry Song]

On Tue, Oct 20, 2026 at 10:36 AM Ridong Chen <ridong.chen@linux.dev> wrote:
>
> From: Ridong Chen <chenridong@xiaomi.com>
>
> lru_gen_folio_seq() computes how many generations below max_seq a
> folio should be added to, but stores it in a variable named "gen".
> Elsewhere in MGLRU "gen" means an index into lrugen->folios[], i.e.
> seq % MAX_NR_GENS, so reusing the name for a relative offset is
> confusing.
>
> The comment table above the code also no longer matches it. It only
> covers the PG_active and the final branch, leaving out the reclaiming
> and "can't evict yet" cases, and it lists LRU_REFS_FLAGS as an input
> although lru_gen_folio_seq() never looks at it.
>
> Rename the local variable to "age", redraw the table so that each
> branch maps to the age and seq it produces, and note that the result
> is clamped to min_seq[type].
>
> No functional change.
>
> Assisted-by: LLM
> Signed-off-by: Ridong Chen <chenridong@xiaomi.com>
> ---

Hi Ridong,

The cleanup might be right, but this part is changing rapidly
with Kairui's MGLRU-FG series. Maybe we should wait until
that series lands and then see if this cleanup is still needed?

Best Regards
Barry

Re: [PATCH mm-new] mm/mglru: clarify the generation placement in lru_gen_folio_seq()

[Ridong Chen]

On 10/20/2026 1:43 PM, Barry Song wrote:
> On Tue, Oct 20, 2026 at 10:36 AM Ridong Chen <ridong.chen@linux.dev> wrote:
>>
>> From: Ridong Chen <chenridong@xiaomi.com>
>>
>> lru_gen_folio_seq() computes how many generations below max_seq a
>> folio should be added to, but stores it in a variable named "gen".
>> Elsewhere in MGLRU "gen" means an index into lrugen->folios[], i.e.
>> seq % MAX_NR_GENS, so reusing the name for a relative offset is
>> confusing.
>>
>> The comment table above the code also no longer matches it. It only
>> covers the PG_active and the final branch, leaving out the reclaiming
>> and "can't evict yet" cases, and it lists LRU_REFS_FLAGS as an input
>> although lru_gen_folio_seq() never looks at it.
>>
>> Rename the local variable to "age", redraw the table so that each
>> branch maps to the age and seq it produces, and note that the result
>> is clamped to min_seq[type].
>>
>> No functional change.
>>
>> Assisted-by: LLM
>> Signed-off-by: Ridong Chen <chenridong@xiaomi.com>
>> ---
> 
> Hi Ridong,
> 
> The cleanup might be right, but this part is changing rapidly
> with Kairui's MGLRU-FG series. Maybe we should wait until
> that series lands and then see if this cleanup is still needed?
> 
Sure, I'm fine to wait. Looking at MGLRU-FG v4, though, only [4/17]
touches this function, and it mostly adapts the workingset checks to
LRU refs. The local is still called "gen" and the table still leaves
out the reclaiming and "can't evict yet" branches, so the function
stays just as confusing after the series.

Or，Kairui, do you think this is worth cleaning up? If so, would you
mind adding a patch to MGLRU-FG to clean it up, so it doesn't
conflict with your changes?
-- 
Best regards
Ridong