docs/vm: page_migration: convert to ReST format

.. _page_migration:

==============

Page migration

--------------

==============

Page migration allows the moving of the physical location of pages between

nodes in a numa system while the process is running. This means that the

(a version later than 0.9.3 is required. Get it from

ftp://oss.sgi.com/www/projects/libnuma/download/). numactl provides libnuma

which provides an interface similar to other numa functionality for page

migration.  cat /proc/<pid>/numa_maps allows an easy review of where the

migration.  cat ``/proc/<pid>/numa_maps`` allows an easy review of where the

pages of a process are located. See also the numa_maps documentation in the

proc(5) man page.

(for userspace usage see the Andi Kleen's numactl package mentioned above)

and then a low level description of how the low level details work.

A. In kernel use of migrate_pages()

-----------------------------------

In kernel use of migrate_pages()

================================

1. Remove pages from the LRU.

   the new page for each page that is considered for

   moving.

B. How migrate_pages() works

----------------------------

How migrate_pages() works

=========================

migrate_pages() does several passes over its list of pages. A page is moved

if all references to a page are removable at the time. The page has

20. The new page is moved to the LRU and can be scanned by the swapper

    etc again.

C. Non-LRU page migration

-------------------------

Non-LRU page migration

======================

Although original migration aimed for reducing the latency of memory access

for NUMA, compaction who want to create high-order page is also main customer.

If a driver want to make own pages movable, it should define three functions

which are function pointers of struct address_space_operations.

1. bool (*isolate_page) (struct page *page, isolate_mode_t mode);

1. ``bool (*isolate_page) (struct page *page, isolate_mode_t mode);``

   What VM expects on isolate_page function of driver is to return *true*

   if driver isolates page successfully. On returing true, VM marks the page

   Once page is successfully isolated, VM uses page.lru fields so driver

   shouldn't expect to preserve values in that fields.

2. int (*migratepage) (struct address_space *mapping,

		struct page *newpage, struct page *oldpage, enum migrate_mode);

2. ``int (*migratepage) (struct address_space *mapping,``

|	``struct page *newpage, struct page *oldpage, enum migrate_mode);``

   After isolation, VM calls migratepage of driver with isolated page.

   The function of migratepage is to move content of the old page to new page

   Driver shouldn't touch page.lru field VM using in the functions.

3. void (*putback_page)(struct page *);

3. ``void (*putback_page)(struct page *);``

   If migration fails on isolated page, VM should return the isolated page

   to the driver so VM calls driver's putback_page with migration failed page.

   * PG_movable

Driver should use the below function to make page movable under page_lock.

     Driver should use the below function to make page movable under page_lock::

	void __SetPageMovable(struct page *page, struct address_space *mapping)

It needs argument of address_space for registering migration family functions

which will be called by VM. Exactly speaking, PG_movable is not a real flag of

struct page. Rather than, VM reuses page->mapping's lower bits to represent it.

     It needs argument of address_space for registering migration

     family functions which will be called by VM. Exactly speaking,

     PG_movable is not a real flag of struct page. Rather than, VM

     reuses page->mapping's lower bits to represent it.

::

	#define PAGE_MAPPING_MOVABLE 0x2

	page->mapping = page->mapping | PAGE_MAPPING_MOVABLE;