| 1 |
.\" Copyright 2003 Andries E. Brouwer ([email protected]) |
| 2 |
.\" |
| 3 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 4 |
.\" |
| 5 |
.TH alloc_hugepages 2 2024-05-02 "Linux man-pages 6.9.1" |
| 6 |
.SH NAME |
| 7 |
alloc_hugepages, free_hugepages \- allocate or free huge pages |
| 8 |
.SH SYNOPSIS |
| 9 |
.nf |
| 10 |
.BI "void *syscall(SYS_alloc_hugepages, int " key ", void " addr [. len "], \ |
| 11 |
size_t " len , |
| 12 |
.BI " int " prot ", int " flag ); |
| 13 |
.\" asmlinkage unsigned long sys_alloc_hugepages(int key, unsigned long addr, |
| 14 |
.\" unsigned long len, int prot, int flag); |
| 15 |
.BI "int syscall(SYS_free_hugepages, void *" addr ); |
| 16 |
.\" asmlinkage int sys_free_hugepages(unsigned long addr); |
| 17 |
.fi |
| 18 |
.P |
| 19 |
.IR Note : |
| 20 |
glibc provides no wrappers for these system calls, |
| 21 |
necessitating the use of |
| 22 |
.BR syscall (2). |
| 23 |
.SH DESCRIPTION |
| 24 |
The system calls |
| 25 |
.BR alloc_hugepages () |
| 26 |
and |
| 27 |
.BR free_hugepages () |
| 28 |
were introduced in Linux 2.5.36 and removed again in Linux 2.5.54. |
| 29 |
They existed only on i386 and ia64 (when built with |
| 30 |
.BR CONFIG_HUGETLB_PAGE ). |
| 31 |
In Linux 2.4.20, the syscall numbers exist, |
| 32 |
but the calls fail with the error |
| 33 |
.BR ENOSYS . |
| 34 |
.P |
| 35 |
On i386 the memory management hardware knows about ordinary pages (4\ KiB) |
| 36 |
and huge pages (2 or 4\ MiB). |
| 37 |
Similarly ia64 knows about huge pages of |
| 38 |
several sizes. |
| 39 |
These system calls serve to map huge pages into the |
| 40 |
process's memory or to free them again. |
| 41 |
Huge pages are locked into memory, and are not swapped. |
| 42 |
.P |
| 43 |
The |
| 44 |
.I key |
| 45 |
argument is an identifier. |
| 46 |
When zero the pages are private, and |
| 47 |
not inherited by children. |
| 48 |
When positive the pages are shared with other applications using the same |
| 49 |
.IR key , |
| 50 |
and inherited by child processes. |
| 51 |
.P |
| 52 |
The |
| 53 |
.I addr |
| 54 |
argument of |
| 55 |
.BR free_hugepages () |
| 56 |
tells which page is being freed: it was the return value of a |
| 57 |
call to |
| 58 |
.BR alloc_hugepages (). |
| 59 |
(The memory is first actually freed when all users have released it.) |
| 60 |
The |
| 61 |
.I addr |
| 62 |
argument of |
| 63 |
.BR alloc_hugepages () |
| 64 |
is a hint, that the kernel may or may not follow. |
| 65 |
Addresses must be properly aligned. |
| 66 |
.P |
| 67 |
The |
| 68 |
.I len |
| 69 |
argument is the length of the required segment. |
| 70 |
It must be a multiple of the huge page size. |
| 71 |
.P |
| 72 |
The |
| 73 |
.I prot |
| 74 |
argument specifies the memory protection of the segment. |
| 75 |
It is one of |
| 76 |
.BR PROT_READ , |
| 77 |
.BR PROT_WRITE , |
| 78 |
.BR PROT_EXEC . |
| 79 |
.P |
| 80 |
The |
| 81 |
.I flag |
| 82 |
argument is ignored, unless |
| 83 |
.I key |
| 84 |
is positive. |
| 85 |
In that case, if |
| 86 |
.I flag |
| 87 |
is |
| 88 |
.BR IPC_CREAT , |
| 89 |
then a new huge page segment is created when none |
| 90 |
with the given key existed. |
| 91 |
If this flag is not set, then |
| 92 |
.B ENOENT |
| 93 |
is returned when no segment with the given key exists. |
| 94 |
.SH RETURN VALUE |
| 95 |
On success, |
| 96 |
.BR alloc_hugepages () |
| 97 |
returns the allocated virtual address, and |
| 98 |
.BR free_hugepages () |
| 99 |
returns zero. |
| 100 |
On error, \-1 is returned, and |
| 101 |
.I errno |
| 102 |
is set to indicate the error. |
| 103 |
.SH ERRORS |
| 104 |
.TP |
| 105 |
.B ENOSYS |
| 106 |
The system call is not supported on this kernel. |
| 107 |
.SH FILES |
| 108 |
.TP |
| 109 |
.I /proc/sys/vm/nr_hugepages |
| 110 |
Number of configured hugetlb pages. |
| 111 |
This can be read and written. |
| 112 |
.TP |
| 113 |
.I /proc/meminfo |
| 114 |
Gives info on the number of configured hugetlb pages and on their size |
| 115 |
in the three variables HugePages_Total, HugePages_Free, Hugepagesize. |
| 116 |
.SH STANDARDS |
| 117 |
Linux on Intel processors. |
| 118 |
.SH HISTORY |
| 119 |
These system calls are gone; |
| 120 |
they existed only in Linux 2.5.36 through to Linux 2.5.54. |
| 121 |
.SH NOTES |
| 122 |
Now the hugetlbfs filesystem can be used instead. |
| 123 |
Memory backed by huge pages (if the CPU supports them) is obtained by |
| 124 |
using |
| 125 |
.BR mmap (2) |
| 126 |
to map files in this virtual filesystem. |
| 127 |
.P |
| 128 |
The maximal number of huge pages can be specified using the |
| 129 |
.B hugepages= |
| 130 |
boot parameter. |
| 131 |
.\".P |
| 132 |
.\" requires CONFIG_HUGETLB_PAGE (under "Processor type and features") |
| 133 |
.\" and CONFIG_HUGETLBFS (under "Filesystems"). |
| 134 |
.\" mount \-t hugetlbfs hugetlbfs /huge |
| 135 |
.\" SHM_HUGETLB |