Commit | Line | Data |
---|---|---|
7701c9c0 HD |
1 | How to use the Kernel Samepage Merging feature |
2 | ---------------------------------------------- | |
3 | ||
4 | KSM is a memory-saving de-duplication feature, enabled by CONFIG_KSM=y, | |
5 | added to the Linux kernel in 2.6.32. See mm/ksm.c for its implementation, | |
6 | and http://lwn.net/Articles/306704/ and http://lwn.net/Articles/330589/ | |
7 | ||
8 | The KSM daemon ksmd periodically scans those areas of user memory which | |
9 | have been registered with it, looking for pages of identical content which | |
10 | can be replaced by a single write-protected page (which is automatically | |
11 | copied if a process later wants to update its content). | |
12 | ||
13 | KSM was originally developed for use with KVM (where it was known as | |
14 | Kernel Shared Memory), to fit more virtual machines into physical memory, | |
15 | by sharing the data common between them. But it can be useful to any | |
16 | application which generates many instances of the same data. | |
17 | ||
18 | KSM only merges anonymous (private) pages, never pagecache (file) pages. | |
d0f209f6 HD |
19 | KSM's merged pages were originally locked into kernel memory, but can now |
20 | be swapped out just like other user pages (but sharing is broken when they | |
21 | are swapped back in: ksmd must rediscover their identity and merge again). | |
7701c9c0 HD |
22 | |
23 | KSM only operates on those areas of address space which an application | |
24 | has advised to be likely candidates for merging, by using the madvise(2) | |
25 | system call: int madvise(addr, length, MADV_MERGEABLE). | |
26 | ||
27 | The app may call int madvise(addr, length, MADV_UNMERGEABLE) to cancel | |
28 | that advice and restore unshared pages: whereupon KSM unmerges whatever | |
29 | it merged in that range. Note: this unmerging call may suddenly require | |
30 | more memory than is available - possibly failing with EAGAIN, but more | |
31 | probably arousing the Out-Of-Memory killer. | |
32 | ||
33 | If KSM is not configured into the running kernel, madvise MADV_MERGEABLE | |
34 | and MADV_UNMERGEABLE simply fail with EINVAL. If the running kernel was | |
35 | built with CONFIG_KSM=y, those calls will normally succeed: even if the | |
36 | the KSM daemon is not currently running, MADV_MERGEABLE still registers | |
37 | the range for whenever the KSM daemon is started; even if the range | |
38 | cannot contain any pages which KSM could actually merge; even if | |
39 | MADV_UNMERGEABLE is applied to a range which was never MADV_MERGEABLE. | |
40 | ||
def5efe0 DR |
41 | If a region of memory must be split into at least one new MADV_MERGEABLE |
42 | or MADV_UNMERGEABLE region, the madvise may return ENOMEM if the process | |
43 | will exceed vm.max_map_count (see Documentation/sysctl/vm.txt). | |
44 | ||
7701c9c0 HD |
45 | Like other madvise calls, they are intended for use on mapped areas of |
46 | the user address space: they will report ENOMEM if the specified range | |
47 | includes unmapped gaps (though working on the intervening mapped areas), | |
48 | and might fail with EAGAIN if not enough memory for internal structures. | |
49 | ||
50 | Applications should be considerate in their use of MADV_MERGEABLE, | |
d0f209f6 HD |
51 | restricting its use to areas likely to benefit. KSM's scans may use a lot |
52 | of processing power: some installations will disable KSM for that reason. | |
7701c9c0 HD |
53 | |
54 | The KSM daemon is controlled by sysfs files in /sys/kernel/mm/ksm/, | |
55 | readable by all but writable only by root: | |
56 | ||
7701c9c0 | 57 | pages_to_scan - how many present pages to scan before ksmd goes to sleep |
c73602ad HD |
58 | e.g. "echo 100 > /sys/kernel/mm/ksm/pages_to_scan" |
59 | Default: 100 (chosen for demonstration purposes) | |
7701c9c0 HD |
60 | |
61 | sleep_millisecs - how many milliseconds ksmd should sleep before next scan | |
62 | e.g. "echo 20 > /sys/kernel/mm/ksm/sleep_millisecs" | |
63 | Default: 20 (chosen for demonstration purposes) | |
64 | ||
90bd6fd3 PH |
65 | merge_across_nodes - specifies if pages from different numa nodes can be merged. |
66 | When set to 0, ksm merges only pages which physically | |
8fdb3dbf HD |
67 | reside in the memory area of same NUMA node. That brings |
68 | lower latency to access of shared pages. Systems with more | |
69 | nodes, at significant NUMA distances, are likely to benefit | |
70 | from the lower latency of setting 0. Smaller systems, which | |
71 | need to minimize memory usage, are likely to benefit from | |
72 | the greater sharing of setting 1 (default). You may wish to | |
73 | compare how your system performs under each setting, before | |
74 | deciding on which to use. merge_across_nodes setting can be | |
75 | changed only when there are no ksm shared pages in system: | |
76 | set run 2 to unmerge pages first, then to 1 after changing | |
77 | merge_across_nodes, to remerge according to the new setting. | |
78 | Default: 1 (merging across nodes as in earlier releases) | |
90bd6fd3 | 79 | |
7701c9c0 HD |
80 | run - set 0 to stop ksmd from running but keep merged pages, |
81 | set 1 to run ksmd e.g. "echo 1 > /sys/kernel/mm/ksm/run", | |
82 | set 2 to stop ksmd and unmerge all pages currently merged, | |
83 | but leave mergeable areas registered for next run | |
c73602ad HD |
84 | Default: 0 (must be changed to 1 to activate KSM, |
85 | except if CONFIG_SYSFS is disabled) | |
7701c9c0 | 86 | |
e86c59b1 CI |
87 | use_zero_pages - specifies whether empty pages (i.e. allocated pages |
88 | that only contain zeroes) should be treated specially. | |
89 | When set to 1, empty pages are merged with the kernel | |
90 | zero page(s) instead of with each other as it would | |
91 | happen normally. This can improve the performance on | |
92 | architectures with coloured zero pages, depending on | |
93 | the workload. Care should be taken when enabling this | |
94 | setting, as it can potentially degrade the performance | |
95 | of KSM for some workloads, for example if the checksums | |
96 | of pages candidate for merging match the checksum of | |
97 | an empty page. This setting can be changed at any time, | |
98 | it is only effective for pages merged after the change. | |
99 | Default: 0 (normal KSM behaviour as in earlier releases) | |
100 | ||
2c653d0e AA |
101 | max_page_sharing - Maximum sharing allowed for each KSM page. This |
102 | enforces a deduplication limit to avoid the virtual | |
103 | memory rmap lists to grow too large. The minimum | |
104 | value is 2 as a newly created KSM page will have at | |
105 | least two sharers. The rmap walk has O(N) | |
106 | complexity where N is the number of rmap_items | |
107 | (i.e. virtual mappings) that are sharing the page, | |
108 | which is in turn capped by max_page_sharing. So | |
109 | this effectively spread the the linear O(N) | |
110 | computational complexity from rmap walk context | |
111 | over different KSM pages. The ksmd walk over the | |
112 | stable_node "chains" is also O(N), but N is the | |
113 | number of stable_node "dups", not the number of | |
114 | rmap_items, so it has not a significant impact on | |
115 | ksmd performance. In practice the best stable_node | |
116 | "dup" candidate will be kept and found at the head | |
117 | of the "dups" list. The higher this value the | |
118 | faster KSM will merge the memory (because there | |
119 | will be fewer stable_node dups queued into the | |
120 | stable_node chain->hlist to check for pruning) and | |
121 | the higher the deduplication factor will be, but | |
122 | the slowest the worst case rmap walk could be for | |
123 | any given KSM page. Slowing down the rmap_walk | |
124 | means there will be higher latency for certain | |
125 | virtual memory operations happening during | |
126 | swapping, compaction, NUMA balancing and page | |
127 | migration, in turn decreasing responsiveness for | |
128 | the caller of those virtual memory operations. The | |
129 | scheduler latency of other tasks not involved with | |
130 | the VM operations doing the rmap walk is not | |
131 | affected by this parameter as the rmap walks are | |
132 | always schedule friendly themselves. | |
133 | ||
134 | stable_node_chains_prune_millisecs - How frequently to walk the whole | |
135 | list of stable_node "dups" linked in the | |
136 | stable_node "chains" in order to prune stale | |
137 | stable_nodes. Smaller milllisecs values will free | |
138 | up the KSM metadata with lower latency, but they | |
139 | will make ksmd use more CPU during the scan. This | |
140 | only applies to the stable_node chains so it's a | |
141 | noop if not a single KSM page hit the | |
142 | max_page_sharing yet (there would be no stable_node | |
143 | chains in such case). | |
144 | ||
7701c9c0 HD |
145 | The effectiveness of KSM and MADV_MERGEABLE is shown in /sys/kernel/mm/ksm/: |
146 | ||
d0f209f6 | 147 | pages_shared - how many shared pages are being used |
7701c9c0 HD |
148 | pages_sharing - how many more sites are sharing them i.e. how much saved |
149 | pages_unshared - how many pages unique but repeatedly checked for merging | |
150 | pages_volatile - how many pages changing too fast to be placed in a tree | |
151 | full_scans - how many times all mergeable areas have been scanned | |
152 | ||
2c653d0e AA |
153 | stable_node_chains - number of stable node chains allocated, this is |
154 | effectively the number of KSM pages that hit the | |
155 | max_page_sharing limit | |
156 | stable_node_dups - number of stable node dups queued into the | |
157 | stable_node chains | |
158 | ||
7701c9c0 HD |
159 | A high ratio of pages_sharing to pages_shared indicates good sharing, but |
160 | a high ratio of pages_unshared to pages_sharing indicates wasted effort. | |
161 | pages_volatile embraces several different kinds of activity, but a high | |
162 | proportion there would also indicate poor use of madvise MADV_MERGEABLE. | |
163 | ||
2c653d0e AA |
164 | The maximum possible page_sharing/page_shared ratio is limited by the |
165 | max_page_sharing tunable. To increase the ratio max_page_sharing must | |
166 | be increased accordingly. | |
167 | ||
168 | The stable_node_dups/stable_node_chains ratio is also affected by the | |
169 | max_page_sharing tunable, and an high ratio may indicate fragmentation | |
170 | in the stable_node dups, which could be solved by introducing | |
171 | fragmentation algorithms in ksmd which would refile rmap_items from | |
172 | one stable_node dup to another stable_node dup, in order to freeup | |
173 | stable_node "dups" with few rmap_items in them, but that may increase | |
174 | the ksmd CPU usage and possibly slowdown the readonly computations on | |
175 | the KSM pages of the applications. | |
176 | ||
7701c9c0 | 177 | Izik Eidus, |
d0f209f6 | 178 | Hugh Dickins, 17 Nov 2009 |