blob: 06eb6d957c83097b85fd15e87e94b8ed7edfe1cf [file] [log] [blame]
Balbir Singh00f0b822008-03-04 14:28:39 -08001Memory Resource Controller
2
Jörg Sommer67de0162011-06-15 13:00:47 -07003NOTE: The Memory Resource Controller has generically been referred to as the
4 memory controller in this document. Do not confuse memory controller
5 used here with the memory controller that is used in hardware.
Balbir Singh1b6df3a2008-02-07 00:13:46 -08006
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -07007(For editors)
8In this document:
9 When we mention a cgroup (cgroupfs's directory) with memory controller,
10 we call it "memory cgroup". When you see git-log and source code, you'll
11 see patch's title and function names tend to use "memcg".
12 In this document, we avoid using it.
Balbir Singh1b6df3a2008-02-07 00:13:46 -080013
Balbir Singh1b6df3a2008-02-07 00:13:46 -080014Benefits and Purpose of the memory controller
15
16The memory controller isolates the memory behaviour of a group of tasks
17from the rest of the system. The article on LWN [12] mentions some probable
18uses of the memory controller. The memory controller can be used to
19
20a. Isolate an application or a group of applications
21 Memory hungry applications can be isolated and limited to a smaller
22 amount of memory.
23b. Create a cgroup with limited amount of memory, this can be used
24 as a good alternative to booting with mem=XXXX.
25c. Virtualization solutions can control the amount of memory they want
26 to assign to a virtual machine instance.
27d. A CD/DVD burner could control the amount of memory used by the
28 rest of the system to ensure that burning does not fail due to lack
29 of available memory.
30e. There are several other use cases, find one or use the controller just
31 for fun (to learn and hack on the VM subsystem).
32
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -070033Current Status: linux-2.6.34-mmotm(development version of 2010/April)
34
35Features:
36 - accounting anonymous pages, file caches, swap caches usage and limiting them.
37 - private LRU and reclaim routine. (system's global LRU and private LRU
38 work independently from each other)
39 - optionally, memory+swap usage can be accounted and limited.
40 - hierarchical accounting
41 - soft limit
42 - moving(recharging) account at moving a task is selectable.
43 - usage threshold notifier
44 - oom-killer disable knob and oom-notifier
45 - Root cgroup has no limit controls.
46
47 Kernel memory and Hugepages are not under control yet. We just manage
48 pages on LRU. To add more controls, we have to take care of performance.
49
50Brief summary of control files.
51
52 tasks # attach a task(thread) and show list of threads
53 cgroup.procs # show list of processes
54 cgroup.event_control # an interface for event_fd()
Daisuke Nishimuraa111c962011-04-27 15:26:48 -070055 memory.usage_in_bytes # show current res_counter usage for memory
56 (See 5.5 for details)
57 memory.memsw.usage_in_bytes # show current res_counter usage for memory+Swap
58 (See 5.5 for details)
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -070059 memory.limit_in_bytes # set/show limit of memory usage
60 memory.memsw.limit_in_bytes # set/show limit of memory+Swap usage
61 memory.failcnt # show the number of memory usage hits limits
62 memory.memsw.failcnt # show the number of memory+Swap hits limits
63 memory.max_usage_in_bytes # show max memory usage recorded
64 memory.memsw.usage_in_bytes # show max memory+Swap usage recorded
65 memory.soft_limit_in_bytes # set/show soft limit of memory usage
66 memory.stat # show various statistics
67 memory.use_hierarchy # set/show hierarchical account enabled
68 memory.force_empty # trigger forced move charge to parent
69 memory.swappiness # set/show swappiness parameter of vmscan
70 (See sysctl's vm.swappiness)
71 memory.move_charge_at_immigrate # set/show controls of moving charges
72 memory.oom_control # set/show oom controls.
Ying Han50c35e52011-06-15 15:08:16 -070073 memory.numa_stat # show the number of memory usage per numa node
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -070074
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800751. History
76
77The memory controller has a long history. A request for comments for the memory
78controller was posted by Balbir Singh [1]. At the time the RFC was posted
79there were several implementations for memory control. The goal of the
80RFC was to build consensus and agreement for the minimal features required
81for memory control. The first RSS controller was posted by Balbir Singh[2]
82in Feb 2007. Pavel Emelianov [3][4][5] has since posted three versions of the
83RSS controller. At OLS, at the resource management BoF, everyone suggested
84that we handle both page cache and RSS together. Another request was raised
85to allow user space handling of OOM. The current memory controller is
86at version 6; it combines both mapped (RSS) and unmapped Page
87Cache Control [11].
88
892. Memory Control
90
91Memory is a unique resource in the sense that it is present in a limited
92amount. If a task requires a lot of CPU processing, the task can spread
93its processing over a period of hours, days, months or years, but with
94memory, the same physical memory needs to be reused to accomplish the task.
95
96The memory controller implementation has been divided into phases. These
97are:
98
991. Memory controller
1002. mlock(2) controller
1013. Kernel user memory accounting and slab control
1024. user mappings length controller
103
104The memory controller is the first controller developed.
105
1062.1. Design
107
108The core of the design is a counter called the res_counter. The res_counter
109tracks the current memory usage and limit of the group of processes associated
110with the controller. Each cgroup has a memory controller specific data
111structure (mem_cgroup) associated with it.
112
1132.2. Accounting
114
115 +--------------------+
116 | mem_cgroup |
117 | (res_counter) |
118 +--------------------+
119 / ^ \
120 / | \
121 +---------------+ | +---------------+
122 | mm_struct | |.... | mm_struct |
123 | | | | |
124 +---------------+ | +---------------+
125 |
126 + --------------+
127 |
128 +---------------+ +------+--------+
129 | page +----------> page_cgroup|
130 | | | |
131 +---------------+ +---------------+
132
133 (Figure 1: Hierarchy of Accounting)
134
135
136Figure 1 shows the important aspects of the controller
137
1381. Accounting happens per cgroup
1392. Each mm_struct knows about which cgroup it belongs to
1403. Each page has a pointer to the page_cgroup, which in turn knows the
141 cgroup it belongs to
142
143The accounting is done as follows: mem_cgroup_charge() is invoked to setup
144the necessary data structures and check if the cgroup that is being charged
145is over its limit. If it is then reclaim is invoked on the cgroup.
146More details can be found in the reclaim section of this document.
147If everything goes well, a page meta-data-structure called page_cgroup is
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700148updated. page_cgroup has its own LRU on cgroup.
149(*) page_cgroup structure is allocated at boot/memory-hotplug time.
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800150
1512.2.1 Accounting details
152
KAMEZAWA Hiroyuki5b4e6552008-10-18 20:28:10 -0700153All mapped anon pages (RSS) and cache pages (Page Cache) are accounted.
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700154Some pages which are never reclaimable and will not be on the global LRU
155are not accounted. We just account pages under usual VM management.
KAMEZAWA Hiroyuki5b4e6552008-10-18 20:28:10 -0700156
157RSS pages are accounted at page_fault unless they've already been accounted
158for earlier. A file page will be accounted for as Page Cache when it's
159inserted into inode (radix-tree). While it's mapped into the page tables of
160processes, duplicate accounting is carefully avoided.
161
162A RSS page is unaccounted when it's fully unmapped. A PageCache page is
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700163unaccounted when it's removed from radix-tree. Even if RSS pages are fully
164unmapped (by kswapd), they may exist as SwapCache in the system until they
165are really freed. Such SwapCaches also also accounted.
166A swapped-in page is not accounted until it's mapped.
167
168Note: The kernel does swapin-readahead and read multiple swaps at once.
169This means swapped-in pages may contain pages for other tasks than a task
170causing page fault. So, we avoid accounting at swap-in I/O.
KAMEZAWA Hiroyuki5b4e6552008-10-18 20:28:10 -0700171
172At page migration, accounting information is kept.
173
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700174Note: we just account pages-on-LRU because our purpose is to control amount
175of used pages; not-on-LRU pages tend to be out-of-control from VM view.
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800176
1772.3 Shared Page Accounting
178
179Shared pages are accounted on the basis of the first touch approach. The
180cgroup that first touches a page is accounted for the page. The principle
181behind this approach is that a cgroup that aggressively uses a shared
182page will eventually get charged for it (once it is uncharged from
183the cgroup that brought it in -- this will happen on memory pressure).
184
Jörg Sommer67de0162011-06-15 13:00:47 -0700185Exception: If CONFIG_CGROUP_CGROUP_MEM_RES_CTLR_SWAP is not used.
KAMEZAWA Hiroyuki8c7c6e342009-01-07 18:08:00 -0800186When you do swapoff and make swapped-out pages of shmem(tmpfs) to
KAMEZAWA Hiroyukid13d1442009-01-07 18:07:56 -0800187be backed into memory in force, charges for pages are accounted against the
188caller of swapoff rather than the users of shmem.
189
190
KAMEZAWA Hiroyuki8c7c6e342009-01-07 18:08:00 -08001912.4 Swap Extension (CONFIG_CGROUP_MEM_RES_CTLR_SWAP)
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700192
KAMEZAWA Hiroyuki8c7c6e342009-01-07 18:08:00 -0800193Swap Extension allows you to record charge for swap. A swapped-in page is
194charged back to original page allocator if possible.
195
196When swap is accounted, following files are added.
197 - memory.memsw.usage_in_bytes.
198 - memory.memsw.limit_in_bytes.
199
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700200memsw means memory+swap. Usage of memory+swap is limited by
201memsw.limit_in_bytes.
KAMEZAWA Hiroyuki8c7c6e342009-01-07 18:08:00 -0800202
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700203Example: Assume a system with 4G of swap. A task which allocates 6G of memory
204(by mistake) under 2G memory limitation will use all swap.
205In this case, setting memsw.limit_in_bytes=3G will prevent bad use of swap.
206By using memsw limit, you can avoid system OOM which can be caused by swap
207shortage.
208
209* why 'memory+swap' rather than swap.
KAMEZAWA Hiroyuki8c7c6e342009-01-07 18:08:00 -0800210The global LRU(kswapd) can swap out arbitrary pages. Swap-out means
211to move account from memory to swap...there is no change in usage of
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700212memory+swap. In other words, when we want to limit the usage of swap without
213affecting global LRU, memory+swap limit is better than just limiting swap from
KAMEZAWA Hiroyuki22a668d2009-06-17 16:27:19 -0700214OS point of view.
KAMEZAWA Hiroyuki8c7c6e342009-01-07 18:08:00 -0800215
KAMEZAWA Hiroyuki22a668d2009-06-17 16:27:19 -0700216* What happens when a cgroup hits memory.memsw.limit_in_bytes
Jörg Sommer67de0162011-06-15 13:00:47 -0700217When a cgroup hits memory.memsw.limit_in_bytes, it's useless to do swap-out
KAMEZAWA Hiroyuki22a668d2009-06-17 16:27:19 -0700218in this cgroup. Then, swap-out will not be done by cgroup routine and file
219caches are dropped. But as mentioned above, global LRU can do swapout memory
220from it for sanity of the system's memory management state. You can't forbid
221it by cgroup.
KAMEZAWA Hiroyuki8c7c6e342009-01-07 18:08:00 -0800222
2232.5 Reclaim
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800224
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700225Each cgroup maintains a per cgroup LRU which has the same structure as
226global VM. When a cgroup goes over its limit, we first try
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800227to reclaim memory from the cgroup so as to make space for the new
228pages that the cgroup has touched. If the reclaim is unsuccessful,
229an OOM routine is invoked to select and kill the bulkiest task in the
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700230cgroup. (See 10. OOM Control below.)
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800231
232The reclaim algorithm has not been modified for cgroups, except that
233pages that are selected for reclaiming come from the per cgroup LRU
234list.
235
Balbir Singh4b3bde42009-09-23 15:56:32 -0700236NOTE: Reclaim does not work for the root cgroup, since we cannot set any
237limits on the root cgroup.
238
KAMEZAWA Hiroyukidaaf1e62010-03-10 15:22:32 -0800239Note2: When panic_on_oom is set to "2", the whole system will panic.
240
KAMEZAWA Hiroyuki9490ff22010-05-26 14:42:36 -0700241When oom event notifier is registered, event will be delivered.
242(See oom_control section)
243
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -07002442.6 Locking
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800245
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700246 lock_page_cgroup()/unlock_page_cgroup() should not be called under
247 mapping->tree_lock.
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800248
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700249 Other lock order is following:
250 PG_locked.
251 mm->page_table_lock
252 zone->lru_lock
253 lock_page_cgroup.
254 In many cases, just lock_page_cgroup() is called.
255 per-zone-per-cgroup LRU (cgroup's private LRU) is just guarded by
256 zone->lru_lock, it has no lock of its own.
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800257
2583. User Interface
259
2600. Configuration
261
262a. Enable CONFIG_CGROUPS
263b. Enable CONFIG_RESOURCE_COUNTERS
Balbir Singh00f0b822008-03-04 14:28:39 -0800264c. Enable CONFIG_CGROUP_MEM_RES_CTLR
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700265d. Enable CONFIG_CGROUP_MEM_RES_CTLR_SWAP (to use swap extension)
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800266
Jörg Sommerf6e07d32011-06-15 12:59:45 -07002671. Prepare the cgroups (see cgroups.txt, Why are cgroups needed?)
268# mount -t tmpfs none /sys/fs/cgroup
269# mkdir /sys/fs/cgroup/memory
270# mount -t cgroup none /sys/fs/cgroup/memory -o memory
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800271
2722. Make the new group and move bash into it
Jörg Sommerf6e07d32011-06-15 12:59:45 -0700273# mkdir /sys/fs/cgroup/memory/0
274# echo $$ > /sys/fs/cgroup/memory/0/tasks
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800275
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700276Since now we're in the 0 cgroup, we can alter the memory limit:
Jörg Sommerf6e07d32011-06-15 12:59:45 -0700277# echo 4M > /sys/fs/cgroup/memory/0/memory.limit_in_bytes
Balbir Singh0eea1032008-02-07 00:13:57 -0800278
279NOTE: We can use a suffix (k, K, m, M, g or G) to indicate values in kilo,
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700280mega or gigabytes. (Here, Kilo, Mega, Giga are Kibibytes, Mebibytes, Gibibytes.)
281
Daisuke Nishimurac5b947b2009-06-17 16:27:20 -0700282NOTE: We can write "-1" to reset the *.limit_in_bytes(unlimited).
Balbir Singh4b3bde42009-09-23 15:56:32 -0700283NOTE: We cannot set limits on the root cgroup any more.
Balbir Singh0eea1032008-02-07 00:13:57 -0800284
Jörg Sommerf6e07d32011-06-15 12:59:45 -0700285# cat /sys/fs/cgroup/memory/0/memory.limit_in_bytes
Li Zefan2324c5d2008-02-23 15:24:12 -08002864194304
Balbir Singh0eea1032008-02-07 00:13:57 -0800287
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800288We can check the usage:
Jörg Sommerf6e07d32011-06-15 12:59:45 -0700289# cat /sys/fs/cgroup/memory/0/memory.usage_in_bytes
Li Zefan2324c5d2008-02-23 15:24:12 -08002901216512
Balbir Singh0eea1032008-02-07 00:13:57 -0800291
292A successful write to this file does not guarantee a successful set of
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700293this limit to the value written into the file. This can be due to a
Balbir Singh0eea1032008-02-07 00:13:57 -0800294number of factors, such as rounding up to page boundaries or the total
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700295availability of memory on the system. The user is required to re-read
Balbir Singh0eea1032008-02-07 00:13:57 -0800296this file after a write to guarantee the value committed by the kernel.
297
Balbir Singhfb789222008-03-04 14:28:24 -0800298# echo 1 > memory.limit_in_bytes
Balbir Singh0eea1032008-02-07 00:13:57 -0800299# cat memory.limit_in_bytes
Li Zefan2324c5d2008-02-23 15:24:12 -08003004096
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800301
302The memory.failcnt field gives the number of times that the cgroup limit was
303exceeded.
304
KAMEZAWA Hiroyukidfc05c22008-02-07 00:14:41 -0800305The memory.stat file gives accounting information. Now, the number of
306caches, RSS and Active pages/Inactive pages are shown.
307
Balbir Singh1b6df3a2008-02-07 00:13:46 -08003084. Testing
309
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700310For testing features and implementation, see memcg_test.txt.
311
312Performance test is also important. To see pure memory controller's overhead,
313testing on tmpfs will give you good numbers of small overheads.
314Example: do kernel make on tmpfs.
315
316Page-fault scalability is also important. At measuring parallel
317page fault test, multi-process test may be better than multi-thread
318test because it has noise of shared objects/status.
319
320But the above two are testing extreme situations.
321Trying usual test under memory controller is always helpful.
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800322
3234.1 Troubleshooting
324
325Sometimes a user might find that the application under a cgroup is
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700326terminated by OOM killer. There are several causes for this:
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800327
3281. The cgroup limit is too low (just too low to do anything useful)
3292. The user is using anonymous memory and swap is turned off or too low
330
331A sync followed by echo 1 > /proc/sys/vm/drop_caches will help get rid of
332some of the pages cached in the cgroup (page cache pages).
333
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700334To know what happens, disable OOM_Kill by 10. OOM Control(see below) and
335seeing what happens will be helpful.
336
Balbir Singh1b6df3a2008-02-07 00:13:46 -08003374.2 Task migration
338
Francis Galieguea33f3222010-04-23 00:08:02 +0200339When a task migrates from one cgroup to another, its charge is not
Daisuke Nishimura7dc74be2010-03-10 15:22:13 -0800340carried forward by default. The pages allocated from the original cgroup still
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800341remain charged to it, the charge is dropped when the page is freed or
342reclaimed.
343
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700344You can move charges of a task along with task migration.
345See 8. "Move charges at task migration"
Daisuke Nishimura7dc74be2010-03-10 15:22:13 -0800346
Balbir Singh1b6df3a2008-02-07 00:13:46 -08003474.3 Removing a cgroup
348
349A cgroup can be removed by rmdir, but as discussed in sections 4.1 and 4.2, a
350cgroup might have some charge associated with it, even though all
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700351tasks have migrated away from it. (because we charge against pages, not
352against tasks.)
353
354Such charges are freed or moved to their parent. At moving, both of RSS
355and CACHES are moved to parent.
356rmdir() may return -EBUSY if freeing/moving fails. See 5.1 also.
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800357
KAMEZAWA Hiroyuki8c7c6e342009-01-07 18:08:00 -0800358Charges recorded in swap information is not updated at removal of cgroup.
359Recorded information is discarded and a cgroup which uses swap (swapcache)
360will be charged as a new owner of it.
361
362
KAMEZAWA Hiroyukic1e862c2009-01-07 18:07:55 -08003635. Misc. interfaces.
364
3655.1 force_empty
366 memory.force_empty interface is provided to make cgroup's memory usage empty.
367 You can use this interface only when the cgroup has no tasks.
368 When writing anything to this
369
370 # echo 0 > memory.force_empty
371
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700372 Almost all pages tracked by this memory cgroup will be unmapped and freed.
373 Some pages cannot be freed because they are locked or in-use. Such pages are
374 moved to parent and this cgroup will be empty. This may return -EBUSY if
375 VM is too busy to free/move all pages immediately.
KAMEZAWA Hiroyukic1e862c2009-01-07 18:07:55 -0800376
377 Typical use case of this interface is that calling this before rmdir().
378 Because rmdir() moves all pages to parent, some out-of-use page caches can be
379 moved to the parent. If you want to avoid that, force_empty will be useful.
380
KOSAKI Motohiro7f016ee2009-01-07 18:08:22 -08003815.2 stat file
KOSAKI Motohiro7f016ee2009-01-07 18:08:22 -0800382
Johannes Weiner185efc02011-09-14 16:21:58 -0700383memory.stat file includes following statistics
KOSAKI Motohiro7f016ee2009-01-07 18:08:22 -0800384
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700385# per-memory cgroup local status
Bharata B Raoc863d832009-04-13 14:40:15 -0700386cache - # of bytes of page cache memory.
387rss - # of bytes of anonymous and swap cache memory.
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700388mapped_file - # of bytes of mapped file (includes tmpfs/shmem)
Bharata B Raoc863d832009-04-13 14:40:15 -0700389pgpgin - # of pages paged in (equivalent to # of charging events).
390pgpgout - # of pages paged out (equivalent to # of uncharging events).
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700391swap - # of bytes of swap usage
Bharata B Raoc863d832009-04-13 14:40:15 -0700392inactive_anon - # of bytes of anonymous memory and swap cache memory on
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700393 LRU list.
394active_anon - # of bytes of anonymous and swap cache memory on active
395 inactive LRU list.
396inactive_file - # of bytes of file-backed memory on inactive LRU list.
397active_file - # of bytes of file-backed memory on active LRU list.
Bharata B Raoc863d832009-04-13 14:40:15 -0700398unevictable - # of bytes of memory that cannot be reclaimed (mlocked etc).
399
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700400# status considering hierarchy (see memory.use_hierarchy settings)
401
402hierarchical_memory_limit - # of bytes of memory limit with regard to hierarchy
403 under which the memory cgroup is
404hierarchical_memsw_limit - # of bytes of memory+swap limit with regard to
405 hierarchy under which memory cgroup is.
406
407total_cache - sum of all children's "cache"
408total_rss - sum of all children's "rss"
409total_mapped_file - sum of all children's "cache"
410total_pgpgin - sum of all children's "pgpgin"
411total_pgpgout - sum of all children's "pgpgout"
412total_swap - sum of all children's "swap"
413total_inactive_anon - sum of all children's "inactive_anon"
414total_active_anon - sum of all children's "active_anon"
415total_inactive_file - sum of all children's "inactive_file"
416total_active_file - sum of all children's "active_file"
417total_unevictable - sum of all children's "unevictable"
418
419# The following additional stats are dependent on CONFIG_DEBUG_VM.
Bharata B Raoc863d832009-04-13 14:40:15 -0700420
421inactive_ratio - VM internal parameter. (see mm/page_alloc.c)
422recent_rotated_anon - VM internal parameter. (see mm/vmscan.c)
423recent_rotated_file - VM internal parameter. (see mm/vmscan.c)
424recent_scanned_anon - VM internal parameter. (see mm/vmscan.c)
425recent_scanned_file - VM internal parameter. (see mm/vmscan.c)
426
427Memo:
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700428 recent_rotated means recent frequency of LRU rotation.
429 recent_scanned means recent # of scans to LRU.
KOSAKI Motohiro7f016ee2009-01-07 18:08:22 -0800430 showing for better debug please see the code for meanings.
431
Bharata B Raoc863d832009-04-13 14:40:15 -0700432Note:
433 Only anonymous and swap cache memory is listed as part of 'rss' stat.
434 This should not be confused with the true 'resident set size' or the
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700435 amount of physical memory used by the cgroup.
436 'rss + file_mapped" will give you resident set size of cgroup.
437 (Note: file and shmem may be shared among other cgroups. In that case,
438 file_mapped is accounted only when the memory cgroup is owner of page
439 cache.)
KOSAKI Motohiro7f016ee2009-01-07 18:08:22 -0800440
KOSAKI Motohiroa7885eb2009-01-07 18:08:24 -08004415.3 swappiness
KOSAKI Motohiroa7885eb2009-01-07 18:08:24 -0800442
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700443Similar to /proc/sys/vm/swappiness, but affecting a hierarchy of groups only.
KOSAKI Motohiroa7885eb2009-01-07 18:08:24 -0800444
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700445Following cgroups' swappiness can't be changed.
446- root cgroup (uses /proc/sys/vm/swappiness).
447- a cgroup which uses hierarchy and it has other cgroup(s) below it.
448- a cgroup which uses hierarchy and not the root of hierarchy.
449
4505.4 failcnt
451
452A memory cgroup provides memory.failcnt and memory.memsw.failcnt files.
453This failcnt(== failure count) shows the number of times that a usage counter
454hit its limit. When a memory cgroup hits a limit, failcnt increases and
455memory under it will be reclaimed.
456
457You can reset failcnt by writing 0 to failcnt file.
458# echo 0 > .../memory.failcnt
KOSAKI Motohiroa7885eb2009-01-07 18:08:24 -0800459
Daisuke Nishimuraa111c962011-04-27 15:26:48 -07004605.5 usage_in_bytes
461
462For efficiency, as other kernel components, memory cgroup uses some optimization
463to avoid unnecessary cacheline false sharing. usage_in_bytes is affected by the
464method and doesn't show 'exact' value of memory(and swap) usage, it's an fuzz
465value for efficient access. (Of course, when necessary, it's synchronized.)
466If you want to know more exact memory usage, you should use RSS+CACHE(+SWAP)
467value in memory.stat(see 5.2).
468
Ying Han50c35e52011-06-15 15:08:16 -07004695.6 numa_stat
470
471This is similar to numa_maps but operates on a per-memcg basis. This is
472useful for providing visibility into the numa locality information within
473an memcg since the pages are allowed to be allocated from any physical
474node. One of the usecases is evaluating application performance by
475combining this information with the application's cpu allocation.
476
477We export "total", "file", "anon" and "unevictable" pages per-node for
478each memcg. The ouput format of memory.numa_stat is:
479
480total=<total pages> N0=<node 0 pages> N1=<node 1 pages> ...
481file=<total file pages> N0=<node 0 pages> N1=<node 1 pages> ...
482anon=<total anon pages> N0=<node 0 pages> N1=<node 1 pages> ...
483unevictable=<total anon pages> N0=<node 0 pages> N1=<node 1 pages> ...
484
485And we have total = file + anon + unevictable.
486
Balbir Singh52bc0d82009-01-07 18:08:03 -08004876. Hierarchy support
KAMEZAWA Hiroyukic1e862c2009-01-07 18:07:55 -0800488
Balbir Singh52bc0d82009-01-07 18:08:03 -0800489The memory controller supports a deep hierarchy and hierarchical accounting.
490The hierarchy is created by creating the appropriate cgroups in the
491cgroup filesystem. Consider for example, the following cgroup filesystem
492hierarchy
493
Jörg Sommer67de0162011-06-15 13:00:47 -0700494 root
Balbir Singh52bc0d82009-01-07 18:08:03 -0800495 / | \
Jörg Sommer67de0162011-06-15 13:00:47 -0700496 / | \
497 a b c
498 | \
499 | \
500 d e
Balbir Singh52bc0d82009-01-07 18:08:03 -0800501
502In the diagram above, with hierarchical accounting enabled, all memory
503usage of e, is accounted to its ancestors up until the root (i.e, c and root),
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700504that has memory.use_hierarchy enabled. If one of the ancestors goes over its
Balbir Singh52bc0d82009-01-07 18:08:03 -0800505limit, the reclaim algorithm reclaims from the tasks in the ancestor and the
506children of the ancestor.
507
5086.1 Enabling hierarchical accounting and reclaim
509
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700510A memory cgroup by default disables the hierarchy feature. Support
Balbir Singh52bc0d82009-01-07 18:08:03 -0800511can be enabled by writing 1 to memory.use_hierarchy file of the root cgroup
512
513# echo 1 > memory.use_hierarchy
514
515The feature can be disabled by
516
517# echo 0 > memory.use_hierarchy
518
Greg Thelen689bca32011-02-16 17:51:23 -0800519NOTE1: Enabling/disabling will fail if either the cgroup already has other
520 cgroups created below it, or if the parent cgroup has use_hierarchy
521 enabled.
Balbir Singh52bc0d82009-01-07 18:08:03 -0800522
KAMEZAWA Hiroyukidaaf1e62010-03-10 15:22:32 -0800523NOTE2: When panic_on_oom is set to "2", the whole system will panic in
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700524 case of an OOM event in any cgroup.
Balbir Singh52bc0d82009-01-07 18:08:03 -0800525
Balbir Singha6df6362009-09-23 15:56:34 -07005267. Soft limits
527
528Soft limits allow for greater sharing of memory. The idea behind soft limits
529is to allow control groups to use as much of the memory as needed, provided
530
531a. There is no memory contention
532b. They do not exceed their hard limit
533
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700534When the system detects memory contention or low memory, control groups
Balbir Singha6df6362009-09-23 15:56:34 -0700535are pushed back to their soft limits. If the soft limit of each control
536group is very high, they are pushed back as much as possible to make
537sure that one control group does not starve the others of memory.
538
539Please note that soft limits is a best effort feature, it comes with
540no guarantees, but it does its best to make sure that when memory is
541heavily contended for, memory is allocated based on the soft limit
542hints/setup. Currently soft limit based reclaim is setup such that
543it gets invoked from balance_pgdat (kswapd).
544
5457.1 Interface
546
547Soft limits can be setup by using the following commands (in this example we
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700548assume a soft limit of 256 MiB)
Balbir Singha6df6362009-09-23 15:56:34 -0700549
550# echo 256M > memory.soft_limit_in_bytes
551
552If we want to change this to 1G, we can at any time use
553
554# echo 1G > memory.soft_limit_in_bytes
555
556NOTE1: Soft limits take effect over a long period of time, since they involve
557 reclaiming memory for balancing between memory cgroups
558NOTE2: It is recommended to set the soft limit always below the hard limit,
559 otherwise the hard limit will take precedence.
560
Daisuke Nishimura7dc74be2010-03-10 15:22:13 -08005618. Move charges at task migration
562
563Users can move charges associated with a task along with task migration, that
564is, uncharge task's pages from the old cgroup and charge them to the new cgroup.
Daisuke Nishimura02491442010-03-10 15:22:17 -0800565This feature is not supported in !CONFIG_MMU environments because of lack of
566page tables.
Daisuke Nishimura7dc74be2010-03-10 15:22:13 -0800567
5688.1 Interface
569
570This feature is disabled by default. It can be enabled(and disabled again) by
571writing to memory.move_charge_at_immigrate of the destination cgroup.
572
573If you want to enable it:
574
575# echo (some positive value) > memory.move_charge_at_immigrate
576
577Note: Each bits of move_charge_at_immigrate has its own meaning about what type
578 of charges should be moved. See 8.2 for details.
579Note: Charges are moved only when you move mm->owner, IOW, a leader of a thread
580 group.
581Note: If we cannot find enough space for the task in the destination cgroup, we
582 try to make space by reclaiming memory. Task migration may fail if we
583 cannot make enough space.
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700584Note: It can take several seconds if you move charges much.
Daisuke Nishimura7dc74be2010-03-10 15:22:13 -0800585
586And if you want disable it again:
587
588# echo 0 > memory.move_charge_at_immigrate
589
5908.2 Type of charges which can be move
591
592Each bits of move_charge_at_immigrate has its own meaning about what type of
Daisuke Nishimura87946a72010-05-26 14:42:39 -0700593charges should be moved. But in any cases, it must be noted that an account of
594a page or a swap can be moved only when it is charged to the task's current(old)
595memory cgroup.
Daisuke Nishimura7dc74be2010-03-10 15:22:13 -0800596
597 bit | what type of charges would be moved ?
598 -----+------------------------------------------------------------------------
599 0 | A charge of an anonymous page(or swap of it) used by the target task.
600 | Those pages and swaps must be used only by the target task. You must
601 | enable Swap Extension(see 2.4) to enable move of swap charges.
Daisuke Nishimura87946a72010-05-26 14:42:39 -0700602 -----+------------------------------------------------------------------------
603 1 | A charge of file pages(normal file, tmpfs file(e.g. ipc shared memory)
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700604 | and swaps of tmpfs file) mmapped by the target task. Unlike the case of
Daisuke Nishimura87946a72010-05-26 14:42:39 -0700605 | anonymous pages, file pages(and swaps) in the range mmapped by the task
606 | will be moved even if the task hasn't done page fault, i.e. they might
607 | not be the task's "RSS", but other task's "RSS" that maps the same file.
608 | And mapcount of the page is ignored(the page can be moved even if
609 | page_mapcount(page) > 1). You must enable Swap Extension(see 2.4) to
610 | enable move of swap charges.
Daisuke Nishimura7dc74be2010-03-10 15:22:13 -0800611
6128.3 TODO
613
Daisuke Nishimura7dc74be2010-03-10 15:22:13 -0800614- Implement madvise(2) to let users decide the vma to be moved or not to be
615 moved.
616- All of moving charge operations are done under cgroup_mutex. It's not good
617 behavior to hold the mutex too long, so we may need some trick.
618
Kirill A. Shutemov2e72b632010-03-10 15:22:24 -08006199. Memory thresholds
620
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700621Memory cgroup implements memory thresholds using cgroups notification
Kirill A. Shutemov2e72b632010-03-10 15:22:24 -0800622API (see cgroups.txt). It allows to register multiple memory and memsw
623thresholds and gets notifications when it crosses.
624
625To register a threshold application need:
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700626- create an eventfd using eventfd(2);
627- open memory.usage_in_bytes or memory.memsw.usage_in_bytes;
628- write string like "<event_fd> <fd of memory.usage_in_bytes> <threshold>" to
629 cgroup.event_control.
Kirill A. Shutemov2e72b632010-03-10 15:22:24 -0800630
631Application will be notified through eventfd when memory usage crosses
632threshold in any direction.
633
634It's applicable for root and non-root cgroup.
635
KAMEZAWA Hiroyuki9490ff22010-05-26 14:42:36 -070063610. OOM Control
637
KAMEZAWA Hiroyuki3c11ecf2010-05-26 14:42:37 -0700638memory.oom_control file is for OOM notification and other controls.
639
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700640Memory cgroup implements OOM notifier using cgroup notification
641API (See cgroups.txt). It allows to register multiple OOM notification
642delivery and gets notification when OOM happens.
KAMEZAWA Hiroyuki9490ff22010-05-26 14:42:36 -0700643
644To register a notifier, application need:
645 - create an eventfd using eventfd(2)
646 - open memory.oom_control file
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700647 - write string like "<event_fd> <fd of memory.oom_control>" to
648 cgroup.event_control
KAMEZAWA Hiroyuki9490ff22010-05-26 14:42:36 -0700649
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700650Application will be notified through eventfd when OOM happens.
KAMEZAWA Hiroyuki9490ff22010-05-26 14:42:36 -0700651OOM notification doesn't work for root cgroup.
652
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700653You can disable OOM-killer by writing "1" to memory.oom_control file, as:
654
KAMEZAWA Hiroyuki3c11ecf2010-05-26 14:42:37 -0700655 #echo 1 > memory.oom_control
656
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700657This operation is only allowed to the top cgroup of sub-hierarchy.
658If OOM-killer is disabled, tasks under cgroup will hang/sleep
659in memory cgroup's OOM-waitqueue when they request accountable memory.
KAMEZAWA Hiroyuki3c11ecf2010-05-26 14:42:37 -0700660
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700661For running them, you have to relax the memory cgroup's OOM status by
KAMEZAWA Hiroyuki3c11ecf2010-05-26 14:42:37 -0700662 * enlarge limit or reduce usage.
663To reduce usage,
664 * kill some tasks.
665 * move some tasks to other group with account migration.
666 * remove some files (on tmpfs?)
667
668Then, stopped tasks will work again.
669
670At reading, current status of OOM is shown.
671 oom_kill_disable 0 or 1 (if 1, oom-killer is disabled)
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700672 under_oom 0 or 1 (if 1, the memory cgroup is under OOM, tasks may
KAMEZAWA Hiroyuki3c11ecf2010-05-26 14:42:37 -0700673 be stopped.)
KAMEZAWA Hiroyuki9490ff22010-05-26 14:42:36 -0700674
67511. TODO
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800676
6771. Add support for accounting huge pages (as a separate controller)
KAMEZAWA Hiroyukidfc05c22008-02-07 00:14:41 -08006782. Make per-cgroup scanner reclaim not-shared pages first
6793. Teach controller to account for shared-pages
KAMEZAWA Hiroyuki628f4232008-07-25 01:47:20 -07006804. Start reclamation in the background when the limit is
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800681 not yet hit but the usage is getting closer
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800682
683Summary
684
685Overall, the memory controller has been a stable controller and has been
686commented and discussed quite extensively in the community.
687
688References
689
6901. Singh, Balbir. RFC: Memory Controller, http://lwn.net/Articles/206697/
6912. Singh, Balbir. Memory Controller (RSS Control),
692 http://lwn.net/Articles/222762/
6933. Emelianov, Pavel. Resource controllers based on process cgroups
694 http://lkml.org/lkml/2007/3/6/198
6954. Emelianov, Pavel. RSS controller based on process cgroups (v2)
Li Zefan2324c5d2008-02-23 15:24:12 -0800696 http://lkml.org/lkml/2007/4/9/78
Balbir Singh1b6df3a2008-02-07 00:13:46 -08006975. Emelianov, Pavel. RSS controller based on process cgroups (v3)
698 http://lkml.org/lkml/2007/5/30/244
6996. Menage, Paul. Control Groups v10, http://lwn.net/Articles/236032/
7007. Vaidyanathan, Srinivasan, Control Groups: Pagecache accounting and control
701 subsystem (v3), http://lwn.net/Articles/235534/
Li Zefan2324c5d2008-02-23 15:24:12 -08007028. Singh, Balbir. RSS controller v2 test results (lmbench),
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800703 http://lkml.org/lkml/2007/5/17/232
Li Zefan2324c5d2008-02-23 15:24:12 -08007049. Singh, Balbir. RSS controller v2 AIM9 results
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800705 http://lkml.org/lkml/2007/5/18/1
Li Zefan2324c5d2008-02-23 15:24:12 -080070610. Singh, Balbir. Memory controller v6 test results,
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800707 http://lkml.org/lkml/2007/8/19/36
Li Zefan2324c5d2008-02-23 15:24:12 -080070811. Singh, Balbir. Memory controller introduction (v6),
709 http://lkml.org/lkml/2007/8/17/69
Balbir Singh1b6df3a2008-02-07 00:13:46 -080071012. Corbet, Jonathan, Controlling memory use in cgroups,
711 http://lwn.net/Articles/243795/