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       --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
63
64       The following options affect how hugectl behaves.
65
66
67       --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
73
74       --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
82
83       --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
93
94       --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
100
101       --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
107
108       --library-path <path>
109              This  option  forces  hugectl  to use the libhugetlbfs libraries
110              within the given prefix.
111
112
113       The following options affect the verbosity of libhugetlbfs.
114
115
116       --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
123
124       -q     The -q option will drecease the verbosity level by 1  each  time
125              it is specified to a minimum of 0.
126
127

SEE ALSO

129       oprofile(1), hugeadm(7), libhugetlbfs(7)
130

AUTHORS

132       libhugetlbfs  was  written  by various people on the libhugetlbfs-devel
133       mailing list.
134
135
136
137
138                               October 10, 2008                     HUGECTL(8)
Impressum