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 LT |
20 | |
21 | The kernel built with hugepage support should show the number of configured | |
5c7ad510 | 22 | hugepages 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 | |
27 | the configured hugepage size - this is needed for generating the proper | |
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 | ..... | |
33 | HugePages_Total: xxx | |
34 | HugePages_Free: yyy | |
5e122271 RD |
35 | HugePages_Rsvd: www |
36 | Hugepagesize: zzz kB | |
37 | ||
38 | where: | |
39 | HugePages_Total is the size of the pool of hugepages. | |
40 | HugePages_Free is the number of hugepages in the pool that are not yet | |
41 | allocated. | |
42 | HugePages_Rsvd is short for "reserved," and is the number of hugepages | |
43 | for which a commitment to allocate from the pool has been made, but no | |
44 | allocation has yet been made. It's vaguely analogous to overcommit. | |
1da177e4 LT |
45 | |
46 | /proc/filesystems should also show a filesystem of type "hugetlbfs" configured | |
47 | in the kernel. | |
48 | ||
49 | /proc/sys/vm/nr_hugepages indicates the current number of configured hugetlb | |
50 | pages in the kernel. Super user can dynamically request more (or free some | |
5c7ad510 MBY |
51 | pre-configured) hugepages. |
52 | The allocation (or deallocation) of hugetlb pages is possible only if there are | |
1da177e4 | 53 | enough physically contiguous free pages in system (freeing of hugepages is |
21a26d49 | 54 | possible only if there are enough hugetlb pages free that can be transferred |
1da177e4 LT |
55 | back to regular memory pool). |
56 | ||
21a26d49 RD |
57 | Pages that are used as hugetlb pages are reserved inside the kernel and cannot |
58 | be used for other purposes. | |
1da177e4 LT |
59 | |
60 | Once the kernel with Hugetlb page support is built and running, a user can | |
61 | use either the mmap system call or shared memory system calls to start using | |
62 | the huge pages. It is required that the system administrator preallocate | |
5c7ad510 | 63 | enough memory for huge page purposes. |
1da177e4 LT |
64 | |
65 | Use the following command to dynamically allocate/deallocate hugepages: | |
66 | ||
67 | echo 20 > /proc/sys/vm/nr_hugepages | |
68 | ||
69 | This command will try to configure 20 hugepages in the system. The success | |
70 | or failure of allocation depends on the amount of physically contiguous | |
71 | memory that is preset in system at this time. System administrators may want | |
21a26d49 | 72 | to put this command in one of the local rc init files. This will enable the |
1da177e4 LT |
73 | kernel to request huge pages early in the boot process (when the possibility |
74 | of getting physical contiguous pages is still very high). | |
75 | ||
76 | If the user applications are going to request hugepages using mmap system | |
77 | call, then it is required that system administrator mount a file system of | |
78 | type hugetlbfs: | |
79 | ||
e73a75fa RD |
80 | mount -t hugetlbfs \ |
81 | -o uid=<value>,gid=<value>,mode=<value>,size=<value>,nr_inodes=<value> \ | |
82 | none /mnt/huge | |
1da177e4 LT |
83 | |
84 | This command mounts a (pseudo) filesystem of type hugetlbfs on the directory | |
85 | /mnt/huge. Any files created on /mnt/huge uses hugepages. The uid and gid | |
86 | options sets the owner and group of the root of the file system. By default | |
87 | the uid and gid of the current process are taken. The mode option sets the | |
88 | mode of root of file system to value & 0777. This value is given in octal. | |
89 | By default the value 0755 is picked. The size option sets the maximum value of | |
90 | memory (huge pages) allowed for that filesystem (/mnt/huge). The size is | |
21a26d49 | 91 | rounded down to HPAGE_SIZE. The option nr_inodes sets the maximum number of |
e73a75fa | 92 | inodes that /mnt/huge can use. If the size or nr_inodes option is not |
1da177e4 | 93 | provided on command line then no limits are set. For size and nr_inodes |
5c7ad510 | 94 | options, you can use [G|g]/[M|m]/[K|k] to represent giga/mega/kilo. For |
e73a75fa | 95 | example, size=2K has the same meaning as size=2048. |
1da177e4 LT |
96 | |
97 | read and write system calls are not supported on files that reside on hugetlb | |
98 | file systems. | |
99 | ||
21a26d49 | 100 | Regular chown, chgrp, and chmod commands (with right permissions) could be |
1da177e4 LT |
101 | used to change the file attributes on hugetlbfs. |
102 | ||
103 | Also, it is important to note that no such mount command is required if the | |
104 | applications are going to use only shmat/shmget system calls. Users who | |
105 | wish to use hugetlb page via shared memory segment should be a member of | |
106 | a supplementary group and system admin needs to configure that gid into | |
107 | /proc/sys/vm/hugetlb_shm_group. It is possible for same or different | |
21a26d49 RD |
108 | applications to use any combination of mmaps and shm* calls, though the |
109 | mount of filesystem will be required for using mmap calls. | |
1da177e4 LT |
110 | |
111 | ******************************************************************* | |
112 | ||
113 | /* | |
114 | * Example of using hugepage memory in a user application using Sys V shared | |
115 | * memory system calls. In this example the app is requesting 256MB of | |
116 | * memory that is backed by huge pages. The application uses the flag | |
117 | * SHM_HUGETLB in the shmget system call to inform the kernel that it is | |
118 | * requesting hugepages. | |
119 | * | |
120 | * For the ia64 architecture, the Linux kernel reserves Region number 4 for | |
121 | * hugepages. That means the addresses starting with 0x800000... will need | |
122 | * to be specified. Specifying a fixed address is not required on ppc64, | |
123 | * i386 or x86_64. | |
124 | * | |
125 | * Note: The default shared memory limit is quite low on many kernels, | |
126 | * you may need to increase it via: | |
127 | * | |
128 | * echo 268435456 > /proc/sys/kernel/shmmax | |
129 | * | |
130 | * This will increase the maximum size per shared memory segment to 256MB. | |
131 | * The other limit that you will hit eventually is shmall which is the | |
132 | * total amount of shared memory in pages. To set it to 16GB on a system | |
133 | * with a 4kB pagesize do: | |
134 | * | |
135 | * echo 4194304 > /proc/sys/kernel/shmall | |
136 | */ | |
137 | #include <stdlib.h> | |
138 | #include <stdio.h> | |
139 | #include <sys/types.h> | |
140 | #include <sys/ipc.h> | |
141 | #include <sys/shm.h> | |
142 | #include <sys/mman.h> | |
143 | ||
144 | #ifndef SHM_HUGETLB | |
145 | #define SHM_HUGETLB 04000 | |
146 | #endif | |
147 | ||
148 | #define LENGTH (256UL*1024*1024) | |
149 | ||
150 | #define dprintf(x) printf(x) | |
151 | ||
152 | /* Only ia64 requires this */ | |
153 | #ifdef __ia64__ | |
154 | #define ADDR (void *)(0x8000000000000000UL) | |
155 | #define SHMAT_FLAGS (SHM_RND) | |
156 | #else | |
157 | #define ADDR (void *)(0x0UL) | |
158 | #define SHMAT_FLAGS (0) | |
159 | #endif | |
160 | ||
161 | int main(void) | |
162 | { | |
163 | int shmid; | |
164 | unsigned long i; | |
165 | char *shmaddr; | |
166 | ||
167 | if ((shmid = shmget(2, LENGTH, | |
168 | SHM_HUGETLB | IPC_CREAT | SHM_R | SHM_W)) < 0) { | |
169 | perror("shmget"); | |
170 | exit(1); | |
171 | } | |
172 | printf("shmid: 0x%x\n", shmid); | |
173 | ||
174 | shmaddr = shmat(shmid, ADDR, SHMAT_FLAGS); | |
175 | if (shmaddr == (char *)-1) { | |
176 | perror("Shared memory attach failure"); | |
177 | shmctl(shmid, IPC_RMID, NULL); | |
178 | exit(2); | |
179 | } | |
180 | printf("shmaddr: %p\n", shmaddr); | |
181 | ||
182 | dprintf("Starting the writes:\n"); | |
183 | for (i = 0; i < LENGTH; i++) { | |
184 | shmaddr[i] = (char)(i); | |
185 | if (!(i % (1024 * 1024))) | |
186 | dprintf("."); | |
187 | } | |
188 | dprintf("\n"); | |
189 | ||
190 | dprintf("Starting the Check..."); | |
191 | for (i = 0; i < LENGTH; i++) | |
192 | if (shmaddr[i] != (char)i) | |
193 | printf("\nIndex %lu mismatched\n", i); | |
194 | dprintf("Done.\n"); | |
195 | ||
196 | if (shmdt((const void *)shmaddr) != 0) { | |
197 | perror("Detach failure"); | |
198 | shmctl(shmid, IPC_RMID, NULL); | |
199 | exit(3); | |
200 | } | |
201 | ||
202 | shmctl(shmid, IPC_RMID, NULL); | |
203 | ||
204 | return 0; | |
205 | } | |
206 | ||
207 | ******************************************************************* | |
208 | ||
209 | /* | |
210 | * Example of using hugepage memory in a user application using the mmap | |
211 | * system call. Before running this application, make sure that the | |
212 | * administrator has mounted the hugetlbfs filesystem (on some directory | |
213 | * like /mnt) using the command mount -t hugetlbfs nodev /mnt. In this | |
214 | * example, the app is requesting memory of size 256MB that is backed by | |
215 | * huge pages. | |
216 | * | |
217 | * For ia64 architecture, Linux kernel reserves Region number 4 for hugepages. | |
218 | * That means the addresses starting with 0x800000... will need to be | |
219 | * specified. Specifying a fixed address is not required on ppc64, i386 | |
220 | * or x86_64. | |
221 | */ | |
222 | #include <stdlib.h> | |
223 | #include <stdio.h> | |
224 | #include <unistd.h> | |
225 | #include <sys/mman.h> | |
226 | #include <fcntl.h> | |
227 | ||
228 | #define FILE_NAME "/mnt/hugepagefile" | |
229 | #define LENGTH (256UL*1024*1024) | |
230 | #define PROTECTION (PROT_READ | PROT_WRITE) | |
231 | ||
232 | /* Only ia64 requires this */ | |
233 | #ifdef __ia64__ | |
234 | #define ADDR (void *)(0x8000000000000000UL) | |
235 | #define FLAGS (MAP_SHARED | MAP_FIXED) | |
236 | #else | |
237 | #define ADDR (void *)(0x0UL) | |
238 | #define FLAGS (MAP_SHARED) | |
239 | #endif | |
240 | ||
241 | void check_bytes(char *addr) | |
242 | { | |
243 | printf("First hex is %x\n", *((unsigned int *)addr)); | |
244 | } | |
245 | ||
246 | void write_bytes(char *addr) | |
247 | { | |
248 | unsigned long i; | |
249 | ||
250 | for (i = 0; i < LENGTH; i++) | |
251 | *(addr + i) = (char)i; | |
252 | } | |
253 | ||
254 | void read_bytes(char *addr) | |
255 | { | |
256 | unsigned long i; | |
257 | ||
258 | check_bytes(addr); | |
259 | for (i = 0; i < LENGTH; i++) | |
260 | if (*(addr + i) != (char)i) { | |
261 | printf("Mismatch at %lu\n", i); | |
262 | break; | |
263 | } | |
264 | } | |
265 | ||
266 | int main(void) | |
267 | { | |
268 | void *addr; | |
269 | int fd; | |
270 | ||
271 | fd = open(FILE_NAME, O_CREAT | O_RDWR, 0755); | |
272 | if (fd < 0) { | |
273 | perror("Open failed"); | |
274 | exit(1); | |
275 | } | |
276 | ||
277 | addr = mmap(ADDR, LENGTH, PROTECTION, FLAGS, fd, 0); | |
278 | if (addr == MAP_FAILED) { | |
279 | perror("mmap"); | |
280 | unlink(FILE_NAME); | |
281 | exit(1); | |
282 | } | |
283 | ||
284 | printf("Returned address is %p\n", addr); | |
285 | check_bytes(addr); | |
286 | write_bytes(addr); | |
287 | read_bytes(addr); | |
288 | ||
289 | munmap(addr, LENGTH); | |
290 | close(fd); | |
291 | unlink(FILE_NAME); | |
292 | ||
293 | return 0; | |
294 | } |