]>
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. | |
19 | KSM's merged pages are at present locked into kernel memory for as long | |
20 | as they are shared: so cannot be swapped out like the user pages they | |
21 | replace (but swapping KSM pages should follow soon in a later release). | |
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 | ||
41 | Like other madvise calls, they are intended for use on mapped areas of | |
42 | the user address space: they will report ENOMEM if the specified range | |
43 | includes unmapped gaps (though working on the intervening mapped areas), | |
44 | and might fail with EAGAIN if not enough memory for internal structures. | |
45 | ||
46 | Applications should be considerate in their use of MADV_MERGEABLE, | |
47 | restricting its use to areas likely to benefit. KSM's scans may use | |
48 | a lot of processing power, and its kernel-resident pages are a limited | |
49 | resource. Some installations will disable KSM for these reasons. | |
50 | ||
51 | The KSM daemon is controlled by sysfs files in /sys/kernel/mm/ksm/, | |
52 | readable by all but writable only by root: | |
53 | ||
54 | max_kernel_pages - set to maximum number of kernel pages that KSM may use | |
c73602ad | 55 | e.g. "echo 100000 > /sys/kernel/mm/ksm/max_kernel_pages" |
7701c9c0 HD |
56 | Value 0 imposes no limit on the kernel pages KSM may use; |
57 | but note that any process using MADV_MERGEABLE can cause | |
58 | KSM to allocate these pages, unswappable until it exits. | |
c73602ad | 59 | Default: quarter of memory (chosen to not pin too much) |
7701c9c0 HD |
60 | |
61 | pages_to_scan - how many present pages to scan before ksmd goes to sleep | |
c73602ad HD |
62 | e.g. "echo 100 > /sys/kernel/mm/ksm/pages_to_scan" |
63 | Default: 100 (chosen for demonstration purposes) | |
7701c9c0 HD |
64 | |
65 | sleep_millisecs - how many milliseconds ksmd should sleep before next scan | |
66 | e.g. "echo 20 > /sys/kernel/mm/ksm/sleep_millisecs" | |
67 | Default: 20 (chosen for demonstration purposes) | |
68 | ||
69 | run - set 0 to stop ksmd from running but keep merged pages, | |
70 | set 1 to run ksmd e.g. "echo 1 > /sys/kernel/mm/ksm/run", | |
71 | set 2 to stop ksmd and unmerge all pages currently merged, | |
72 | but leave mergeable areas registered for next run | |
c73602ad HD |
73 | Default: 0 (must be changed to 1 to activate KSM, |
74 | except if CONFIG_SYSFS is disabled) | |
7701c9c0 HD |
75 | |
76 | The effectiveness of KSM and MADV_MERGEABLE is shown in /sys/kernel/mm/ksm/: | |
77 | ||
78 | pages_shared - how many shared unswappable kernel pages KSM is using | |
79 | pages_sharing - how many more sites are sharing them i.e. how much saved | |
80 | pages_unshared - how many pages unique but repeatedly checked for merging | |
81 | pages_volatile - how many pages changing too fast to be placed in a tree | |
82 | full_scans - how many times all mergeable areas have been scanned | |
83 | ||
84 | A high ratio of pages_sharing to pages_shared indicates good sharing, but | |
85 | a high ratio of pages_unshared to pages_sharing indicates wasted effort. | |
86 | pages_volatile embraces several different kinds of activity, but a high | |
87 | proportion there would also indicate poor use of madvise MADV_MERGEABLE. | |
88 | ||
89 | Izik Eidus, | |
c73602ad | 90 | Hugh Dickins, 24 Sept 2009 |