| 1 |
================== |
| 2 |
Idle Page Tracking |
| 3 |
================== |
| 4 |
|
| 5 |
Motivation |
| 6 |
========== |
| 7 |
|
| 8 |
The idle page tracking feature allows to track which memory pages are being |
| 9 |
accessed by a workload and which are idle. This information can be useful for |
| 10 |
estimating the workload's working set size, which, in turn, can be taken into |
| 11 |
account when configuring the workload parameters, setting memory cgroup limits, |
| 12 |
or deciding where to place the workload within a compute cluster. |
| 13 |
|
| 14 |
It is enabled by CONFIG_IDLE_PAGE_TRACKING=y. |
| 15 |
|
| 16 |
.. _user_api: |
| 17 |
|
| 18 |
User API |
| 19 |
======== |
| 20 |
|
| 21 |
The idle page tracking API is located at ``/sys/kernel/mm/page_idle``. |
| 22 |
Currently, it consists of the only read-write file, |
| 23 |
``/sys/kernel/mm/page_idle/bitmap``. |
| 24 |
|
| 25 |
The file implements a bitmap where each bit corresponds to a memory page. The |
| 26 |
bitmap is represented by an array of 8-byte integers, and the page at PFN #i is |
| 27 |
mapped to bit #i%64 of array element #i/64, byte order is native. When a bit is |
| 28 |
set, the corresponding page is idle. |
| 29 |
|
| 30 |
A page is considered idle if it has not been accessed since it was marked idle |
| 31 |
(for more details on what "accessed" actually means see the :ref:`Implementation |
| 32 |
Details <impl_details>` section). |
| 33 |
To mark a page idle one has to set the bit corresponding to |
| 34 |
the page by writing to the file. A value written to the file is OR-ed with the |
| 35 |
current bitmap value. |
| 36 |
|
| 37 |
Only accesses to user memory pages are tracked. These are pages mapped to a |
| 38 |
process address space, page cache and buffer pages, swap cache pages. For other |
| 39 |
page types (e.g. SLAB pages) an attempt to mark a page idle is silently ignored, |
| 40 |
and hence such pages are never reported idle. |
| 41 |
|
| 42 |
For huge pages the idle flag is set only on the head page, so one has to read |
| 43 |
``/proc/kpageflags`` in order to correctly count idle huge pages. |
| 44 |
|
| 45 |
Reading from or writing to ``/sys/kernel/mm/page_idle/bitmap`` will return |
| 46 |
-EINVAL if you are not starting the read/write on an 8-byte boundary, or |
| 47 |
if the size of the read/write is not a multiple of 8 bytes. Writing to |
| 48 |
this file beyond max PFN will return -ENXIO. |
| 49 |
|
| 50 |
That said, in order to estimate the amount of pages that are not used by a |
| 51 |
workload one should: |
| 52 |
|
| 53 |
1. Mark all the workload's pages as idle by setting corresponding bits in |
| 54 |
``/sys/kernel/mm/page_idle/bitmap``. The pages can be found by reading |
| 55 |
``/proc/pid/pagemap`` if the workload is represented by a process, or by |
| 56 |
filtering out alien pages using ``/proc/kpagecgroup`` in case the workload |
| 57 |
is placed in a memory cgroup. |
| 58 |
|
| 59 |
2. Wait until the workload accesses its working set. |
| 60 |
|
| 61 |
3. Read ``/sys/kernel/mm/page_idle/bitmap`` and count the number of bits set. |
| 62 |
If one wants to ignore certain types of pages, e.g. mlocked pages since they |
| 63 |
are not reclaimable, he or she can filter them out using |
| 64 |
``/proc/kpageflags``. |
| 65 |
|
| 66 |
The page-types tool in the tools/mm directory can be used to assist in this. |
| 67 |
If the tool is run initially with the appropriate option, it will mark all the |
| 68 |
queried pages as idle. Subsequent runs of the tool can then show which pages have |
| 69 |
their idle flag cleared in the interim. |
| 70 |
|
| 71 |
See Documentation/admin-guide/mm/pagemap.rst for more information about |
| 72 |
``/proc/pid/pagemap``, ``/proc/kpageflags``, and ``/proc/kpagecgroup``. |
| 73 |
|
| 74 |
.. _impl_details: |
| 75 |
|
| 76 |
Implementation Details |
| 77 |
====================== |
| 78 |
|
| 79 |
The kernel internally keeps track of accesses to user memory pages in order to |
| 80 |
reclaim unreferenced pages first on memory shortage conditions. A page is |
| 81 |
considered referenced if it has been recently accessed via a process address |
| 82 |
space, in which case one or more PTEs it is mapped to will have the Accessed bit |
| 83 |
set, or marked accessed explicitly by the kernel (see mark_page_accessed()). The |
| 84 |
latter happens when: |
| 85 |
|
| 86 |
- a userspace process reads or writes a page using a system call (e.g. read(2) |
| 87 |
or write(2)) |
| 88 |
|
| 89 |
- a page that is used for storing filesystem buffers is read or written, |
| 90 |
because a process needs filesystem metadata stored in it (e.g. lists a |
| 91 |
directory tree) |
| 92 |
|
| 93 |
- a page is accessed by a device driver using get_user_pages() |
| 94 |
|
| 95 |
When a dirty page is written to swap or disk as a result of memory reclaim or |
| 96 |
exceeding the dirty memory limit, it is not marked referenced. |
| 97 |
|
| 98 |
The idle memory tracking feature adds a new page flag, the Idle flag. This flag |
| 99 |
is set manually, by writing to ``/sys/kernel/mm/page_idle/bitmap`` (see the |
| 100 |
:ref:`User API <user_api>` |
| 101 |
section), and cleared automatically whenever a page is referenced as defined |
| 102 |
above. |
| 103 |
|
| 104 |
When a page is marked idle, the Accessed bit must be cleared in all PTEs it is |
| 105 |
mapped to, otherwise we will not be able to detect accesses to the page coming |
| 106 |
from a process address space. To avoid interference with the reclaimer, which, |
| 107 |
as noted above, uses the Accessed bit to promote actively referenced pages, one |
| 108 |
more page flag is introduced, the Young flag. When the PTE Accessed bit is |
| 109 |
cleared as a result of setting or updating a page's Idle flag, the Young flag |
| 110 |
is set on the page. The reclaimer treats the Young flag as an extra PTE |
| 111 |
Accessed bit and therefore will consider such a page as referenced. |
| 112 |
|
| 113 |
Since the idle memory tracking feature is based on the memory reclaimer logic, |
| 114 |
it only works with pages that are on an LRU list, other pages are silently |
| 115 |
ignored. That means it will ignore a user memory page if it is isolated, but |
| 116 |
since there are usually not many of them, it should not affect the overall |
| 117 |
result noticeably. In order not to stall scanning of the idle page bitmap, |
| 118 |
locked pages may be skipped too. |