← Documents Documentation/admin-guide/cgroup-v1/memory.rst GitHub 원문 ↗

Linux 6.18.37 · Administration / Cgroup v1

Memory Resource Controller

Cgroup v1 memory controller의 page accounting, reclaim·OOM, hierarchy, kmem와 notification interface를 설명합니다.

Source pathDocumentation/admin-guide/cgroup-v1/memory.rst
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

Overview and accounting

memory.rst:1-282

문서 상태, controller interface, page_counter·page_cgroup accounting과 memory+swap를 설명합니다.

Reclaim, kmem and usage

memory.rst:283-525

Per-memcg reclaim/OOM, locking, kernel memory와 user-space setup·testing을 다룹니다.

Statistics and hierarchy

memory.rst:526-708

force_empty, memory.stat, swappiness·NUMA와 hierarchical accounting을 정리합니다.

Deprecated controls and events

memory.rst:709-923

Soft limit, move charge, threshold·OOM·pressure notification을 설명합니다.

TODO and references

memory.rst:924-964

남은 구현 과제와 원 controller 설계·test reference를 보존합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

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

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

문서 상태, 목적과 control files

1-126

이 문서는 심하게 낡아 완전한 rewrite가 필요하다는 경고가 붙어 있습니다. 여전히 유용한 정보가 있어 보존하지만 깊이 이해하려면 current code를 반드시 확인해야 합니다.

본문의 memory controller는 hardware memory controller가 아니라 Memory Resource Controller를 뜻합니다. Memory controller와 함께 쓰는 cgroup directory는 `memory cgroup`이라 하고 git log와 source code에서는 대개 `memcg`라는 이름을 사용합니다.

Memory controller는 task group의 memory behavior를 나머지 system과 격리합니다. LWN article [12]가 가능한 사용 사례를 설명합니다.

Memory-controller use cases
Use casePurpose
Memory-hungry application작은 memory quota 안에 격리
Limited-memory cgroup`mem=XXXX` boot option의 대안
Virtual machineInstance별 assigned memory 제어
CD/DVD burner나머지 system memory를 제한해 buffer starvation 방지
VM learning and experimentationVM subsystem 학습·개발

제한과 격리가 유용한 대표 상황입니다.

문서가 기록한 current status는 `linux-2.6.34-mmotm(development version of 2010/April)`입니다.

Documented feature set
FeatureBehavior
Anonymous/file/swap cacheUsage accounting and limits
Per-memcg LRUPages belong exclusively; no global LRU membership
Memory+swapOptional accounting and limiting
HierarchyAncestor accounting and reclaim
Soft limitBest-effort balancing; deprecated
Charge migrationSelectable task-move recharging; now deprecated
NotificationsUsage threshold, pressure, OOM eventfd
OOM controlKiller-disable knob and notifier; deprecated
Root cgroupNo limit controls
Kernel memoryBasic support noted as work in progress

당시 memory controller가 제공한다고 기록한 기능입니다.

Memory cgroup control files
FilePurpose or status
tasksAttach a task/thread and list threads
cgroup.procsList processes
cgroup.event_controleventfd interface; unavailable on CONFIG_PREEMPT_RT
memory.usage_in_bytesCurrent memory usage; fuzzy for efficiency
memory.memsw.usage_in_bytesCurrent memory+swap usage
memory.limit_in_bytesMemory hard limit
memory.memsw.limit_in_bytesMemory+swap hard limit
memory.failcntMemory-limit hit count
memory.memsw.failcntMemory+swap-limit hit count
memory.max_usage_in_bytesRecorded maximum memory usage
memory.memsw.max_usage_in_bytesRecorded maximum memory+swap usage
memory.soft_limit_in_bytesBest-effort soft limit; deprecated, unavailable on CONFIG_PREEMPT_RT
memory.statDetailed local and hierarchical statistics
memory.use_hierarchyHierarchy accounting; disabling deprecated
memory.force_emptyForce page reclaim before removal
memory.pressure_levelPressure notifications; deprecated
memory.swappinessPer-memcg vmscan swappiness; no cgroup v2 equivalent
memory.move_charge_at_immigrateDeprecated charge-move knob
memory.oom_controlOOM controls and status; deprecated
memory.numa_statPer-node memory usage
memory.kmem.limit_in_bytesDeprecated; kernel hard limit unsupported since 5.16 and writes have no effect
memory.kmem.usage_in_bytesCurrent kernel memory allocation
memory.kmem.failcntKernel memory limit-hit count
memory.kmem.max_usage_in_bytesMaximum kernel memory usage
memory.kmem.tcp.limit_in_bytesDeprecated TCP buffer hard limit
memory.kmem.tcp.usage_in_bytesDeprecated current TCP buffer usage
memory.kmem.tcp.failcntDeprecated TCP buffer limit-hit count
memory.kmem.tcp.max_usage_in_bytesDeprecated maximum TCP buffer usage

원문의 brief summary를 기능별로 정리했습니다.

역사와 구현 단계

127-159

Memory controller는 긴 역사를 가집니다. Balbir Singh가 memory controller RFC [1]을 올렸고, 당시 여러 memory-control 구현 사이에서 최소 필수 기능에 대한 consensus를 만드는 것이 목표였습니다.

Memory-controller history
Balbir Singh RFC [1]First RSS controller [2], Feb 2007Pavel Emelianov RSS controller v1-v3 [3]-[5]OLS resource-management BoFRequire page cache plus RSS and userspace OOM handlingMemory controller v6 with Page Cache Control [11]

RSS-only control에서 mapped RSS와 unmapped page cache를 함께 다루는 version 6까지의 흐름입니다.

Memory는 CPU와 달리 한정된 물리 resource를 반복 재사용해야 합니다. CPU-intensive task는 실행 시간을 늘릴 수 있지만 memory request는 같은 physical memory를 회수·재사용해야 진행할 수 있습니다.

Planned controller phases
PhaseController
1Memory controller
2mlock(2) controller
3Kernel user-memory accounting and slab control
4User mappings length controller

Memory control 구현은 다음 단계로 나뉘었고 첫 단계가 이 문서의 controller입니다.

page_counter와 page accounting

160-235

설계의 핵심은 `page_counter`입니다. 이 counter가 controller에 연결된 process group의 current memory usage와 limit을 추적하고, 각 cgroup에는 memory-controller-specific `mem_cgroup` structure가 연결됩니다.

Hierarchy of accounting
mm_struct for taskKnows owning mem_cgroupmem_cgroup page_counter
Physical pagepage_cgroup metadataKnows owning mem_cgroupmem_cgroup page_counter

원문의 Figure 1을 object 관계로 다시 그렸습니다.

Accounting invariants
InvariantMeaning
Per-cgroup accountingUsage and limits belong to mem_cgroup
mm_struct ownershipEach mm_struct knows its cgroup
Page metadata ownershipPage -> page_cgroup -> cgroup

Figure 1이 강조하는 세 관계입니다.

`mem_cgroup_charge_common()`은 필요한 data structure를 준비하고 charge 대상 cgroup이 limit을 넘는지 검사합니다. Limit을 넘으면 그 cgroup에서 reclaim을 시도합니다. 성공하면 page metadata인 `page_cgroup`을 update하고, page_cgroup은 cgroup별 LRU를 가집니다. Structure 자체는 boot 또는 memory hotplug 때 allocate됩니다.

Charge path
Page becomes chargeablemem_cgroup_charge_common()Prepare accounting dataCheck page_counter limitOver limit?Run memcg reclaim or update page_cgroup and per-cgroup LRU

Page charge가 limit 검사와 reclaim을 거쳐 metadata에 commit되는 순서입니다.

Detailed page-accounting events
Page type or eventAccounting behavior
Mapped anonymous RSSCharge at page fault unless already charged
File page cacheCharge when inserted into inode xarray
Duplicate process mappingAvoid duplicate accounting
RSS fully unmappedUnaccount RSS ownership
PageCache removed from xarrayUnaccount page cache
Unmapped page retained as SwapCacheKeep accounting until really freed
Swap-inCharge after adding to swapcache
Page migrationPreserve accounting information

Page 유형별 account·unaccount 시점입니다.

일반 VM 관리 아래 있는 mapped anon page와 cache page만 account합니다. Reclaim 불가능하고 LRU에 오르지 않는 page는 목적 범위 밖입니다. Kernel은 swapin readahead로 여러 swap을 한꺼번에 읽으며 memsw 활성 여부와 관계없이 swap에 memcg가 기록되어 있으므로 swap-in 후 올바른 cgroup에 charge합니다.

Shared page와 memory+swap extension

236-282

Shared page는 first-touch 방식으로 account합니다. Page를 처음 touch한 cgroup이 charge를 가지며, 그 page를 적극 사용하는 다른 cgroup은 memory pressure로 기존 owner에서 uncharge된 뒤 다시 touch할 때 결국 charge를 받을 수 있습니다.

First-touch shared-page accounting
Cgroup A first touches shared pageCharge ACgroup B uses same page without duplicate chargePage uncharged from A under pressureNext aggressive touch can charge B

Shared page의 charge는 현재 owner가 reclaim 압력으로 놓을 때 이동할 수 있습니다.

Swap usage는 cgroup별로 항상 기록됩니다. `CONFIG_SWAP`이면 `memory.memsw.usage_in_bytes`와 `memory.memsw.limit_in_bytes`가 추가되고, memsw는 memory+swap 합계를 뜻합니다.

Memory+swap extension
SettingEffect
memory.limit_in_bytes=2GResident memory를 2G로 제한
No memsw limitTask가 system의 4G swap 전체를 사용할 수 있음
memory.memsw.limit_in_bytes=3GCombined memory+swap를 3G로 제한
ResultSwap shortage로 인한 system OOM 위험 감소

2G memory limit 아래 잘못된 6G allocation이 4G swap을 모두 쓰는 예제입니다.

Why limit memory+swap
Global LRU or kswapd selects pageSwap outMemory usage decreasesSwap usage increasesMemory+swap usage unchanged

Swap-out은 memory charge를 swap charge로 옮길 뿐 합계는 바꾸지 않습니다.

`memory.memsw.limit_in_bytes`에 도달한 cgroup에서는 local swap-out이 합계를 줄이지 못하므로 cgroup reclaim은 swap-out 대신 file cache를 drop합니다. System memory-management sanity를 위해 global LRU가 그 cgroup memory를 swap-out하는 것은 cgroup이 금지할 수 없습니다.

Limit reclaim, OOM과 lock order

283-323

각 cgroup은 global VM과 같은 구조의 per-cgroup LRU를 유지합니다. Limit을 넘으면 새 page 공간을 만들기 위해 해당 cgroup LRU에서 먼저 reclaim합니다. 실패하면 OOM routine이 cgroup에서 가장 큰 task를 골라 kill합니다.

Memcg limit reclaim
Charge would exceed cgroup limitSelect pages from per-cgroup LRURun normal reclaim algorithmEnough space?Continue charge or invoke memcg OOM killer

Root cgroup에는 limit을 설정할 수 없어 이 reclaim path가 적용되지 않습니다.

Cgroup용 reclaim algorithm 자체는 바꾸지 않고 page source만 per-cgroup LRU로 제한합니다. `panic_on_oom=2`이면 전체 system이 panic합니다. OOM event notifier가 등록돼 있으면 event도 전달합니다.

2.6 Locking
-----------

Lock order is as follows::

  folio_lock
    mm->page_table_lock or split pte_lock
      folio_memcg_lock (memcg->move_lock)
        mapping->i_pages lock
          lruvec->lru_lock.
Memory-controller lock order
folio_lockmm->page_table_lock or split pte_lockfolio_memcg_lock (memcg->move_lock)mapping->i_pages locklruvec->lru_lock

원문 순서를 어기지 않아야 하는 nested lock chain입니다.

Node·memcg별 private LRU는 `lruvec->lru_lock`으로 보호합니다. Folio를 LRU에서 isolate할 때 같은 lock 아래에서 folio LRU flag를 먼저 clear합니다.

Kernel memory accounting

324-402

Kernel memory extension은 system에서 쓰는 kernel memory 양을 memory controller가 제한하게 합니다. Kernel memory는 swap-out할 수 없어 과도하게 소비하면 system DoS가 가능하다는 점에서 user memory와 근본적으로 다릅니다.

Kernel memory accounting은 기본적으로 모든 memory cgroup에서 enabled입니다. Boot parameter `cgroup.memory=nokmem`으로 system-wide 비활성화하면 전혀 account하지 않습니다. Root cgroup에는 kernel memory limit을 부과하지 않으며 usage는 account될 수도, 안 될 수도 있습니다.

Accounted kernel resources
ResourceAccounting behavior
Process stack pagesHigh kmem usage can prevent new process creation
SLAB/SLUB pagesLazily create per-memcg kmem_cache; early objects may be skipped
Socket memory pressureControl protocol thresholds per cgroup instead of globally
TCP memory pressureTCP-specific socket pressure accounting

문서가 열거하는 kmem charge 대상입니다.

Kernel usage는 `memory.kmem.usage_in_bytes` 또는 의미가 있을 때 별도 counter(TCP)에 누적됩니다. Main `kmem` counter는 main user counter에도 합쳐지므로 kmem charge가 user usage에도 보입니다. Kernel memory soft limit은 구현되지 않았고 limit에서 slab reclaim을 trigger하는 것은 future work로 기록돼 있습니다.

SLAB/SLUB allocator page를 추적하며 memcg가 cache를 처음 touch할 때 `kmem_cache` copy를 lazy 생성합니다. 같은 slab page의 object는 모두 같은 memcg여야 하지만 cache allocation 중 task가 다른 memcg로 migration하는 경우 예외가 생길 수 있습니다.

User limit U and kernel limit K
ConfigurationMeaningCaveat
U != 0, K = unlimitedClassic memcg; kernel memory ignoredNo kernel-memory protection
U != 0, K < UKernel memory is subset of user memoryDo not overcommit non-reclaimable K; hitting K below U does not trigger reclaim
U != 0, K >= UUnified user+kernel view; U effectively constrains bothUseful for tracking kmem

Kmem counter가 main counter에 포함되므로 완전히 독립적인 제한은 불가능합니다.

Mount, limit 설정과 조회

403-462

User interface를 쓰려면 kernel에서 `CONFIG_CGROUPS`와 `CONFIG_MEMCG`를 enable하고 memory hierarchy를 mount한 뒤 child group을 만들고 Bash를 이동합니다.

3. User Interface
=================

To use the user interface:

1. Enable CONFIG_CGROUPS and CONFIG_MEMCG options
2. Prepare the cgroups (see :ref:`Why are cgroups needed?
   <cgroups-why-needed>` for the background information)::

	# mount -t tmpfs none /sys/fs/cgroup
	# mkdir /sys/fs/cgroup/memory
	# mount -t cgroup none /sys/fs/cgroup/memory -o memory

3. Make the new group and move bash into it::

	# mkdir /sys/fs/cgroup/memory/0
	# echo $$ > /sys/fs/cgroup/memory/0/tasks

4. Since now we're in the 0 cgroup, we can alter the memory limit::

	# echo 4M > /sys/fs/cgroup/memory/0/memory.limit_in_bytes

   The limit can now be queried::

	# cat /sys/fs/cgroup/memory/0/memory.limit_in_bytes
	4194304

.. note::
Create a limited memory cgroup
Mount tmpfs at /sys/fs/cgroupmkdir memoryMount cgroup -o memorymkdir memory/0Write $$ to tasksWrite 4M to memory.limit_in_bytesRead back 4194304

Tmpfs mount에서 4 MiB hard limit을 가진 group 0을 만드는 절차입니다.

Limit-value syntax
InputMeaning
k or KKibibytes
m or MMebibytes
g or GGibibytes
-1Reset *.limit_in_bytes to unlimited
Root cgroupLimits cannot be set

Write 후 kernel이 실제 commit한 값을 반드시 다시 읽어야 합니다.

.. note::
   We cannot set limits on the root cgroup any more.


We can check the usage::

  # cat /sys/fs/cgroup/memory/0/memory.usage_in_bytes
  1216512

A successful write to this file does not guarantee a successful setting of
this limit to the value written into the file. This can be due to a
number of factors, such as rounding up to page boundaries or the total
availability of memory on the system. The user is required to re-read
this file after a write to guarantee the value committed by the kernel::

  # echo 1 > memory.limit_in_bytes
  # cat memory.limit_in_bytes
  4096
Limit write normalization
Write 1 to memory.limit_in_bytesKernel rounds to page boundaryRead file againCommitted value is 4096

Page boundary와 available memory 때문에 requested value와 committed value가 다를 수 있습니다.

`memory.failcnt`는 cgroup이 limit을 넘은 횟수를 보여 주고 `memory.stat`은 cache, RSS, active/inactive page 등 accounting 정보를 제공합니다.

Testing, migration과 cgroup 제거

463-525
Memory-controller tests
TestPurpose
memcg_test.txtFeature and implementation tests
Kernel build on tmpfsPure controller overhead with small extra cost
Parallel multi-process page faultsPage-fault scalability with less shared-state noise
Ordinary application workloadRealistic behavior beyond extreme tests

기능·성능·scalability를 서로 다른 workload로 확인합니다.

Cgroup application이 OOM killer에 의해 종료된다면 limit이 실용적으로 너무 낮거나 anonymous memory를 쓰는데 swap이 꺼져 있거나 부족한 경우를 먼저 확인합니다.

OOM troubleshooting
ActionPurpose
syncFlush dirty data
echo 1 > /proc/sys/vm/drop_cachesDrop reclaimable cgroup page cache
Temporarily disable OOM_KillObserve blocked allocation and pressure state

Page cache 정리와 OOM killer 비활성화 관찰로 원인을 좁힙니다.

Task가 다른 cgroup으로 이동해도 default로 기존 charge는 따라가지 않습니다. Original cgroup에서 allocate한 page는 free 또는 reclaim될 때까지 그곳에 charge됩니다. Deprecated move-charge 기능을 사용하면 task와 함께 charge를 옮길 수 있습니다.

Task migration and cgroup removal
Task leaves child cgroupAllocated pages remain charged to childrmdir offlines cgroupMove stats to parentUncharge child only as pages free or reclaim
Swap charge record at removalDiscard old owner informationNext swapcache user is charged as new owner

Accounting은 task가 아니라 page에 연결되므로 task가 없어도 cgroup charge가 남을 수 있습니다.

force_empty와 memory.stat

526-620

`memory.force_empty`에 아무 값이나 쓰면 cgroup을 reclaim해 가능한 한 많은 page를 회수합니다. `rmdir()` 전에 charged file cache 때문에 offline memcg가 오래 남는 것을 줄이는 용도입니다.

5.1 force_empty
---------------
  memory.force_empty interface is provided to make cgroup's memory usage empty.
  When writing anything to this::

    # echo 0 > memory.force_empty
force_empty before removal
Cgroup has no tasks but charged file cacheWrite to memory.force_emptyReclaim as many pages as possibleCall rmdir()Reduce lingering offline memcg lifetime

Memory pressure를 기다리지 않고 사용하지 않는 charged cache를 먼저 회수합니다.

memory.stat local counters
CounterMeaning
cachePage cache bytes
rssAnonymous + swap-cache bytes, including THP
rss_hugeAnonymous transparent hugepage bytes
mapped_fileMapped file bytes including tmpfs/shmem
pgpginCharge events for mapped anon or page cache
pgpgoutUncharge events
swapSwap usage bytes
swapcachedSwap cached in memory
dirtyBytes waiting for disk writeback
writebackFile/anon cache queued for disk sync
inactive_anonInactive anon and swap cache
active_anonActive anon and swap cache
inactive_fileInactive file-backed and MADV_FREE LazyFree
active_fileActive file-backed memory
unevictableUnreclaimable memory such as mlocked pages

Per-memory-cgroup local status의 주요 counter입니다.

memory.stat hierarchical counters
CounterMeaning
hierarchical_memory_limitEffective ancestor memory limit
hierarchical_memsw_limitEffective ancestor memory+swap limit
total_<counter>Local counter plus all hierarchical children, e.g. total_cache

Hierarchy-aware limit과 descendant 합계를 제공합니다.

CONFIG_DEBUG_VM counters
CounterMeaning
recent_rotated_anonRecent anonymous LRU rotation
recent_rotated_fileRecent file LRU rotation
recent_scanned_anonRecent anonymous LRU scans
recent_scanned_fileRecent file LRU scans

LRU rotation과 scan debugging을 위한 optional VM parameter입니다.

`rss`는 anonymous와 swap cache만 포함하며 진짜 resident set size와 같지 않습니다. Cgroup resident set은 대략 `rss + mapped_file`입니다. THP 같은 큰 allocation은 일부만 map돼도 전체가 두 counter에 잡힐 수 있습니다. Shared file/shmem의 `mapped_file`은 memcg가 page-cache owner일 때만 account됩니다.

Swappiness, failcnt, usage와 NUMA

621-676

`memory.swappiness`는 해당 group의 `/proc/sys/vm/swappiness`를 override하고 root knob는 global setting에 대응합니다. Global reclaim과 달리 limit reclaim에서 swappiness 0은 swap storage가 있어도 swap을 완전히 금지하므로 reclaim할 file page가 없으면 memcg OOM killer로 이어질 수 있습니다.

Miscellaneous accounting interfaces
InterfaceBehavior
memory.swappinessPer-group reclaim preference; 0 forbids limit-reclaim swap
memory.failcnt / memory.memsw.failcntIncrement when usage counter hits limit; write 0 to reset
memory.usage_in_bytesCacheline-sharing optimization 때문에 exact가 아닌 fuzzy value
memory.stat RSS+CACHE(+SWAP)더 정확한 usage 추정에 권장

정확도와 reset 방법을 포함한 사용상 주의점입니다.

This failcnt(== failure count) shows the number of times that a usage counter
hit its limit. When a memory cgroup hits a limit, failcnt increases and
memory under it will be reclaimed.

You can reset failcnt by writing 0 to failcnt file::

	# echo 0 > .../memory.failcnt

`memory.numa_stat`은 `numa_maps`와 비슷하지만 per-memcg 단위로 physical node locality를 보여 줍니다. Application CPU allocation과 함께 보면 NUMA locality가 performance에 미치는 영향을 평가할 수 있습니다.

The output format of memory.numa_stat is::

  total=<total pages> N0=<node 0 pages> N1=<node 1 pages> ...
  file=<total file pages> N0=<node 0 pages> N1=<node 1 pages> ...
  anon=<total anon pages> N0=<node 0 pages> N1=<node 1 pages> ...
  unevictable=<total anon pages> N0=<node 0 pages> N1=<node 1 pages> ...
  hierarchical_<counter>=<counter pages> N0=<node 0 pages> N1=<node 1 pages> ...
memory.numa_stat fields
FieldMeaning
totalfile + anon + unevictable page count
fileFile-backed pages
anonAnonymous pages
unevictableUnevictable pages
hierarchical_<counter>Local plus all hierarchical children
N0, N1, ...Per-node page counts

Local과 hierarchical page count를 node별로 보여 줍니다.

Hierarchical accounting과 reclaim

677-708

Memory controller는 deep hierarchy와 hierarchical accounting을 지원합니다. Cgroup filesystem에 directory를 만들어 hierarchy를 구성합니다.

Memory cgroup hierarchy
roota
rootb
rootcd
rootce

원문의 root-a/b/c-d/e ASCII tree를 구조화했습니다.

Ancestor accounting and reclaim
EventResult
e allocates memoryCharge e, c, and root
c exceeds limitReclaim from tasks in c and descendants d/e
rootNo configurable limit reclaim

E의 usage와 limit pressure가 어떻게 위로 전달되는지 보여 줍니다.

Hierarchical accounting은 default로 enabled입니다. Disable은 deprecated이며 시도하면 실패하고 dmesg warning이 출력됩니다. Compatibility를 위해 `echo 1 > memory.use_hierarchy`는 항상 성공합니다.

Deprecated soft limit와 charge migration

709-760

Soft limit은 deprecated입니다. Memory contention이 없고 hard limit을 넘지 않는 동안 cgroup이 필요한 만큼 memory를 쓰게 하되, low-memory 또는 contention 시 soft limit 쪽으로 best-effort reclaim해 group 사이 공유를 유도합니다.

Soft-limit balancing
No contention and below hard limitCgroup may exceed soft hintSystem detects contentionbalance_pgdat invokes soft-limit reclaimPush groups toward soft limits

보장은 없으며 `balance_pgdat`의 kswapd path에서 긴 시간에 걸쳐 반영됩니다.

7.1 Interface
-------------

Soft limits can be setup by using the following commands (in this example we
assume a soft limit of 256 MiB)::

	# echo 256M > memory.soft_limit_in_bytes

If we want to change this to 1G, we can at any time use::

	# echo 1G > memory.soft_limit_in_bytes

.. note::
       Soft limits take effect over a long period of time, since they involve
       reclaiming memory for balancing between memory cgroups

.. note::
       It is recommended to set the soft limit always below the hard limit,
       otherwise the hard limit will take precedence.
Deprecated limit and migration knobs
InterfaceCurrent documented behavior
memory.soft_limit_in_bytesDeprecated best-effort hint; set below hard limit
memory.move_charge_at_immigrateDeprecated; read always 0, write always -EINVAL

현재 문서가 명시하는 interface 상태입니다.

Threshold notification과 deprecated OOM control

761-831

Memory threshold는 cgroup notification API(`cgroups.txt` 참고)를 사용해 memory와 memsw threshold를 여러 개 등록하고 usage가 어느 방향으로든 crossing할 때 eventfd notification을 보냅니다. Root와 non-root cgroup 모두 적용됩니다.

Register a memory threshold
eventfd(2) creates event_fdOpen memory.usage_in_bytes or memory.memsw.usage_in_bytesWrite <event_fd> <fd of memory.usage_in_bytes> <threshold> to cgroup.event_controlUsage crosses threshold up or downReceive eventfd notification

Usage file descriptor와 threshold를 `cgroup.event_control`에 연결합니다.

`memory.oom_control`은 deprecated OOM notification·control file입니다. Cgroup notification API로 multiple notifier를 등록하지만 root cgroup에서는 OOM notification이 동작하지 않습니다.

Register an OOM notifier
Create eventfdOpen memory.oom_controlWrite <event_fd> <fd of memory.oom_control> to cgroup.event_controlMemcg enters OOMReceive eventfd notification

OOM control file descriptor를 eventfd와 연결합니다.

`echo 1 > memory.oom_control`로 OOM killer를 disable하면 accountable memory를 요청한 task가 memcg OOM waitqueue에서 hang/sleep합니다. 다시 실행하려면 limit을 늘리거나 usage를 줄여 OOM 상태를 완화해야 합니다.

Recover tasks from disabled-OOM waitqueue
ActionEffect
Enlarge memory limitCreate charge headroom
Kill tasksRelease charged pages
Move tasks with account migrationMove ownership out
Remove tmpfs or other filesDrop charged file-backed memory

Memory pressure를 실제로 낮춰야 stopped task가 진행합니다.

memory.oom_control read fields
FieldMeaning
oom_kill_disable1 if memcg OOM killer disabled
under_oom1 if cgroup is under OOM and tasks may be stopped
oom_killProcesses in this cgroup killed by any OOM killer

현재 OOM 상태와 kill 통계를 보여 줍니다.

Deprecated memory-pressure notification

832-923

Memory pressure notification은 deprecated이지만 allocation cost를 감시해 application이 pressure 수준별 memory-management 전략을 구현하도록 합니다.

Memory-pressure levels
LevelSystem stateSuggested response
lowReclaiming memory for new allocationsInspect vmstat and preemptively trim caches or unimportant services
mediumSwap and active file-cache pagingInspect vmstat/zoneinfo/memcg and free reconstructible resources
criticalActive thrashing, near OOM or OOM killerTake immediate action without expensive analysis

Level이 높을수록 즉시 대응해야 합니다.

Default event는 listener가 처리할 때까지만 ancestor로 올라가며 pass-through가 아닙니다. A->B->C hierarchy에서 C가 pressure를 겪고 A/B/C 모두 listener가 있으면 C만 받습니다. C listener가 없을 때만 B가 받을 수 있어 low-memory 상황의 excessive broadcast를 피합니다.

Default pressure propagation
Pressure originates in CC listener exists?Notify C and stop
No C listenerTry BNotify nearest ancestor listener and stop

가장 가까운 listener가 event를 처리하면 상위 전파를 멈춥니다.

Pressure notification modes
ModeBehavior for A->B->C pressure at C
default or omittedNearest listener handles; no pass-through
hierarchyAlways propagate to root; A, B, and C may all receive
localOnly pressure in the registered memcg; ancestors never receive C event

Optional mode가 ancestor 전파 범위를 바꿉니다.

Level과 mode는 comma-delimited string으로 지정합니다. `low,hierarchy`는 ancestor 모두에 hierarchical pass-through notification을, `medium,local`은 해당 memcg의 medium pressure만 알립니다.

Register pressure eventfd
Create eventfdOpen memory.pressure_levelWrite <event_fd> <fd of memory.pressure_level> <level[,mode]> to cgroup.event_controlPressure reaches requested level or higherReceive eventfd notification

`memory.pressure_level`은 eventfd setup에만 쓰며 직접 read/write interface는 구현되지 않았습니다.

Test:

   Here is a small script example that makes a new cgroup, sets up a
   memory limit, sets up a notification in the cgroup and then makes child
   cgroup experience a critical pressure::

	# cd /sys/fs/cgroup/memory/
	# mkdir foo
	# cd foo
	# cgroup_event_listener memory.pressure_level low,hierarchy &
	# echo 8000000 > memory.limit_in_bytes
	# echo 8000000 > memory.memsw.limit_in_bytes
	# echo $$ > tasks
	# dd if=/dev/zero | read x

   (Expect a bunch of notifications, and eventually, the oom-killer will
Critical-pressure test
Create memory/fooListen on low,hierarchySet memory and memsw limits to 8000000Attach current shelldd /dev/zero into readReceive notificationsEventually trigger OOM killer

8,000,000-byte memory·memsw limit 아래 endless zero stream으로 notification과 OOM을 유도합니다.

TODO, summary와 references

924-964
Document TODO
ItemGoal
Per-cgroup scannerReclaim non-shared pages first
Shared-page accountingTeach controller to account shared pages
Background reclaimStart before hard limit as usage approaches it

원문이 남긴 세 개선 과제입니다.

원문은 memory controller가 전반적으로 안정적이며 community에서 폭넓게 comment·discussion되어 왔다고 요약합니다.

Primary references
RefCitation
[1]Balbir Singh, RFC: Memory Controller, http://lwn.net/Articles/206697/
[2]Balbir Singh, Memory Controller (RSS Control), http://lwn.net/Articles/222762/
[3]Pavel Emelianov, Resource controllers, https://lore.kernel.org/r/[email protected]
[4]Pavel Emelianov, RSS controller v2, https://lore.kernel.org/r/[email protected]
[5]Pavel Emelianov, RSS controller v3, https://lore.kernel.org/r/[email protected]
6Paul Menage, Control Groups v10, http://lwn.net/Articles/236032/
7Srinivasan Vaidyanathan, Pagecache accounting v3, http://lwn.net/Articles/235534/
8Balbir Singh, RSS controller v2 lmbench, https://lore.kernel.org/r/[email protected]
9Balbir Singh, RSS controller v2 AIM9, https://lore.kernel.org/r/[email protected]
10Balbir Singh, memory controller v6 tests, https://lore.kernel.org/r/20070819094658.654.84837.sendpatchset@balbir-laptop
[11]Balbir Singh, memory controller introduction v6, https://lore.kernel.org/r/20070817084228.26003.12568.sendpatchset@balbir-laptop
[12]Jonathan Corbet, Controlling memory use in cgroups, http://lwn.net/Articles/243795/

원문에 실린 RFC, controller revision, test와 overview 자료입니다.