560 lines · plain
1==============================2Unevictable LRU Infrastructure3==============================4 5.. contents:: :local:6 7 8Introduction9============10 11This document describes the Linux memory manager's "Unevictable LRU"12infrastructure and the use of this to manage several types of "unevictable"13folios.14 15The document attempts to provide the overall rationale behind this mechanism16and the rationale for some of the design decisions that drove the17implementation. The latter design rationale is discussed in the context of an18implementation description. Admittedly, one can obtain the implementation19details - the "what does it do?" - by reading the code. One hopes that the20descriptions below add value by provide the answer to "why does it do that?".21 22 23 24The Unevictable LRU25===================26 27The Unevictable LRU facility adds an additional LRU list to track unevictable28folios and to hide these folios from vmscan. This mechanism is based on a patch29by Larry Woodman of Red Hat to address several scalability problems with folio30reclaim in Linux. The problems have been observed at customer sites on large31memory x86_64 systems.32 33To illustrate this with an example, a non-NUMA x86_64 platform with 128GB of34main memory will have over 32 million 4k pages in a single node. When a large35fraction of these pages are not evictable for any reason [see below], vmscan36will spend a lot of time scanning the LRU lists looking for the small fraction37of pages that are evictable. This can result in a situation where all CPUs are38spending 100% of their time in vmscan for hours or days on end, with the system39completely unresponsive.40 41The unevictable list addresses the following classes of unevictable pages:42 43 * Those owned by ramfs.44 45 * Those owned by tmpfs with the noswap mount option.46 47 * Those mapped into SHM_LOCK'd shared memory regions.48 49 * Those mapped into VM_LOCKED [mlock()ed] VMAs.50 51The infrastructure may also be able to handle other conditions that make pages52unevictable, either by definition or by circumstance, in the future.53 54 55The Unevictable LRU Folio List56------------------------------57 58The Unevictable LRU folio list is a lie. It was never an LRU-ordered59list, but a companion to the LRU-ordered anonymous and file, active and60inactive folio lists; and now it is not even a folio list. But following61familiar convention, here in this document and in the source, we often62imagine it as a fifth LRU folio list.63 64The Unevictable LRU infrastructure consists of an additional, per-node, LRU list65called the "unevictable" list and an associated folio flag, PG_unevictable, to66indicate that the folio is being managed on the unevictable list.67 68The PG_unevictable flag is analogous to, and mutually exclusive with, the69PG_active flag in that it indicates on which LRU list a folio resides when70PG_lru is set.71 72The Unevictable LRU infrastructure maintains unevictable folios as if they were73on an additional LRU list for a few reasons:74 75 (1) We get to "treat unevictable folios just like we treat other folios in the76 system - which means we get to use the same code to manipulate them, the77 same code to isolate them (for migrate, etc.), the same code to keep track78 of the statistics, etc..." [Rik van Riel]79 80 (2) We want to be able to migrate unevictable folios between nodes for memory81 defragmentation, workload management and memory hotplug. The Linux kernel82 can only migrate folios that it can successfully isolate from the LRU83 lists (or "Movable" folios: outside of consideration here). If we were to84 maintain folios elsewhere than on an LRU-like list, where they can be85 detected by folio_isolate_lru(), we would prevent their migration.86 87The unevictable list does not differentiate between file-backed and88anonymous, swap-backed folios. This differentiation is only important89while the folios are, in fact, evictable.90 91The unevictable list benefits from the "arrayification" of the per-node LRU92lists and statistics originally proposed and posted by Christoph Lameter.93 94 95Memory Control Group Interaction96--------------------------------97 98The unevictable LRU facility interacts with the memory control group [aka99memory controller; see Documentation/admin-guide/cgroup-v1/memory.rst] by100extending the lru_list enum.101 102The memory controller data structure automatically gets a per-node unevictable103list as a result of the "arrayification" of the per-node LRU lists (one per104lru_list enum element). The memory controller tracks the movement of pages to105and from the unevictable list.106 107When a memory control group comes under memory pressure, the controller will108not attempt to reclaim pages on the unevictable list. This has a couple of109effects:110 111 (1) Because the pages are "hidden" from reclaim on the unevictable list, the112 reclaim process can be more efficient, dealing only with pages that have a113 chance of being reclaimed.114 115 (2) On the other hand, if too many of the pages charged to the control group116 are unevictable, the evictable portion of the working set of the tasks in117 the control group may not fit into the available memory. This can cause118 the control group to thrash or to OOM-kill tasks.119 120 121.. _mark_addr_space_unevict:122 123Marking Address Spaces Unevictable124----------------------------------125 126For facilities such as ramfs none of the pages attached to the address space127may be evicted. To prevent eviction of any such pages, the AS_UNEVICTABLE128address space flag is provided, and this can be manipulated by a filesystem129using a number of wrapper functions:130 131 * ``void mapping_set_unevictable(struct address_space *mapping);``132 133 Mark the address space as being completely unevictable.134 135 * ``void mapping_clear_unevictable(struct address_space *mapping);``136 137 Mark the address space as being evictable.138 139 * ``int mapping_unevictable(struct address_space *mapping);``140 141 Query the address space, and return true if it is completely142 unevictable.143 144These are currently used in three places in the kernel:145 146 (1) By ramfs to mark the address spaces of its inodes when they are created,147 and this mark remains for the life of the inode.148 149 (2) By SYSV SHM to mark SHM_LOCK'd address spaces until SHM_UNLOCK is called.150 Note that SHM_LOCK is not required to page in the locked pages if they're151 swapped out; the application must touch the pages manually if it wants to152 ensure they're in memory.153 154 (3) By the i915 driver to mark pinned address space until it's unpinned. The155 amount of unevictable memory marked by i915 driver is roughly the bounded156 object size in debugfs/dri/0/i915_gem_objects.157 158 159Detecting Unevictable Pages160---------------------------161 162The function folio_evictable() in mm/internal.h determines whether a folio is163evictable or not using the query function outlined above [see section164:ref:`Marking address spaces unevictable <mark_addr_space_unevict>`]165to check the AS_UNEVICTABLE flag.166 167For address spaces that are so marked after being populated (as SHM regions168might be), the lock action (e.g. SHM_LOCK) can be lazy, and need not populate169the page tables for the region as does, for example, mlock(), nor need it make170any special effort to push any pages in the SHM_LOCK'd area to the unevictable171list. Instead, vmscan will do this if and when it encounters the folios during172a reclamation scan.173 174On an unlock action (such as SHM_UNLOCK), the unlocker (e.g. shmctl()) must scan175the pages in the region and "rescue" them from the unevictable list if no other176condition is keeping them unevictable. If an unevictable region is destroyed,177the pages are also "rescued" from the unevictable list in the process of178freeing them.179 180folio_evictable() also checks for mlocked folios by calling181folio_test_mlocked(), which is set when a folio is faulted into a182VM_LOCKED VMA, or found in a VMA being VM_LOCKED.183 184 185Vmscan's Handling of Unevictable Folios186---------------------------------------187 188If unevictable folios are culled in the fault path, or moved to the unevictable189list at mlock() or mmap() time, vmscan will not encounter the folios until they190have become evictable again (via munlock() for example) and have been "rescued"191from the unevictable list. However, there may be situations where we decide,192for the sake of expediency, to leave an unevictable folio on one of the regular193active/inactive LRU lists for vmscan to deal with. vmscan checks for such194folios in all of the shrink_{active|inactive|folio}_list() functions and will195"cull" such folios that it encounters: that is, it diverts those folios to the196unevictable list for the memory cgroup and node being scanned.197 198There may be situations where a folio is mapped into a VM_LOCKED VMA,199but the folio does not have the mlocked flag set. Such folios will make200it all the way to shrink_active_list() or shrink_folio_list() where they201will be detected when vmscan walks the reverse map in folio_referenced()202or try_to_unmap(). The folio is culled to the unevictable list when it203is released by the shrinker.204 205To "cull" an unevictable folio, vmscan simply puts the folio back on206the LRU list using folio_putback_lru() - the inverse operation to207folio_isolate_lru() - after dropping the folio lock. Because the208condition which makes the folio unevictable may change once the folio209is unlocked, __pagevec_lru_add_fn() will recheck the unevictable state210of a folio before placing it on the unevictable list.211 212 213MLOCKED Pages214=============215 216The unevictable folio list is also useful for mlock(), in addition to ramfs and217SYSV SHM. Note that mlock() is only available in CONFIG_MMU=y situations; in218NOMMU situations, all mappings are effectively mlocked.219 220 221History222-------223 224The "Unevictable mlocked Pages" infrastructure is based on work originally225posted by Nick Piggin in an RFC patch entitled "mm: mlocked pages off LRU".226Nick posted his patch as an alternative to a patch posted by Christoph Lameter227to achieve the same objective: hiding mlocked pages from vmscan.228 229In Nick's patch, he used one of the struct page LRU list link fields as a count230of VM_LOCKED VMAs that map the page (Rik van Riel had the same idea three years231earlier). But this use of the link field for a count prevented the management232of the pages on an LRU list, and thus mlocked pages were not migratable as233folio_isolate_lru() could not detect them, and the LRU list link field was not234available to the migration subsystem.235 236Nick resolved this by putting mlocked pages back on the LRU list before237attempting to isolate them, thus abandoning the count of VM_LOCKED VMAs. When238Nick's patch was integrated with the Unevictable LRU work, the count was239replaced by walking the reverse map when munlocking, to determine whether any240other VM_LOCKED VMAs still mapped the page.241 242However, walking the reverse map for each page when munlocking was ugly and243inefficient, and could lead to catastrophic contention on a file's rmap lock,244when many processes which had it mlocked were trying to exit. In 5.18, the245idea of keeping mlock_count in Unevictable LRU list link field was revived and246put to work, without preventing the migration of mlocked pages. This is why247the "Unevictable LRU list" cannot be a linked list of pages now; but there was248no use for that linked list anyway - though its size is maintained for meminfo.249 250 251Basic Management252----------------253 254mlocked pages - pages mapped into a VM_LOCKED VMA - are a class of unevictable255pages. When such a page has been "noticed" by the memory management subsystem,256the folio is marked with the PG_mlocked flag. This can be manipulated using257folio_set_mlocked() and folio_clear_mlocked() functions.258 259A PG_mlocked page will be placed on the unevictable list when it is added to260the LRU. Such pages can be "noticed" by memory management in several places:261 262 (1) in the mlock()/mlock2()/mlockall() system call handlers;263 264 (2) in the mmap() system call handler when mmapping a region with the265 MAP_LOCKED flag;266 267 (3) mmapping a region in a task that has called mlockall() with the MCL_FUTURE268 flag;269 270 (4) in the fault path and when a VM_LOCKED stack segment is expanded; or271 272 (5) as mentioned above, in vmscan:shrink_folio_list() when attempting to273 reclaim a page in a VM_LOCKED VMA by folio_referenced() or try_to_unmap().274 275mlocked pages become unlocked and rescued from the unevictable list when:276 277 (1) mapped in a range unlocked via the munlock()/munlockall() system calls;278 279 (2) munmap()'d out of the last VM_LOCKED VMA that maps the page, including280 unmapping at task exit;281 282 (3) when the page is truncated from the last VM_LOCKED VMA of an mmapped file;283 or284 285 (4) before a page is COW'd in a VM_LOCKED VMA.286 287 288mlock()/mlock2()/mlockall() System Call Handling289------------------------------------------------290 291mlock(), mlock2() and mlockall() system call handlers proceed to mlock_fixup()292for each VMA in the range specified by the call. In the case of mlockall(),293this is the entire active address space of the task. Note that mlock_fixup()294is used for both mlocking and munlocking a range of memory. A call to mlock()295an already VM_LOCKED VMA, or to munlock() a VMA that is not VM_LOCKED, is296treated as a no-op and mlock_fixup() simply returns.297 298If the VMA passes some filtering as described in "Filtering Special VMAs"299below, mlock_fixup() will attempt to merge the VMA with its neighbors or split300off a subset of the VMA if the range does not cover the entire VMA. Any pages301already present in the VMA are then marked as mlocked by mlock_folio() via302mlock_pte_range() via walk_page_range() via mlock_vma_pages_range().303 304Before returning from the system call, do_mlock() or mlockall() will call305__mm_populate() to fault in the remaining pages via get_user_pages() and to306mark those pages as mlocked as they are faulted.307 308Note that the VMA being mlocked might be mapped with PROT_NONE. In this case,309get_user_pages() will be unable to fault in the pages. That's okay. If pages310do end up getting faulted into this VM_LOCKED VMA, they will be handled in the311fault path - which is also how mlock2()'s MLOCK_ONFAULT areas are handled.312 313For each PTE (or PMD) being faulted into a VMA, the page add rmap function314calls mlock_vma_folio(), which calls mlock_folio() when the VMA is VM_LOCKED315(unless it is a PTE mapping of a part of a transparent huge page). Or when316it is a newly allocated anonymous page, folio_add_lru_vma() calls317mlock_new_folio() instead: similar to mlock_folio(), but can make better318judgments, since this page is held exclusively and known not to be on LRU yet.319 320mlock_folio() sets PG_mlocked immediately, then places the page on the CPU's321mlock folio batch, to batch up the rest of the work to be done under lru_lock by322__mlock_folio(). __mlock_folio() sets PG_unevictable, initializes mlock_count323and moves the page to unevictable state ("the unevictable LRU", but with324mlock_count in place of LRU threading). Or if the page was already PG_lru325and PG_unevictable and PG_mlocked, it simply increments the mlock_count.326 327But in practice that may not work ideally: the page may not yet be on an LRU, or328it may have been temporarily isolated from LRU. In such cases the mlock_count329field cannot be touched, but will be set to 0 later when __munlock_folio()330returns the page to "LRU". Races prohibit mlock_count from being set to 1 then:331rather than risk stranding a page indefinitely as unevictable, always err with332mlock_count on the low side, so that when munlocked the page will be rescued to333an evictable LRU, then perhaps be mlocked again later if vmscan finds it in a334VM_LOCKED VMA.335 336 337Filtering Special VMAs338----------------------339 340mlock_fixup() filters several classes of "special" VMAs:341 3421) VMAs with VM_IO or VM_PFNMAP set are skipped entirely. The pages behind343 these mappings are inherently pinned, so we don't need to mark them as344 mlocked. In any case, most of the pages have no struct page in which to so345 mark the page. Because of this, get_user_pages() will fail for these VMAs,346 so there is no sense in attempting to visit them.347 3482) VMAs mapping hugetlbfs page are already effectively pinned into memory. We349 neither need nor want to mlock() these pages. But __mm_populate() includes350 hugetlbfs ranges, allocating the huge pages and populating the PTEs.351 3523) VMAs with VM_DONTEXPAND are generally userspace mappings of kernel pages,353 such as the VDSO page, relay channel pages, etc. These pages are inherently354 unevictable and are not managed on the LRU lists. __mm_populate() includes355 these ranges, populating the PTEs if not already populated.356 3574) VMAs with VM_MIXEDMAP set are not marked VM_LOCKED, but __mm_populate()358 includes these ranges, populating the PTEs if not already populated.359 360Note that for all of these special VMAs, mlock_fixup() does not set the361VM_LOCKED flag. Therefore, we won't have to deal with them later during362munlock(), munmap() or task exit. Neither does mlock_fixup() account these363VMAs against the task's "locked_vm".364 365 366munlock()/munlockall() System Call Handling367-------------------------------------------368 369The munlock() and munlockall() system calls are handled by the same370mlock_fixup() function as mlock(), mlock2() and mlockall() system calls are.371If called to munlock an already munlocked VMA, mlock_fixup() simply returns.372Because of the VMA filtering discussed above, VM_LOCKED will not be set in373any "special" VMAs. So, those VMAs will be ignored for munlock.374 375If the VMA is VM_LOCKED, mlock_fixup() again attempts to merge or split off the376specified range. All pages in the VMA are then munlocked by munlock_folio() via377mlock_pte_range() via walk_page_range() via mlock_vma_pages_range() - the same378function used when mlocking a VMA range, with new flags for the VMA indicating379that it is munlock() being performed.380 381munlock_folio() uses the mlock pagevec to batch up work to be done382under lru_lock by __munlock_folio(). __munlock_folio() decrements the383folio's mlock_count, and when that reaches 0 it clears the mlocked flag384and clears the unevictable flag, moving the folio from unevictable state385to the inactive LRU.386 387But in practice that may not work ideally: the folio may not yet have reached388"the unevictable LRU", or it may have been temporarily isolated from it. In389those cases its mlock_count field is unusable and must be assumed to be 0: so390that the folio will be rescued to an evictable LRU, then perhaps be mlocked391again later if vmscan finds it in a VM_LOCKED VMA.392 393 394Migrating MLOCKED Pages395-----------------------396 397A page that is being migrated has been isolated from the LRU lists and is held398locked across unmapping of the page, updating the page's address space entry399and copying the contents and state, until the page table entry has been400replaced with an entry that refers to the new page. Linux supports migration401of mlocked pages and other unevictable pages. PG_mlocked is cleared from the402the old page when it is unmapped from the last VM_LOCKED VMA, and set when the403new page is mapped in place of migration entry in a VM_LOCKED VMA. If the page404was unevictable because mlocked, PG_unevictable follows PG_mlocked; but if the405page was unevictable for other reasons, PG_unevictable is copied explicitly.406 407Note that page migration can race with mlocking or munlocking of the same page.408There is mostly no problem since page migration requires unmapping all PTEs of409the old page (including munlock where VM_LOCKED), then mapping in the new page410(including mlock where VM_LOCKED). The page table locks provide sufficient411synchronization.412 413However, since mlock_vma_pages_range() starts by setting VM_LOCKED on a VMA,414before mlocking any pages already present, if one of those pages were migrated415before mlock_pte_range() reached it, it would get counted twice in mlock_count.416To prevent that, mlock_vma_pages_range() temporarily marks the VMA as VM_IO,417so that mlock_vma_folio() will skip it.418 419To complete page migration, we place the old and new pages back onto the LRU420afterwards. The "unneeded" page - old page on success, new page on failure -421is freed when the reference count held by the migration process is released.422 423 424Compacting MLOCKED Pages425------------------------426 427The memory map can be scanned for compactable regions and the default behavior428is to let unevictable pages be moved. /proc/sys/vm/compact_unevictable_allowed429controls this behavior (see Documentation/admin-guide/sysctl/vm.rst). The work430of compaction is mostly handled by the page migration code and the same work431flow as described in Migrating MLOCKED Pages will apply.432 433 434MLOCKING Transparent Huge Pages435-------------------------------436 437A transparent huge page is represented by a single entry on an LRU list.438Therefore, we can only make unevictable an entire compound page, not439individual subpages.440 441If a user tries to mlock() part of a huge page, and no user mlock()s the442whole of the huge page, we want the rest of the page to be reclaimable.443 444We cannot just split the page on partial mlock() as split_huge_page() can445fail and a new intermittent failure mode for the syscall is undesirable.446 447We handle this by keeping PTE-mlocked huge pages on evictable LRU lists:448the PMD on the border of a VM_LOCKED VMA will be split into a PTE table.449 450This way the huge page is accessible for vmscan. Under memory pressure the451page will be split, subpages which belong to VM_LOCKED VMAs will be moved452to the unevictable LRU and the rest can be reclaimed.453 454/proc/meminfo's Unevictable and Mlocked amounts do not include those parts455of a transparent huge page which are mapped only by PTEs in VM_LOCKED VMAs.456 457 458mmap(MAP_LOCKED) System Call Handling459-------------------------------------460 461In addition to the mlock(), mlock2() and mlockall() system calls, an application462can request that a region of memory be mlocked by supplying the MAP_LOCKED flag463to the mmap() call. There is one important and subtle difference here, though.464mmap() + mlock() will fail if the range cannot be faulted in (e.g. because465mm_populate fails) and returns with ENOMEM while mmap(MAP_LOCKED) will not fail.466The mmapped area will still have properties of the locked area - pages will not467get swapped out - but major page faults to fault memory in might still happen.468 469Furthermore, any mmap() call or brk() call that expands the heap by a task470that has previously called mlockall() with the MCL_FUTURE flag will result471in the newly mapped memory being mlocked. Before the unevictable/mlock472changes, the kernel simply called make_pages_present() to allocate pages473and populate the page table.474 475To mlock a range of memory under the unevictable/mlock infrastructure,476the mmap() handler and task address space expansion functions call477populate_vma_page_range() specifying the vma and the address range to mlock.478 479 480munmap()/exit()/exec() System Call Handling481-------------------------------------------482 483When unmapping an mlocked region of memory, whether by an explicit call to484munmap() or via an internal unmap from exit() or exec() processing, we must485munlock the pages if we're removing the last VM_LOCKED VMA that maps the pages.486Before the unevictable/mlock changes, mlocking did not mark the pages in any487way, so unmapping them required no processing.488 489For each PTE (or PMD) being unmapped from a VMA, folio_remove_rmap_*() calls490munlock_vma_folio(), which calls munlock_folio() when the VMA is VM_LOCKED491(unless it was a PTE mapping of a part of a transparent huge page).492 493munlock_folio() uses the mlock pagevec to batch up work to be done494under lru_lock by __munlock_folio(). __munlock_folio() decrements the495folio's mlock_count, and when that reaches 0 it clears the mlocked flag496and clears the unevictable flag, moving the folio from unevictable state497to the inactive LRU.498 499But in practice that may not work ideally: the folio may not yet have reached500"the unevictable LRU", or it may have been temporarily isolated from it. In501those cases its mlock_count field is unusable and must be assumed to be 0: so502that the folio will be rescued to an evictable LRU, then perhaps be mlocked503again later if vmscan finds it in a VM_LOCKED VMA.504 505 506Truncating MLOCKED Pages507------------------------508 509File truncation or hole punching forcibly unmaps the deleted pages from510userspace; truncation even unmaps and deletes any private anonymous pages511which had been Copied-On-Write from the file pages now being truncated.512 513Mlocked pages can be munlocked and deleted in this way: like with munmap(),514for each PTE (or PMD) being unmapped from a VMA, folio_remove_rmap_*() calls515munlock_vma_folio(), which calls munlock_folio() when the VMA is VM_LOCKED516(unless it was a PTE mapping of a part of a transparent huge page).517 518However, if there is a racing munlock(), since mlock_vma_pages_range() starts519munlocking by clearing VM_LOCKED from a VMA, before munlocking all the pages520present, if one of those pages were unmapped by truncation or hole punch before521mlock_pte_range() reached it, it would not be recognized as mlocked by this VMA,522and would not be counted out of mlock_count. In this rare case, a page may523still appear as PG_mlocked after it has been fully unmapped: and it is left to524release_pages() (or __page_cache_release()) to clear it and update statistics525before freeing (this event is counted in /proc/vmstat unevictable_pgs_cleared,526which is usually 0).527 528 529Page Reclaim in shrink_*_list()530-------------------------------531 532vmscan's shrink_active_list() culls any obviously unevictable pages -533i.e. !page_evictable(page) pages - diverting those to the unevictable list.534However, shrink_active_list() only sees unevictable pages that made it onto the535active/inactive LRU lists. Note that these pages do not have PG_unevictable536set - otherwise they would be on the unevictable list and shrink_active_list()537would never see them.538 539Some examples of these unevictable pages on the LRU lists are:540 541 (1) ramfs pages that have been placed on the LRU lists when first allocated.542 543 (2) SHM_LOCK'd shared memory pages. shmctl(SHM_LOCK) does not attempt to544 allocate or fault in the pages in the shared memory region. This happens545 when an application accesses the page the first time after SHM_LOCK'ing546 the segment.547 548 (3) pages still mapped into VM_LOCKED VMAs, which should be marked mlocked,549 but events left mlock_count too low, so they were munlocked too early.550 551vmscan's shrink_inactive_list() and shrink_folio_list() also divert obviously552unevictable pages found on the inactive lists to the appropriate memory cgroup553and node unevictable list.554 555rmap's folio_referenced_one(), called via vmscan's shrink_active_list() or556shrink_folio_list(), and rmap's try_to_unmap_one() called via shrink_folio_list(),557check for (3) pages still mapped into VM_LOCKED VMAs, and call mlock_vma_folio()558to correct them. Such pages are culled to the unevictable list when released559by the shrinker.560