[PATCH v2] mm/migrate_device: document folio_get requirement before frozen PMD split

[PATCH v2] mm/migrate_device: document folio_get requirement before frozen PMD split

[Usama Arif]

split_huge_pmd_address() with freeze=true splits a PMD migration entry
into PTE migration entries, consuming one folio reference in the
process.  The folio_get() before it provides this reference.

Add a comment explaining this relationship. The expected folio refcount
at the start of migrate_vma_split_unmapped_folio() is 1.

Suggested-by: Zi Yan <ziy@nvidia.com>
Reviewed-by: Zi Yan <ziy@nvidia.com>
Reviewed-by: Nico Pache <npache@redhat.com>
Signed-off-by: Usama Arif <usama.arif@linux.dev>
---
v1 -> v2:
- Remove warning if folio refcount !=1 at the start of
  migrate_vma_split_unmapped_folio() (David)
---
 mm/migrate_device.c | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/mm/migrate_device.c b/mm/migrate_device.c
index 78c7acf02461..fbfe5715f635 100644
--- a/mm/migrate_device.c
+++ b/mm/migrate_device.c
@@ -908,6 +908,10 @@ static int migrate_vma_split_unmapped_folio(struct migrate_vma *migrate,
 	unsigned long flags;
 	int ret = 0;
 
+	/*
+	 * take a reference, since split_huge_pmd_address() with freeze = true
+	 * drops a reference at the end.
+	 */
 	folio_get(folio);
 	split_huge_pmd_address(migrate->vma, addr, true);
 	ret = folio_split_unmapped(folio, 0);
-- 
2.47.3

Re: [PATCH v2] mm/migrate_device: document folio_get requirement before frozen PMD split

[David Hildenbrand (Arm)]

On 3/9/26 22:25, Usama Arif wrote:
> split_huge_pmd_address() with freeze=true splits a PMD migration entry
> into PTE migration entries, consuming one folio reference in the
> process.  The folio_get() before it provides this reference.
> 
> Add a comment explaining this relationship. The expected folio refcount
> at the start of migrate_vma_split_unmapped_folio() is 1.
> 
> Suggested-by: Zi Yan <ziy@nvidia.com>
> Reviewed-by: Zi Yan <ziy@nvidia.com>
> Reviewed-by: Nico Pache <npache@redhat.com>
> Signed-off-by: Usama Arif <usama.arif@linux.dev>
> ---
> v1 -> v2:
> - Remove warning if folio refcount !=1 at the start of
>   migrate_vma_split_unmapped_folio() (David)
> ---
>  mm/migrate_device.c | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/mm/migrate_device.c b/mm/migrate_device.c
> index 78c7acf02461..fbfe5715f635 100644
> --- a/mm/migrate_device.c
> +++ b/mm/migrate_device.c
> @@ -908,6 +908,10 @@ static int migrate_vma_split_unmapped_folio(struct migrate_vma *migrate,
>  	unsigned long flags;
>  	int ret = 0;
>  
> +	/*
> +	 * take a reference, since split_huge_pmd_address() with freeze = true
> +	 * drops a reference at the end.
> +	 */
>  	folio_get(folio);
>  	split_huge_pmd_address(migrate->vma, addr, true);
>  	ret = folio_split_unmapped(folio, 0);

Acked-by: David Hildenbrand (Arm) <david@kernel.org>

-- 
Cheers,

David

Re: [PATCH v2] mm/migrate_device: document folio_get requirement before frozen PMD split

[Wei Yang]

On Mon, Mar 09, 2026 at 02:25:02PM -0700, Usama Arif wrote:
>split_huge_pmd_address() with freeze=true splits a PMD migration entry
>into PTE migration entries, consuming one folio reference in the
>process.  The folio_get() before it provides this reference.
>
>Add a comment explaining this relationship. The expected folio refcount
>at the start of migrate_vma_split_unmapped_folio() is 1.
>
>Suggested-by: Zi Yan <ziy@nvidia.com>
>Reviewed-by: Zi Yan <ziy@nvidia.com>
>Reviewed-by: Nico Pache <npache@redhat.com>
>Signed-off-by: Usama Arif <usama.arif@linux.dev>

Reviewed-by: Wei Yang <richard.weiyang@gmail.com>

Another thing come up my mind.

>---
>v1 -> v2:
>- Remove warning if folio refcount !=1 at the start of
>  migrate_vma_split_unmapped_folio() (David)
>---
> mm/migrate_device.c | 4 ++++
> 1 file changed, 4 insertions(+)
>
>diff --git a/mm/migrate_device.c b/mm/migrate_device.c
>index 78c7acf02461..fbfe5715f635 100644
>--- a/mm/migrate_device.c
>+++ b/mm/migrate_device.c
>@@ -908,6 +908,10 @@ static int migrate_vma_split_unmapped_folio(struct migrate_vma *migrate,
> 	unsigned long flags;
> 	int ret = 0;
> 
>+	/*
>+	 * take a reference, since split_huge_pmd_address() with freeze = true
>+	 * drops a reference at the end.
>+	 */
> 	folio_get(folio);
> 	split_huge_pmd_address(migrate->vma, addr, true);
> 	ret = folio_split_unmapped(folio, 0);

This makes me think why we need an extra refcount, while other user of
split_huge_pmd_locked(@freeze = true) not.

The put_page() when @freeze = true in __split_huge_pmd_locked() is to balance
refcount for the mapping count change.  Since after freeze, the folio is
removed from one pmd mapping.

So we need an extra refcount here, as this folio is not mapped before split as
the function name indicated.

If my analysis above is correct, I am curious about the put_page() in
__split_huge_pmd_locked() now.

Currently we always drop refcount if @freeze = true. But when
pmd_is_migration_entry(), we already unmap it and drop one refcount in
set_pmd_migration_entry(). Would it be a problem to put_page() when
pmd_is_migration_entry()?

-- 
Wei Yang
Help you, Help me