1.. _hugetlbpage: 2 3============= 4HugeTLB Pages 5============= 6 7Overview 8======== 9 10The intent of this file is to give a brief summary of hugetlbpage support in 11the Linux kernel. This support is built on top of multiple page size support 12that is provided by most modern architectures. For example, x86 CPUs normally 13support 4K and 2M (1G if architecturally supported) page sizes, ia64 14architecture supports multiple page sizes 4K, 8K, 64K, 256K, 1M, 4M, 16M, 15256M and ppc64 supports 4K and 16M. A TLB is a cache of virtual-to-physical 16translations. Typically this is a very scarce resource on processor. 17Operating systems try to make best use of limited number of TLB resources. 18This optimization is more critical now as bigger and bigger physical memories 19(several GBs) are more readily available. 20 21Users can use the huge page support in Linux kernel by either using the mmap 22system call or standard SYSV shared memory system calls (shmget, shmat). 23 24First the Linux kernel needs to be built with the CONFIG_HUGETLBFS 25(present under "File systems") and CONFIG_HUGETLB_PAGE (selected 26automatically when CONFIG_HUGETLBFS is selected) configuration 27options. 28 29The ``/proc/meminfo`` file provides information about the total number of 30persistent hugetlb pages in the kernel's huge page pool. It also displays 31default huge page size and information about the number of free, reserved 32and surplus huge pages in the pool of huge pages of default size. 33The huge page size is needed for generating the proper alignment and 34size of the arguments to system calls that map huge page regions. 35 36The output of ``cat /proc/meminfo`` will include lines like:: 37 38 HugePages_Total: uuu 39 HugePages_Free: vvv 40 HugePages_Rsvd: www 41 HugePages_Surp: xxx 42 Hugepagesize: yyy kB 43 Hugetlb: zzz kB 44 45where: 46 47HugePages_Total 48 is the size of the pool of huge pages. 49HugePages_Free 50 is the number of huge pages in the pool that are not yet 51 allocated. 52HugePages_Rsvd 53 is short for "reserved," and is the number of huge pages for 54 which a commitment to allocate from the pool has been made, 55 but no allocation has yet been made. Reserved huge pages 56 guarantee that an application will be able to allocate a 57 huge page from the pool of huge pages at fault time. 58HugePages_Surp 59 is short for "surplus," and is the number of huge pages in 60 the pool above the value in ``/proc/sys/vm/nr_hugepages``. The 61 maximum number of surplus huge pages is controlled by 62 ``/proc/sys/vm/nr_overcommit_hugepages``. 63 Note: When the feature of freeing unused vmemmap pages associated 64 with each hugetlb page is enabled, the number of surplus huge pages 65 may be temporarily larger than the maximum number of surplus huge 66 pages when the system is under memory pressure. 67Hugepagesize 68 is the default hugepage size (in Kb). 69Hugetlb 70 is the total amount of memory (in kB), consumed by huge 71 pages of all sizes. 72 If huge pages of different sizes are in use, this number 73 will exceed HugePages_Total \* Hugepagesize. To get more 74 detailed information, please, refer to 75 ``/sys/kernel/mm/hugepages`` (described below). 76 77 78``/proc/filesystems`` should also show a filesystem of type "hugetlbfs" 79configured in the kernel. 80 81``/proc/sys/vm/nr_hugepages`` indicates the current number of "persistent" huge 82pages in the kernel's huge page pool. "Persistent" huge pages will be 83returned to the huge page pool when freed by a task. A user with root 84privileges can dynamically allocate more or free some persistent huge pages 85by increasing or decreasing the value of ``nr_hugepages``. 86 87Note: When the feature of freeing unused vmemmap pages associated with each 88hugetlb page is enabled, we can fail to free the huge pages triggered by 89the user when ths system is under memory pressure. Please try again later. 90 91Pages that are used as huge pages are reserved inside the kernel and cannot 92be used for other purposes. Huge pages cannot be swapped out under 93memory pressure. 94 95Once a number of huge pages have been pre-allocated to the kernel huge page 96pool, a user with appropriate privilege can use either the mmap system call 97or shared memory system calls to use the huge pages. See the discussion of 98:ref:`Using Huge Pages <using_huge_pages>`, below. 99 100The administrator can allocate persistent huge pages on the kernel boot 101command line by specifying the "hugepages=N" parameter, where 'N' = the 102number of huge pages requested. This is the most reliable method of 103allocating huge pages as memory has not yet become fragmented. 104 105Some platforms support multiple huge page sizes. To allocate huge pages 106of a specific size, one must precede the huge pages boot command parameters 107with a huge page size selection parameter "hugepagesz=<size>". <size> must 108be specified in bytes with optional scale suffix [kKmMgG]. The default huge 109page size may be selected with the "default_hugepagesz=<size>" boot parameter. 110 111Hugetlb boot command line parameter semantics 112 113hugepagesz 114 Specify a huge page size. Used in conjunction with hugepages 115 parameter to preallocate a number of huge pages of the specified 116 size. Hence, hugepagesz and hugepages are typically specified in 117 pairs such as:: 118 119 hugepagesz=2M hugepages=512 120 121 hugepagesz can only be specified once on the command line for a 122 specific huge page size. Valid huge page sizes are architecture 123 dependent. 124hugepages 125 Specify the number of huge pages to preallocate. This typically 126 follows a valid hugepagesz or default_hugepagesz parameter. However, 127 if hugepages is the first or only hugetlb command line parameter it 128 implicitly specifies the number of huge pages of default size to 129 allocate. If the number of huge pages of default size is implicitly 130 specified, it can not be overwritten by a hugepagesz,hugepages 131 parameter pair for the default size. This parameter also has a 132 node format. The node format specifies the number of huge pages 133 to allocate on specific nodes. 134 135 For example, on an architecture with 2M default huge page size:: 136 137 hugepages=256 hugepagesz=2M hugepages=512 138 139 will result in 256 2M huge pages being allocated and a warning message 140 indicating that the hugepages=512 parameter is ignored. If a hugepages 141 parameter is preceded by an invalid hugepagesz parameter, it will 142 be ignored. 143 144 Node format example:: 145 146 hugepagesz=2M hugepages=0:1,1:2 147 148 It will allocate 1 2M hugepage on node0 and 2 2M hugepages on node1. 149 If the node number is invalid, the parameter will be ignored. 150 151default_hugepagesz 152 Specify the default huge page size. This parameter can 153 only be specified once on the command line. default_hugepagesz can 154 optionally be followed by the hugepages parameter to preallocate a 155 specific number of huge pages of default size. The number of default 156 sized huge pages to preallocate can also be implicitly specified as 157 mentioned in the hugepages section above. Therefore, on an 158 architecture with 2M default huge page size:: 159 160 hugepages=256 161 default_hugepagesz=2M hugepages=256 162 hugepages=256 default_hugepagesz=2M 163 164 will all result in 256 2M huge pages being allocated. Valid default 165 huge page size is architecture dependent. 166hugetlb_free_vmemmap 167 When CONFIG_HUGETLB_PAGE_FREE_VMEMMAP is set, this enables freeing 168 unused vmemmap pages associated with each HugeTLB page. 169 170When multiple huge page sizes are supported, ``/proc/sys/vm/nr_hugepages`` 171indicates the current number of pre-allocated huge pages of the default size. 172Thus, one can use the following command to dynamically allocate/deallocate 173default sized persistent huge pages:: 174 175 echo 20 > /proc/sys/vm/nr_hugepages 176 177This command will try to adjust the number of default sized huge pages in the 178huge page pool to 20, allocating or freeing huge pages, as required. 179 180On a NUMA platform, the kernel will attempt to distribute the huge page pool 181over all the set of allowed nodes specified by the NUMA memory policy of the 182task that modifies ``nr_hugepages``. The default for the allowed nodes--when the 183task has default memory policy--is all on-line nodes with memory. Allowed 184nodes with insufficient available, contiguous memory for a huge page will be 185silently skipped when allocating persistent huge pages. See the 186:ref:`discussion below <mem_policy_and_hp_alloc>` 187of the interaction of task memory policy, cpusets and per node attributes 188with the allocation and freeing of persistent huge pages. 189 190The success or failure of huge page allocation depends on the amount of 191physically contiguous memory that is present in system at the time of the 192allocation attempt. If the kernel is unable to allocate huge pages from 193some nodes in a NUMA system, it will attempt to make up the difference by 194allocating extra pages on other nodes with sufficient available contiguous 195memory, if any. 196 197System administrators may want to put this command in one of the local rc 198init files. This will enable the kernel to allocate huge pages early in 199the boot process when the possibility of getting physical contiguous pages 200is still very high. Administrators can verify the number of huge pages 201actually allocated by checking the sysctl or meminfo. To check the per node 202distribution of huge pages in a NUMA system, use:: 203 204 cat /sys/devices/system/node/node*/meminfo | fgrep Huge 205 206``/proc/sys/vm/nr_overcommit_hugepages`` specifies how large the pool of 207huge pages can grow, if more huge pages than ``/proc/sys/vm/nr_hugepages`` are 208requested by applications. Writing any non-zero value into this file 209indicates that the hugetlb subsystem is allowed to try to obtain that 210number of "surplus" huge pages from the kernel's normal page pool, when the 211persistent huge page pool is exhausted. As these surplus huge pages become 212unused, they are freed back to the kernel's normal page pool. 213 214When increasing the huge page pool size via ``nr_hugepages``, any existing 215surplus pages will first be promoted to persistent huge pages. Then, additional 216huge pages will be allocated, if necessary and if possible, to fulfill 217the new persistent huge page pool size. 218 219The administrator may shrink the pool of persistent huge pages for 220the default huge page size by setting the ``nr_hugepages`` sysctl to a 221smaller value. The kernel will attempt to balance the freeing of huge pages 222across all nodes in the memory policy of the task modifying ``nr_hugepages``. 223Any free huge pages on the selected nodes will be freed back to the kernel's 224normal page pool. 225 226Caveat: Shrinking the persistent huge page pool via ``nr_hugepages`` such that 227it becomes less than the number of huge pages in use will convert the balance 228of the in-use huge pages to surplus huge pages. This will occur even if 229the number of surplus pages would exceed the overcommit value. As long as 230this condition holds--that is, until ``nr_hugepages+nr_overcommit_hugepages`` is 231increased sufficiently, or the surplus huge pages go out of use and are freed-- 232no more surplus huge pages will be allowed to be allocated. 233 234With support for multiple huge page pools at run-time available, much of 235the huge page userspace interface in ``/proc/sys/vm`` has been duplicated in 236sysfs. 237The ``/proc`` interfaces discussed above have been retained for backwards 238compatibility. The root huge page control directory in sysfs is:: 239 240 /sys/kernel/mm/hugepages 241 242For each huge page size supported by the running kernel, a subdirectory 243will exist, of the form:: 244 245 hugepages-${size}kB 246 247Inside each of these directories, the set of files contained in ``/proc`` 248will exist. In addition, two additional interfaces for demoting huge 249pages may exist:: 250 251 demote 252 demote_size 253 nr_hugepages 254 nr_hugepages_mempolicy 255 nr_overcommit_hugepages 256 free_hugepages 257 resv_hugepages 258 surplus_hugepages 259 260The demote interfaces provide the ability to split a huge page into 261smaller huge pages. For example, the x86 architecture supports both 2621GB and 2MB huge pages sizes. A 1GB huge page can be split into 512 2632MB huge pages. Demote interfaces are not available for the smallest 264huge page size. The demote interfaces are: 265 266demote_size 267 is the size of demoted pages. When a page is demoted a corresponding 268 number of huge pages of demote_size will be created. By default, 269 demote_size is set to the next smaller huge page size. If there are 270 multiple smaller huge page sizes, demote_size can be set to any of 271 these smaller sizes. Only huge page sizes less than the current huge 272 pages size are allowed. 273 274demote 275 is used to demote a number of huge pages. A user with root privileges 276 can write to this file. It may not be possible to demote the 277 requested number of huge pages. To determine how many pages were 278 actually demoted, compare the value of nr_hugepages before and after 279 writing to the demote interface. demote is a write only interface. 280 281The interfaces which are the same as in ``/proc`` (all except demote and 282demote_size) function as described above for the default huge page-sized case. 283 284.. _mem_policy_and_hp_alloc: 285 286Interaction of Task Memory Policy with Huge Page Allocation/Freeing 287=================================================================== 288 289Whether huge pages are allocated and freed via the ``/proc`` interface or 290the ``/sysfs`` interface using the ``nr_hugepages_mempolicy`` attribute, the 291NUMA nodes from which huge pages are allocated or freed are controlled by the 292NUMA memory policy of the task that modifies the ``nr_hugepages_mempolicy`` 293sysctl or attribute. When the ``nr_hugepages`` attribute is used, mempolicy 294is ignored. 295 296The recommended method to allocate or free huge pages to/from the kernel 297huge page pool, using the ``nr_hugepages`` example above, is:: 298 299 numactl --interleave <node-list> echo 20 \ 300 >/proc/sys/vm/nr_hugepages_mempolicy 301 302or, more succinctly:: 303 304 numactl -m <node-list> echo 20 >/proc/sys/vm/nr_hugepages_mempolicy 305 306This will allocate or free ``abs(20 - nr_hugepages)`` to or from the nodes 307specified in <node-list>, depending on whether number of persistent huge pages 308is initially less than or greater than 20, respectively. No huge pages will be 309allocated nor freed on any node not included in the specified <node-list>. 310 311When adjusting the persistent hugepage count via ``nr_hugepages_mempolicy``, any 312memory policy mode--bind, preferred, local or interleave--may be used. The 313resulting effect on persistent huge page allocation is as follows: 314 315#. Regardless of mempolicy mode [see 316 :ref:`Documentation/admin-guide/mm/numa_memory_policy.rst <numa_memory_policy>`], 317 persistent huge pages will be distributed across the node or nodes 318 specified in the mempolicy as if "interleave" had been specified. 319 However, if a node in the policy does not contain sufficient contiguous 320 memory for a huge page, the allocation will not "fallback" to the nearest 321 neighbor node with sufficient contiguous memory. To do this would cause 322 undesirable imbalance in the distribution of the huge page pool, or 323 possibly, allocation of persistent huge pages on nodes not allowed by 324 the task's memory policy. 325 326#. One or more nodes may be specified with the bind or interleave policy. 327 If more than one node is specified with the preferred policy, only the 328 lowest numeric id will be used. Local policy will select the node where 329 the task is running at the time the nodes_allowed mask is constructed. 330 For local policy to be deterministic, the task must be bound to a cpu or 331 cpus in a single node. Otherwise, the task could be migrated to some 332 other node at any time after launch and the resulting node will be 333 indeterminate. Thus, local policy is not very useful for this purpose. 334 Any of the other mempolicy modes may be used to specify a single node. 335 336#. The nodes allowed mask will be derived from any non-default task mempolicy, 337 whether this policy was set explicitly by the task itself or one of its 338 ancestors, such as numactl. This means that if the task is invoked from a 339 shell with non-default policy, that policy will be used. One can specify a 340 node list of "all" with numactl --interleave or --membind [-m] to achieve 341 interleaving over all nodes in the system or cpuset. 342 343#. Any task mempolicy specified--e.g., using numactl--will be constrained by 344 the resource limits of any cpuset in which the task runs. Thus, there will 345 be no way for a task with non-default policy running in a cpuset with a 346 subset of the system nodes to allocate huge pages outside the cpuset 347 without first moving to a cpuset that contains all of the desired nodes. 348 349#. Boot-time huge page allocation attempts to distribute the requested number 350 of huge pages over all on-lines nodes with memory. 351 352Per Node Hugepages Attributes 353============================= 354 355A subset of the contents of the root huge page control directory in sysfs, 356described above, will be replicated under each the system device of each 357NUMA node with memory in:: 358 359 /sys/devices/system/node/node[0-9]*/hugepages/ 360 361Under this directory, the subdirectory for each supported huge page size 362contains the following attribute files:: 363 364 nr_hugepages 365 free_hugepages 366 surplus_hugepages 367 368The free\_' and surplus\_' attribute files are read-only. They return the number 369of free and surplus [overcommitted] huge pages, respectively, on the parent 370node. 371 372The ``nr_hugepages`` attribute returns the total number of huge pages on the 373specified node. When this attribute is written, the number of persistent huge 374pages on the parent node will be adjusted to the specified value, if sufficient 375resources exist, regardless of the task's mempolicy or cpuset constraints. 376 377Note that the number of overcommit and reserve pages remain global quantities, 378as we don't know until fault time, when the faulting task's mempolicy is 379applied, from which node the huge page allocation will be attempted. 380 381.. _using_huge_pages: 382 383Using Huge Pages 384================ 385 386If the user applications are going to request huge pages using mmap system 387call, then it is required that system administrator mount a file system of 388type hugetlbfs:: 389 390 mount -t hugetlbfs \ 391 -o uid=<value>,gid=<value>,mode=<value>,pagesize=<value>,size=<value>,\ 392 min_size=<value>,nr_inodes=<value> none /mnt/huge 393 394This command mounts a (pseudo) filesystem of type hugetlbfs on the directory 395``/mnt/huge``. Any file created on ``/mnt/huge`` uses huge pages. 396 397The ``uid`` and ``gid`` options sets the owner and group of the root of the 398file system. By default the ``uid`` and ``gid`` of the current process 399are taken. 400 401The ``mode`` option sets the mode of root of file system to value & 01777. 402This value is given in octal. By default the value 0755 is picked. 403 404If the platform supports multiple huge page sizes, the ``pagesize`` option can 405be used to specify the huge page size and associated pool. ``pagesize`` 406is specified in bytes. If ``pagesize`` is not specified the platform's 407default huge page size and associated pool will be used. 408 409The ``size`` option sets the maximum value of memory (huge pages) allowed 410for that filesystem (``/mnt/huge``). The ``size`` option can be specified 411in bytes, or as a percentage of the specified huge page pool (``nr_hugepages``). 412The size is rounded down to HPAGE_SIZE boundary. 413 414The ``min_size`` option sets the minimum value of memory (huge pages) allowed 415for the filesystem. ``min_size`` can be specified in the same way as ``size``, 416either bytes or a percentage of the huge page pool. 417At mount time, the number of huge pages specified by ``min_size`` are reserved 418for use by the filesystem. 419If there are not enough free huge pages available, the mount will fail. 420As huge pages are allocated to the filesystem and freed, the reserve count 421is adjusted so that the sum of allocated and reserved huge pages is always 422at least ``min_size``. 423 424The option ``nr_inodes`` sets the maximum number of inodes that ``/mnt/huge`` 425can use. 426 427If the ``size``, ``min_size`` or ``nr_inodes`` option is not provided on 428command line then no limits are set. 429 430For ``pagesize``, ``size``, ``min_size`` and ``nr_inodes`` options, you can 431use [G|g]/[M|m]/[K|k] to represent giga/mega/kilo. 432For example, size=2K has the same meaning as size=2048. 433 434While read system calls are supported on files that reside on hugetlb 435file systems, write system calls are not. 436 437Regular chown, chgrp, and chmod commands (with right permissions) could be 438used to change the file attributes on hugetlbfs. 439 440Also, it is important to note that no such mount command is required if 441applications are going to use only shmat/shmget system calls or mmap with 442MAP_HUGETLB. For an example of how to use mmap with MAP_HUGETLB see 443:ref:`map_hugetlb <map_hugetlb>` below. 444 445Users who wish to use hugetlb memory via shared memory segment should be 446members of a supplementary group and system admin needs to configure that gid 447into ``/proc/sys/vm/hugetlb_shm_group``. It is possible for same or different 448applications to use any combination of mmaps and shm* calls, though the mount of 449filesystem will be required for using mmap calls without MAP_HUGETLB. 450 451Syscalls that operate on memory backed by hugetlb pages only have their lengths 452aligned to the native page size of the processor; they will normally fail with 453errno set to EINVAL or exclude hugetlb pages that extend beyond the length if 454not hugepage aligned. For example, munmap(2) will fail if memory is backed by 455a hugetlb page and the length is smaller than the hugepage size. 456 457 458Examples 459======== 460 461.. _map_hugetlb: 462 463``map_hugetlb`` 464 see tools/testing/selftests/vm/map_hugetlb.c 465 466``hugepage-shm`` 467 see tools/testing/selftests/vm/hugepage-shm.c 468 469``hugepage-mmap`` 470 see tools/testing/selftests/vm/hugepage-mmap.c 471 472The `libhugetlbfs`_ library provides a wide range of userspace tools 473to help with huge page usability, environment setup, and control. 474 475.. _libhugetlbfs: https://github.com/libhugetlbfs/libhugetlbfs 476