1========================== 2Memory Resource Controller 3========================== 4 5.. caution:: 6 This document is hopelessly outdated and it asks for a complete 7 rewrite. It still contains a useful information so we are keeping it 8 here but make sure to check the current code if you need a deeper 9 understanding. 10 11.. note:: 12 The Memory Resource Controller has generically been referred to as the 13 memory controller in this document. Do not confuse memory controller 14 used here with the memory controller that is used in hardware. 15 16.. hint:: 17 When we mention a cgroup (cgroupfs's directory) with memory controller, 18 we call it "memory cgroup". When you see git-log and source code, you'll 19 see patch's title and function names tend to use "memcg". 20 In this document, we avoid using it. 21 22Benefits and Purpose of the memory controller 23============================================= 24 25The memory controller isolates the memory behaviour of a group of tasks 26from the rest of the system. The article on LWN [12]_ mentions some probable 27uses of the memory controller. The memory controller can be used to 28 29a. Isolate an application or a group of applications 30 Memory-hungry applications can be isolated and limited to a smaller 31 amount of memory. 32b. Create a cgroup with a limited amount of memory; this can be used 33 as a good alternative to booting with mem=XXXX. 34c. Virtualization solutions can control the amount of memory they want 35 to assign to a virtual machine instance. 36d. A CD/DVD burner could control the amount of memory used by the 37 rest of the system to ensure that burning does not fail due to lack 38 of available memory. 39e. There are several other use cases; find one or use the controller just 40 for fun (to learn and hack on the VM subsystem). 41 42Current Status: linux-2.6.34-mmotm(development version of 2010/April) 43 44Features: 45 46 - accounting anonymous pages, file caches, swap caches usage and limiting them. 47 - pages are linked to per-memcg LRU exclusively, and there is no global LRU. 48 - optionally, memory+swap usage can be accounted and limited. 49 - hierarchical accounting 50 - soft limit 51 - moving (recharging) account at moving a task is selectable. 52 - usage threshold notifier 53 - memory pressure notifier 54 - oom-killer disable knob and oom-notifier 55 - Root cgroup has no limit controls. 56 57 Kernel memory support is a work in progress, and the current version provides 58 basically functionality. (See :ref:`section 2.7 59 <cgroup-v1-memory-kernel-extension>`) 60 61Brief summary of control files. 62 63==================================== ========================================== 64 tasks attach a task(thread) and show list of 65 threads 66 cgroup.procs show list of processes 67 cgroup.event_control an interface for event_fd() 68 This knob is not available on CONFIG_PREEMPT_RT systems. 69 memory.usage_in_bytes show current usage for memory 70 (See 5.5 for details) 71 memory.memsw.usage_in_bytes show current usage for memory+Swap 72 (See 5.5 for details) 73 memory.limit_in_bytes set/show limit of memory usage 74 memory.memsw.limit_in_bytes set/show limit of memory+Swap usage 75 memory.failcnt show the number of memory usage hits limits 76 memory.memsw.failcnt show the number of memory+Swap hits limits 77 memory.max_usage_in_bytes show max memory usage recorded 78 memory.memsw.max_usage_in_bytes show max memory+Swap usage recorded 79 memory.soft_limit_in_bytes set/show soft limit of memory usage 80 This knob is not available on CONFIG_PREEMPT_RT systems. 81 memory.stat show various statistics 82 memory.use_hierarchy set/show hierarchical account enabled 83 This knob is deprecated and shouldn't be 84 used. 85 memory.force_empty trigger forced page reclaim 86 memory.pressure_level set memory pressure notifications 87 memory.swappiness set/show swappiness parameter of vmscan 88 (See sysctl's vm.swappiness) 89 memory.move_charge_at_immigrate set/show controls of moving charges 90 This knob is deprecated and shouldn't be 91 used. 92 memory.oom_control set/show oom controls. 93 memory.numa_stat show the number of memory usage per numa 94 node 95 memory.kmem.limit_in_bytes Deprecated knob to set and read the kernel 96 memory hard limit. Kernel hard limit is not 97 supported since 5.16. Writing any value to 98 do file will not have any effect same as if 99 nokmem kernel parameter was specified. 100 Kernel memory is still charged and reported 101 by memory.kmem.usage_in_bytes. 102 memory.kmem.usage_in_bytes show current kernel memory allocation 103 memory.kmem.failcnt show the number of kernel memory usage 104 hits limits 105 memory.kmem.max_usage_in_bytes show max kernel memory usage recorded 106 107 memory.kmem.tcp.limit_in_bytes set/show hard limit for tcp buf memory 108 memory.kmem.tcp.usage_in_bytes show current tcp buf memory allocation 109 memory.kmem.tcp.failcnt show the number of tcp buf memory usage 110 hits limits 111 memory.kmem.tcp.max_usage_in_bytes show max tcp buf memory usage recorded 112==================================== ========================================== 113 1141. History 115========== 116 117The memory controller has a long history. A request for comments for the memory 118controller was posted by Balbir Singh [1]_. At the time the RFC was posted 119there were several implementations for memory control. The goal of the 120RFC was to build consensus and agreement for the minimal features required 121for memory control. The first RSS controller was posted by Balbir Singh [2]_ 122in Feb 2007. Pavel Emelianov [3]_ [4]_ [5]_ has since posted three versions 123of the RSS controller. At OLS, at the resource management BoF, everyone 124suggested that we handle both page cache and RSS together. Another request was 125raised to allow user space handling of OOM. The current memory controller is 126at version 6; it combines both mapped (RSS) and unmapped Page 127Cache Control [11]_. 128 1292. Memory Control 130================= 131 132Memory is a unique resource in the sense that it is present in a limited 133amount. If a task requires a lot of CPU processing, the task can spread 134its processing over a period of hours, days, months or years, but with 135memory, the same physical memory needs to be reused to accomplish the task. 136 137The memory controller implementation has been divided into phases. These 138are: 139 1401. Memory controller 1412. mlock(2) controller 1423. Kernel user memory accounting and slab control 1434. user mappings length controller 144 145The memory controller is the first controller developed. 146 1472.1. Design 148----------- 149 150The core of the design is a counter called the page_counter. The 151page_counter tracks the current memory usage and limit of the group of 152processes associated with the controller. Each cgroup has a memory controller 153specific data structure (mem_cgroup) associated with it. 154 1552.2. Accounting 156--------------- 157 158.. code-block:: 159 :caption: Figure 1: Hierarchy of Accounting 160 161 +--------------------+ 162 | mem_cgroup | 163 | (page_counter) | 164 +--------------------+ 165 / ^ \ 166 / | \ 167 +---------------+ | +---------------+ 168 | mm_struct | |.... | mm_struct | 169 | | | | | 170 +---------------+ | +---------------+ 171 | 172 + --------------+ 173 | 174 +---------------+ +------+--------+ 175 | page +----------> page_cgroup| 176 | | | | 177 +---------------+ +---------------+ 178 179 180 181Figure 1 shows the important aspects of the controller 182 1831. Accounting happens per cgroup 1842. Each mm_struct knows about which cgroup it belongs to 1853. Each page has a pointer to the page_cgroup, which in turn knows the 186 cgroup it belongs to 187 188The accounting is done as follows: mem_cgroup_charge_common() is invoked to 189set up the necessary data structures and check if the cgroup that is being 190charged is over its limit. If it is, then reclaim is invoked on the cgroup. 191More details can be found in the reclaim section of this document. 192If everything goes well, a page meta-data-structure called page_cgroup is 193updated. page_cgroup has its own LRU on cgroup. 194(*) page_cgroup structure is allocated at boot/memory-hotplug time. 195 1962.2.1 Accounting details 197------------------------ 198 199All mapped anon pages (RSS) and cache pages (Page Cache) are accounted. 200Some pages which are never reclaimable and will not be on the LRU 201are not accounted. We just account pages under usual VM management. 202 203RSS pages are accounted at page_fault unless they've already been accounted 204for earlier. A file page will be accounted for as Page Cache when it's 205inserted into inode (xarray). While it's mapped into the page tables of 206processes, duplicate accounting is carefully avoided. 207 208An RSS page is unaccounted when it's fully unmapped. A PageCache page is 209unaccounted when it's removed from xarray. Even if RSS pages are fully 210unmapped (by kswapd), they may exist as SwapCache in the system until they 211are really freed. Such SwapCaches are also accounted. 212A swapped-in page is accounted after adding into swapcache. 213 214Note: The kernel does swapin-readahead and reads multiple swaps at once. 215Since page's memcg recorded into swap whatever memsw enabled, the page will 216be accounted after swapin. 217 218At page migration, accounting information is kept. 219 220Note: we just account pages-on-LRU because our purpose is to control amount 221of used pages; not-on-LRU pages tend to be out-of-control from VM view. 222 2232.3 Shared Page Accounting 224-------------------------- 225 226Shared pages are accounted on the basis of the first touch approach. The 227cgroup that first touches a page is accounted for the page. The principle 228behind this approach is that a cgroup that aggressively uses a shared 229page will eventually get charged for it (once it is uncharged from 230the cgroup that brought it in -- this will happen on memory pressure). 231 232But see :ref:`section 8.2 <cgroup-v1-memory-movable-charges>` when moving a 233task to another cgroup, its pages may be recharged to the new cgroup, if 234move_charge_at_immigrate has been chosen. 235 2362.4 Swap Extension 237-------------------------------------- 238 239Swap usage is always recorded for each of cgroup. Swap Extension allows you to 240read and limit it. 241 242When CONFIG_SWAP is enabled, following files are added. 243 244 - memory.memsw.usage_in_bytes. 245 - memory.memsw.limit_in_bytes. 246 247memsw means memory+swap. Usage of memory+swap is limited by 248memsw.limit_in_bytes. 249 250Example: Assume a system with 4G of swap. A task which allocates 6G of memory 251(by mistake) under 2G memory limitation will use all swap. 252In this case, setting memsw.limit_in_bytes=3G will prevent bad use of swap. 253By using the memsw limit, you can avoid system OOM which can be caused by swap 254shortage. 255 2562.4.1 why 'memory+swap' rather than swap 257~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 258 259The global LRU(kswapd) can swap out arbitrary pages. Swap-out means 260to move account from memory to swap...there is no change in usage of 261memory+swap. In other words, when we want to limit the usage of swap without 262affecting global LRU, memory+swap limit is better than just limiting swap from 263an OS point of view. 264 2652.4.2. What happens when a cgroup hits memory.memsw.limit_in_bytes 266~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 267 268When a cgroup hits memory.memsw.limit_in_bytes, it's useless to do swap-out 269in this cgroup. Then, swap-out will not be done by cgroup routine and file 270caches are dropped. But as mentioned above, global LRU can do swapout memory 271from it for sanity of the system's memory management state. You can't forbid 272it by cgroup. 273 2742.5 Reclaim 275----------- 276 277Each cgroup maintains a per cgroup LRU which has the same structure as 278global VM. When a cgroup goes over its limit, we first try 279to reclaim memory from the cgroup so as to make space for the new 280pages that the cgroup has touched. If the reclaim is unsuccessful, 281an OOM routine is invoked to select and kill the bulkiest task in the 282cgroup. (See :ref:`10. OOM Control <cgroup-v1-memory-oom-control>` below.) 283 284The reclaim algorithm has not been modified for cgroups, except that 285pages that are selected for reclaiming come from the per-cgroup LRU 286list. 287 288.. note:: 289 Reclaim does not work for the root cgroup, since we cannot set any 290 limits on the root cgroup. 291 292.. note:: 293 When panic_on_oom is set to "2", the whole system will panic. 294 295When oom event notifier is registered, event will be delivered. 296(See :ref:`oom_control <cgroup-v1-memory-oom-control>` section) 297 2982.6 Locking 299----------- 300 301Lock order is as follows:: 302 303 Page lock (PG_locked bit of page->flags) 304 mm->page_table_lock or split pte_lock 305 folio_memcg_lock (memcg->move_lock) 306 mapping->i_pages lock 307 lruvec->lru_lock. 308 309Per-node-per-memcgroup LRU (cgroup's private LRU) is guarded by 310lruvec->lru_lock; PG_lru bit of page->flags is cleared before 311isolating a page from its LRU under lruvec->lru_lock. 312 313.. _cgroup-v1-memory-kernel-extension: 314 3152.7 Kernel Memory Extension 316----------------------------------------------- 317 318With the Kernel memory extension, the Memory Controller is able to limit 319the amount of kernel memory used by the system. Kernel memory is fundamentally 320different than user memory, since it can't be swapped out, which makes it 321possible to DoS the system by consuming too much of this precious resource. 322 323Kernel memory accounting is enabled for all memory cgroups by default. But 324it can be disabled system-wide by passing cgroup.memory=nokmem to the kernel 325at boot time. In this case, kernel memory will not be accounted at all. 326 327Kernel memory limits are not imposed for the root cgroup. Usage for the root 328cgroup may or may not be accounted. The memory used is accumulated into 329memory.kmem.usage_in_bytes, or in a separate counter when it makes sense. 330(currently only for tcp). 331 332The main "kmem" counter is fed into the main counter, so kmem charges will 333also be visible from the user counter. 334 335Currently no soft limit is implemented for kernel memory. It is future work 336to trigger slab reclaim when those limits are reached. 337 3382.7.1 Current Kernel Memory resources accounted 339----------------------------------------------- 340 341stack pages: 342 every process consumes some stack pages. By accounting into 343 kernel memory, we prevent new processes from being created when the kernel 344 memory usage is too high. 345 346slab pages: 347 pages allocated by the SLAB or SLUB allocator are tracked. A copy 348 of each kmem_cache is created every time the cache is touched by the first time 349 from inside the memcg. The creation is done lazily, so some objects can still be 350 skipped while the cache is being created. All objects in a slab page should 351 belong to the same memcg. This only fails to hold when a task is migrated to a 352 different memcg during the page allocation by the cache. 353 354sockets memory pressure: 355 some sockets protocols have memory pressure 356 thresholds. The Memory Controller allows them to be controlled individually 357 per cgroup, instead of globally. 358 359tcp memory pressure: 360 sockets memory pressure for the tcp protocol. 361 3622.7.2 Common use cases 363---------------------- 364 365Because the "kmem" counter is fed to the main user counter, kernel memory can 366never be limited completely independently of user memory. Say "U" is the user 367limit, and "K" the kernel limit. There are three possible ways limits can be 368set: 369 370U != 0, K = unlimited: 371 This is the standard memcg limitation mechanism already present before kmem 372 accounting. Kernel memory is completely ignored. 373 374U != 0, K < U: 375 Kernel memory is a subset of the user memory. This setup is useful in 376 deployments where the total amount of memory per-cgroup is overcommitted. 377 Overcommitting kernel memory limits is definitely not recommended, since the 378 box can still run out of non-reclaimable memory. 379 In this case, the admin could set up K so that the sum of all groups is 380 never greater than the total memory, and freely set U at the cost of his 381 QoS. 382 383 .. warning:: 384 In the current implementation, memory reclaim will NOT be triggered for 385 a cgroup when it hits K while staying below U, which makes this setup 386 impractical. 387 388U != 0, K >= U: 389 Since kmem charges will also be fed to the user counter and reclaim will be 390 triggered for the cgroup for both kinds of memory. This setup gives the 391 admin a unified view of memory, and it is also useful for people who just 392 want to track kernel memory usage. 393 3943. User Interface 395================= 396 397To use the user interface: 398 3991. Enable CONFIG_CGROUPS and CONFIG_MEMCG options 4002. Prepare the cgroups (see :ref:`Why are cgroups needed? 401 <cgroups-why-needed>` for the background information):: 402 403 # mount -t tmpfs none /sys/fs/cgroup 404 # mkdir /sys/fs/cgroup/memory 405 # mount -t cgroup none /sys/fs/cgroup/memory -o memory 406 4073. Make the new group and move bash into it:: 408 409 # mkdir /sys/fs/cgroup/memory/0 410 # echo $$ > /sys/fs/cgroup/memory/0/tasks 411 4124. Since now we're in the 0 cgroup, we can alter the memory limit:: 413 414 # echo 4M > /sys/fs/cgroup/memory/0/memory.limit_in_bytes 415 416 The limit can now be queried:: 417 418 # cat /sys/fs/cgroup/memory/0/memory.limit_in_bytes 419 4194304 420 421.. note:: 422 We can use a suffix (k, K, m, M, g or G) to indicate values in kilo, 423 mega or gigabytes. (Here, Kilo, Mega, Giga are Kibibytes, Mebibytes, 424 Gibibytes.) 425 426.. note:: 427 We can write "-1" to reset the ``*.limit_in_bytes(unlimited)``. 428 429.. note:: 430 We cannot set limits on the root cgroup any more. 431 432 433We can check the usage:: 434 435 # cat /sys/fs/cgroup/memory/0/memory.usage_in_bytes 436 1216512 437 438A successful write to this file does not guarantee a successful setting of 439this limit to the value written into the file. This can be due to a 440number of factors, such as rounding up to page boundaries or the total 441availability of memory on the system. The user is required to re-read 442this file after a write to guarantee the value committed by the kernel:: 443 444 # echo 1 > memory.limit_in_bytes 445 # cat memory.limit_in_bytes 446 4096 447 448The memory.failcnt field gives the number of times that the cgroup limit was 449exceeded. 450 451The memory.stat file gives accounting information. Now, the number of 452caches, RSS and Active pages/Inactive pages are shown. 453 4544. Testing 455========== 456 457For testing features and implementation, see memcg_test.txt. 458 459Performance test is also important. To see pure memory controller's overhead, 460testing on tmpfs will give you good numbers of small overheads. 461Example: do kernel make on tmpfs. 462 463Page-fault scalability is also important. At measuring parallel 464page fault test, multi-process test may be better than multi-thread 465test because it has noise of shared objects/status. 466 467But the above two are testing extreme situations. 468Trying usual test under memory controller is always helpful. 469 470.. _cgroup-v1-memory-test-troubleshoot: 471 4724.1 Troubleshooting 473------------------- 474 475Sometimes a user might find that the application under a cgroup is 476terminated by the OOM killer. There are several causes for this: 477 4781. The cgroup limit is too low (just too low to do anything useful) 4792. The user is using anonymous memory and swap is turned off or too low 480 481A sync followed by echo 1 > /proc/sys/vm/drop_caches will help get rid of 482some of the pages cached in the cgroup (page cache pages). 483 484To know what happens, disabling OOM_Kill as per :ref:`"10. OOM Control" 485<cgroup-v1-memory-oom-control>` (below) and seeing what happens will be 486helpful. 487 488.. _cgroup-v1-memory-test-task-migration: 489 4904.2 Task migration 491------------------ 492 493When a task migrates from one cgroup to another, its charge is not 494carried forward by default. The pages allocated from the original cgroup still 495remain charged to it, the charge is dropped when the page is freed or 496reclaimed. 497 498You can move charges of a task along with task migration. 499See :ref:`8. "Move charges at task migration" <cgroup-v1-memory-move-charges>` 500 5014.3 Removing a cgroup 502--------------------- 503 504A cgroup can be removed by rmdir, but as discussed in :ref:`sections 4.1 505<cgroup-v1-memory-test-troubleshoot>` and :ref:`4.2 506<cgroup-v1-memory-test-task-migration>`, a cgroup might have some charge 507associated with it, even though all tasks have migrated away from it. (because 508we charge against pages, not against tasks.) 509 510We move the stats to parent, and no change on the charge except uncharging 511from the child. 512 513Charges recorded in swap information is not updated at removal of cgroup. 514Recorded information is discarded and a cgroup which uses swap (swapcache) 515will be charged as a new owner of it. 516 5175. Misc. interfaces 518=================== 519 5205.1 force_empty 521--------------- 522 memory.force_empty interface is provided to make cgroup's memory usage empty. 523 When writing anything to this:: 524 525 # echo 0 > memory.force_empty 526 527 the cgroup will be reclaimed and as many pages reclaimed as possible. 528 529 The typical use case for this interface is before calling rmdir(). 530 Though rmdir() offlines memcg, but the memcg may still stay there due to 531 charged file caches. Some out-of-use page caches may keep charged until 532 memory pressure happens. If you want to avoid that, force_empty will be useful. 533 5345.2 stat file 535------------- 536 537memory.stat file includes following statistics: 538 539 * per-memory cgroup local status 540 541 =============== =============================================================== 542 cache # of bytes of page cache memory. 543 rss # of bytes of anonymous and swap cache memory (includes 544 transparent hugepages). 545 rss_huge # of bytes of anonymous transparent hugepages. 546 mapped_file # of bytes of mapped file (includes tmpfs/shmem) 547 pgpgin # of charging events to the memory cgroup. The charging 548 event happens each time a page is accounted as either mapped 549 anon page(RSS) or cache page(Page Cache) to the cgroup. 550 pgpgout # of uncharging events to the memory cgroup. The uncharging 551 event happens each time a page is unaccounted from the 552 cgroup. 553 swap # of bytes of swap usage 554 dirty # of bytes that are waiting to get written back to the disk. 555 writeback # of bytes of file/anon cache that are queued for syncing to 556 disk. 557 inactive_anon # of bytes of anonymous and swap cache memory on inactive 558 LRU list. 559 active_anon # of bytes of anonymous and swap cache memory on active 560 LRU list. 561 inactive_file # of bytes of file-backed memory and MADV_FREE anonymous 562 memory (LazyFree pages) on inactive LRU list. 563 active_file # of bytes of file-backed memory on active LRU list. 564 unevictable # of bytes of memory that cannot be reclaimed (mlocked etc). 565 =============== =============================================================== 566 567 * status considering hierarchy (see memory.use_hierarchy settings): 568 569 ========================= =================================================== 570 hierarchical_memory_limit # of bytes of memory limit with regard to 571 hierarchy 572 under which the memory cgroup is 573 hierarchical_memsw_limit # of bytes of memory+swap limit with regard to 574 hierarchy under which memory cgroup is. 575 576 total_<counter> # hierarchical version of <counter>, which in 577 addition to the cgroup's own value includes the 578 sum of all hierarchical children's values of 579 <counter>, i.e. total_cache 580 ========================= =================================================== 581 582 * additional vm parameters (depends on CONFIG_DEBUG_VM): 583 584 ========================= ======================================== 585 recent_rotated_anon VM internal parameter. (see mm/vmscan.c) 586 recent_rotated_file VM internal parameter. (see mm/vmscan.c) 587 recent_scanned_anon VM internal parameter. (see mm/vmscan.c) 588 recent_scanned_file VM internal parameter. (see mm/vmscan.c) 589 ========================= ======================================== 590 591.. hint:: 592 recent_rotated means recent frequency of LRU rotation. 593 recent_scanned means recent # of scans to LRU. 594 showing for better debug please see the code for meanings. 595 596.. note:: 597 Only anonymous and swap cache memory is listed as part of 'rss' stat. 598 This should not be confused with the true 'resident set size' or the 599 amount of physical memory used by the cgroup. 600 601 'rss + mapped_file" will give you resident set size of cgroup. 602 603 (Note: file and shmem may be shared among other cgroups. In that case, 604 mapped_file is accounted only when the memory cgroup is owner of page 605 cache.) 606 6075.3 swappiness 608-------------- 609 610Overrides /proc/sys/vm/swappiness for the particular group. The tunable 611in the root cgroup corresponds to the global swappiness setting. 612 613Please note that unlike during the global reclaim, limit reclaim 614enforces that 0 swappiness really prevents from any swapping even if 615there is a swap storage available. This might lead to memcg OOM killer 616if there are no file pages to reclaim. 617 6185.4 failcnt 619----------- 620 621A memory cgroup provides memory.failcnt and memory.memsw.failcnt files. 622This failcnt(== failure count) shows the number of times that a usage counter 623hit its limit. When a memory cgroup hits a limit, failcnt increases and 624memory under it will be reclaimed. 625 626You can reset failcnt by writing 0 to failcnt file:: 627 628 # echo 0 > .../memory.failcnt 629 6305.5 usage_in_bytes 631------------------ 632 633For efficiency, as other kernel components, memory cgroup uses some optimization 634to avoid unnecessary cacheline false sharing. usage_in_bytes is affected by the 635method and doesn't show 'exact' value of memory (and swap) usage, it's a fuzz 636value for efficient access. (Of course, when necessary, it's synchronized.) 637If you want to know more exact memory usage, you should use RSS+CACHE(+SWAP) 638value in memory.stat(see 5.2). 639 6405.6 numa_stat 641------------- 642 643This is similar to numa_maps but operates on a per-memcg basis. This is 644useful for providing visibility into the numa locality information within 645an memcg since the pages are allowed to be allocated from any physical 646node. One of the use cases is evaluating application performance by 647combining this information with the application's CPU allocation. 648 649Each memcg's numa_stat file includes "total", "file", "anon" and "unevictable" 650per-node page counts including "hierarchical_<counter>" which sums up all 651hierarchical children's values in addition to the memcg's own value. 652 653The output format of memory.numa_stat is:: 654 655 total=<total pages> N0=<node 0 pages> N1=<node 1 pages> ... 656 file=<total file pages> N0=<node 0 pages> N1=<node 1 pages> ... 657 anon=<total anon pages> N0=<node 0 pages> N1=<node 1 pages> ... 658 unevictable=<total anon pages> N0=<node 0 pages> N1=<node 1 pages> ... 659 hierarchical_<counter>=<counter pages> N0=<node 0 pages> N1=<node 1 pages> ... 660 661The "total" count is sum of file + anon + unevictable. 662 6636. Hierarchy support 664==================== 665 666The memory controller supports a deep hierarchy and hierarchical accounting. 667The hierarchy is created by creating the appropriate cgroups in the 668cgroup filesystem. Consider for example, the following cgroup filesystem 669hierarchy:: 670 671 root 672 / | \ 673 / | \ 674 a b c 675 | \ 676 | \ 677 d e 678 679In the diagram above, with hierarchical accounting enabled, all memory 680usage of e, is accounted to its ancestors up until the root (i.e, c and root). 681If one of the ancestors goes over its limit, the reclaim algorithm reclaims 682from the tasks in the ancestor and the children of the ancestor. 683 6846.1 Hierarchical accounting and reclaim 685--------------------------------------- 686 687Hierarchical accounting is enabled by default. Disabling the hierarchical 688accounting is deprecated. An attempt to do it will result in a failure 689and a warning printed to dmesg. 690 691For compatibility reasons writing 1 to memory.use_hierarchy will always pass:: 692 693 # echo 1 > memory.use_hierarchy 694 6957. Soft limits 696============== 697 698Soft limits allow for greater sharing of memory. The idea behind soft limits 699is to allow control groups to use as much of the memory as needed, provided 700 701a. There is no memory contention 702b. They do not exceed their hard limit 703 704When the system detects memory contention or low memory, control groups 705are pushed back to their soft limits. If the soft limit of each control 706group is very high, they are pushed back as much as possible to make 707sure that one control group does not starve the others of memory. 708 709Please note that soft limits is a best-effort feature; it comes with 710no guarantees, but it does its best to make sure that when memory is 711heavily contended for, memory is allocated based on the soft limit 712hints/setup. Currently soft limit based reclaim is set up such that 713it gets invoked from balance_pgdat (kswapd). 714 7157.1 Interface 716------------- 717 718Soft limits can be setup by using the following commands (in this example we 719assume a soft limit of 256 MiB):: 720 721 # echo 256M > memory.soft_limit_in_bytes 722 723If we want to change this to 1G, we can at any time use:: 724 725 # echo 1G > memory.soft_limit_in_bytes 726 727.. note:: 728 Soft limits take effect over a long period of time, since they involve 729 reclaiming memory for balancing between memory cgroups 730 731.. note:: 732 It is recommended to set the soft limit always below the hard limit, 733 otherwise the hard limit will take precedence. 734 735.. _cgroup-v1-memory-move-charges: 736 7378. Move charges at task migration (DEPRECATED!) 738=============================================== 739 740THIS IS DEPRECATED! 741 742It's expensive and unreliable! It's better practice to launch workload 743tasks directly from inside their target cgroup. Use dedicated workload 744cgroups to allow fine-grained policy adjustments without having to 745move physical pages between control domains. 746 747Users can move charges associated with a task along with task migration, that 748is, uncharge task's pages from the old cgroup and charge them to the new cgroup. 749This feature is not supported in !CONFIG_MMU environments because of lack of 750page tables. 751 7528.1 Interface 753------------- 754 755This feature is disabled by default. It can be enabled (and disabled again) by 756writing to memory.move_charge_at_immigrate of the destination cgroup. 757 758If you want to enable it:: 759 760 # echo (some positive value) > memory.move_charge_at_immigrate 761 762.. note:: 763 Each bits of move_charge_at_immigrate has its own meaning about what type 764 of charges should be moved. See :ref:`section 8.2 765 <cgroup-v1-memory-movable-charges>` for details. 766 767.. note:: 768 Charges are moved only when you move mm->owner, in other words, 769 a leader of a thread group. 770 771.. note:: 772 If we cannot find enough space for the task in the destination cgroup, we 773 try to make space by reclaiming memory. Task migration may fail if we 774 cannot make enough space. 775 776.. note:: 777 It can take several seconds if you move charges much. 778 779And if you want disable it again:: 780 781 # echo 0 > memory.move_charge_at_immigrate 782 783.. _cgroup-v1-memory-movable-charges: 784 7858.2 Type of charges which can be moved 786-------------------------------------- 787 788Each bit in move_charge_at_immigrate has its own meaning about what type of 789charges should be moved. But in any case, it must be noted that an account of 790a page or a swap can be moved only when it is charged to the task's current 791(old) memory cgroup. 792 793+---+--------------------------------------------------------------------------+ 794|bit| what type of charges would be moved ? | 795+===+==========================================================================+ 796| 0 | A charge of an anonymous page (or swap of it) used by the target task. | 797| | You must enable Swap Extension (see 2.4) to enable move of swap charges. | 798+---+--------------------------------------------------------------------------+ 799| 1 | A charge of file pages (normal file, tmpfs file (e.g. ipc shared memory) | 800| | and swaps of tmpfs file) mmapped by the target task. Unlike the case of | 801| | anonymous pages, file pages (and swaps) in the range mmapped by the task | 802| | will be moved even if the task hasn't done page fault, i.e. they might | 803| | not be the task's "RSS", but other task's "RSS" that maps the same file. | 804| | And mapcount of the page is ignored (the page can be moved even if | 805| | page_mapcount(page) > 1). You must enable Swap Extension (see 2.4) to | 806| | enable move of swap charges. | 807+---+--------------------------------------------------------------------------+ 808 8098.3 TODO 810-------- 811 812- All of moving charge operations are done under cgroup_mutex. It's not good 813 behavior to hold the mutex too long, so we may need some trick. 814 8159. Memory thresholds 816==================== 817 818Memory cgroup implements memory thresholds using the cgroups notification 819API (see cgroups.txt). It allows to register multiple memory and memsw 820thresholds and gets notifications when it crosses. 821 822To register a threshold, an application must: 823 824- create an eventfd using eventfd(2); 825- open memory.usage_in_bytes or memory.memsw.usage_in_bytes; 826- write string like "<event_fd> <fd of memory.usage_in_bytes> <threshold>" to 827 cgroup.event_control. 828 829Application will be notified through eventfd when memory usage crosses 830threshold in any direction. 831 832It's applicable for root and non-root cgroup. 833 834.. _cgroup-v1-memory-oom-control: 835 83610. OOM Control 837=============== 838 839memory.oom_control file is for OOM notification and other controls. 840 841Memory cgroup implements OOM notifier using the cgroup notification 842API (See cgroups.txt). It allows to register multiple OOM notification 843delivery and gets notification when OOM happens. 844 845To register a notifier, an application must: 846 847 - create an eventfd using eventfd(2) 848 - open memory.oom_control file 849 - write string like "<event_fd> <fd of memory.oom_control>" to 850 cgroup.event_control 851 852The application will be notified through eventfd when OOM happens. 853OOM notification doesn't work for the root cgroup. 854 855You can disable the OOM-killer by writing "1" to memory.oom_control file, as: 856 857 #echo 1 > memory.oom_control 858 859If OOM-killer is disabled, tasks under cgroup will hang/sleep 860in memory cgroup's OOM-waitqueue when they request accountable memory. 861 862For running them, you have to relax the memory cgroup's OOM status by 863 864 * enlarge limit or reduce usage. 865 866To reduce usage, 867 868 * kill some tasks. 869 * move some tasks to other group with account migration. 870 * remove some files (on tmpfs?) 871 872Then, stopped tasks will work again. 873 874At reading, current status of OOM is shown. 875 876 - oom_kill_disable 0 or 1 877 (if 1, oom-killer is disabled) 878 - under_oom 0 or 1 879 (if 1, the memory cgroup is under OOM, tasks may be stopped.) 880 - oom_kill integer counter 881 The number of processes belonging to this cgroup killed by any 882 kind of OOM killer. 883 88411. Memory Pressure 885=================== 886 887The pressure level notifications can be used to monitor the memory 888allocation cost; based on the pressure, applications can implement 889different strategies of managing their memory resources. The pressure 890levels are defined as following: 891 892The "low" level means that the system is reclaiming memory for new 893allocations. Monitoring this reclaiming activity might be useful for 894maintaining cache level. Upon notification, the program (typically 895"Activity Manager") might analyze vmstat and act in advance (i.e. 896prematurely shutdown unimportant services). 897 898The "medium" level means that the system is experiencing medium memory 899pressure, the system might be making swap, paging out active file caches, 900etc. Upon this event applications may decide to further analyze 901vmstat/zoneinfo/memcg or internal memory usage statistics and free any 902resources that can be easily reconstructed or re-read from a disk. 903 904The "critical" level means that the system is actively thrashing, it is 905about to out of memory (OOM) or even the in-kernel OOM killer is on its 906way to trigger. Applications should do whatever they can to help the 907system. It might be too late to consult with vmstat or any other 908statistics, so it's advisable to take an immediate action. 909 910By default, events are propagated upward until the event is handled, i.e. the 911events are not pass-through. For example, you have three cgroups: A->B->C. Now 912you set up an event listener on cgroups A, B and C, and suppose group C 913experiences some pressure. In this situation, only group C will receive the 914notification, i.e. groups A and B will not receive it. This is done to avoid 915excessive "broadcasting" of messages, which disturbs the system and which is 916especially bad if we are low on memory or thrashing. Group B, will receive 917notification only if there are no event listeners for group C. 918 919There are three optional modes that specify different propagation behavior: 920 921 - "default": this is the default behavior specified above. This mode is the 922 same as omitting the optional mode parameter, preserved by backwards 923 compatibility. 924 925 - "hierarchy": events always propagate up to the root, similar to the default 926 behavior, except that propagation continues regardless of whether there are 927 event listeners at each level, with the "hierarchy" mode. In the above 928 example, groups A, B, and C will receive notification of memory pressure. 929 930 - "local": events are pass-through, i.e. they only receive notifications when 931 memory pressure is experienced in the memcg for which the notification is 932 registered. In the above example, group C will receive notification if 933 registered for "local" notification and the group experiences memory 934 pressure. However, group B will never receive notification, regardless if 935 there is an event listener for group C or not, if group B is registered for 936 local notification. 937 938The level and event notification mode ("hierarchy" or "local", if necessary) are 939specified by a comma-delimited string, i.e. "low,hierarchy" specifies 940hierarchical, pass-through, notification for all ancestor memcgs. Notification 941that is the default, non pass-through behavior, does not specify a mode. 942"medium,local" specifies pass-through notification for the medium level. 943 944The file memory.pressure_level is only used to setup an eventfd. To 945register a notification, an application must: 946 947- create an eventfd using eventfd(2); 948- open memory.pressure_level; 949- write string as "<event_fd> <fd of memory.pressure_level> <level[,mode]>" 950 to cgroup.event_control. 951 952Application will be notified through eventfd when memory pressure is at 953the specific level (or higher). Read/write operations to 954memory.pressure_level are no implemented. 955 956Test: 957 958 Here is a small script example that makes a new cgroup, sets up a 959 memory limit, sets up a notification in the cgroup and then makes child 960 cgroup experience a critical pressure:: 961 962 # cd /sys/fs/cgroup/memory/ 963 # mkdir foo 964 # cd foo 965 # cgroup_event_listener memory.pressure_level low,hierarchy & 966 # echo 8000000 > memory.limit_in_bytes 967 # echo 8000000 > memory.memsw.limit_in_bytes 968 # echo $$ > tasks 969 # dd if=/dev/zero | read x 970 971 (Expect a bunch of notifications, and eventually, the oom-killer will 972 trigger.) 973 97412. TODO 975======== 976 9771. Make per-cgroup scanner reclaim not-shared pages first 9782. Teach controller to account for shared-pages 9793. Start reclamation in the background when the limit is 980 not yet hit but the usage is getting closer 981 982Summary 983======= 984 985Overall, the memory controller has been a stable controller and has been 986commented and discussed quite extensively in the community. 987 988References 989========== 990 991.. [1] Singh, Balbir. RFC: Memory Controller, http://lwn.net/Articles/206697/ 992.. [2] Singh, Balbir. Memory Controller (RSS Control), 993 http://lwn.net/Articles/222762/ 994.. [3] Emelianov, Pavel. Resource controllers based on process cgroups 995 https://lore.kernel.org/r/45ED7DEC.7010403@sw.ru 996.. [4] Emelianov, Pavel. RSS controller based on process cgroups (v2) 997 https://lore.kernel.org/r/461A3010.90403@sw.ru 998.. [5] Emelianov, Pavel. RSS controller based on process cgroups (v3) 999 https://lore.kernel.org/r/465D9739.8070209@openvz.org 1000 10016. Menage, Paul. Control Groups v10, http://lwn.net/Articles/236032/ 10027. Vaidyanathan, Srinivasan, Control Groups: Pagecache accounting and control 1003 subsystem (v3), http://lwn.net/Articles/235534/ 10048. Singh, Balbir. RSS controller v2 test results (lmbench), 1005 https://lore.kernel.org/r/464C95D4.7070806@linux.vnet.ibm.com 10069. Singh, Balbir. RSS controller v2 AIM9 results 1007 https://lore.kernel.org/r/464D267A.50107@linux.vnet.ibm.com 100810. Singh, Balbir. Memory controller v6 test results, 1009 https://lore.kernel.org/r/20070819094658.654.84837.sendpatchset@balbir-laptop 1010 1011.. [11] Singh, Balbir. Memory controller introduction (v6), 1012 https://lore.kernel.org/r/20070817084228.26003.12568.sendpatchset@balbir-laptop 1013.. [12] Corbet, Jonathan, Controlling memory use in cgroups, 1014 http://lwn.net/Articles/243795/ 1015