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 swapcached # of bytes of swap cached in memory 555 dirty # of bytes that are waiting to get written back to the disk. 556 writeback # of bytes of file/anon cache that are queued for syncing to 557 disk. 558 inactive_anon # of bytes of anonymous and swap cache memory on inactive 559 LRU list. 560 active_anon # of bytes of anonymous and swap cache memory on active 561 LRU list. 562 inactive_file # of bytes of file-backed memory and MADV_FREE anonymous 563 memory (LazyFree pages) on inactive LRU list. 564 active_file # of bytes of file-backed memory on active LRU list. 565 unevictable # of bytes of memory that cannot be reclaimed (mlocked etc). 566 =============== =============================================================== 567 568 * status considering hierarchy (see memory.use_hierarchy settings): 569 570 ========================= =================================================== 571 hierarchical_memory_limit # of bytes of memory limit with regard to 572 hierarchy 573 under which the memory cgroup is 574 hierarchical_memsw_limit # of bytes of memory+swap limit with regard to 575 hierarchy under which memory cgroup is. 576 577 total_<counter> # hierarchical version of <counter>, which in 578 addition to the cgroup's own value includes the 579 sum of all hierarchical children's values of 580 <counter>, i.e. total_cache 581 ========================= =================================================== 582 583 * additional vm parameters (depends on CONFIG_DEBUG_VM): 584 585 ========================= ======================================== 586 recent_rotated_anon VM internal parameter. (see mm/vmscan.c) 587 recent_rotated_file VM internal parameter. (see mm/vmscan.c) 588 recent_scanned_anon VM internal parameter. (see mm/vmscan.c) 589 recent_scanned_file VM internal parameter. (see mm/vmscan.c) 590 ========================= ======================================== 591 592.. hint:: 593 recent_rotated means recent frequency of LRU rotation. 594 recent_scanned means recent # of scans to LRU. 595 showing for better debug please see the code for meanings. 596 597.. note:: 598 Only anonymous and swap cache memory is listed as part of 'rss' stat. 599 This should not be confused with the true 'resident set size' or the 600 amount of physical memory used by the cgroup. 601 602 'rss + mapped_file" will give you resident set size of cgroup. 603 604 (Note: file and shmem may be shared among other cgroups. In that case, 605 mapped_file is accounted only when the memory cgroup is owner of page 606 cache.) 607 6085.3 swappiness 609-------------- 610 611Overrides /proc/sys/vm/swappiness for the particular group. The tunable 612in the root cgroup corresponds to the global swappiness setting. 613 614Please note that unlike during the global reclaim, limit reclaim 615enforces that 0 swappiness really prevents from any swapping even if 616there is a swap storage available. This might lead to memcg OOM killer 617if there are no file pages to reclaim. 618 6195.4 failcnt 620----------- 621 622A memory cgroup provides memory.failcnt and memory.memsw.failcnt files. 623This failcnt(== failure count) shows the number of times that a usage counter 624hit its limit. When a memory cgroup hits a limit, failcnt increases and 625memory under it will be reclaimed. 626 627You can reset failcnt by writing 0 to failcnt file:: 628 629 # echo 0 > .../memory.failcnt 630 6315.5 usage_in_bytes 632------------------ 633 634For efficiency, as other kernel components, memory cgroup uses some optimization 635to avoid unnecessary cacheline false sharing. usage_in_bytes is affected by the 636method and doesn't show 'exact' value of memory (and swap) usage, it's a fuzz 637value for efficient access. (Of course, when necessary, it's synchronized.) 638If you want to know more exact memory usage, you should use RSS+CACHE(+SWAP) 639value in memory.stat(see 5.2). 640 6415.6 numa_stat 642------------- 643 644This is similar to numa_maps but operates on a per-memcg basis. This is 645useful for providing visibility into the numa locality information within 646an memcg since the pages are allowed to be allocated from any physical 647node. One of the use cases is evaluating application performance by 648combining this information with the application's CPU allocation. 649 650Each memcg's numa_stat file includes "total", "file", "anon" and "unevictable" 651per-node page counts including "hierarchical_<counter>" which sums up all 652hierarchical children's values in addition to the memcg's own value. 653 654The output format of memory.numa_stat is:: 655 656 total=<total pages> N0=<node 0 pages> N1=<node 1 pages> ... 657 file=<total file pages> N0=<node 0 pages> N1=<node 1 pages> ... 658 anon=<total anon pages> N0=<node 0 pages> N1=<node 1 pages> ... 659 unevictable=<total anon pages> N0=<node 0 pages> N1=<node 1 pages> ... 660 hierarchical_<counter>=<counter pages> N0=<node 0 pages> N1=<node 1 pages> ... 661 662The "total" count is sum of file + anon + unevictable. 663 6646. Hierarchy support 665==================== 666 667The memory controller supports a deep hierarchy and hierarchical accounting. 668The hierarchy is created by creating the appropriate cgroups in the 669cgroup filesystem. Consider for example, the following cgroup filesystem 670hierarchy:: 671 672 root 673 / | \ 674 / | \ 675 a b c 676 | \ 677 | \ 678 d e 679 680In the diagram above, with hierarchical accounting enabled, all memory 681usage of e, is accounted to its ancestors up until the root (i.e, c and root). 682If one of the ancestors goes over its limit, the reclaim algorithm reclaims 683from the tasks in the ancestor and the children of the ancestor. 684 6856.1 Hierarchical accounting and reclaim 686--------------------------------------- 687 688Hierarchical accounting is enabled by default. Disabling the hierarchical 689accounting is deprecated. An attempt to do it will result in a failure 690and a warning printed to dmesg. 691 692For compatibility reasons writing 1 to memory.use_hierarchy will always pass:: 693 694 # echo 1 > memory.use_hierarchy 695 6967. Soft limits 697============== 698 699Soft limits allow for greater sharing of memory. The idea behind soft limits 700is to allow control groups to use as much of the memory as needed, provided 701 702a. There is no memory contention 703b. They do not exceed their hard limit 704 705When the system detects memory contention or low memory, control groups 706are pushed back to their soft limits. If the soft limit of each control 707group is very high, they are pushed back as much as possible to make 708sure that one control group does not starve the others of memory. 709 710Please note that soft limits is a best-effort feature; it comes with 711no guarantees, but it does its best to make sure that when memory is 712heavily contended for, memory is allocated based on the soft limit 713hints/setup. Currently soft limit based reclaim is set up such that 714it gets invoked from balance_pgdat (kswapd). 715 7167.1 Interface 717------------- 718 719Soft limits can be setup by using the following commands (in this example we 720assume a soft limit of 256 MiB):: 721 722 # echo 256M > memory.soft_limit_in_bytes 723 724If we want to change this to 1G, we can at any time use:: 725 726 # echo 1G > memory.soft_limit_in_bytes 727 728.. note:: 729 Soft limits take effect over a long period of time, since they involve 730 reclaiming memory for balancing between memory cgroups 731 732.. note:: 733 It is recommended to set the soft limit always below the hard limit, 734 otherwise the hard limit will take precedence. 735 736.. _cgroup-v1-memory-move-charges: 737 7388. Move charges at task migration (DEPRECATED!) 739=============================================== 740 741THIS IS DEPRECATED! 742 743It's expensive and unreliable! It's better practice to launch workload 744tasks directly from inside their target cgroup. Use dedicated workload 745cgroups to allow fine-grained policy adjustments without having to 746move physical pages between control domains. 747 748Users can move charges associated with a task along with task migration, that 749is, uncharge task's pages from the old cgroup and charge them to the new cgroup. 750This feature is not supported in !CONFIG_MMU environments because of lack of 751page tables. 752 7538.1 Interface 754------------- 755 756This feature is disabled by default. It can be enabled (and disabled again) by 757writing to memory.move_charge_at_immigrate of the destination cgroup. 758 759If you want to enable it:: 760 761 # echo (some positive value) > memory.move_charge_at_immigrate 762 763.. note:: 764 Each bits of move_charge_at_immigrate has its own meaning about what type 765 of charges should be moved. See :ref:`section 8.2 766 <cgroup-v1-memory-movable-charges>` for details. 767 768.. note:: 769 Charges are moved only when you move mm->owner, in other words, 770 a leader of a thread group. 771 772.. note:: 773 If we cannot find enough space for the task in the destination cgroup, we 774 try to make space by reclaiming memory. Task migration may fail if we 775 cannot make enough space. 776 777.. note:: 778 It can take several seconds if you move charges much. 779 780And if you want disable it again:: 781 782 # echo 0 > memory.move_charge_at_immigrate 783 784.. _cgroup-v1-memory-movable-charges: 785 7868.2 Type of charges which can be moved 787-------------------------------------- 788 789Each bit in move_charge_at_immigrate has its own meaning about what type of 790charges should be moved. But in any case, it must be noted that an account of 791a page or a swap can be moved only when it is charged to the task's current 792(old) memory cgroup. 793 794+---+--------------------------------------------------------------------------+ 795|bit| what type of charges would be moved ? | 796+===+==========================================================================+ 797| 0 | A charge of an anonymous page (or swap of it) used by the target task. | 798| | You must enable Swap Extension (see 2.4) to enable move of swap charges. | 799+---+--------------------------------------------------------------------------+ 800| 1 | A charge of file pages (normal file, tmpfs file (e.g. ipc shared memory) | 801| | and swaps of tmpfs file) mmapped by the target task. Unlike the case of | 802| | anonymous pages, file pages (and swaps) in the range mmapped by the task | 803| | will be moved even if the task hasn't done page fault, i.e. they might | 804| | not be the task's "RSS", but other task's "RSS" that maps the same file. | 805| | And mapcount of the page is ignored (the page can be moved even if | 806| | page_mapcount(page) > 1). You must enable Swap Extension (see 2.4) to | 807| | enable move of swap charges. | 808+---+--------------------------------------------------------------------------+ 809 8108.3 TODO 811-------- 812 813- All of moving charge operations are done under cgroup_mutex. It's not good 814 behavior to hold the mutex too long, so we may need some trick. 815 8169. Memory thresholds 817==================== 818 819Memory cgroup implements memory thresholds using the cgroups notification 820API (see cgroups.txt). It allows to register multiple memory and memsw 821thresholds and gets notifications when it crosses. 822 823To register a threshold, an application must: 824 825- create an eventfd using eventfd(2); 826- open memory.usage_in_bytes or memory.memsw.usage_in_bytes; 827- write string like "<event_fd> <fd of memory.usage_in_bytes> <threshold>" to 828 cgroup.event_control. 829 830Application will be notified through eventfd when memory usage crosses 831threshold in any direction. 832 833It's applicable for root and non-root cgroup. 834 835.. _cgroup-v1-memory-oom-control: 836 83710. OOM Control 838=============== 839 840memory.oom_control file is for OOM notification and other controls. 841 842Memory cgroup implements OOM notifier using the cgroup notification 843API (See cgroups.txt). It allows to register multiple OOM notification 844delivery and gets notification when OOM happens. 845 846To register a notifier, an application must: 847 848 - create an eventfd using eventfd(2) 849 - open memory.oom_control file 850 - write string like "<event_fd> <fd of memory.oom_control>" to 851 cgroup.event_control 852 853The application will be notified through eventfd when OOM happens. 854OOM notification doesn't work for the root cgroup. 855 856You can disable the OOM-killer by writing "1" to memory.oom_control file, as: 857 858 #echo 1 > memory.oom_control 859 860If OOM-killer is disabled, tasks under cgroup will hang/sleep 861in memory cgroup's OOM-waitqueue when they request accountable memory. 862 863For running them, you have to relax the memory cgroup's OOM status by 864 865 * enlarge limit or reduce usage. 866 867To reduce usage, 868 869 * kill some tasks. 870 * move some tasks to other group with account migration. 871 * remove some files (on tmpfs?) 872 873Then, stopped tasks will work again. 874 875At reading, current status of OOM is shown. 876 877 - oom_kill_disable 0 or 1 878 (if 1, oom-killer is disabled) 879 - under_oom 0 or 1 880 (if 1, the memory cgroup is under OOM, tasks may be stopped.) 881 - oom_kill integer counter 882 The number of processes belonging to this cgroup killed by any 883 kind of OOM killer. 884 88511. Memory Pressure 886=================== 887 888The pressure level notifications can be used to monitor the memory 889allocation cost; based on the pressure, applications can implement 890different strategies of managing their memory resources. The pressure 891levels are defined as following: 892 893The "low" level means that the system is reclaiming memory for new 894allocations. Monitoring this reclaiming activity might be useful for 895maintaining cache level. Upon notification, the program (typically 896"Activity Manager") might analyze vmstat and act in advance (i.e. 897prematurely shutdown unimportant services). 898 899The "medium" level means that the system is experiencing medium memory 900pressure, the system might be making swap, paging out active file caches, 901etc. Upon this event applications may decide to further analyze 902vmstat/zoneinfo/memcg or internal memory usage statistics and free any 903resources that can be easily reconstructed or re-read from a disk. 904 905The "critical" level means that the system is actively thrashing, it is 906about to out of memory (OOM) or even the in-kernel OOM killer is on its 907way to trigger. Applications should do whatever they can to help the 908system. It might be too late to consult with vmstat or any other 909statistics, so it's advisable to take an immediate action. 910 911By default, events are propagated upward until the event is handled, i.e. the 912events are not pass-through. For example, you have three cgroups: A->B->C. Now 913you set up an event listener on cgroups A, B and C, and suppose group C 914experiences some pressure. In this situation, only group C will receive the 915notification, i.e. groups A and B will not receive it. This is done to avoid 916excessive "broadcasting" of messages, which disturbs the system and which is 917especially bad if we are low on memory or thrashing. Group B, will receive 918notification only if there are no event listeners for group C. 919 920There are three optional modes that specify different propagation behavior: 921 922 - "default": this is the default behavior specified above. This mode is the 923 same as omitting the optional mode parameter, preserved by backwards 924 compatibility. 925 926 - "hierarchy": events always propagate up to the root, similar to the default 927 behavior, except that propagation continues regardless of whether there are 928 event listeners at each level, with the "hierarchy" mode. In the above 929 example, groups A, B, and C will receive notification of memory pressure. 930 931 - "local": events are pass-through, i.e. they only receive notifications when 932 memory pressure is experienced in the memcg for which the notification is 933 registered. In the above example, group C will receive notification if 934 registered for "local" notification and the group experiences memory 935 pressure. However, group B will never receive notification, regardless if 936 there is an event listener for group C or not, if group B is registered for 937 local notification. 938 939The level and event notification mode ("hierarchy" or "local", if necessary) are 940specified by a comma-delimited string, i.e. "low,hierarchy" specifies 941hierarchical, pass-through, notification for all ancestor memcgs. Notification 942that is the default, non pass-through behavior, does not specify a mode. 943"medium,local" specifies pass-through notification for the medium level. 944 945The file memory.pressure_level is only used to setup an eventfd. To 946register a notification, an application must: 947 948- create an eventfd using eventfd(2); 949- open memory.pressure_level; 950- write string as "<event_fd> <fd of memory.pressure_level> <level[,mode]>" 951 to cgroup.event_control. 952 953Application will be notified through eventfd when memory pressure is at 954the specific level (or higher). Read/write operations to 955memory.pressure_level are no implemented. 956 957Test: 958 959 Here is a small script example that makes a new cgroup, sets up a 960 memory limit, sets up a notification in the cgroup and then makes child 961 cgroup experience a critical pressure:: 962 963 # cd /sys/fs/cgroup/memory/ 964 # mkdir foo 965 # cd foo 966 # cgroup_event_listener memory.pressure_level low,hierarchy & 967 # echo 8000000 > memory.limit_in_bytes 968 # echo 8000000 > memory.memsw.limit_in_bytes 969 # echo $$ > tasks 970 # dd if=/dev/zero | read x 971 972 (Expect a bunch of notifications, and eventually, the oom-killer will 973 trigger.) 974 97512. TODO 976======== 977 9781. Make per-cgroup scanner reclaim not-shared pages first 9792. Teach controller to account for shared-pages 9803. Start reclamation in the background when the limit is 981 not yet hit but the usage is getting closer 982 983Summary 984======= 985 986Overall, the memory controller has been a stable controller and has been 987commented and discussed quite extensively in the community. 988 989References 990========== 991 992.. [1] Singh, Balbir. RFC: Memory Controller, http://lwn.net/Articles/206697/ 993.. [2] Singh, Balbir. Memory Controller (RSS Control), 994 http://lwn.net/Articles/222762/ 995.. [3] Emelianov, Pavel. Resource controllers based on process cgroups 996 https://lore.kernel.org/r/45ED7DEC.7010403@sw.ru 997.. [4] Emelianov, Pavel. RSS controller based on process cgroups (v2) 998 https://lore.kernel.org/r/461A3010.90403@sw.ru 999.. [5] Emelianov, Pavel. RSS controller based on process cgroups (v3) 1000 https://lore.kernel.org/r/465D9739.8070209@openvz.org 1001 10026. Menage, Paul. Control Groups v10, http://lwn.net/Articles/236032/ 10037. Vaidyanathan, Srinivasan, Control Groups: Pagecache accounting and control 1004 subsystem (v3), http://lwn.net/Articles/235534/ 10058. Singh, Balbir. RSS controller v2 test results (lmbench), 1006 https://lore.kernel.org/r/464C95D4.7070806@linux.vnet.ibm.com 10079. Singh, Balbir. RSS controller v2 AIM9 results 1008 https://lore.kernel.org/r/464D267A.50107@linux.vnet.ibm.com 100910. Singh, Balbir. Memory controller v6 test results, 1010 https://lore.kernel.org/r/20070819094658.654.84837.sendpatchset@balbir-laptop 1011 1012.. [11] Singh, Balbir. Memory controller introduction (v6), 1013 https://lore.kernel.org/r/20070817084228.26003.12568.sendpatchset@balbir-laptop 1014.. [12] Corbet, Jonathan, Controlling memory use in cgroups, 1015 http://lwn.net/Articles/243795/ 1016