[PATCH v2 0/8] mm/migrate: separate hugetlb, movable_ops and LRU migration paths

From: Shivank Garg

Date: Thu Nov 19 2026 - 02:12:23 EST


migrate_pages() handles hugetlb folios, movable_ops pages and LRU folios,
although their locking, mapping and retry requirements differ. It already
dispatches hugetlb folios to a dedicated engine, but that engine rescans
the whole source list on every retry pass, movable_ops pages still pass
through the regular folio unmap and move machinery, and the LRU batching,
synchronous fallback and split folio retry are open-coded in
migrate_pages() itself.

This series sorts the source list by migration class once, gives each
class its own entry point, and splits the LRU batch engine into explicit
unmap, TLB flush, move and undo phases.

Thanks to Zi Yan and David Hildenbrand for the discussions and suggestions
that helped shape this series. I also used LLM tools to refine my ideas,
identify the edge-cases/bugs.

Old flow
========

migrate_pages(mode, reason)
|
+-- migrate_hugetlbs()
| `-- scan the mixed source list (from) on each retry
|
`-- split the remaining list into batches
|
+-- MIGRATE_ASYNC
| `-- migrate_pages_batch()
| inline unmap/retry -> flush -> move/retry
|
`-- MIGRATE_SYNC[_LIGHT]
`-- migrate_pages_sync()
+-- try async batch pre-pass
`-- retry failures one at a time through
migrate_pages_batch()

movable_ops pages are identified by branches inside the batch unmap and
move paths.

New flow
========

migrate_pages(mode, reason)
|
+-- sort the source list into hugetlb, movable_ops and LRU lists
|
+-- migrate_hugetlbs()
| `-- retry each hugetlb folio
|
+-- migrate_movable_ops_pages()
| `-- allocate, lock, invoke the movable_ops callback and retry
|
`-- migrate_lru_folios()
`-- form bounded LRU batches
`-- __migrate_lru_folios()
+-- async: migrate_folios_batch()
+-- sync:
| +-- async batch pre-pass
| `-- retry failures one at a time
`-- one async attempt for folios split on the way

migrate_folios_batch()
|
+-- migrate_folios_unmap()
+-- try_to_unmap_flush()
+-- migrate_folios_move()
`-- migrate_folios_undo()

migrate_pages() now only sorts and dispatches classes. Each entry point
owns its retries; the LRU entry point also owns batching, the synchronous
fallback and the split folio retry. Folios that are not migrated are still
returned through the original source list.

Motivation
==========

This refactor makes the migration control flow easier to follow and gives
new optimizations clear boundaries and insertion points.

Separating movable_ops also prepares for memdescs, where these pages are
expected to lose their folio representation and folio->lru handoff. The
current list interface remains, but its folio dependencies are now isolated.

As a side benefit, a folio's class is tested once when the source
list is sorted, instead of in every unmap, move and retry pass, and
retrying a hugetlb folio no longer rescans the whole source list.

Behavior Changes
================

No functional change is intended for the LRU and hugetlb migration paths.

The movable_ops pass has three intentional differences:

- movable_ops pages are attempted before LRU folios;
- movable_ops pages no longer use the LRU asynchronous pre-pass;
synchronous callers use their requested mode from the first attempt;
- a movable_ops callback returning -EAGAIN drops both page locks and
releases the destination, so a retry allocates a new one.

---
Changes in v2:
- Rebase onto mm-core/for-next.
- Drop the migrate_control patches, will post as a separate
series; and this series is limited to mm/migrate.c.
- migrate_pages() now sorts hugetlb folios and movable_ops pages onto
their own lists in a single pass, instead of migrate_hugetlbs() and
migrate_movable_ops_pages() each scanning the source list.
- movable_ops: count permanent failures in nr_failed_pages as they happen,
mirroring migrate_hugetlbs(); the totals are unchanged.
- Avoid the migrate_lru_folios() -> __migrate_lru_folios() rename
by introducing the per-batch function under its final name.
- Some rewording of comments and commit text.
- Link to v1: https://lore.kernel.org/r/20260902-migrate-refactor-shivank-v1-0-9dcca87669c4@xxxxxxx

---
Shivank Garg (8):
mm/migrate: extract folio unmap phase
mm/migrate: handle retries in migrate_folios_move()
mm/migrate: factor out folio splitting on allocation failure
mm/migrate: use a dedicated list for hugetlb folios
mm/migrate: add a dedicated movable_ops migration pass
mm/migrate: rename migrate_pages_batch() to migrate_folios_batch()
mm/migrate: fold the LRU batch paths into __migrate_lru_folios()
mm/migrate: add migrate_lru_folios() entry point

mm/migrate.c | 561 ++++++++++++++++++++++++++++++++++++++++-------------------
1 file changed, 378 insertions(+), 183 deletions(-)
---
base-commit: f7d95bf74091373fad7273db4557df9b5a902335
change-id: 20260824-migrate-refactor-shivank-4ee3949fcdcb

Best regards,
--
Shivank Garg <shivankg@xxxxxxx>