hugectl - Control policy for backing text, data and malloc() with hugepages
hugectl [options] command {arguments}
hugectl runs processes with a specific policy for backing memory regions
with hugepages. The use of hugepages benefit applications that use large
amounts of address space and suffer a performance hit due to TLB misses.
Policy is enforced by
libhugetlbfs and
hugectl configures the
environment based on the options provided. Wall-clock time or oprofile can be
used to determine if there is a performance benefit from using hugepages or
not.
To effectively back text/data, the target process must be relinked to align the
ELF segments on a hugepage boundary. The library also supports more options
for the control of memory regions than are exposed by the
hugectl
utility. See the
libhugetlbfs manual page for more details.
The following options affect what memory regions are backed by hugepages.
- --text[=<size>],--data[=<size>],--bss[=<size>]
- Back the text, data or BSS segments with hugepages,
optionally with pages of the specified size. To be effective, the process
must be relinked as described in the HOWTO to align the ELF segments. It
is possible to partially back segments using the HUGETLB_FORCE_ELMAP
environment variable as described in the libhugetlbfs manual page.
- --heap[=<size>]
- Use the glibc morecore hook to back malloc() with
hugepages, optionally with pages of the specified size. Note that this
does not affect brk() segments and applications that use custom allocators
potentially do not use hugepages for their heap even with this option
specified.
- --shm
- This option overrides shmget() to back shared memory
regions with hugepages if possible. Segment size requests will be aligned
to fit to the default hugepage size region.
- --share-text
- Request that multiple application instances share text
segments that are backed with huge pages. This option sets the environment
variable HUGETLB_SHARE to 1.
- --thp
- Align heap regions to huge page size for promotion by
khugepaged. For more information on transparent huge pages see
linux-2.6/Documentation/transhuge.txt
The following options affect how
hugectl behaves.
- --no-preload
- Disable any pre-loading of the libhugetlbfs library.
This may be necessary if only the heap is being backed by hugepages and
the application is already linked against the library. hugectl may
pre-load the library by mistake and this option prevents that.
- --force-preload
- Force pre-loading of the libhugetlbfs library. This
option is used when the segments of the binary are aligned to the hugepage
boundary of interest but the binary is not linked against libhugetlbfs.
This is useful on PPC64 where binaries are aligned to 64K as required by
the ABI and the kernel is using a 4K base pagesize.
- --no-reserve
- By default, huge pages are reserved at mmap() time so
future faults will succeed. This avoids unexpected application but some
applications depend on memory overcommit to create large sparse mappings.
For this type of application, this switch will create huge page backed
mappings without a reservation if the kernel is recent enough to make this
operation safe. Use this option with extreme care as in the event huge
pages are not available when the mapping is faulted, the application will
be killed.
- --dry-run
- Instead of running the process, the hugectl utility
will describe what environment variables it set for libhugetlbfs.
This is useful if additional environment variables are to be set and a
launcher shell script is being developed.
- --library-use-path
- By default, hugectl will use the version of
libhugetlbfs it was installed with, even if this is not in the
LD_LIBRARY_PATH environment. Using this option forces hugectl to
use the version of libhugetlbfs installed in the library system
path.
- --library-path <path>
- This option forces hugectl to use the
libhugetlbfs libraries within the given prefix.
The following options affect the verbosity of libhugetlbfs.
- --verbose <level>, -v
- The default value for the verbosity level is 1 and the
range of the value can be set with --verbose from 0 to 99. The higher the
value, the more verbose the library will be. 0 is quiet and 3 will output
much debugging information. The verbosity level is increased by one each
time -v is specified.
- -q
- The -q option will drecease the verbosity level by 1 each
time it is specified to a minimum of 0.
oprofile(1),
hugeadm(7),
libhugetlbfs(7)
libhugetlbfs was written by various people on the libhugetlbfs-devel mailing
list.