Commit | Line | Data |
---|---|---|
e3f2025a MR |
1 | ================== |
2 | Idle Page Tracking | |
3 | ================== | |
4 | ||
5 | Motivation | |
6 | ========== | |
33c3fc71 VD |
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 | ||
e3f2025a | 16 | .. _user_api: |
33c3fc71 | 17 | |
e3f2025a MR |
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``. | |
33c3fc71 VD |
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 | |
e3f2025a MR |
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 | |
33c3fc71 VD |
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 | |
e3f2025a | 43 | ``/proc/kpageflags`` in order to correctly count idle huge pages. |
33c3fc71 | 44 | |
e3f2025a | 45 | Reading from or writing to ``/sys/kernel/mm/page_idle/bitmap`` will return |
33c3fc71 VD |
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 | |
e3f2025a MR |
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. | |
33c3fc71 VD |
58 | |
59 | 2. Wait until the workload accesses its working set. | |
60 | ||
e3f2025a MR |
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 | ||
799fb82a | 66 | The page-types tool in the tools/mm directory can be used to assist in this. |
59ae96ff CH |
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 | ||
00cba6b6 MRI |
71 | See Documentation/admin-guide/mm/pagemap.rst for more information about |
72 | ``/proc/pid/pagemap``, ``/proc/kpageflags``, and ``/proc/kpagecgroup``. | |
33c3fc71 | 73 | |
e3f2025a | 74 | .. _impl_details: |
33c3fc71 | 75 | |
e3f2025a MR |
76 | Implementation Details |
77 | ====================== | |
33c3fc71 VD |
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 | |
e3f2025a MR |
99 | is set manually, by writing to ``/sys/kernel/mm/page_idle/bitmap`` (see the |
100 | :ref:`User API <user_api>` | |
33c3fc71 VD |
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. |