]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 2003 Andries E. Brouwer (aeb@cwi.nl) |
2 | .\" | |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
fea681da MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
fea681da | 24 | .\" |
d1dcf598 | 25 | .TH ALLOC_HUGEPAGES 2 2007-05-31 "Linux" "Linux Programmer's Manual" |
fea681da MK |
26 | .SH NAME |
27 | alloc_hugepages, free_hugepages \- allocate or free huge pages | |
28 | .SH SYNOPSIS | |
616c0fd3 | 29 | .nf |
c13182ef | 30 | .BI "void *alloc_hugepages(int " key ", void *" addr ", size_t " len , |
616c0fd3 | 31 | .BI " int " prot ", int " flag ); |
fea681da MK |
32 | .\" asmlinkage unsigned long sys_alloc_hugepages(int key, unsigned long addr, |
33 | .\" unsigned long len, int prot, int flag); | |
34 | .sp | |
35 | .BI "int free_hugepages(void *" addr ); | |
36 | .\" asmlinkage int sys_free_hugepages(unsigned long addr); | |
616c0fd3 | 37 | .fi |
fea681da MK |
38 | .SH DESCRIPTION |
39 | The system calls | |
e511ffb6 | 40 | .BR alloc_hugepages () |
fea681da | 41 | and |
e511ffb6 | 42 | .BR free_hugepages () |
fea681da | 43 | were introduced in Linux 2.5.36 and removed again in 2.5.54. |
682edefb MK |
44 | They existed only on i386 and ia64 (when built with |
45 | .BR CONFIG_HUGETLB_PAGE ). | |
11b520ed | 46 | In Linux 2.4.20, the syscall numbers exist, |
988db661 | 47 | but the calls fail with the error |
d1dcf598 | 48 | .BR ENOSYS . |
fea681da MK |
49 | .LP |
50 | On i386 the memory management hardware knows about ordinary pages (4 KiB) | |
c13182ef MK |
51 | and huge pages (2 or 4 MiB). |
52 | Similarly ia64 knows about huge pages of | |
53 | several sizes. | |
54 | These system calls serve to map huge pages into the | |
fc7ba057 | 55 | process's memory or to free them again. |
fea681da MK |
56 | Huge pages are locked into memory, and are not swapped. |
57 | .LP | |
58 | The | |
59 | .I key | |
c4bb193f | 60 | argument is an identifier. |
c13182ef | 61 | When zero the pages are private, and |
fea681da MK |
62 | not inherited by children. |
63 | When positive the pages are shared with other applications using the same | |
64 | .IR key , | |
65 | and inherited by child processes. | |
66 | .LP | |
67 | The | |
68 | .I addr | |
c4bb193f | 69 | argument of |
63aa9df0 | 70 | .BR free_hugepages () |
e9496f74 | 71 | tells which page is being freed: it was the return value of a |
fea681da | 72 | call to |
63aa9df0 | 73 | .BR alloc_hugepages (). |
fea681da MK |
74 | (The memory is first actually freed when all users have released it.) |
75 | The | |
76 | .I addr | |
c4bb193f | 77 | argument of |
63aa9df0 | 78 | .BR alloc_hugepages () |
fea681da MK |
79 | is a hint, that the kernel may or may not follow. |
80 | Addresses must be properly aligned. | |
81 | .LP | |
82 | The | |
83 | .I len | |
c4bb193f | 84 | argument is the length of the required segment. |
c13182ef | 85 | It must be a multiple of the huge page size. |
fea681da MK |
86 | .LP |
87 | The | |
88 | .I prot | |
c4bb193f | 89 | argument specifies the memory protection of the segment. |
682edefb MK |
90 | It is one of |
91 | .BR PROT_READ , | |
92 | .BR PROT_WRITE , | |
93 | .BR PROT_EXEC . | |
fea681da MK |
94 | .LP |
95 | The | |
96 | .I flag | |
c4bb193f | 97 | argument is ignored, unless |
fea681da | 98 | .I key |
c13182ef MK |
99 | is positive. |
100 | In that case, if | |
fea681da | 101 | .I flag |
682edefb MK |
102 | is |
103 | .BR IPC_CREAT , | |
104 | then a new huge page segment is created when none | |
c13182ef | 105 | with the given key existed. |
682edefb | 106 | If this flag is not set, then |
0daa9e92 | 107 | .B ENOENT |
fea681da | 108 | is returned when no segment with the given key exists. |
47297adb | 109 | .SH RETURN VALUE |
fea681da | 110 | On success, |
e511ffb6 | 111 | .BR alloc_hugepages () |
fea681da | 112 | returns the allocated virtual address, and |
e511ffb6 | 113 | .BR free_hugepages () |
c13182ef MK |
114 | returns zero. |
115 | On error, \-1 is returned, and | |
fea681da MK |
116 | .I errno |
117 | is set appropriately. | |
118 | .SH ERRORS | |
119 | .TP | |
120 | .B ENOSYS | |
121 | The system call is not supported on this kernel. | |
fea681da MK |
122 | .SH FILES |
123 | .I /proc/sys/vm/nr_hugepages | |
124 | Number of configured hugetlb pages. | |
125 | This can be read and written. | |
126 | .LP | |
127 | .I /proc/meminfo | |
128 | Gives info on the number of configured hugetlb pages and on their size | |
129 | in the three variables HugePages_Total, HugePages_Free, Hugepagesize. | |
47297adb | 130 | .SH CONFORMING TO |
2b2581ee MK |
131 | These calls are specific to Linux on Intel processors, and should not be |
132 | used in programs intended to be portable. | |
fea681da | 133 | .SH NOTES |
d1dcf598 MK |
134 | These system calls are gone; |
135 | they existed only in Linux 2.5.36 through to 2.5.54. | |
9ee4a2b6 | 136 | Now the hugetlbfs filesystem can be used instead. |
fea681da | 137 | Memory backed by huge pages (if the CPU supports them) is obtained by |
1e321034 | 138 | using |
0bfa087b | 139 | .BR mmap (2) |
9ee4a2b6 | 140 | to map files in this virtual filesystem. |
fea681da MK |
141 | .LP |
142 | The maximal number of huge pages can be specified using the | |
143 | .B hugepages= | |
144 | boot parameter. | |
145 | ||
146 | .\" requires CONFIG_HUGETLB_PAGE (under "Processor type and features") | |
147 | .\" and CONFIG_HUGETLBFS (under "Filesystems"). | |
148 | .\" mount -t hugetlbfs hugetlbfs /huge | |
149 | .\" SHM_HUGETLB |