Transparent Hugepage Support

THP 설계 원칙

Transparent Hugepage 지원

이 문서는 Transparent Hugepage(THP) 지원의 설계 원칙과 메모리 관리 시스템의 다른 부분과 상호 작용하는 방식을 설명합니다.

설계 원칙

• `graceful fallback`: THP를 모르는 mm 구성 요소는 huge PMD mapping을 PTE table로 풀고, 필요하면 THP 자체도 분할합니다. 그러면 기존 구성 요소는 regular page 또는 regular PTE mapping에서 계속 동작할 수 있습니다.
• Memory fragmentation 때문에 hugepage 할당이 실패하면 regular page를 대신 자연스럽게 할당하여 같은 VMA에 섞습니다. 실패나 큰 지연이 없어야 하며 userspace가 이를 알아차리지 않아야 합니다.
• Task가 종료되어 buddy 또는 VM을 통해 hugepage가 더 생기면 regular page가 backing하던 guest physical memory를 `khugepaged`가 자동으로 hugepage로 옮겨야 합니다.
• THP는 memory reservation을 요구하지 않고 가능할 때마다 hugepage를 사용합니다. `kernelcore=`로 unmovable page가 전체 memory를 조각내지 않게 하는 예약은 가능하지만, 이는 THP 전용이 아니라 kernel의 모든 dynamic high-order allocation에 적용되는 일반 기능입니다.

다음 절은 `get_user_pages`와 `pin_user_pages`의 동작을 설명합니다.

============================
Transparent Hugepage Support
============================

This document describes design principles for Transparent Hugepage (THP)
support and its interaction with other parts of the memory management
system.

Design principles
=================

- "graceful fallback": mm components which don't have transparent hugepage
  knowledge fall back to breaking huge pmd mapping into table of ptes and,
  if necessary, split a transparent hugepage. Therefore these components
  can continue working on the regular pages or regular pte mappings.

- if a hugepage allocation fails because of memory fragmentation,
  regular pages should be gracefully allocated instead and mixed in
  the same vma without any failure or significant delay and without
  userland noticing

- if some task quits and more hugepages become available (either
  immediately in the buddy or through the VM), guest physical memory
  backed by regular pages should be relocated on hugepages
  automatically (with khugepaged)

- it doesn't require memory reservation and in turn it uses hugepages
  whenever possible (the only possible reservation here is kernelcore=
  to avoid unmovable pages to fragment all the memory but such a tweak
  is not specific to transparent hugepage support and it's a generic
  feature that applies to all dynamic high order allocations in the
  kernel)

get_user_pages and pin_user_pages

GUP와 head·tail page

`get_user_pages`와 `pin_user_pages`를 hugepage에서 실행하면 hugetlbfs에서와 마찬가지로 head page 또는 tail page를 반환합니다.

대부분의 GUP 사용자는 실제 physical address와 I/O가 끝날 때까지 유지할 임시 pin만 필요하므로 page가 hugepage라는 사실을 알지 못합니다.

하지만 driver가 tail page의 `page->mapping`처럼 head page에만 의미가 있는 `struct page` 필드를 조사하거나 바꾸려 한다면 head page로 이동해 확인하도록 고쳐야 합니다. Head 또는 tail 어느 page에서든 reference를 얻으면 누구도 그 page를 분할할 수 없습니다.

이는 GUP API의 새 제약이 아닙니다. hugetlbfs에도 같은 제약이 적용되므로 hugetlbfs에서 GUP를 처리할 수 있는 driver는 THP-backed mapping에서도 정상 동작합니다.

=================================

get_user_pages and pin_user_pages if run on a hugepage, will return the
head or tail pages as usual (exactly as they would do on
hugetlbfs). Most GUP users will only care about the actual physical
address of the page and its temporary pinning to release after the I/O
is complete, so they won't ever notice the fact the page is huge. But
if any driver is going to mangle over the page structure of the tail
page (like for checking page->mapping or other bits that are relevant
for the head page and not the tail page), it should be updated to jump
to check head page instead. Taking a reference on any head/tail page would
prevent the page from being split by anyone.

.. note::
   these aren't new constraints to the GUP API, and they match the
   same constraints that apply to hugetlbfs too, so any driver capable
   of handling GUP on hugetlbfs will also work fine on transparent
   hugepage backed mappings.

Page-table과 physical hugepage fallback

Graceful fallback

Page table을 순회하지만 huge PMD를 모르는 코드는 `pmd_offset`이 돌려준 pmd에 `split_huge_pmd(vma, pmd, addr)`를 호출하면 됩니다. `pmd_offset`을 검색해 빠진 곳마다 이 한 줄을 넣으면 수백 또는 수천 줄의 복잡한 hugepage 전용 코드를 작성하지 않고도 기존 경로를 사용할 수 있습니다.

Page table을 순회하지 않더라도 code가 physical hugepage를 직접 처리할 수 없다면 `split_huge_page(page)`로 분할할 수 있습니다. Linux VM도 hugepage를 swap out하기 전에 이 방식을 사용합니다. Page가 pinned 상태이면 `split_huge_page()`가 실패할 수 있으므로 이 실패를 올바르게 처리해야 합니다.

이어지는 diff는 `mm/mremap.c`의 `pmd_offset(pud, addr)` 바로 다음에 `split_huge_pmd(vma, pmd, addr)`를 추가하는 한 줄 변경 예입니다. 원문의 diff와 line coordinate는 아래 source block에 그대로 보존했습니다.

Graceful fallback
=================

Code walking pagetables but unaware about huge pmds can simply call
split_huge_pmd(vma, pmd, addr) where the pmd is the one returned by
pmd_offset. It's trivial to make the code transparent hugepage aware
by just grepping for "pmd_offset" and adding split_huge_pmd where
missing after pmd_offset returns the pmd. Thanks to the graceful
fallback design, with a one liner change, you can avoid to write
hundreds if not thousands of lines of complex code to make your code
hugepage aware.

If you're not walking pagetables but you run into a physical hugepage
that you can't handle natively in your code, you can split it by
calling split_huge_page(page). This is what the Linux VM does before
it tries to swapout the hugepage for example. split_huge_page() can fail
if the page is pinned and you must handle this correctly.

Example to make mremap.c transparent hugepage aware with a one liner
change::

        diff --git a/mm/mremap.c b/mm/mremap.c
        --- a/mm/mremap.c
        +++ b/mm/mremap.c
        @@ -41,6 +41,7 @@ static pmd_t *get_old_pmd(struct mm_stru
                        return NULL;

                pmd = pmd_offset(pud, addr);
        +        split_huge_pmd(vma, pmd, addr);
                if (pmd_none_or_clear_bad(pmd))
                        return NULL;

Locking in hugepage aware code

Hugepage-aware 순회의 재확인

Hugepage-aware code의 잠금

`split_huge_page()`와 `split_huge_pmd()`에는 비용이 있으므로 가능한 많은 code가 hugepage를 직접 처리하는 편이 좋습니다.

Page-table walk가 huge PMD를 인식하게 하려면 `pmd_offset`이 반환한 pmd에 `pmd_trans_huge()`를 호출합니다. `khugepaged`가 아래에서 huge PMD를 새로 만들지 못하도록 `mmap_lock`을 read 또는 write mode로 보유해야 합니다. `khugepaged`의 `collapse_huge_page`는 `anon_vma` lock에 더해 mmap write lock도 획득합니다.

첫 `pmd_trans_huge()`가 false이면 기존 경로로 돌아갑니다. True이면 `pmd_lock()`으로 page-table lock을 잡고 `pmd_trans_huge()`를 다시 실행합니다. 이 잠금은 동시에 실행되는 `split_huge_pmd`가 huge PMD를 regular PMD로 바꾸지 못하게 합니다.

두 번째 검사에서 false가 되면 page-table lock을 놓고 기존 경로로 fallback합니다. 여전히 true이면 huge PMD와 hugepage를 native 방식으로 처리한 뒤 lock을 해제합니다.

THP refcount는 다른 compound page의 refcount와 대부분 일관됩니다. `get_page()`·`put_page()`와 GUP는 `folio->_refcount`에서 동작하며 tail page의 `->_refcount`는 언제나 0이어서 `get_page_unless_zero()`가 성공하지 않습니다.

==============================

We want as much code as possible hugepage aware, as calling
split_huge_page() or split_huge_pmd() has a cost.

To make pagetable walks huge pmd aware, all you need to do is to call
pmd_trans_huge() on the pmd returned by pmd_offset. You must hold the
mmap_lock in read (or write) mode to be sure a huge pmd cannot be
created from under you by khugepaged (khugepaged collapse_huge_page
takes the mmap_lock in write mode in addition to the anon_vma lock). If
pmd_trans_huge returns false, you just fallback in the old code
paths. If instead pmd_trans_huge returns true, you have to take the
page table lock (pmd_lock()) and re-run pmd_trans_huge. Taking the
page table lock will prevent the huge pmd being converted into a
regular pmd from under you (split_huge_pmd can run in parallel to the
pagetable walk). If the second pmd_trans_huge returns false, you
should just drop the page table lock and fallback to the old code as
before. Otherwise, you can proceed to process the huge pmd and the
hugepage natively. Once finished, you can drop the page table lock.

Refcounts and transparent huge pages
====================================

Refcounting on THP is mostly consistent with refcounting on other compound
pages:

  - get_page()/put_page() and GUP operate on the folio->_refcount.

  - ->_refcount in tail pages is always zero: get_page_unless_zero() never
    succeeds on tail pages.

PMD·PTE mapcount와 분할

THP 전체를 가리키는 PMD 엔트리를 map 또는 unmap하면 `folio->_entire_mapcount`와 `folio->_large_mapcount`를 증가 또는 감소시킵니다. MM owner를 추적하는 두 slot, 즉 MM ID와 대응 mapcount 및 현재 상태인 `maybe mapped shared` 또는 `mapped exclusively`도 유지합니다.

`CONFIG_PAGE_MAPCOUNT`에서는 `_entire_mapcount`가 -1에서 0 또는 0에서 -1로 바뀔 때 `folio->_nr_pages_mapped`를 `ENTIRELY_MAPPED`만큼 증가 또는 감소시킵니다.

개별 page를 PTE 엔트리로 map 또는 unmap하면 `folio->_large_mapcount`를 바꾸고 같은 두 MM-owner slot과 현재 상태를 유지합니다. `CONFIG_PAGE_MAPCOUNT`에서는 `page->_mapcount`도 바꾸며, 이 값이 -1과 0 사이를 오갈 때 PTE로 map된 page 수를 세기 위해 `folio->_nr_pages_mapped`를 증가 또는 감소시킵니다.

`split_huge_page`는 page 구조에서 `PG_head`와 tail bit를 지우기 전에 head page의 refcount를 tail page에 분배해야 합니다. Page-table entry가 얻은 reference는 분배할 수 있지만 `get_user_pages` 등의 추가 pin을 어느 subpage에 나눠야 하는지는 알 수 없습니다.

따라서 `split_huge_page()`는 pinned hugepage 분할을 거부합니다. 기대하는 page count는 모든 subpage mapcount의 합에 caller가 head page에 보유해야 하는 reference 하나를 더한 값입니다.

Anonymous page의 `page->_refcount`와 `page->_mapcount`를 안정화할 때는 migration entry를 사용하고, file page는 unmap합니다.

Physical-memory scanner가 합법적으로 reference를 얻는 유일한 방법은 `get_page_unless_zero()`입니다. 모든 tail page는 `atomic_add()` 전까지 `->_refcount`가 0이므로 scanner가 reference를 얻지 못합니다. 그 뒤에는 head에서 빼야 할 reference 수를 이미 알기 때문에 tail refcount 값은 문제가 되지 않습니다.

Head page의 `get_page_unless_zero()`는 성공해도 괜찮습니다. 분할 뒤에도 그 reference는 head page에 남습니다. `split_huge_pmd()`에는 refcount 제약이 없어서 어느 시점에나 PMD를 분할할 수 있으며 실패하지 않습니다.

  - map/unmap of a PMD entry for the whole THP increment/decrement
    folio->_entire_mapcount and folio->_large_mapcount.

    We also maintain the two slots for tracking MM owners (MM ID and
    corresponding mapcount), and the current status ("maybe mapped shared" vs.
    "mapped exclusively").

    With CONFIG_PAGE_MAPCOUNT, we also increment/decrement
    folio->_nr_pages_mapped by ENTIRELY_MAPPED when _entire_mapcount goes
    from -1 to 0 or 0 to -1.

  - map/unmap of individual pages with PTE entry increment/decrement
    folio->_large_mapcount.

    We also maintain the two slots for tracking MM owners (MM ID and
    corresponding mapcount), and the current status ("maybe mapped shared" vs.
    "mapped exclusively").

    With CONFIG_PAGE_MAPCOUNT, we also increment/decrement
    page->_mapcount and increment/decrement folio->_nr_pages_mapped when
    page->_mapcount goes from -1 to 0 or 0 to -1 as this counts the number
    of pages mapped by PTE.

split_huge_page internally has to distribute the refcounts in the head
page to the tail pages before clearing all PG_head/tail bits from the page
structures. It can be done easily for refcounts taken by page table
entries, but we don't have enough information on how to distribute any
additional pins (i.e. from get_user_pages). split_huge_page() fails any
requests to split pinned huge pages: it expects page count to be equal to
the sum of mapcount of all sub-pages plus one (split_huge_page caller must
have a reference to the head page).

split_huge_page uses migration entries to stabilize page->_refcount and
page->_mapcount of anonymous pages. File pages just get unmapped.

We are safe against physical memory scanners too: the only legitimate way
a scanner can get a reference to a page is get_page_unless_zero().

All tail pages have zero ->_refcount until atomic_add(). This prevents the
scanner from getting a reference to the tail page up to that point. After the
atomic_add() we don't care about the ->_refcount value. We already know how
many references should be uncharged from the head page.

For head page get_page_unless_zero() will succeed and we don't mind. It's
clear where references should go after split: it will stay on the head page.

Note that split_huge_pmd() doesn't have any limitations on refcounting:
pmd can be split at any point and never fails.

부분 unmap과 지연 분할

부분 unmap과 `deferred_split_folio()`(anonymous THP 전용)

`munmap()` 등의 방법으로 THP 일부를 unmap해도 memory는 즉시 해제되지 않습니다. 대신 `folio_remove_rmap_*()`에서 THP의 subpage가 사용되지 않음을 감지하고 memory pressure가 올 때 분할하도록 THP를 queue에 넣습니다. 실제 분할이 일어나면 사용하지 않는 subpage가 해제됩니다.

부분 unmap을 감지하는 지점의 locking context 때문에 즉시 분할할 수 없습니다. 또한 THP가 VMA 경계를 가로지르면 `exit(2)` 중 부분 unmap이 자주 일어나므로 즉시 분할은 오히려 비효율적일 수 있습니다.

`deferred_split_folio()`가 folio를 분할 queue에 넣고, 실제 분할은 memory pressure가 생길 때 shrinker interface를 통해 수행됩니다.

`CONFIG_PAGE_MAPCOUNT`에서는 `folio->_nr_pages_mapped`를 이용해 부분 mapping을 안정적으로 감지합니다.

`CONFIG_NO_PAGE_MAPCOUNT`에서는 THP의 page당 평균 mapcount가 1보다 작으면 anonymous THP가 확실히 부분 mapping되었다고 판단합니다. Process 하나만 THP를 map하는 동안에는 신뢰할 수 있지만, 오래 실행되는 child process가 있으면 현재 감지하지 못하는 경우가 있습니다. 향후 memory reclaim 중 비동기 감지가 필요할 수 있습니다.

Partial unmap and deferred_split_folio() (anon THP only)
========================================================

Unmapping part of THP (with munmap() or other way) is not going to free
memory immediately. Instead, we detect that a subpage of THP is not in use
in folio_remove_rmap_*() and queue the THP for splitting if memory pressure
comes. Splitting will free up unused subpages.

Splitting the page right away is not an option due to locking context in
the place where we can detect partial unmap. It also might be
counterproductive since in many cases partial unmap happens during exit(2) if
a THP crosses a VMA boundary.

The function deferred_split_folio() is used to queue a folio for splitting.
The splitting itself will happen when we get memory pressure via shrinker
interface.

With CONFIG_PAGE_MAPCOUNT, we reliably detect partial mappings based on
folio->_nr_pages_mapped.

With CONFIG_NO_PAGE_MAPCOUNT, we detect partial mappings based on the
average per-page mapcount in a THP: if the average is < 1, an anon THP is
certainly partially mapped. As long as only a single process maps a THP,
this detection is reliable. With long-running child processes, there can
be scenarios where partial mappings can currently not be detected, and
might need asynchronous detection during memory reclaim in the future.