blob: 4c95c0034a4bbbffdae12a99ff2ddbd0798ca09c [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
Glauber Costa65c64ce2011-12-22 01:02:27 +000047 Kernel memory support is work in progress, and the current version provides
48 basically functionality. (See Section 2.7)
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -070049
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
Zhu Yanhaid66c1ce2012-01-12 17:18:24 -080064 memory.memsw.max_usage_in_bytes # show max memory+Swap usage recorded
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -070065 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
Glauber Costa3aaabe22011-12-11 21:47:06 +000075 memory.kmem.tcp.limit_in_bytes # set/show hard limit for tcp buf memory
Glauber Costa5a6dd342011-12-11 21:47:07 +000076 memory.kmem.tcp.usage_in_bytes # show current tcp buf memory allocation
Glauber Costae5671df2011-12-11 21:47:01 +000077
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800781. History
79
80The memory controller has a long history. A request for comments for the memory
81controller was posted by Balbir Singh [1]. At the time the RFC was posted
82there were several implementations for memory control. The goal of the
83RFC was to build consensus and agreement for the minimal features required
84for memory control. The first RSS controller was posted by Balbir Singh[2]
85in Feb 2007. Pavel Emelianov [3][4][5] has since posted three versions of the
86RSS controller. At OLS, at the resource management BoF, everyone suggested
87that we handle both page cache and RSS together. Another request was raised
88to allow user space handling of OOM. The current memory controller is
89at version 6; it combines both mapped (RSS) and unmapped Page
90Cache Control [11].
91
922. Memory Control
93
94Memory is a unique resource in the sense that it is present in a limited
95amount. If a task requires a lot of CPU processing, the task can spread
96its processing over a period of hours, days, months or years, but with
97memory, the same physical memory needs to be reused to accomplish the task.
98
99The memory controller implementation has been divided into phases. These
100are:
101
1021. Memory controller
1032. mlock(2) controller
1043. Kernel user memory accounting and slab control
1054. user mappings length controller
106
107The memory controller is the first controller developed.
108
1092.1. Design
110
111The core of the design is a counter called the res_counter. The res_counter
112tracks the current memory usage and limit of the group of processes associated
113with the controller. Each cgroup has a memory controller specific data
114structure (mem_cgroup) associated with it.
115
1162.2. Accounting
117
118 +--------------------+
119 | mem_cgroup |
120 | (res_counter) |
121 +--------------------+
122 / ^ \
123 / | \
124 +---------------+ | +---------------+
125 | mm_struct | |.... | mm_struct |
126 | | | | |
127 +---------------+ | +---------------+
128 |
129 + --------------+
130 |
131 +---------------+ +------+--------+
132 | page +----------> page_cgroup|
133 | | | |
134 +---------------+ +---------------+
135
136 (Figure 1: Hierarchy of Accounting)
137
138
139Figure 1 shows the important aspects of the controller
140
1411. Accounting happens per cgroup
1422. Each mm_struct knows about which cgroup it belongs to
1433. Each page has a pointer to the page_cgroup, which in turn knows the
144 cgroup it belongs to
145
146The accounting is done as follows: mem_cgroup_charge() is invoked to setup
147the necessary data structures and check if the cgroup that is being charged
148is over its limit. If it is then reclaim is invoked on the cgroup.
149More details can be found in the reclaim section of this document.
150If everything goes well, a page meta-data-structure called page_cgroup is
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700151updated. page_cgroup has its own LRU on cgroup.
152(*) page_cgroup structure is allocated at boot/memory-hotplug time.
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800153
1542.2.1 Accounting details
155
KAMEZAWA Hiroyuki5b4e6552008-10-18 20:28:10 -0700156All mapped anon pages (RSS) and cache pages (Page Cache) are accounted.
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700157Some pages which are never reclaimable and will not be on the global LRU
158are not accounted. We just account pages under usual VM management.
KAMEZAWA Hiroyuki5b4e6552008-10-18 20:28:10 -0700159
160RSS pages are accounted at page_fault unless they've already been accounted
161for earlier. A file page will be accounted for as Page Cache when it's
162inserted into inode (radix-tree). While it's mapped into the page tables of
163processes, duplicate accounting is carefully avoided.
164
165A RSS page is unaccounted when it's fully unmapped. A PageCache page is
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700166unaccounted when it's removed from radix-tree. Even if RSS pages are fully
167unmapped (by kswapd), they may exist as SwapCache in the system until they
168are really freed. Such SwapCaches also also accounted.
169A swapped-in page is not accounted until it's mapped.
170
171Note: The kernel does swapin-readahead and read multiple swaps at once.
172This means swapped-in pages may contain pages for other tasks than a task
173causing page fault. So, we avoid accounting at swap-in I/O.
KAMEZAWA Hiroyuki5b4e6552008-10-18 20:28:10 -0700174
175At page migration, accounting information is kept.
176
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700177Note: we just account pages-on-LRU because our purpose is to control amount
178of used pages; not-on-LRU pages tend to be out-of-control from VM view.
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800179
1802.3 Shared Page Accounting
181
182Shared pages are accounted on the basis of the first touch approach. The
183cgroup that first touches a page is accounted for the page. The principle
184behind this approach is that a cgroup that aggressively uses a shared
185page will eventually get charged for it (once it is uncharged from
186the cgroup that brought it in -- this will happen on memory pressure).
187
Jörg Sommer67de0162011-06-15 13:00:47 -0700188Exception: If CONFIG_CGROUP_CGROUP_MEM_RES_CTLR_SWAP is not used.
KAMEZAWA Hiroyuki8c7c6e342009-01-07 18:08:00 -0800189When you do swapoff and make swapped-out pages of shmem(tmpfs) to
KAMEZAWA Hiroyukid13d1442009-01-07 18:07:56 -0800190be backed into memory in force, charges for pages are accounted against the
191caller of swapoff rather than the users of shmem.
192
193
KAMEZAWA Hiroyuki8c7c6e342009-01-07 18:08:00 -08001942.4 Swap Extension (CONFIG_CGROUP_MEM_RES_CTLR_SWAP)
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700195
KAMEZAWA Hiroyuki8c7c6e342009-01-07 18:08:00 -0800196Swap Extension allows you to record charge for swap. A swapped-in page is
197charged back to original page allocator if possible.
198
199When swap is accounted, following files are added.
200 - memory.memsw.usage_in_bytes.
201 - memory.memsw.limit_in_bytes.
202
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700203memsw means memory+swap. Usage of memory+swap is limited by
204memsw.limit_in_bytes.
KAMEZAWA Hiroyuki8c7c6e342009-01-07 18:08:00 -0800205
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700206Example: Assume a system with 4G of swap. A task which allocates 6G of memory
207(by mistake) under 2G memory limitation will use all swap.
208In this case, setting memsw.limit_in_bytes=3G will prevent bad use of swap.
209By using memsw limit, you can avoid system OOM which can be caused by swap
210shortage.
211
212* why 'memory+swap' rather than swap.
KAMEZAWA Hiroyuki8c7c6e342009-01-07 18:08:00 -0800213The global LRU(kswapd) can swap out arbitrary pages. Swap-out means
214to move account from memory to swap...there is no change in usage of
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700215memory+swap. In other words, when we want to limit the usage of swap without
216affecting global LRU, memory+swap limit is better than just limiting swap from
KAMEZAWA Hiroyuki22a668d2009-06-17 16:27:19 -0700217OS point of view.
KAMEZAWA Hiroyuki8c7c6e342009-01-07 18:08:00 -0800218
KAMEZAWA Hiroyuki22a668d2009-06-17 16:27:19 -0700219* What happens when a cgroup hits memory.memsw.limit_in_bytes
Jörg Sommer67de0162011-06-15 13:00:47 -0700220When a cgroup hits memory.memsw.limit_in_bytes, it's useless to do swap-out
KAMEZAWA Hiroyuki22a668d2009-06-17 16:27:19 -0700221in this cgroup. Then, swap-out will not be done by cgroup routine and file
222caches are dropped. But as mentioned above, global LRU can do swapout memory
223from it for sanity of the system's memory management state. You can't forbid
224it by cgroup.
KAMEZAWA Hiroyuki8c7c6e342009-01-07 18:08:00 -0800225
2262.5 Reclaim
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800227
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700228Each cgroup maintains a per cgroup LRU which has the same structure as
229global VM. When a cgroup goes over its limit, we first try
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800230to reclaim memory from the cgroup so as to make space for the new
231pages that the cgroup has touched. If the reclaim is unsuccessful,
232an OOM routine is invoked to select and kill the bulkiest task in the
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700233cgroup. (See 10. OOM Control below.)
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800234
235The reclaim algorithm has not been modified for cgroups, except that
236pages that are selected for reclaiming come from the per cgroup LRU
237list.
238
Balbir Singh4b3bde42009-09-23 15:56:32 -0700239NOTE: Reclaim does not work for the root cgroup, since we cannot set any
240limits on the root cgroup.
241
KAMEZAWA Hiroyukidaaf1e62010-03-10 15:22:32 -0800242Note2: When panic_on_oom is set to "2", the whole system will panic.
243
KAMEZAWA Hiroyuki9490ff22010-05-26 14:42:36 -0700244When oom event notifier is registered, event will be delivered.
245(See oom_control section)
246
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -07002472.6 Locking
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800248
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700249 lock_page_cgroup()/unlock_page_cgroup() should not be called under
250 mapping->tree_lock.
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800251
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700252 Other lock order is following:
253 PG_locked.
254 mm->page_table_lock
255 zone->lru_lock
256 lock_page_cgroup.
257 In many cases, just lock_page_cgroup() is called.
258 per-zone-per-cgroup LRU (cgroup's private LRU) is just guarded by
259 zone->lru_lock, it has no lock of its own.
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800260
Glauber Costae5671df2011-12-11 21:47:01 +00002612.7 Kernel Memory Extension (CONFIG_CGROUP_MEM_RES_CTLR_KMEM)
262
263With the Kernel memory extension, the Memory Controller is able to limit
264the amount of kernel memory used by the system. Kernel memory is fundamentally
265different than user memory, since it can't be swapped out, which makes it
266possible to DoS the system by consuming too much of this precious resource.
267
Glauber Costae5671df2011-12-11 21:47:01 +0000268Kernel memory limits are not imposed for the root cgroup. Usage for the root
269cgroup may or may not be accounted.
270
Glauber Costae5671df2011-12-11 21:47:01 +0000271Currently no soft limit is implemented for kernel memory. It is future work
272to trigger slab reclaim when those limits are reached.
273
2742.7.1 Current Kernel Memory resources accounted
275
Glauber Costae1aab162011-12-11 21:47:03 +0000276* sockets memory pressure: some sockets protocols have memory pressure
277thresholds. The Memory Controller allows them to be controlled individually
278per cgroup, instead of globally.
Glauber Costae5671df2011-12-11 21:47:01 +0000279
Glauber Costad1a4c0b2011-12-11 21:47:04 +0000280* tcp memory pressure: sockets memory pressure for the tcp protocol.
281
Balbir Singh1b6df3a2008-02-07 00:13:46 -08002823. User Interface
283
2840. Configuration
285
286a. Enable CONFIG_CGROUPS
287b. Enable CONFIG_RESOURCE_COUNTERS
Balbir Singh00f0b822008-03-04 14:28:39 -0800288c. Enable CONFIG_CGROUP_MEM_RES_CTLR
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700289d. Enable CONFIG_CGROUP_MEM_RES_CTLR_SWAP (to use swap extension)
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800290
Jörg Sommerf6e07d32011-06-15 12:59:45 -07002911. Prepare the cgroups (see cgroups.txt, Why are cgroups needed?)
292# mount -t tmpfs none /sys/fs/cgroup
293# mkdir /sys/fs/cgroup/memory
294# mount -t cgroup none /sys/fs/cgroup/memory -o memory
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800295
2962. Make the new group and move bash into it
Jörg Sommerf6e07d32011-06-15 12:59:45 -0700297# mkdir /sys/fs/cgroup/memory/0
298# echo $$ > /sys/fs/cgroup/memory/0/tasks
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800299
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700300Since now we're in the 0 cgroup, we can alter the memory limit:
Jörg Sommerf6e07d32011-06-15 12:59:45 -0700301# echo 4M > /sys/fs/cgroup/memory/0/memory.limit_in_bytes
Balbir Singh0eea1032008-02-07 00:13:57 -0800302
303NOTE: We can use a suffix (k, K, m, M, g or G) to indicate values in kilo,
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700304mega or gigabytes. (Here, Kilo, Mega, Giga are Kibibytes, Mebibytes, Gibibytes.)
305
Daisuke Nishimurac5b947b2009-06-17 16:27:20 -0700306NOTE: We can write "-1" to reset the *.limit_in_bytes(unlimited).
Balbir Singh4b3bde42009-09-23 15:56:32 -0700307NOTE: We cannot set limits on the root cgroup any more.
Balbir Singh0eea1032008-02-07 00:13:57 -0800308
Jörg Sommerf6e07d32011-06-15 12:59:45 -0700309# cat /sys/fs/cgroup/memory/0/memory.limit_in_bytes
Li Zefan2324c5d2008-02-23 15:24:12 -08003104194304
Balbir Singh0eea1032008-02-07 00:13:57 -0800311
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800312We can check the usage:
Jörg Sommerf6e07d32011-06-15 12:59:45 -0700313# cat /sys/fs/cgroup/memory/0/memory.usage_in_bytes
Li Zefan2324c5d2008-02-23 15:24:12 -08003141216512
Balbir Singh0eea1032008-02-07 00:13:57 -0800315
316A successful write to this file does not guarantee a successful set of
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700317this limit to the value written into the file. This can be due to a
Balbir Singh0eea1032008-02-07 00:13:57 -0800318number of factors, such as rounding up to page boundaries or the total
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700319availability of memory on the system. The user is required to re-read
Balbir Singh0eea1032008-02-07 00:13:57 -0800320this file after a write to guarantee the value committed by the kernel.
321
Balbir Singhfb789222008-03-04 14:28:24 -0800322# echo 1 > memory.limit_in_bytes
Balbir Singh0eea1032008-02-07 00:13:57 -0800323# cat memory.limit_in_bytes
Li Zefan2324c5d2008-02-23 15:24:12 -08003244096
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800325
326The memory.failcnt field gives the number of times that the cgroup limit was
327exceeded.
328
KAMEZAWA Hiroyukidfc05c22008-02-07 00:14:41 -0800329The memory.stat file gives accounting information. Now, the number of
330caches, RSS and Active pages/Inactive pages are shown.
331
Balbir Singh1b6df3a2008-02-07 00:13:46 -08003324. Testing
333
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700334For testing features and implementation, see memcg_test.txt.
335
336Performance test is also important. To see pure memory controller's overhead,
337testing on tmpfs will give you good numbers of small overheads.
338Example: do kernel make on tmpfs.
339
340Page-fault scalability is also important. At measuring parallel
341page fault test, multi-process test may be better than multi-thread
342test because it has noise of shared objects/status.
343
344But the above two are testing extreme situations.
345Trying usual test under memory controller is always helpful.
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800346
3474.1 Troubleshooting
348
349Sometimes a user might find that the application under a cgroup is
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700350terminated by OOM killer. There are several causes for this:
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800351
3521. The cgroup limit is too low (just too low to do anything useful)
3532. The user is using anonymous memory and swap is turned off or too low
354
355A sync followed by echo 1 > /proc/sys/vm/drop_caches will help get rid of
356some of the pages cached in the cgroup (page cache pages).
357
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700358To know what happens, disable OOM_Kill by 10. OOM Control(see below) and
359seeing what happens will be helpful.
360
Balbir Singh1b6df3a2008-02-07 00:13:46 -08003614.2 Task migration
362
Francis Galieguea33f3222010-04-23 00:08:02 +0200363When a task migrates from one cgroup to another, its charge is not
Daisuke Nishimura7dc74be2010-03-10 15:22:13 -0800364carried forward by default. The pages allocated from the original cgroup still
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800365remain charged to it, the charge is dropped when the page is freed or
366reclaimed.
367
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700368You can move charges of a task along with task migration.
369See 8. "Move charges at task migration"
Daisuke Nishimura7dc74be2010-03-10 15:22:13 -0800370
Balbir Singh1b6df3a2008-02-07 00:13:46 -08003714.3 Removing a cgroup
372
373A cgroup can be removed by rmdir, but as discussed in sections 4.1 and 4.2, a
374cgroup might have some charge associated with it, even though all
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700375tasks have migrated away from it. (because we charge against pages, not
376against tasks.)
377
378Such charges are freed or moved to their parent. At moving, both of RSS
379and CACHES are moved to parent.
380rmdir() may return -EBUSY if freeing/moving fails. See 5.1 also.
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800381
KAMEZAWA Hiroyuki8c7c6e342009-01-07 18:08:00 -0800382Charges recorded in swap information is not updated at removal of cgroup.
383Recorded information is discarded and a cgroup which uses swap (swapcache)
384will be charged as a new owner of it.
385
386
KAMEZAWA Hiroyukic1e862c2009-01-07 18:07:55 -08003875. Misc. interfaces.
388
3895.1 force_empty
390 memory.force_empty interface is provided to make cgroup's memory usage empty.
391 You can use this interface only when the cgroup has no tasks.
392 When writing anything to this
393
394 # echo 0 > memory.force_empty
395
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700396 Almost all pages tracked by this memory cgroup will be unmapped and freed.
397 Some pages cannot be freed because they are locked or in-use. Such pages are
398 moved to parent and this cgroup will be empty. This may return -EBUSY if
399 VM is too busy to free/move all pages immediately.
KAMEZAWA Hiroyukic1e862c2009-01-07 18:07:55 -0800400
401 Typical use case of this interface is that calling this before rmdir().
402 Because rmdir() moves all pages to parent, some out-of-use page caches can be
403 moved to the parent. If you want to avoid that, force_empty will be useful.
404
KOSAKI Motohiro7f016ee2009-01-07 18:08:22 -08004055.2 stat file
KOSAKI Motohiro7f016ee2009-01-07 18:08:22 -0800406
Johannes Weiner185efc02011-09-14 16:21:58 -0700407memory.stat file includes following statistics
KOSAKI Motohiro7f016ee2009-01-07 18:08:22 -0800408
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700409# per-memory cgroup local status
Bharata B Raoc863d832009-04-13 14:40:15 -0700410cache - # of bytes of page cache memory.
411rss - # of bytes of anonymous and swap cache memory.
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700412mapped_file - # of bytes of mapped file (includes tmpfs/shmem)
Ying Han0527b692012-01-12 17:18:27 -0800413pgpgin - # of charging events to the memory cgroup. The charging
414 event happens each time a page is accounted as either mapped
415 anon page(RSS) or cache page(Page Cache) to the cgroup.
416pgpgout - # of uncharging events to the memory cgroup. The uncharging
417 event happens each time a page is unaccounted from the cgroup.
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700418swap - # of bytes of swap usage
Bharata B Raoc863d832009-04-13 14:40:15 -0700419inactive_anon - # of bytes of anonymous memory and swap cache memory on
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700420 LRU list.
421active_anon - # of bytes of anonymous and swap cache memory on active
422 inactive LRU list.
423inactive_file - # of bytes of file-backed memory on inactive LRU list.
424active_file - # of bytes of file-backed memory on active LRU list.
Bharata B Raoc863d832009-04-13 14:40:15 -0700425unevictable - # of bytes of memory that cannot be reclaimed (mlocked etc).
426
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700427# status considering hierarchy (see memory.use_hierarchy settings)
428
429hierarchical_memory_limit - # of bytes of memory limit with regard to hierarchy
430 under which the memory cgroup is
431hierarchical_memsw_limit - # of bytes of memory+swap limit with regard to
432 hierarchy under which memory cgroup is.
433
434total_cache - sum of all children's "cache"
435total_rss - sum of all children's "rss"
436total_mapped_file - sum of all children's "cache"
437total_pgpgin - sum of all children's "pgpgin"
438total_pgpgout - sum of all children's "pgpgout"
439total_swap - sum of all children's "swap"
440total_inactive_anon - sum of all children's "inactive_anon"
441total_active_anon - sum of all children's "active_anon"
442total_inactive_file - sum of all children's "inactive_file"
443total_active_file - sum of all children's "active_file"
444total_unevictable - sum of all children's "unevictable"
445
446# The following additional stats are dependent on CONFIG_DEBUG_VM.
Bharata B Raoc863d832009-04-13 14:40:15 -0700447
Bharata B Raoc863d832009-04-13 14:40:15 -0700448recent_rotated_anon - VM internal parameter. (see mm/vmscan.c)
449recent_rotated_file - VM internal parameter. (see mm/vmscan.c)
450recent_scanned_anon - VM internal parameter. (see mm/vmscan.c)
451recent_scanned_file - VM internal parameter. (see mm/vmscan.c)
452
453Memo:
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700454 recent_rotated means recent frequency of LRU rotation.
455 recent_scanned means recent # of scans to LRU.
KOSAKI Motohiro7f016ee2009-01-07 18:08:22 -0800456 showing for better debug please see the code for meanings.
457
Bharata B Raoc863d832009-04-13 14:40:15 -0700458Note:
459 Only anonymous and swap cache memory is listed as part of 'rss' stat.
460 This should not be confused with the true 'resident set size' or the
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700461 amount of physical memory used by the cgroup.
462 'rss + file_mapped" will give you resident set size of cgroup.
463 (Note: file and shmem may be shared among other cgroups. In that case,
464 file_mapped is accounted only when the memory cgroup is owner of page
465 cache.)
KOSAKI Motohiro7f016ee2009-01-07 18:08:22 -0800466
KOSAKI Motohiroa7885eb2009-01-07 18:08:24 -08004675.3 swappiness
KOSAKI Motohiroa7885eb2009-01-07 18:08:24 -0800468
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700469Similar to /proc/sys/vm/swappiness, but affecting a hierarchy of groups only.
KOSAKI Motohiroa7885eb2009-01-07 18:08:24 -0800470
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700471Following cgroups' swappiness can't be changed.
472- root cgroup (uses /proc/sys/vm/swappiness).
473- a cgroup which uses hierarchy and it has other cgroup(s) below it.
474- a cgroup which uses hierarchy and not the root of hierarchy.
475
4765.4 failcnt
477
478A memory cgroup provides memory.failcnt and memory.memsw.failcnt files.
479This failcnt(== failure count) shows the number of times that a usage counter
480hit its limit. When a memory cgroup hits a limit, failcnt increases and
481memory under it will be reclaimed.
482
483You can reset failcnt by writing 0 to failcnt file.
484# echo 0 > .../memory.failcnt
KOSAKI Motohiroa7885eb2009-01-07 18:08:24 -0800485
Daisuke Nishimuraa111c962011-04-27 15:26:48 -07004865.5 usage_in_bytes
487
488For efficiency, as other kernel components, memory cgroup uses some optimization
489to avoid unnecessary cacheline false sharing. usage_in_bytes is affected by the
490method and doesn't show 'exact' value of memory(and swap) usage, it's an fuzz
491value for efficient access. (Of course, when necessary, it's synchronized.)
492If you want to know more exact memory usage, you should use RSS+CACHE(+SWAP)
493value in memory.stat(see 5.2).
494
Ying Han50c35e52011-06-15 15:08:16 -07004955.6 numa_stat
496
497This is similar to numa_maps but operates on a per-memcg basis. This is
498useful for providing visibility into the numa locality information within
499an memcg since the pages are allowed to be allocated from any physical
500node. One of the usecases is evaluating application performance by
501combining this information with the application's cpu allocation.
502
503We export "total", "file", "anon" and "unevictable" pages per-node for
504each memcg. The ouput format of memory.numa_stat is:
505
506total=<total pages> N0=<node 0 pages> N1=<node 1 pages> ...
507file=<total file pages> N0=<node 0 pages> N1=<node 1 pages> ...
508anon=<total anon pages> N0=<node 0 pages> N1=<node 1 pages> ...
509unevictable=<total anon pages> N0=<node 0 pages> N1=<node 1 pages> ...
510
511And we have total = file + anon + unevictable.
512
Balbir Singh52bc0d82009-01-07 18:08:03 -08005136. Hierarchy support
KAMEZAWA Hiroyukic1e862c2009-01-07 18:07:55 -0800514
Balbir Singh52bc0d82009-01-07 18:08:03 -0800515The memory controller supports a deep hierarchy and hierarchical accounting.
516The hierarchy is created by creating the appropriate cgroups in the
517cgroup filesystem. Consider for example, the following cgroup filesystem
518hierarchy
519
Jörg Sommer67de0162011-06-15 13:00:47 -0700520 root
Balbir Singh52bc0d82009-01-07 18:08:03 -0800521 / | \
Jörg Sommer67de0162011-06-15 13:00:47 -0700522 / | \
523 a b c
524 | \
525 | \
526 d e
Balbir Singh52bc0d82009-01-07 18:08:03 -0800527
528In the diagram above, with hierarchical accounting enabled, all memory
529usage of e, is accounted to its ancestors up until the root (i.e, c and root),
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700530that has memory.use_hierarchy enabled. If one of the ancestors goes over its
Balbir Singh52bc0d82009-01-07 18:08:03 -0800531limit, the reclaim algorithm reclaims from the tasks in the ancestor and the
532children of the ancestor.
533
5346.1 Enabling hierarchical accounting and reclaim
535
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700536A memory cgroup by default disables the hierarchy feature. Support
Balbir Singh52bc0d82009-01-07 18:08:03 -0800537can be enabled by writing 1 to memory.use_hierarchy file of the root cgroup
538
539# echo 1 > memory.use_hierarchy
540
541The feature can be disabled by
542
543# echo 0 > memory.use_hierarchy
544
Greg Thelen689bca32011-02-16 17:51:23 -0800545NOTE1: Enabling/disabling will fail if either the cgroup already has other
546 cgroups created below it, or if the parent cgroup has use_hierarchy
547 enabled.
Balbir Singh52bc0d82009-01-07 18:08:03 -0800548
KAMEZAWA Hiroyukidaaf1e62010-03-10 15:22:32 -0800549NOTE2: When panic_on_oom is set to "2", the whole system will panic in
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700550 case of an OOM event in any cgroup.
Balbir Singh52bc0d82009-01-07 18:08:03 -0800551
Balbir Singha6df6362009-09-23 15:56:34 -07005527. Soft limits
553
554Soft limits allow for greater sharing of memory. The idea behind soft limits
555is to allow control groups to use as much of the memory as needed, provided
556
557a. There is no memory contention
558b. They do not exceed their hard limit
559
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700560When the system detects memory contention or low memory, control groups
Balbir Singha6df6362009-09-23 15:56:34 -0700561are pushed back to their soft limits. If the soft limit of each control
562group is very high, they are pushed back as much as possible to make
563sure that one control group does not starve the others of memory.
564
565Please note that soft limits is a best effort feature, it comes with
566no guarantees, but it does its best to make sure that when memory is
567heavily contended for, memory is allocated based on the soft limit
568hints/setup. Currently soft limit based reclaim is setup such that
569it gets invoked from balance_pgdat (kswapd).
570
5717.1 Interface
572
573Soft limits can be setup by using the following commands (in this example we
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700574assume a soft limit of 256 MiB)
Balbir Singha6df6362009-09-23 15:56:34 -0700575
576# echo 256M > memory.soft_limit_in_bytes
577
578If we want to change this to 1G, we can at any time use
579
580# echo 1G > memory.soft_limit_in_bytes
581
582NOTE1: Soft limits take effect over a long period of time, since they involve
583 reclaiming memory for balancing between memory cgroups
584NOTE2: It is recommended to set the soft limit always below the hard limit,
585 otherwise the hard limit will take precedence.
586
Daisuke Nishimura7dc74be2010-03-10 15:22:13 -08005878. Move charges at task migration
588
589Users can move charges associated with a task along with task migration, that
590is, uncharge task's pages from the old cgroup and charge them to the new cgroup.
Daisuke Nishimura02491442010-03-10 15:22:17 -0800591This feature is not supported in !CONFIG_MMU environments because of lack of
592page tables.
Daisuke Nishimura7dc74be2010-03-10 15:22:13 -0800593
5948.1 Interface
595
596This feature is disabled by default. It can be enabled(and disabled again) by
597writing to memory.move_charge_at_immigrate of the destination cgroup.
598
599If you want to enable it:
600
601# echo (some positive value) > memory.move_charge_at_immigrate
602
603Note: Each bits of move_charge_at_immigrate has its own meaning about what type
604 of charges should be moved. See 8.2 for details.
605Note: Charges are moved only when you move mm->owner, IOW, a leader of a thread
606 group.
607Note: If we cannot find enough space for the task in the destination cgroup, we
608 try to make space by reclaiming memory. Task migration may fail if we
609 cannot make enough space.
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700610Note: It can take several seconds if you move charges much.
Daisuke Nishimura7dc74be2010-03-10 15:22:13 -0800611
612And if you want disable it again:
613
614# echo 0 > memory.move_charge_at_immigrate
615
6168.2 Type of charges which can be move
617
618Each bits of move_charge_at_immigrate has its own meaning about what type of
Daisuke Nishimura87946a72010-05-26 14:42:39 -0700619charges should be moved. But in any cases, it must be noted that an account of
620a page or a swap can be moved only when it is charged to the task's current(old)
621memory cgroup.
Daisuke Nishimura7dc74be2010-03-10 15:22:13 -0800622
623 bit | what type of charges would be moved ?
624 -----+------------------------------------------------------------------------
625 0 | A charge of an anonymous page(or swap of it) used by the target task.
626 | Those pages and swaps must be used only by the target task. You must
627 | enable Swap Extension(see 2.4) to enable move of swap charges.
Daisuke Nishimura87946a72010-05-26 14:42:39 -0700628 -----+------------------------------------------------------------------------
629 1 | A charge of file pages(normal file, tmpfs file(e.g. ipc shared memory)
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700630 | and swaps of tmpfs file) mmapped by the target task. Unlike the case of
Daisuke Nishimura87946a72010-05-26 14:42:39 -0700631 | anonymous pages, file pages(and swaps) in the range mmapped by the task
632 | will be moved even if the task hasn't done page fault, i.e. they might
633 | not be the task's "RSS", but other task's "RSS" that maps the same file.
634 | And mapcount of the page is ignored(the page can be moved even if
635 | page_mapcount(page) > 1). You must enable Swap Extension(see 2.4) to
636 | enable move of swap charges.
Daisuke Nishimura7dc74be2010-03-10 15:22:13 -0800637
6388.3 TODO
639
Daisuke Nishimura7dc74be2010-03-10 15:22:13 -0800640- Implement madvise(2) to let users decide the vma to be moved or not to be
641 moved.
642- All of moving charge operations are done under cgroup_mutex. It's not good
643 behavior to hold the mutex too long, so we may need some trick.
644
Kirill A. Shutemov2e72b632010-03-10 15:22:24 -08006459. Memory thresholds
646
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700647Memory cgroup implements memory thresholds using cgroups notification
Kirill A. Shutemov2e72b632010-03-10 15:22:24 -0800648API (see cgroups.txt). It allows to register multiple memory and memsw
649thresholds and gets notifications when it crosses.
650
651To register a threshold application need:
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700652- create an eventfd using eventfd(2);
653- open memory.usage_in_bytes or memory.memsw.usage_in_bytes;
654- write string like "<event_fd> <fd of memory.usage_in_bytes> <threshold>" to
655 cgroup.event_control.
Kirill A. Shutemov2e72b632010-03-10 15:22:24 -0800656
657Application will be notified through eventfd when memory usage crosses
658threshold in any direction.
659
660It's applicable for root and non-root cgroup.
661
KAMEZAWA Hiroyuki9490ff22010-05-26 14:42:36 -070066210. OOM Control
663
KAMEZAWA Hiroyuki3c11ecf2010-05-26 14:42:37 -0700664memory.oom_control file is for OOM notification and other controls.
665
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700666Memory cgroup implements OOM notifier using cgroup notification
667API (See cgroups.txt). It allows to register multiple OOM notification
668delivery and gets notification when OOM happens.
KAMEZAWA Hiroyuki9490ff22010-05-26 14:42:36 -0700669
670To register a notifier, application need:
671 - create an eventfd using eventfd(2)
672 - open memory.oom_control file
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700673 - write string like "<event_fd> <fd of memory.oom_control>" to
674 cgroup.event_control
KAMEZAWA Hiroyuki9490ff22010-05-26 14:42:36 -0700675
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700676Application will be notified through eventfd when OOM happens.
KAMEZAWA Hiroyuki9490ff22010-05-26 14:42:36 -0700677OOM notification doesn't work for root cgroup.
678
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700679You can disable OOM-killer by writing "1" to memory.oom_control file, as:
680
KAMEZAWA Hiroyuki3c11ecf2010-05-26 14:42:37 -0700681 #echo 1 > memory.oom_control
682
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700683This operation is only allowed to the top cgroup of sub-hierarchy.
684If OOM-killer is disabled, tasks under cgroup will hang/sleep
685in memory cgroup's OOM-waitqueue when they request accountable memory.
KAMEZAWA Hiroyuki3c11ecf2010-05-26 14:42:37 -0700686
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700687For running them, you have to relax the memory cgroup's OOM status by
KAMEZAWA Hiroyuki3c11ecf2010-05-26 14:42:37 -0700688 * enlarge limit or reduce usage.
689To reduce usage,
690 * kill some tasks.
691 * move some tasks to other group with account migration.
692 * remove some files (on tmpfs?)
693
694Then, stopped tasks will work again.
695
696At reading, current status of OOM is shown.
697 oom_kill_disable 0 or 1 (if 1, oom-killer is disabled)
KAMEZAWA Hiroyukidc10e282010-05-26 14:42:40 -0700698 under_oom 0 or 1 (if 1, the memory cgroup is under OOM, tasks may
KAMEZAWA Hiroyuki3c11ecf2010-05-26 14:42:37 -0700699 be stopped.)
KAMEZAWA Hiroyuki9490ff22010-05-26 14:42:36 -0700700
70111. TODO
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800702
7031. Add support for accounting huge pages (as a separate controller)
KAMEZAWA Hiroyukidfc05c22008-02-07 00:14:41 -08007042. Make per-cgroup scanner reclaim not-shared pages first
7053. Teach controller to account for shared-pages
KAMEZAWA Hiroyuki628f4232008-07-25 01:47:20 -07007064. Start reclamation in the background when the limit is
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800707 not yet hit but the usage is getting closer
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800708
709Summary
710
711Overall, the memory controller has been a stable controller and has been
712commented and discussed quite extensively in the community.
713
714References
715
7161. Singh, Balbir. RFC: Memory Controller, http://lwn.net/Articles/206697/
7172. Singh, Balbir. Memory Controller (RSS Control),
718 http://lwn.net/Articles/222762/
7193. Emelianov, Pavel. Resource controllers based on process cgroups
720 http://lkml.org/lkml/2007/3/6/198
7214. Emelianov, Pavel. RSS controller based on process cgroups (v2)
Li Zefan2324c5d2008-02-23 15:24:12 -0800722 http://lkml.org/lkml/2007/4/9/78
Balbir Singh1b6df3a2008-02-07 00:13:46 -08007235. Emelianov, Pavel. RSS controller based on process cgroups (v3)
724 http://lkml.org/lkml/2007/5/30/244
7256. Menage, Paul. Control Groups v10, http://lwn.net/Articles/236032/
7267. Vaidyanathan, Srinivasan, Control Groups: Pagecache accounting and control
727 subsystem (v3), http://lwn.net/Articles/235534/
Li Zefan2324c5d2008-02-23 15:24:12 -08007288. Singh, Balbir. RSS controller v2 test results (lmbench),
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800729 http://lkml.org/lkml/2007/5/17/232
Li Zefan2324c5d2008-02-23 15:24:12 -08007309. Singh, Balbir. RSS controller v2 AIM9 results
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800731 http://lkml.org/lkml/2007/5/18/1
Li Zefan2324c5d2008-02-23 15:24:12 -080073210. Singh, Balbir. Memory controller v6 test results,
Balbir Singh1b6df3a2008-02-07 00:13:46 -0800733 http://lkml.org/lkml/2007/8/19/36
Li Zefan2324c5d2008-02-23 15:24:12 -080073411. Singh, Balbir. Memory controller introduction (v6),
735 http://lkml.org/lkml/2007/8/17/69
Balbir Singh1b6df3a2008-02-07 00:13:46 -080073612. Corbet, Jonathan, Controlling memory use in cgroups,
737 http://lwn.net/Articles/243795/