]>
Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | |
2 | The intent of this file is to give a brief summary of hugetlbpage support in | |
3 | the Linux kernel. This support is built on top of multiple page size support | |
4 | that is provided by most modern architectures. For example, i386 | |
5 | architecture supports 4K and 4M (2M in PAE mode) page sizes, ia64 | |
6 | architecture supports multiple page sizes 4K, 8K, 64K, 256K, 1M, 4M, 16M, | |
7 | 256M and ppc64 supports 4K and 16M. A TLB is a cache of virtual-to-physical | |
8 | translations. Typically this is a very scarce resource on processor. | |
9 | Operating systems try to make best use of limited number of TLB resources. | |
10 | This optimization is more critical now as bigger and bigger physical memories | |
11 | (several GBs) are more readily available. | |
12 | ||
13 | Users can use the huge page support in Linux kernel by either using the mmap | |
14 | system call or standard SYSv shared memory system calls (shmget, shmat). | |
15 | ||
5c7ad510 MBY |
16 | First the Linux kernel needs to be built with the CONFIG_HUGETLBFS |
17 | (present under "File systems") and CONFIG_HUGETLB_PAGE (selected | |
18 | automatically when CONFIG_HUGETLBFS is selected) configuration | |
19 | options. | |
1da177e4 | 20 | |
41a25e7e LS |
21 | The kernel built with huge page support should show the number of configured |
22 | huge pages in the system by running the "cat /proc/meminfo" command. | |
1da177e4 LT |
23 | |
24 | /proc/meminfo also provides information about the total number of hugetlb | |
25 | pages configured in the kernel. It also displays information about the | |
26 | number of free hugetlb pages at any time. It also displays information about | |
41a25e7e | 27 | the configured huge page size - this is needed for generating the proper |
1da177e4 LT |
28 | alignment and size of the arguments to the above system calls. |
29 | ||
21a26d49 | 30 | The output of "cat /proc/meminfo" will have lines like: |
1da177e4 LT |
31 | |
32 | ..... | |
d5dbac87 NA |
33 | HugePages_Total: vvv |
34 | HugePages_Free: www | |
35 | HugePages_Rsvd: xxx | |
36 | HugePages_Surp: yyy | |
5e122271 RD |
37 | Hugepagesize: zzz kB |
38 | ||
39 | where: | |
41a25e7e LS |
40 | HugePages_Total is the size of the pool of huge pages. |
41 | HugePages_Free is the number of huge pages in the pool that are not yet | |
42 | allocated. | |
43 | HugePages_Rsvd is short for "reserved," and is the number of huge pages for | |
44 | which a commitment to allocate from the pool has been made, | |
45 | but no allocation has yet been made. Reserved huge pages | |
46 | guarantee that an application will be able to allocate a | |
47 | huge page from the pool of huge pages at fault time. | |
48 | HugePages_Surp is short for "surplus," and is the number of huge pages in | |
49 | the pool above the value in /proc/sys/vm/nr_hugepages. The | |
50 | maximum number of surplus huge pages is controlled by | |
51 | /proc/sys/vm/nr_overcommit_hugepages. | |
1da177e4 LT |
52 | |
53 | /proc/filesystems should also show a filesystem of type "hugetlbfs" configured | |
54 | in the kernel. | |
55 | ||
56 | /proc/sys/vm/nr_hugepages indicates the current number of configured hugetlb | |
57 | pages in the kernel. Super user can dynamically request more (or free some | |
41a25e7e | 58 | pre-configured) huge pages. |
5c7ad510 | 59 | The allocation (or deallocation) of hugetlb pages is possible only if there are |
41a25e7e | 60 | enough physically contiguous free pages in system (freeing of huge pages is |
21a26d49 | 61 | possible only if there are enough hugetlb pages free that can be transferred |
1da177e4 LT |
62 | back to regular memory pool). |
63 | ||
21a26d49 RD |
64 | Pages that are used as hugetlb pages are reserved inside the kernel and cannot |
65 | be used for other purposes. | |
1da177e4 LT |
66 | |
67 | Once the kernel with Hugetlb page support is built and running, a user can | |
68 | use either the mmap system call or shared memory system calls to start using | |
69 | the huge pages. It is required that the system administrator preallocate | |
5c7ad510 | 70 | enough memory for huge page purposes. |
1da177e4 | 71 | |
41a25e7e LS |
72 | The administrator can preallocate huge pages on the kernel boot command line by |
73 | specifying the "hugepages=N" parameter, where 'N' = the number of huge pages | |
74 | requested. This is the most reliable method for preallocating huge pages as | |
75 | memory has not yet become fragmented. | |
76 | ||
77 | Some platforms support multiple huge page sizes. To preallocate huge pages | |
78 | of a specific size, one must preceed the huge pages boot command parameters | |
79 | with a huge page size selection parameter "hugepagesz=<size>". <size> must | |
80 | be specified in bytes with optional scale suffix [kKmMgG]. The default huge | |
81 | page size may be selected with the "default_hugepagesz=<size>" boot parameter. | |
82 | ||
83 | /proc/sys/vm/nr_hugepages indicates the current number of configured [default | |
84 | size] hugetlb pages in the kernel. Super user can dynamically request more | |
85 | (or free some pre-configured) huge pages. | |
86 | ||
87 | Use the following command to dynamically allocate/deallocate default sized | |
88 | huge pages: | |
1da177e4 LT |
89 | |
90 | echo 20 > /proc/sys/vm/nr_hugepages | |
91 | ||
41a25e7e LS |
92 | This command will try to configure 20 default sized huge pages in the system. |
93 | On a NUMA platform, the kernel will attempt to distribute the huge page pool | |
94 | over the all on-line nodes. These huge pages, allocated when nr_hugepages | |
95 | is increased, are called "persistent huge pages". | |
96 | ||
97 | The success or failure of huge page allocation depends on the amount of | |
98 | physically contiguous memory that is preset in system at the time of the | |
99 | allocation attempt. If the kernel is unable to allocate huge pages from | |
100 | some nodes in a NUMA system, it will attempt to make up the difference by | |
101 | allocating extra pages on other nodes with sufficient available contiguous | |
102 | memory, if any. | |
103 | ||
104 | System administrators may want to put this command in one of the local rc init | |
105 | files. This will enable the kernel to request huge pages early in the boot | |
106 | process when the possibility of getting physical contiguous pages is still | |
107 | very high. Administrators can verify the number of huge pages actually | |
108 | allocated by checking the sysctl or meminfo. To check the per node | |
109 | distribution of huge pages in a NUMA system, use: | |
110 | ||
111 | cat /sys/devices/system/node/node*/meminfo | fgrep Huge | |
112 | ||
113 | /proc/sys/vm/nr_overcommit_hugepages specifies how large the pool of | |
114 | huge pages can grow, if more huge pages than /proc/sys/vm/nr_hugepages are | |
115 | requested by applications. Writing any non-zero value into this file | |
116 | indicates that the hugetlb subsystem is allowed to try to obtain "surplus" | |
117 | huge pages from the buddy allocator, when the normal pool is exhausted. As | |
118 | these surplus huge pages go out of use, they are freed back to the buddy | |
d5dbac87 NA |
119 | allocator. |
120 | ||
41a25e7e LS |
121 | When increasing the huge page pool size via nr_hugepages, any surplus |
122 | pages will first be promoted to persistent huge pages. Then, additional | |
123 | huge pages will be allocated, if necessary and if possible, to fulfill | |
124 | the new huge page pool size. | |
125 | ||
126 | The administrator may shrink the pool of preallocated huge pages for | |
127 | the default huge page size by setting the nr_hugepages sysctl to a | |
128 | smaller value. The kernel will attempt to balance the freeing of huge pages | |
129 | across all on-line nodes. Any free huge pages on the selected nodes will | |
130 | be freed back to the buddy allocator. | |
131 | ||
423bec43 | 132 | Caveat: Shrinking the pool via nr_hugepages such that it becomes less |
41a25e7e | 133 | than the number of huge pages in use will convert the balance to surplus |
423bec43 | 134 | huge pages even if it would exceed the overcommit value. As long as |
d5dbac87 NA |
135 | this condition holds, however, no more surplus huge pages will be |
136 | allowed on the system until one of the two sysctls are increased | |
137 | sufficiently, or the surplus huge pages go out of use and are freed. | |
1da177e4 | 138 | |
41a25e7e LS |
139 | With support for multiple huge page pools at run-time available, much of |
140 | the huge page userspace interface has been duplicated in sysfs. The above | |
141 | information applies to the default huge page size which will be | |
142 | controlled by the /proc interfaces for backwards compatibility. The root | |
143 | huge page control directory in sysfs is: | |
a3437870 NA |
144 | |
145 | /sys/kernel/mm/hugepages | |
146 | ||
41a25e7e | 147 | For each huge page size supported by the running kernel, a subdirectory |
a3437870 NA |
148 | will exist, of the form |
149 | ||
150 | hugepages-${size}kB | |
151 | ||
152 | Inside each of these directories, the same set of files will exist: | |
153 | ||
154 | nr_hugepages | |
155 | nr_overcommit_hugepages | |
156 | free_hugepages | |
157 | resv_hugepages | |
158 | surplus_hugepages | |
159 | ||
41a25e7e | 160 | which function as described above for the default huge page-sized case. |
a3437870 | 161 | |
41a25e7e | 162 | If the user applications are going to request huge pages using mmap system |
1da177e4 LT |
163 | call, then it is required that system administrator mount a file system of |
164 | type hugetlbfs: | |
165 | ||
e73a75fa RD |
166 | mount -t hugetlbfs \ |
167 | -o uid=<value>,gid=<value>,mode=<value>,size=<value>,nr_inodes=<value> \ | |
168 | none /mnt/huge | |
1da177e4 LT |
169 | |
170 | This command mounts a (pseudo) filesystem of type hugetlbfs on the directory | |
41a25e7e | 171 | /mnt/huge. Any files created on /mnt/huge uses huge pages. The uid and gid |
1da177e4 LT |
172 | options sets the owner and group of the root of the file system. By default |
173 | the uid and gid of the current process are taken. The mode option sets the | |
174 | mode of root of file system to value & 0777. This value is given in octal. | |
175 | By default the value 0755 is picked. The size option sets the maximum value of | |
176 | memory (huge pages) allowed for that filesystem (/mnt/huge). The size is | |
21a26d49 | 177 | rounded down to HPAGE_SIZE. The option nr_inodes sets the maximum number of |
e73a75fa | 178 | inodes that /mnt/huge can use. If the size or nr_inodes option is not |
1da177e4 | 179 | provided on command line then no limits are set. For size and nr_inodes |
5c7ad510 | 180 | options, you can use [G|g]/[M|m]/[K|k] to represent giga/mega/kilo. For |
e73a75fa | 181 | example, size=2K has the same meaning as size=2048. |
1da177e4 | 182 | |
d5dbac87 NA |
183 | While read system calls are supported on files that reside on hugetlb |
184 | file systems, write system calls are not. | |
1da177e4 | 185 | |
21a26d49 | 186 | Regular chown, chgrp, and chmod commands (with right permissions) could be |
1da177e4 LT |
187 | used to change the file attributes on hugetlbfs. |
188 | ||
189 | Also, it is important to note that no such mount command is required if the | |
190 | applications are going to use only shmat/shmget system calls. Users who | |
191 | wish to use hugetlb page via shared memory segment should be a member of | |
192 | a supplementary group and system admin needs to configure that gid into | |
193 | /proc/sys/vm/hugetlb_shm_group. It is possible for same or different | |
21a26d49 RD |
194 | applications to use any combination of mmaps and shm* calls, though the |
195 | mount of filesystem will be required for using mmap calls. | |
1da177e4 LT |
196 | |
197 | ******************************************************************* | |
198 | ||
199 | /* | |
41a25e7e | 200 | * Example of using huge page memory in a user application using Sys V shared |
1da177e4 LT |
201 | * memory system calls. In this example the app is requesting 256MB of |
202 | * memory that is backed by huge pages. The application uses the flag | |
203 | * SHM_HUGETLB in the shmget system call to inform the kernel that it is | |
41a25e7e | 204 | * requesting huge pages. |
1da177e4 LT |
205 | * |
206 | * For the ia64 architecture, the Linux kernel reserves Region number 4 for | |
41a25e7e | 207 | * huge pages. That means the addresses starting with 0x800000... will need |
1da177e4 LT |
208 | * to be specified. Specifying a fixed address is not required on ppc64, |
209 | * i386 or x86_64. | |
210 | * | |
211 | * Note: The default shared memory limit is quite low on many kernels, | |
212 | * you may need to increase it via: | |
213 | * | |
214 | * echo 268435456 > /proc/sys/kernel/shmmax | |
215 | * | |
216 | * This will increase the maximum size per shared memory segment to 256MB. | |
217 | * The other limit that you will hit eventually is shmall which is the | |
218 | * total amount of shared memory in pages. To set it to 16GB on a system | |
219 | * with a 4kB pagesize do: | |
220 | * | |
221 | * echo 4194304 > /proc/sys/kernel/shmall | |
222 | */ | |
223 | #include <stdlib.h> | |
224 | #include <stdio.h> | |
225 | #include <sys/types.h> | |
226 | #include <sys/ipc.h> | |
227 | #include <sys/shm.h> | |
228 | #include <sys/mman.h> | |
229 | ||
230 | #ifndef SHM_HUGETLB | |
231 | #define SHM_HUGETLB 04000 | |
232 | #endif | |
233 | ||
234 | #define LENGTH (256UL*1024*1024) | |
235 | ||
236 | #define dprintf(x) printf(x) | |
237 | ||
238 | /* Only ia64 requires this */ | |
239 | #ifdef __ia64__ | |
240 | #define ADDR (void *)(0x8000000000000000UL) | |
241 | #define SHMAT_FLAGS (SHM_RND) | |
242 | #else | |
243 | #define ADDR (void *)(0x0UL) | |
244 | #define SHMAT_FLAGS (0) | |
245 | #endif | |
246 | ||
247 | int main(void) | |
248 | { | |
249 | int shmid; | |
250 | unsigned long i; | |
251 | char *shmaddr; | |
252 | ||
253 | if ((shmid = shmget(2, LENGTH, | |
254 | SHM_HUGETLB | IPC_CREAT | SHM_R | SHM_W)) < 0) { | |
255 | perror("shmget"); | |
256 | exit(1); | |
257 | } | |
258 | printf("shmid: 0x%x\n", shmid); | |
259 | ||
260 | shmaddr = shmat(shmid, ADDR, SHMAT_FLAGS); | |
261 | if (shmaddr == (char *)-1) { | |
262 | perror("Shared memory attach failure"); | |
263 | shmctl(shmid, IPC_RMID, NULL); | |
264 | exit(2); | |
265 | } | |
266 | printf("shmaddr: %p\n", shmaddr); | |
267 | ||
268 | dprintf("Starting the writes:\n"); | |
269 | for (i = 0; i < LENGTH; i++) { | |
270 | shmaddr[i] = (char)(i); | |
271 | if (!(i % (1024 * 1024))) | |
272 | dprintf("."); | |
273 | } | |
274 | dprintf("\n"); | |
275 | ||
276 | dprintf("Starting the Check..."); | |
277 | for (i = 0; i < LENGTH; i++) | |
278 | if (shmaddr[i] != (char)i) | |
279 | printf("\nIndex %lu mismatched\n", i); | |
280 | dprintf("Done.\n"); | |
281 | ||
282 | if (shmdt((const void *)shmaddr) != 0) { | |
283 | perror("Detach failure"); | |
284 | shmctl(shmid, IPC_RMID, NULL); | |
285 | exit(3); | |
286 | } | |
287 | ||
288 | shmctl(shmid, IPC_RMID, NULL); | |
289 | ||
290 | return 0; | |
291 | } | |
292 | ||
293 | ******************************************************************* | |
294 | ||
295 | /* | |
41a25e7e | 296 | * Example of using huge page memory in a user application using the mmap |
1da177e4 LT |
297 | * system call. Before running this application, make sure that the |
298 | * administrator has mounted the hugetlbfs filesystem (on some directory | |
299 | * like /mnt) using the command mount -t hugetlbfs nodev /mnt. In this | |
300 | * example, the app is requesting memory of size 256MB that is backed by | |
301 | * huge pages. | |
302 | * | |
41a25e7e | 303 | * For ia64 architecture, Linux kernel reserves Region number 4 for huge pages. |
1da177e4 LT |
304 | * That means the addresses starting with 0x800000... will need to be |
305 | * specified. Specifying a fixed address is not required on ppc64, i386 | |
306 | * or x86_64. | |
307 | */ | |
308 | #include <stdlib.h> | |
309 | #include <stdio.h> | |
310 | #include <unistd.h> | |
311 | #include <sys/mman.h> | |
312 | #include <fcntl.h> | |
313 | ||
314 | #define FILE_NAME "/mnt/hugepagefile" | |
315 | #define LENGTH (256UL*1024*1024) | |
316 | #define PROTECTION (PROT_READ | PROT_WRITE) | |
317 | ||
318 | /* Only ia64 requires this */ | |
319 | #ifdef __ia64__ | |
320 | #define ADDR (void *)(0x8000000000000000UL) | |
321 | #define FLAGS (MAP_SHARED | MAP_FIXED) | |
322 | #else | |
323 | #define ADDR (void *)(0x0UL) | |
324 | #define FLAGS (MAP_SHARED) | |
325 | #endif | |
326 | ||
327 | void check_bytes(char *addr) | |
328 | { | |
329 | printf("First hex is %x\n", *((unsigned int *)addr)); | |
330 | } | |
331 | ||
332 | void write_bytes(char *addr) | |
333 | { | |
334 | unsigned long i; | |
335 | ||
336 | for (i = 0; i < LENGTH; i++) | |
337 | *(addr + i) = (char)i; | |
338 | } | |
339 | ||
340 | void read_bytes(char *addr) | |
341 | { | |
342 | unsigned long i; | |
343 | ||
344 | check_bytes(addr); | |
345 | for (i = 0; i < LENGTH; i++) | |
346 | if (*(addr + i) != (char)i) { | |
347 | printf("Mismatch at %lu\n", i); | |
348 | break; | |
349 | } | |
350 | } | |
351 | ||
352 | int main(void) | |
353 | { | |
354 | void *addr; | |
355 | int fd; | |
356 | ||
357 | fd = open(FILE_NAME, O_CREAT | O_RDWR, 0755); | |
358 | if (fd < 0) { | |
359 | perror("Open failed"); | |
360 | exit(1); | |
361 | } | |
362 | ||
363 | addr = mmap(ADDR, LENGTH, PROTECTION, FLAGS, fd, 0); | |
364 | if (addr == MAP_FAILED) { | |
365 | perror("mmap"); | |
366 | unlink(FILE_NAME); | |
367 | exit(1); | |
368 | } | |
369 | ||
370 | printf("Returned address is %p\n", addr); | |
371 | check_bytes(addr); | |
372 | write_bytes(addr); | |
373 | read_bytes(addr); | |
374 | ||
375 | munmap(addr, LENGTH); | |
376 | close(fd); | |
377 | unlink(FILE_NAME); | |
378 | ||
379 | return 0; | |
380 | } |