admin-guide/mm/hugetlbpage.rst

9 the Linux kernel.  This support is built on top of multiple page size support
11 support 4K and 2M (1G if architecturally supported) page sizes, ia64
12 architecture supports multiple page sizes 4K, 8K, 64K, 256K, 1M, 4M, 16M,
13 256M and ppc64 supports 4K and 16M.  A TLB is a cache of virtual-to-physical
19 Users can use the huge page support in Linux kernel by either using the mmap
28 persistent hugetlb pages in the kernel's huge page pool.  It also displays
29 default huge page size and information about the number of free, reserved
30 and surplus huge pages in the pool of huge pages of default size.
31 The huge page size is needed for generating the proper alignment and
32 size of the arguments to system calls that map huge page regions.
46 	is the size of the pool of huge pages.
55         huge page from the pool of huge pages at fault time.
62 	with each hugetlb page is enabled, the number of surplus huge pages
66 	is the default hugepage size (in kB).
80 pages in the kernel's huge page pool.  "Persistent" huge pages will be
81 returned to the huge page pool when freed by a task.  A user with root
86 hugetlb page is enabled, we can fail to free the huge pages triggered by
93 Once a number of huge pages have been pre-allocated to the kernel huge page
103 Some platforms support multiple huge page sizes.  To allocate huge pages
104 of a specific size, one must precede the huge pages boot command parameters
105 with a huge page size selection parameter "hugepagesz=<size>".  <size> must
107 page size may be selected with the "default_hugepagesz=<size>" boot parameter.
112 	Specify a huge page size.  Used in conjunction with hugepages
114 	size.  Hence, hugepagesz and hugepages are typically specified in
120 	specific huge page size.  Valid huge page sizes are architecture
126 	implicitly specifies the number of huge pages of default size to
127 	allocate.  If the number of huge pages of default size is implicitly
129 	parameter pair for the default size.  This parameter also has a
133 	For example, on an architecture with 2M default huge page size::
150 	Specify the default huge page size.  This parameter can
153 	specific number of huge pages of default size.  The number of default
156 	architecture with 2M default huge page size::
163 	huge page size is architecture dependent.
168 When multiple huge page sizes are supported, ``/proc/sys/vm/nr_hugepages``
169 indicates the current number of pre-allocated huge pages of the default size.
176 huge page pool to 20, allocating or freeing huge pages, as required.
178 On a NUMA platform, the kernel will attempt to distribute the huge page pool
180 task that modifies ``nr_hugepages``. The default for the allowed nodes--when the
181 task has default memory policy--is all on-line nodes with memory.  Allowed
182 nodes with insufficient available, contiguous memory for a huge page will be
188 The success or failure of huge page allocation depends on the amount of
206 requested by applications.  Writing any non-zero value into this file
208 number of "surplus" huge pages from the kernel's normal page pool, when the
209 persistent huge page pool is exhausted. As these surplus huge pages become
210 unused, they are freed back to the kernel's normal page pool.
212 When increasing the huge page pool size via ``nr_hugepages``, any existing
215 the new persistent huge page pool size.
218 the default huge page size by setting the ``nr_hugepages`` sysctl to a
222 normal page pool.
224 Caveat: Shrinking the persistent huge page pool via ``nr_hugepages`` such that
226 of the in-use huge pages to surplus huge pages.  This will occur even if
228 this condition holds--that is, until ``nr_hugepages+nr_overcommit_hugepages`` is
229 increased sufficiently, or the surplus huge pages go out of use and are freed--
232 With support for multiple huge page pools at run-time available, much of
233 the huge page userspace interface in ``/proc/sys/vm`` has been duplicated in
236 compatibility. The root huge page control directory in sysfs is::
240 For each huge page size supported by the running kernel, a subdirectory
243 	hugepages-${size}kB
258 The demote interfaces provide the ability to split a huge page into
260 1GB and 2MB huge pages sizes.  A 1GB huge page can be split into 512
262 huge page size.  The demote interfaces are:
265         is the size of demoted pages.  When a page is demoted a corresponding
267         demote_size is set to the next smaller huge page size.  If there are
268         multiple smaller huge page sizes, demote_size can be set to any of
269         these smaller sizes.  Only huge page sizes less than the current huge
270         pages size are allowed.
280 demote_size) function as described above for the default huge page-sized case.
284 Interaction of Task Memory Policy with Huge Page Allocation/Freeing
295 huge page pool, using the ``nr_hugepages`` example above, is::
297     numactl --interleave <node-list> echo 20 \
302     numactl -m <node-list> echo 20 >/proc/sys/vm/nr_hugepages_mempolicy
304 This will allocate or free ``abs(20 - nr_hugepages)`` to or from the nodes
305 specified in <node-list>, depending on whether number of persistent huge pages
307 allocated nor freed on any node not included in the specified <node-list>.
310 memory policy mode--bind, preferred, local or interleave--may be used.  The
311 resulting effect on persistent huge page allocation is as follows:
314    Documentation/admin-guide/mm/numa_memory_policy.rst],
318    memory for a huge page, the allocation will not "fallback" to the nearest
320    undesirable imbalance in the distribution of the huge page pool, or
334 #. The nodes allowed mask will be derived from any non-default task mempolicy,
337    shell with non-default policy, that policy will be used.  One can specify a
338    node list of "all" with numactl --interleave or --membind [-m] to achieve
341 #. Any task mempolicy specified--e.g., using numactl--will be constrained by
343    be no way for a task with non-default policy running in a cpuset with a
347 #. Boot-time huge page allocation attempts to distribute the requested number
348    of huge pages over all on-lines nodes with memory.
353 A subset of the contents of the root huge page control directory in sysfs,
357 	/sys/devices/system/node/node[0-9]*/hugepages/
359 Under this directory, the subdirectory for each supported huge page size
366 The free\_' and surplus\_' attribute files are read-only.  They return the number
377 applied, from which node the huge page allocation will be attempted.
379 The hugetlb may be migrated between the per-node hugepages pool in the following
384 hugetlb migration, that means these 3 cases can break the per-node hugepages pool.
395   mount -t hugetlbfs \
396 	-o uid=<value>,gid=<value>,mode=<value>,pagesize=<value>,size=<value>,\
409 If the platform supports multiple huge page sizes, the ``pagesize`` option can
410 be used to specify the huge page size and associated pool. ``pagesize``
412 default huge page size and associated pool will be used.
414 The ``size`` option sets the maximum value of memory (huge pages) allowed
415 for that filesystem (``/mnt/huge``). The ``size`` option can be specified
416 in bytes, or as a percentage of the specified huge page pool (``nr_hugepages``).
417 The size is rounded down to HPAGE_SIZE boundary.
420 for the filesystem. ``min_size`` can be specified in the same way as ``size``,
421 either bytes or a percentage of the huge page pool.
432 If the ``size``, ``min_size`` or ``nr_inodes`` option is not provided on
435 For ``pagesize``, ``size``, ``min_size`` and ``nr_inodes`` options, you can
437 For example, size=2K has the same meaning as size=2048.
457 aligned to the native page size of the processor; they will normally fail with
460 a hugetlb page and the length is smaller than the hugepage size.
471 ``hugepage-shm``
472 	see tools/testing/selftests/mm/hugepage-shm.c
474 ``hugepage-mmap``
475 	see tools/testing/selftests/mm/hugepage-mmap.c
478 to help with huge page usability, environment setup, and control.