1HUGECTL(8)                  System Manager's Manual                 HUGECTL(8)
2
3
4

NAME

6       hugectl  -  Control  policy  for  backing  text, data and malloc() with
7       hugepages
8

SYNOPSIS

10       hugectl [options] command {arguments}
11

DESCRIPTION

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
21       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
27       The  following  options  affect  what  memory  regions  are  backed  by
28       hugepages.
29
30
31       --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
39
40       --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
47
48       --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
52
53       --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
58
59       The following options affect how hugectl behaves.
60
61
62       --no-preload
63              Disable any pre-loading of the libhugetlbfs library. This may be
64              necessary  if only the heap is being backed by hugepages and the
65              application is already linked against the library.  hugectl  may
66              pre-load the library by mistake and this option prevents that.
67
68
69       --force-preload
70              Force  pre-loading  of  the libhugetlbfs library. This option is
71              used when the segments of the binary are aligned to the hugepage
72              boundary  of  interest but the binary is not linked against lib‐
73              hugetlbfs. This is useful on PPC64 where binaries are aligned to
74              64K  as  required  by  the ABI and the kernel is using a 4K base
75              pagesize.
76
77
78       --no-reserve
79              By default, huge pages are reserved at  mmap()  time  so  future
80              faults will succeed. This avoids unexpected application but some
81              applications depend on memory overcommit to create large  sparse
82              mappings.  For this type of application, this switch will create
83              huge page backed mappings without a reservation if the kernel is
84              recent enough to make this operation safe.  Use this option with
85              extreme care as in the event huge pages are not  available  when
86              the mapping is faulted, the application will be killed.
87
88
89       --dry-run
90              Instead  of  running  the  process,  the  hugectl  utility  will
91              describe what environment variables  it  set  for  libhugetlbfs.
92              This is useful if additional environment variables are to be set
93              and a launcher shell script is being developed.
94
95
96       --library-use-path
97              By default, hugectl will use the version of libhugetlbfs it  was
98              installed with, even if this is not in the LD_LIBRARY_PATH envi‐
99              ronment. Using this option forces hugectl to use the version  of
100              libhugetlbfs installed in the library system path.
101
102
103       --library-path <path>
104              This  option  forces  hugectl  to use the libhugetlbfs libraries
105              within the given prefix.
106
107
108       The following options affect the verbosity of libhugetlbfs.
109
110
111       --verbose <level>, -v
112              The default value for the verbosity level is 1 and the range  of
113              the value can be set with --verbose from 0 to 99. The higher the
114              value, the more verbose the library will be. 0 is  quiet  and  3
115              will  output  much debugging information. The verbosity level is
116              increased by one each time -v is specified.
117
118
119       -q     The -q option will drecease the verbosity level by 1  each  time
120              it is specified to a minimum of 0.
121
122

SEE ALSO

124       oprofile(1), hugeadm(7), libhugetlbfs(7)
125

AUTHORS

127       libhugetlbfs  was  written  by various people on the libhugetlbfs-devel
128       mailing list.
129
130
131
132
133                               October 10, 2008                     HUGECTL(8)
Impressum