1HUGECTL(8) System Manager's Manual HUGECTL(8)
2
6 hugectl - Control policy for backing text, data and malloc() with
7 hugepages
8
10 hugectl [options] command {arguments}
11
13 hugectl runs processes with a specific policy for backing memory
14 regions with hugepages. The use of hugepages benefit applications that
15 use large amounts of address space and suffer a performance hit due to
16 TLB misses. Policy is enforced by libhugetlbfs and hugectl configures
17 the environment based on the options provided. Wall-clock time or
18 oprofile can be used to determine if there is a performance benefit
19 from using hugepages or not.
20 To effectively back text/data, the target process must be relinked to
22 align the ELF segments on a hugepage boundary. The library also sup‐
23 ports more options for the control of memory regions than are exposed
24 by the hugectl utility. See the libhugetlbfs manual page for more
25 details.
26 The following options affect what memory regions are backed by
28 hugepages.
29 --text[=<size>],--data[=<size>],--bss[=<size>]
32 Back the text, data or BSS segments with hugepages, optionally
33 with pages of the specified size. To be effective, the process
34 must be relinked as described in the HOWTO to align the ELF seg‐
35 ments. It is possible to partially back segments using the
36 HUGETLB_FORCE_ELMAP environment variable as described in the
37 libhugetlbfs manual page.
38 --heap[=<size>]
41 Use the glibc morecore hook to back malloc() with hugepages,
42 optionally with pages of the specified size. Note that this
43 does not affect brk() segments and applications that use custom
44 allocators potentially do not use hugepages for their heap even
45 with this option specified.
46 --shm This option overrides shmget() to back shared memory regions
49 with hugepages if possible. Segment size requests will be
50 aligned to fit to the default hugepage size region.
51 --share-text
54 Request that multiple application instances share text segments
55 that are backed with huge pages. This option sets the environ‐
56 ment variable HUGETLB_SHARE to 1.
57 --thp Align heap regions to huge page size for promotion by
60 khugepaged. For more information on transparent huge pages see
61 linux-2.6/Documentation/transhuge.txt
62 The following options affect how hugectl behaves.
65 --no-preload
68 Disable any pre-loading of the libhugetlbfs library. This may be
69 necessary if only the heap is being backed by hugepages and the
70 application is already linked against the library. hugectl may
71 pre-load the library by mistake and this option prevents that.
72 --force-preload
75 Force pre-loading of the libhugetlbfs library. This option is
76 used when the segments of the binary are aligned to the hugepage
77 boundary of interest but the binary is not linked against lib‐
78 hugetlbfs. This is useful on PPC64 where binaries are aligned to
79 64K as required by the ABI and the kernel is using a 4K base
80 pagesize.
81 --no-reserve
84 By default, huge pages are reserved at mmap() time so future
85 faults will succeed. This avoids unexpected application but some
86 applications depend on memory overcommit to create large sparse
87 mappings. For this type of application, this switch will create
88 huge page backed mappings without a reservation if the kernel is
89 recent enough to make this operation safe. Use this option with
90 extreme care as in the event huge pages are not available when
91 the mapping is faulted, the application will be killed.
92 --dry-run
95 Instead of running the process, the hugectl utility will
96 describe what environment variables it set for libhugetlbfs.
97 This is useful if additional environment variables are to be set
98 and a launcher shell script is being developed.
99 --library-use-path
102 By default, hugectl will use the version of libhugetlbfs it was
103 installed with, even if this is not in the LD_LIBRARY_PATH envi‐
104 ronment. Using this option forces hugectl to use the version of
105 libhugetlbfs installed in the library system path.
106 --library-path <path>
109 This option forces hugectl to use the libhugetlbfs libraries
110 within the given prefix.
111 The following options affect the verbosity of libhugetlbfs.
114 --verbose <level>, -v
117 The default value for the verbosity level is 1 and the range of
118 the value can be set with --verbose from 0 to 99. The higher the
119 value, the more verbose the library will be. 0 is quiet and 3
120 will output much debugging information. The verbosity level is
121 increased by one each time -v is specified.
122 -q The -q option will drecease the verbosity level by 1 each time
125 it is specified to a minimum of 0.
126
129 oprofile(1), hugeadm(7), libhugetlbfs(7)
130
132 libhugetlbfs was written by various people on the libhugetlbfs-devel
133 mailing list.
134 October 10, 2008 HUGECTL(8)