migrate_vma_setup(9)

📦 version 7.3.1, in nixpkgs unstable

🌸 NAME 🌸

Hey bestie 💖 welcome to the migrate_vma_setup(9) page from the Kernel API Manual — this one is all about getting ready to migrate a range of memory. It’s giving “prep era,” no cap.

migrate_vma_setup — prepare to migrate a range of memory.

🌈 SYNOPSIS 🌈

int migrate_vma_setup (struct migrate_vma *args );

💅 ARGUMENTS 💅

  • args — contains the vma, start, and pfns arrays for the migration. The whole setup vibe lives here.

🎀 RETURN 🎀

Negative errno on failures, and 0 when 0 or more pages were migrated without an error. Periodt.

🦋 DESCRIPTION 🦋

okay so migrate_vma_setup() is the prep step for migrating a memory virtual address range ✨ It collects all the pages backing each virtual address in the range and saves them inside the src array. Then it locks those pages and unmaps them. Once the pages are locked and unmapped, it checks whether each page is pinned or not. Pages that aren’t pinned have the MIGRATE_PFN_MIGRATE flag set (by this function) in the corresponding src array entry. Then it restores any pages that are pinned, by remapping and unlocking those pages. Iconic behavior, honestly.

The caller should then allocate destination memory and copy source memory to it for all those entries (ie with MIGRATE_PFN_VALID and MIGRATE_PFN_MIGRATE flag set). Once these are allocated and copied, the caller must update each corresponding entry in the dst array with the pfn value of the destination page and with MIGRATE_PFN_VALID. Destination pages must be locked via lock_page. Don’t forget the lock, bestie 💅

Note that the caller does not have to migrate all the pages that are marked with MIGRATE_PFN_MIGRATE flag in src array unless this is a migration from device memory to system memory.

🚨 If the caller cannot migrate a device page back to system memory, then it must return VM_FAULT_SIGBUS, which has severe consequences for the userspace process, so it must be avoided if at all possible. Like, seriously — avoid it if you can 😭

For empty entries inside CPU page table (pte_none or pmd_none is true) we do set MIGRATE_PFN_MIGRATE flag inside the corresponding source array, thus allowing the caller to allocate device memory for those unbacked virtual addresses. For this the caller simply has to allocate device memory and properly set the destination entry like for regular migration. Note that this can still fail, and thus inside the device driver you must check if the migration was successful for those entries after calling migrate_vma_pages, just like for regular migration.

After that, the callers must call migrate_vma_pages to go over each entry in the src array that has the MIGRATE_PFN_VALID and MIGRATE_PFN_MIGRATE flag set. If the corresponding entry in dst array has MIGRATE_PFN_VALID flag set, then migrate_vma_pages migrates the struct page information from the source struct page to the destination struct page. If it fails to migrate the struct page information, then it clears the MIGRATE_PFN_MIGRATE flag in the src array.

At this point all successfully migrated pages have an entry in the src array with MIGRATE_PFN_VALID and MIGRATE_PFN_MIGRATE flag set and the dst array entry with MIGRATE_PFN_VALID flag set. Slay 💖

Once migrate_vma_pages returns the caller may inspect which pages were successfully migrated, and which were not. Successfully migrated pages will have the MIGRATE_PFN_MIGRATE flag set for their src array entry. Vibe check complete 🔥

It is safe to update device page table after migrate_vma_pages because both destination and source page are still locked, and the mmap_lock is held in read mode (hence no one can unmap the range being migrated). Lowkey elegant.

Once the caller is done cleaning up things and updating its page table (if it chose to do so, this is not an obligation) it finally calls migrate_vma_finalize to update the CPU page table to point to new pages for successfully migrated pages or otherwise restore the CPU page table to point to the original source pages.

🔥 SEE ALSO 🔥

Kernel file ./mm/migrate_device.c and the whole crew:

with love from source/version ./mm, dated October 2026 💖🦋✨

📦 where this page comes from