Documentation/mm/hugetlbfs_reserv.rst

8 Huge pages as described at Documentation/admin-guide/mm/hugetlbpage.rst are
9 typically preallocated for application use.  These huge pages are instantiated
10 in a task's address space at page fault time if the VMA indicates huge pages
11 are to be used.  If no huge page exists at page fault time, the task is sent
12 a SIGBUS and often dies an unhappy death.  Shortly after huge page support
14 of huge pages at mmap() time.  The idea is that if there were not enough
15 huge pages to cover the mapping, the mmap() would fail.  This was first
17 were enough free huge pages to cover the mapping.  Like most things in the
19 'reserve' huge pages at mmap() time to ensure that huge pages would be
21 describe how huge page reserve processing is done in the v4.10 kernel.
34 	This is a global (per-hstate) count of reserved huge pages.  Reserved
35 	huge pages are only available to the task which reserved them.
36 	Therefore, the number of huge pages generally available is computed
50 	There is one reserve map for each huge page mapping in the system.
60 	The 'from' and 'to' fields of the file region structure are huge page
75 	The PagePrivate page flag is used to indicate that a huge page
76 	reservation must be restored when the huge page is freed.  More
77 	details will be discussed in the "Freeing huge pages" section.
83 A huge page mapping or segment is either private or shared.  If private,
101 Reservations are created when a huge page backed shared memory segment is
115 The arguments 'from' and 'to' are huge page indices into the mapping or
137 The reservation map is consulted to determine how many huge page reservations
154 are enough free huge pages to accommodate the reservation.  If there are,
164 If there were enough free huge pages and the global count resv_huge_pages
177 Consuming Reservations/Allocating a Huge Page
180 Reservations are consumed when huge pages associated with the reservations
228 Note, if no huge page can be found that satisfies the VMA's memory policy
230 brings up the issue of surplus huge pages and overcommit which is beyond
260 Instantiate Huge Pages
263 After huge page allocation, the page is typically added to the page tables
267 when a huge page that has been instantiated is freed no adjustment is made
271 Freeing Huge Pages
274 Huge pages are freed by free_huge_folio().  It is only passed a pointer
275 to the folio as it is called from the generic MM code.  When a huge page
284 :ref:`Consuming Reservations/Allocating a Huge Page <consume_resv>`
301 There is a struct hstate associated with each huge page size.  The hstate
302 tracks all huge pages of the specified size.  A subpool represents a subset
307 which indicates the minimum number of huge pages required by the filesystem.
308 If this option is specified, the number of huge pages corresponding to
312 huge pages.  If they can not be reserved, the mount fails.
317 hugepage_subpool_get/put_pages are passed the number of huge pages by which
325 suppose a subpool contains 3 reserved huge pages and someone asks for 5.
344 COW, it is possible that no free huge pages are free and the allocation
388    there are enough huge pages for the operation to succeed.
426 - When a hole is being punched in a hugetlbfs file.  In this case, huge pages
443 region_count() is called when unmapping a private huge page mapping.  In
457 These routines are only interested with reservations for a specific huge
521 Additionally, after a huge page is instantiated the PagePrivate flag is
524 However, there are several instances where errors are encountered after a huge
531 will cause the 'leak' of a reserved huge page.  The global reserve count will
550 so that a reservation will not be leaked when the huge page is freed.
555 Per-node huge page lists existed in struct hstate when git was first used
580 Huge page reservations were added to prevent unexpected page allocation
582 of cpusets or memory policy there is no guarantee that huge pages will be