admin-guide/mm/hugetlbpage.rst

11 the Linux kernel.  This support is built on top of multiple page size support
13 support 4K and 2M (1G if architecturally supported) page sizes, ia64
14 architecture supports multiple page sizes 4K, 8K, 64K, 256K, 1M, 4M, 16M,
15 256M and ppc64 supports 4K and 16M.  A TLB is a cache of virtual-to-physical
21 Users can use the huge page support in Linux kernel by either using the mmap
30 persistent hugetlb pages in the kernel's huge page pool.  It also displays
31 default huge page size and information about the number of free, reserved
32 and surplus huge pages in the pool of huge pages of default size.
33 The huge page size is needed for generating the proper alignment and
34 size of the arguments to system calls that map huge page regions.
48 	is the size of the pool of huge pages.
57         huge page from the pool of huge pages at fault time.
64 	is the default hugepage size (in Kb).
78 pages in the kernel's huge page pool.  "Persistent" huge pages will be
79 returned to the huge page pool when freed by a task.  A user with root
87 Once a number of huge pages have been pre-allocated to the kernel huge page
97 Some platforms support multiple huge page sizes.  To allocate huge pages
98 of a specific size, one must precede the huge pages boot command parameters
99 with a huge page size selection parameter "hugepagesz=<size>".  <size> must
101 page size may be selected with the "default_hugepagesz=<size>" boot parameter.
106 	Specify a huge page size.  Used in conjunction with hugepages
108 	size.  Hence, hugepagesz and hugepages are typically specified in
114 	specific huge page size.  Valid huge page sizes are architecture
120 	implicitly specifies the number of huge pages of default size to
121 	allocate.  If the number of huge pages of default size is implicitly
123 	parameter pair for the default size.
125 	For example, on an architecture with 2M default huge page size::
134 	Specify the default huge page size.  This parameter can
137 	specific number of huge pages of default size.  The number of default
140 	architecture with 2M default huge page size::
147 	huge page size is architecture dependent.
149 When multiple huge page sizes are supported, ``/proc/sys/vm/nr_hugepages``
150 indicates the current number of pre-allocated huge pages of the default size.
157 huge page pool to 20, allocating or freeing huge pages, as required.
159 On a NUMA platform, the kernel will attempt to distribute the huge page pool
161 task that modifies ``nr_hugepages``. The default for the allowed nodes--when the
162 task has default memory policy--is all on-line nodes with memory.  Allowed
163 nodes with insufficient available, contiguous memory for a huge page will be
169 The success or failure of huge page allocation depends on the amount of
187 requested by applications.  Writing any non-zero value into this file
189 number of "surplus" huge pages from the kernel's normal page pool, when the
190 persistent huge page pool is exhausted. As these surplus huge pages become
191 unused, they are freed back to the kernel's normal page pool.
193 When increasing the huge page pool size via ``nr_hugepages``, any existing
196 the new persistent huge page pool size.
199 the default huge page size by setting the ``nr_hugepages`` sysctl to a
203 normal page pool.
205 Caveat: Shrinking the persistent huge page pool via ``nr_hugepages`` such that
207 of the in-use huge pages to surplus huge pages.  This will occur even if
209 this condition holds--that is, until ``nr_hugepages+nr_overcommit_hugepages`` is
210 increased sufficiently, or the surplus huge pages go out of use and are freed--
213 With support for multiple huge page pools at run-time available, much of
214 the huge page userspace interface in ``/proc/sys/vm`` has been duplicated in
217 compatibility. The root huge page control directory in sysfs is::
221 For each huge page size supported by the running kernel, a subdirectory
224 	hugepages-${size}kB
235 which function as described above for the default huge page-sized case.
239 Interaction of Task Memory Policy with Huge Page Allocation/Freeing
250 huge page pool, using the ``nr_hugepages`` example above, is::
252     numactl --interleave <node-list> echo 20 \
257     numactl -m <node-list> echo 20 >/proc/sys/vm/nr_hugepages_mempolicy
259 This will allocate or free ``abs(20 - nr_hugepages)`` to or from the nodes
260 specified in <node-list>, depending on whether number of persistent huge pages
262 allocated nor freed on any node not included in the specified <node-list>.
265 memory policy mode--bind, preferred, local or interleave--may be used.  The
266 resulting effect on persistent huge page allocation is as follows:
269    :ref:`Documentation/admin-guide/mm/numa_memory_policy.rst <numa_memory_policy>`],
273    memory for a huge page, the allocation will not "fallback" to the nearest
275    undesirable imbalance in the distribution of the huge page pool, or
289 #. The nodes allowed mask will be derived from any non-default task mempolicy,
292    shell with non-default policy, that policy will be used.  One can specify a
293    node list of "all" with numactl --interleave or --membind [-m] to achieve
296 #. Any task mempolicy specified--e.g., using numactl--will be constrained by
298    be no way for a task with non-default policy running in a cpuset with a
302 #. Boot-time huge page allocation attempts to distribute the requested number
303    of huge pages over all on-lines nodes with memory.
308 A subset of the contents of the root huge page control directory in sysfs,
312 	/sys/devices/system/node/node[0-9]*/hugepages/
314 Under this directory, the subdirectory for each supported huge page size
321 The free\_' and surplus\_' attribute files are read-only.  They return the number
332 applied, from which node the huge page allocation will be attempted.
343   mount -t hugetlbfs \
344 	-o uid=<value>,gid=<value>,mode=<value>,pagesize=<value>,size=<value>,\
357 If the platform supports multiple huge page sizes, the ``pagesize`` option can
358 be used to specify the huge page size and associated pool. ``pagesize``
360 default huge page size and associated pool will be used.
362 The ``size`` option sets the maximum value of memory (huge pages) allowed
363 for that filesystem (``/mnt/huge``). The ``size`` option can be specified
364 in bytes, or as a percentage of the specified huge page pool (``nr_hugepages``).
365 The size is rounded down to HPAGE_SIZE boundary.
368 for the filesystem. ``min_size`` can be specified in the same way as ``size``,
369 either bytes or a percentage of the huge page pool.
380 If the ``size``, ``min_size`` or ``nr_inodes`` option is not provided on
383 For ``pagesize``, ``size``, ``min_size`` and ``nr_inodes`` options, you can
385 For example, size=2K has the same meaning as size=2048.
405 aligned to the native page size of the processor; they will normally fail with
408 a hugetlb page and the length is smaller than the hugepage size.
419 ``hugepage-shm``
420 	see tools/testing/selftests/vm/hugepage-shm.c
422 ``hugepage-mmap``
423 	see tools/testing/selftests/vm/hugepage-mmap.c
426 to help with huge page usability, environment setup, and control.