1 files changed, 43 insertions, 71 deletions
diff --git a/Documentation/vm/page_migration b/Documentation/vm/page_migration
index 0dd4ef30c361..99f89aa10169 100644
--- a/Documentation/vm/page_migration
+++ b/Documentation/vm/page_migration
@@ -26,8 +26,13 @@ a process are located. See also the numa_maps manpage in the numactl package.
 Manual migration is useful if for example the scheduler has relocated
 a process to a processor on a distant node. A batch scheduler or an
 administrator may detect the situation and move the pages of the process
-nearer to the new processor. At some point in the future we may have
+nearer to the new processor. The kernel itself does only provide
-some mechanism in the scheduler that will automatically move the pages.
+manual page migration support. Automatic page migration may be implemented
+through user space processes that move pages. A special function call
+"move_pages" allows the moving of individual pages within a process.
+A NUMA profiler may f.e. obtain a log showing frequent off node
+accesses and may use the result to move pages to more advantageous
+locations.
 Larger installations usually partition the system using cpusets into
 sections of nodes. Paul Jackson has equipped cpusets with the ability to
@@ -62,22 +67,14 @@ A. In kernel use of migrate_pages()
   It also prevents the swapper or other scans to encounter
   the page.
-2. Generate a list of newly allocates page. These pages will contain the
+2. We need to have a function of type new_page_t that can be
-   contents of the pages from the first list after page migration is
+   passed to migrate_pages(). This function should figure out
-   complete.
+   how to allocate the correct new page given the old page.
 3. The migrate_pages() function is called which attempts
-   to do the migration. It returns the moved pages in the
+   to do the migration. It will call the function to allocate
-   list specified as the third parameter and the failed
+   the new page for each page that is considered for
-   migrations in the fourth parameter. The first parameter
+   moving.
-   will contain the pages that could still be retried.
-4. The leftover pages of various types are returned
-   to the LRU using putback_to_lru_pages() or otherwise
-   disposed of. The pages will still have the refcount as
-   increased by isolate_lru_pages() if putback_to_lru_pages() is not
-   used! The kernel may want to handle the various cases of failures in
-   different ways.
 B. How migrate_pages() works
 ----------------------------
@@ -93,83 +90,58 @@ Steps:
 2. Insure that writeback is complete.
-3. Make sure that the page has assigned swap cache entry if
+3. Prep the new page that we want to move to. It is locked
-   it is an anonyous page. The swap cache reference is necessary
-   to preserve the information contain in the page table maps while
-   page migration occurs.
-4. Prep the new page that we want to move to. It is locked
   and set to not being uptodate so that all accesses to the new
   page immediately lock while the move is in progress.
-5. All the page table references to the page are either dropped (file
+4. The new page is prepped with some settings from the old page so that
-   backed pages) or converted to swap references (anonymous pages).
+   accesses to the new page will discover a page with the correct settings.
-   This should decrease the reference count.
+5. All the page table references to the page are converted
+   to migration entries or dropped (nonlinear vmas).
+   This decrease the mapcount of a page. If the resulting
+   mapcount is not zero then we do not migrate the page.
+   All user space processes that attempt to access the page
+   will now wait on the page lock.
 6. The radix tree lock is taken. This will cause all processes trying
-   to reestablish a pte to block on the radix tree spinlock.
+   to access the page via the mapping to block on the radix tree spinlock.
 7. The refcount of the page is examined and we back out if references remain
   otherwise we know that we are the only one referencing this page.
 8. The radix tree is checked and if it does not contain the pointer to this
-   page then we back out because someone else modified the mapping first.
+   page then we back out because someone else modified the radix tree.
-9. The mapping is checked. If the mapping is gone then a truncate action may
-   be in progress and we back out.
-10. The new page is prepped with some settings from the old page so that
-   accesses to the new page will be discovered to have the correct settings.
-11. The radix tree is changed to point to the new page.
+9. The radix tree is changed to point to the new page.
-12. The reference count of the old page is dropped because the radix tree
+10. The reference count of the old page is dropped because the radix tree
-    reference is gone.
+    reference is gone. A reference to the new page is established because
+    the new page is referenced to by the radix tree.
-13. The radix tree lock is dropped. With that lookups become possible again
+11. The radix tree lock is dropped. With that lookups in the mapping
-    and other processes will move from spinning on the tree lock to sleeping on
+    become possible again. Processes will move from spinning on the tree_lock
-    the locked new page.
+    to sleeping on the locked new page.
-14. The page contents are copied to the new page.
+12. The page contents are copied to the new page.
-15. The remaining page flags are copied to the new page.
+13. The remaining page flags are copied to the new page.
-16. The old page flags are cleared to indicate that the page does
+14. The old page flags are cleared to indicate that the page does
-    not use any information anymore.
+    not provide any information anymore.
-17. Queued up writeback on the new page is triggered.
+15. Queued up writeback on the new page is triggered.
-18. If swap pte's were generated for the page then replace them with real
+16. If migration entries were page then replace them with real ptes. Doing
-    ptes. This will reenable access for processes not blocked by the page lock.
+    so will enable access for user space processes not already waiting for
+    the page lock.
 19. The page locks are dropped from the old and new page.
-    Processes waiting on the page lock can continue.
+    Processes waiting on the page lock will redo their page faults
+    and will reach the new page.
 20. The new page is moved to the LRU and can be scanned by the swapper
    etc again.
-TODO list
+Christoph Lameter, May 8, 2006.
---------
- Page migration requires the use of swap handles to preserve the
-  information of the anonymous page table entries. This means that swap
-  space is reserved but never used. The maximum number of swap handles used
-  is determined by CHUNK_SIZE (see mm/mempolicy.c) per ongoing migration.
-  Reservation of pages could be avoided by having a special type of swap
-  handle that does not require swap space and that would only track the page
-  references. Something like that was proposed by Marcelo Tosatti in the
-  past (search for migration cache on lkml or linux-mm@kvack.org).
- Page migration unmaps ptes for file backed pages and requires page
-  faults to reestablish these ptes. This could be optimized by somehow
-  recording the references before migration and then reestablish them later.
-  However, there are several locking challenges that have to be overcome
-  before this is possible.
- Page migration generates read ptes for anonymous pages. Dirty page
-  faults are required to make the pages writable again. It may be possible
-  to generate a pte marked dirty if it is known that the page is dirty and
-  that this process has the only reference to that page.
-Christoph Lameter, March 8, 2006.

diff --git a/Documentation/vm/page_migration b/Documentation/vm/page_migration index 0dd4ef30c361..99f89aa10169 100644 --- a/Documentation/vm/page_migration +++ b/Documentation/vm/page_migration
@@ -26,8 +26,13 @@ a process are located. See also the numa_maps manpage in the numactl package.
26	Manual migration is useful if for example the scheduler has relocated	26	Manual migration is useful if for example the scheduler has relocated
27	a process to a processor on a distant node. A batch scheduler or an	27	a process to a processor on a distant node. A batch scheduler or an
28	administrator may detect the situation and move the pages of the process	28	administrator may detect the situation and move the pages of the process
29	nearer to the new processor. At some point in the future we may have	29	nearer to the new processor. The kernel itself does only provide
30	some mechanism in the scheduler that will automatically move the pages.	30	manual page migration support. Automatic page migration may be implemented
		31	through user space processes that move pages. A special function call
		32	"move_pages" allows the moving of individual pages within a process.
		33	A NUMA profiler may f.e. obtain a log showing frequent off node
		34	accesses and may use the result to move pages to more advantageous
		35	locations.
31		36
32	Larger installations usually partition the system using cpusets into	37	Larger installations usually partition the system using cpusets into
33	sections of nodes. Paul Jackson has equipped cpusets with the ability to	38	sections of nodes. Paul Jackson has equipped cpusets with the ability to
@@ -62,22 +67,14 @@ A. In kernel use of migrate_pages()
62	It also prevents the swapper or other scans to encounter	67	It also prevents the swapper or other scans to encounter
63	the page.	68	the page.
64		69
65	2. Generate a list of newly allocates page. These pages will contain the	70	2. We need to have a function of type new_page_t that can be
66	contents of the pages from the first list after page migration is	71	passed to migrate_pages(). This function should figure out
67	complete.	72	how to allocate the correct new page given the old page.
68		73
69	3. The migrate_pages() function is called which attempts	74	3. The migrate_pages() function is called which attempts
70	to do the migration. It returns the moved pages in the	75	to do the migration. It will call the function to allocate
71	list specified as the third parameter and the failed	76	the new page for each page that is considered for
72	migrations in the fourth parameter. The first parameter	77	moving.
73	will contain the pages that could still be retried.
74
75	4. The leftover pages of various types are returned
76	to the LRU using putback_to_lru_pages() or otherwise
77	disposed of. The pages will still have the refcount as
78	increased by isolate_lru_pages() if putback_to_lru_pages() is not
79	used! The kernel may want to handle the various cases of failures in
80	different ways.
81		78
82	B. How migrate_pages() works	79	B. How migrate_pages() works
83	----------------------------	80	----------------------------
@@ -93,83 +90,58 @@ Steps:
93		90
94	2. Insure that writeback is complete.	91	2. Insure that writeback is complete.
95		92
96	3. Make sure that the page has assigned swap cache entry if	93	3. Prep the new page that we want to move to. It is locked
97	it is an anonyous page. The swap cache reference is necessary
98	to preserve the information contain in the page table maps while
99	page migration occurs.
100
101	4. Prep the new page that we want to move to. It is locked
102	and set to not being uptodate so that all accesses to the new	94	and set to not being uptodate so that all accesses to the new
103	page immediately lock while the move is in progress.	95	page immediately lock while the move is in progress.
104		96
105	5. All the page table references to the page are either dropped (file	97	4. The new page is prepped with some settings from the old page so that
106	backed pages) or converted to swap references (anonymous pages).	98	accesses to the new page will discover a page with the correct settings.
107	This should decrease the reference count.	99
		100	5. All the page table references to the page are converted
		101	to migration entries or dropped (nonlinear vmas).
		102	This decrease the mapcount of a page. If the resulting
		103	mapcount is not zero then we do not migrate the page.
		104	All user space processes that attempt to access the page
		105	will now wait on the page lock.
108		106
109	6. The radix tree lock is taken. This will cause all processes trying	107	6. The radix tree lock is taken. This will cause all processes trying
110	to reestablish a pte to block on the radix tree spinlock.	108	to access the page via the mapping to block on the radix tree spinlock.
111		109
112	7. The refcount of the page is examined and we back out if references remain	110	7. The refcount of the page is examined and we back out if references remain
113	otherwise we know that we are the only one referencing this page.	111	otherwise we know that we are the only one referencing this page.
114		112
115	8. The radix tree is checked and if it does not contain the pointer to this	113	8. The radix tree is checked and if it does not contain the pointer to this
116	page then we back out because someone else modified the mapping first.	114	page then we back out because someone else modified the radix tree.
117
118	9. The mapping is checked. If the mapping is gone then a truncate action may
119	be in progress and we back out.
120
121	10. The new page is prepped with some settings from the old page so that
122	accesses to the new page will be discovered to have the correct settings.
123		115
124	11. The radix tree is changed to point to the new page.	116	9. The radix tree is changed to point to the new page.
125		117
126	12. The reference count of the old page is dropped because the radix tree	118	10. The reference count of the old page is dropped because the radix tree
127	reference is gone.	119	reference is gone. A reference to the new page is established because
		120	the new page is referenced to by the radix tree.
128		121
129	13. The radix tree lock is dropped. With that lookups become possible again	122	11. The radix tree lock is dropped. With that lookups in the mapping
130	and other processes will move from spinning on the tree lock to sleeping on	123	become possible again. Processes will move from spinning on the tree_lock
131	the locked new page.	124	to sleeping on the locked new page.
132		125
133	14. The page contents are copied to the new page.	126	12. The page contents are copied to the new page.
134		127
135	15. The remaining page flags are copied to the new page.	128	13. The remaining page flags are copied to the new page.
136		129
137	16. The old page flags are cleared to indicate that the page does	130	14. The old page flags are cleared to indicate that the page does
138	not use any information anymore.	131	not provide any information anymore.
139		132
140	17. Queued up writeback on the new page is triggered.	133	15. Queued up writeback on the new page is triggered.
141		134
142	18. If swap pte's were generated for the page then replace them with real	135	16. If migration entries were page then replace them with real ptes. Doing
143	ptes. This will reenable access for processes not blocked by the page lock.	136	so will enable access for user space processes not already waiting for
		137	the page lock.
144		138
145	19. The page locks are dropped from the old and new page.	139	19. The page locks are dropped from the old and new page.
146	Processes waiting on the page lock can continue.	140	Processes waiting on the page lock will redo their page faults
		141	and will reach the new page.
147		142
148	20. The new page is moved to the LRU and can be scanned by the swapper	143	20. The new page is moved to the LRU and can be scanned by the swapper
149	etc again.	144	etc again.
150		145
151	TODO list	146	Christoph Lameter, May 8, 2006.
152	---------
153
154	- Page migration requires the use of swap handles to preserve the
155	information of the anonymous page table entries. This means that swap
156	space is reserved but never used. The maximum number of swap handles used
157	is determined by CHUNK_SIZE (see mm/mempolicy.c) per ongoing migration.
158	Reservation of pages could be avoided by having a special type of swap
159	handle that does not require swap space and that would only track the page
160	references. Something like that was proposed by Marcelo Tosatti in the
161	past (search for migration cache on lkml or linux-mm@kvack.org).
162
163	- Page migration unmaps ptes for file backed pages and requires page
164	faults to reestablish these ptes. This could be optimized by somehow
165	recording the references before migration and then reestablish them later.
166	However, there are several locking challenges that have to be overcome
167	before this is possible.
168
169	- Page migration generates read ptes for anonymous pages. Dirty page
170	faults are required to make the pages writable again. It may be possible
171	to generate a pte marked dirty if it is known that the page is dirty and
172	that this process has the only reference to that page.
173
174	Christoph Lameter, March 8, 2006.
175		147