Documentation/mm/page_migration.rst

2 Page migration
5 Page migration allows moving the physical location of pages between
13 The main intent of page migration is to reduce the latency of memory accesses
17 Page migration allows a process to manually relocate the node on which its
23 Page migration functions are provided by the numactl package by Andi Kleen
26 which provides an interface similar to other NUMA functionality for page
29 proc(5) man page.
35 manual page migration support. Automatic page migration may be implemented
52 Page migration allows the preservation of the relative location of pages
58 Page migration occurs in several steps. First a high level
71    Calling isolate_lru_page() increases the references to the page
72    so that it cannot vanish while the page migration occurs.
74    the page.
87 migrate_pages() does several passes over its list of pages. A page is moved
88 if all references to a page are removable at the time. The page has
90 is increased so that the page cannot be freed while page migration occurs.
94 1. Lock the page to be migrated.
98 3. Lock the new page that we want to move to. It is locked so that accesses to
99    this (not yet up-to-date) page immediately block while the move is in progress.
101 4. All the page table references to the page are converted to migration
102    entries. This decreases the mapcount of a page. If the resulting
103    mapcount is not zero then we do not migrate the page. All user space
104    processes that attempt to access the page will now wait on the page lock
105    or wait for the migration page table entry to be removed.
108    to access the page via the mapping to block on the spinlock.
110 6. The refcount of the page is examined and we back out if references remain.
111    Otherwise, we know that we are the only one referencing this page.
114    page then we back out because someone else modified the radix tree.
116 8. The new page is prepped with some settings from the old page so that
117    accesses to the new page will discover a page with the correct settings.
119 9. The radix tree is changed to point to the new page.
121 10. The reference count of the old page is dropped because the address space
122     reference is gone. A reference to the new page is established because
123     the new page is referenced by the address space.
127     to sleeping on the locked new page.
129 12. The page contents are copied to the new page.
131 13. The remaining page flags are copied to the new page.
133 14. The old page flags are cleared to indicate that the page does
136 15. Queued up writeback on the new page is triggered.
138 16. If migration entries were inserted into the page table, then replace them
140     already waiting for the page lock.
142 17. The page locks are dropped from the old and new page.
143     Processes waiting on the page lock will redo their page faults
144     and will reach the new page.
146 18. The new page is moved to the LRU and can be scanned by the swapper,
149 Non-LRU page migration
159 page that it may be able to move.  This uses the ``page->mapping`` field,
165 The following events (counters) can be used to monitor page migration.
167 1. PGMIGRATE_SUCCESS: Normal page migration success. Each count means that a
168    page was migrated. If the page was a non-THP and non-hugetlb page, then
169    this counter is increased by one. If the page was a THP or hugetlb, then
174 2. PGMIGRATE_FAIL: Normal page migration failure. Same counting rules as for