mirror of
https://sourceware.org/git/glibc.git
synced 2024-12-26 12:41:05 +00:00
9c9ec58197
* manual/tunables.texi (glibc.tune.cpu): Add thunderx2t99 and thunderx2t99p1 to list of cpu names. * sysdeps/unix/sysv/linux/aarch64/cpu-features.c (cpu_list): Add thunderx2t99 and thunderx2t99p1 entries to cpu_list.
280 lines
12 KiB
Plaintext
280 lines
12 KiB
Plaintext
@node Tunables
|
|
@c @node Tunables, , Internal Probes, Top
|
|
@c %MENU% Tunable switches to alter libc internal behavior
|
|
@chapter Tunables
|
|
@cindex tunables
|
|
|
|
@dfn{Tunables} are a feature in @theglibc{} that allows application authors and
|
|
distribution maintainers to alter the runtime library behavior to match
|
|
their workload. These are implemented as a set of switches that may be
|
|
modified in different ways. The current default method to do this is via
|
|
the @env{GLIBC_TUNABLES} environment variable by setting it to a string
|
|
of colon-separated @var{name}=@var{value} pairs. For example, the following
|
|
example enables malloc checking and sets the malloc trim threshold to 128
|
|
bytes:
|
|
|
|
@example
|
|
GLIBC_TUNABLES=glibc.malloc.trim_threshold=128:glibc.malloc.check=3
|
|
export GLIBC_TUNABLES
|
|
@end example
|
|
|
|
Tunables are not part of the @glibcadj{} stable ABI, and they are
|
|
subject to change or removal across releases. Additionally, the method to
|
|
modify tunable values may change between releases and across distributions.
|
|
It is possible to implement multiple `frontends' for the tunables allowing
|
|
distributions to choose their preferred method at build time.
|
|
|
|
Finally, the set of tunables available may vary between distributions as
|
|
the tunables feature allows distributions to add their own tunables under
|
|
their own namespace.
|
|
|
|
@menu
|
|
* Tunable names:: The structure of a tunable name
|
|
* Memory Allocation Tunables:: Tunables in the memory allocation subsystem
|
|
* Hardware Capability Tunables:: Tunables that modify the hardware
|
|
capabilities seen by @theglibc{}
|
|
@end menu
|
|
|
|
@node Tunable names
|
|
@section Tunable names
|
|
@cindex Tunable names
|
|
@cindex Tunable namespaces
|
|
|
|
A tunable name is split into three components, a top namespace, a tunable
|
|
namespace and the tunable name. The top namespace for tunables implemented in
|
|
@theglibc{} is @code{glibc}. Distributions that choose to add custom tunables
|
|
in their maintained versions of @theglibc{} may choose to do so under their own
|
|
top namespace.
|
|
|
|
The tunable namespace is a logical grouping of tunables in a single
|
|
module. This currently holds no special significance, although that may
|
|
change in the future.
|
|
|
|
The tunable name is the actual name of the tunable. It is possible that
|
|
different tunable namespaces may have tunables within them that have the
|
|
same name, likewise for top namespaces. Hence, we only support
|
|
identification of tunables by their full name, i.e. with the top
|
|
namespace, tunable namespace and tunable name, separated by periods.
|
|
|
|
@node Memory Allocation Tunables
|
|
@section Memory Allocation Tunables
|
|
@cindex memory allocation tunables
|
|
@cindex malloc tunables
|
|
@cindex tunables, malloc
|
|
|
|
@deftp {Tunable namespace} glibc.malloc
|
|
Memory allocation behavior can be modified by setting any of the
|
|
following tunables in the @code{malloc} namespace:
|
|
@end deftp
|
|
|
|
@deftp Tunable glibc.malloc.check
|
|
This tunable supersedes the @env{MALLOC_CHECK_} environment variable and is
|
|
identical in features.
|
|
|
|
Setting this tunable to a non-zero value enables a special (less
|
|
efficient) memory allocator for the malloc family of functions that is
|
|
designed to be tolerant against simple errors such as double calls of
|
|
free with the same argument, or overruns of a single byte (off-by-one
|
|
bugs). Not all such errors can be protected against, however, and memory
|
|
leaks can result. Any detected heap corruption results in immediate
|
|
termination of the process.
|
|
|
|
Like @env{MALLOC_CHECK_}, @code{glibc.malloc.check} has a problem in that it
|
|
diverges from normal program behavior by writing to @code{stderr}, which could
|
|
by exploited in SUID and SGID binaries. Therefore, @code{glibc.malloc.check}
|
|
is disabled by default for SUID and SGID binaries. This can be enabled again
|
|
by the system administrator by adding a file @file{/etc/suid-debug}; the
|
|
content of the file could be anything or even empty.
|
|
@end deftp
|
|
|
|
@deftp Tunable glibc.malloc.top_pad
|
|
This tunable supersedes the @env{MALLOC_TOP_PAD_} environment variable and is
|
|
identical in features.
|
|
|
|
This tunable determines the amount of extra memory in bytes to obtain from the
|
|
system when any of the arenas need to be extended. It also specifies the
|
|
number of bytes to retain when shrinking any of the arenas. This provides the
|
|
necessary hysteresis in heap size such that excessive amounts of system calls
|
|
can be avoided.
|
|
|
|
The default value of this tunable is @samp{0}.
|
|
@end deftp
|
|
|
|
@deftp Tunable glibc.malloc.perturb
|
|
This tunable supersedes the @env{MALLOC_PERTURB_} environment variable and is
|
|
identical in features.
|
|
|
|
If set to a non-zero value, memory blocks are initialized with values depending
|
|
on some low order bits of this tunable when they are allocated (except when
|
|
allocated by calloc) and freed. This can be used to debug the use of
|
|
uninitialized or freed heap memory. Note that this option does not guarantee
|
|
that the freed block will have any specific values. It only guarantees that the
|
|
content the block had before it was freed will be overwritten.
|
|
|
|
The default value of this tunable is @samp{0}.
|
|
@end deftp
|
|
|
|
@deftp Tunable glibc.malloc.mmap_threshold
|
|
This tunable supersedes the @env{MALLOC_MMAP_THRESHOLD_} environment variable
|
|
and is identical in features.
|
|
|
|
When this tunable is set, all chunks larger than this value in bytes are
|
|
allocated outside the normal heap, using the @code{mmap} system call. This way
|
|
it is guaranteed that the memory for these chunks can be returned to the system
|
|
on @code{free}. Note that requests smaller than this threshold might still be
|
|
allocated via @code{mmap}.
|
|
|
|
If this tunable is not set, the default value is set to @samp{131072} bytes and
|
|
the threshold is adjusted dynamically to suit the allocation patterns of the
|
|
program. If the tunable is set, the dynamic adjustment is disabled and the
|
|
value is set as static.
|
|
@end deftp
|
|
|
|
@deftp Tunable glibc.malloc.trim_threshold
|
|
This tunable supersedes the @env{MALLOC_TRIM_THRESHOLD_} environment variable
|
|
and is identical in features.
|
|
|
|
The value of this tunable is the minimum size (in bytes) of the top-most,
|
|
releasable chunk in an arena that will trigger a system call in order to return
|
|
memory to the system from that arena.
|
|
|
|
If this tunable is not set, the default value is set as 128 KB and the
|
|
threshold is adjusted dynamically to suit the allocation patterns of the
|
|
program. If the tunable is set, the dynamic adjustment is disabled and the
|
|
value is set as static.
|
|
@end deftp
|
|
|
|
@deftp Tunable glibc.malloc.mmap_max
|
|
This tunable supersedes the @env{MALLOC_MMAP_MAX_} environment variable and is
|
|
identical in features.
|
|
|
|
The value of this tunable is maximum number of chunks to allocate with
|
|
@code{mmap}. Setting this to zero disables all use of @code{mmap}.
|
|
|
|
The default value of this tunable is @samp{65536}.
|
|
@end deftp
|
|
|
|
@deftp Tunable glibc.malloc.arena_test
|
|
This tunable supersedes the @env{MALLOC_ARENA_TEST} environment variable and is
|
|
identical in features.
|
|
|
|
The @code{glibc.malloc.arena_test} tunable specifies the number of arenas that
|
|
can be created before the test on the limit to the number of arenas is
|
|
conducted. The value is ignored if @code{glibc.malloc.arena_max} is set.
|
|
|
|
The default value of this tunable is 2 for 32-bit systems and 8 for 64-bit
|
|
systems.
|
|
@end deftp
|
|
|
|
@deftp Tunable glibc.malloc.arena_max
|
|
This tunable supersedes the @env{MALLOC_ARENA_MAX} environment variable and is
|
|
identical in features.
|
|
|
|
This tunable sets the number of arenas to use in a process regardless of the
|
|
number of cores in the system.
|
|
|
|
The default value of this tunable is @code{0}, meaning that the limit on the
|
|
number of arenas is determined by the number of CPU cores online. For 32-bit
|
|
systems the limit is twice the number of cores online and on 64-bit systems, it
|
|
is 8 times the number of cores online.
|
|
@end deftp
|
|
|
|
@deftp Tunable glibc.malloc.tcache_max
|
|
The maximum size of a request (in bytes) which may be met via the
|
|
per-thread cache. The default (and maximum) value is 1032 bytes on
|
|
64-bit systems and 516 bytes on 32-bit systems.
|
|
@end deftp
|
|
|
|
@deftp Tunable glibc.malloc.tcache_count
|
|
The maximum number of chunks of each size to cache. The default is 7.
|
|
There is no upper limit, other than available system memory. If set
|
|
to zero, the per-thread cache is effectively disabled.
|
|
|
|
The approximate maximum overhead of the per-thread cache is thus equal
|
|
to the number of bins times the chunk count in each bin times the size
|
|
of each chunk. With defaults, the approximate maximum overhead of the
|
|
per-thread cache is approximately 236 KB on 64-bit systems and 118 KB
|
|
on 32-bit systems.
|
|
@end deftp
|
|
|
|
@deftp Tunable glibc.malloc.tcache_unsorted_limit
|
|
When the user requests memory and the request cannot be met via the
|
|
per-thread cache, the arenas are used to meet the request. At this
|
|
time, additional chunks will be moved from existing arena lists to
|
|
pre-fill the corresponding cache. While copies from the fastbins,
|
|
smallbins, and regular bins are bounded and predictable due to the bin
|
|
sizes, copies from the unsorted bin are not bounded, and incur
|
|
additional time penalties as they need to be sorted as they're
|
|
scanned. To make scanning the unsorted list more predictable and
|
|
bounded, the user may set this tunable to limit the number of chunks
|
|
that are scanned from the unsorted list while searching for chunks to
|
|
pre-fill the per-thread cache with. The default, or when set to zero,
|
|
is no limit.
|
|
@end deftp
|
|
|
|
@node Hardware Capability Tunables
|
|
@section Hardware Capability Tunables
|
|
@cindex hardware capability tunables
|
|
@cindex hwcap tunables
|
|
@cindex tunables, hwcap
|
|
@cindex hwcaps tunables
|
|
@cindex tunables, hwcaps
|
|
@cindex data_cache_size tunables
|
|
@cindex tunables, data_cache_size
|
|
@cindex shared_cache_size tunables
|
|
@cindex tunables, shared_cache_size
|
|
@cindex non_temporal_threshold tunables
|
|
@cindex tunables, non_temporal_threshold
|
|
|
|
@deftp {Tunable namespace} glibc.tune
|
|
Behavior of @theglibc{} can be tuned to assume specific hardware capabilities
|
|
by setting the following tunables in the @code{tune} namespace:
|
|
@end deftp
|
|
|
|
@deftp Tunable glibc.tune.hwcap_mask
|
|
This tunable supersedes the @env{LD_HWCAP_MASK} environment variable and is
|
|
identical in features.
|
|
|
|
The @code{AT_HWCAP} key in the Auxilliary Vector specifies instruction set
|
|
extensions available in the processor at runtime for some architectures. The
|
|
@code{glibc.tune.hwcap_mask} tunable allows the user to mask out those
|
|
capabilities at runtime, thus disabling use of those extensions.
|
|
@end deftp
|
|
|
|
@deftp Tunable glibc.tune.hwcaps
|
|
The @code{glibc.tune.hwcaps=-xxx,yyy,-zzz...} tunable allows the user to
|
|
enable CPU/ARCH feature @code{yyy}, disable CPU/ARCH feature @code{xxx}
|
|
and @code{zzz} where the feature name is case-sensitive and has to match
|
|
the ones in @code{sysdeps/x86/cpu-features.h}.
|
|
|
|
This tunable is specific to i386 and x86-64.
|
|
@end deftp
|
|
|
|
@deftp Tunable glibc.tune.cpu
|
|
The @code{glibc.tune.cpu=xxx} tunable allows the user to tell @theglibc{} to
|
|
assume that the CPU is @code{xxx} where xxx may have one of these values:
|
|
@code{generic}, @code{falkor}, @code{thunderxt88}, @code{thunderx2t99},
|
|
@code{thunderx2t99p1}.
|
|
|
|
This tunable is specific to aarch64.
|
|
@end deftp
|
|
|
|
@deftp Tunable glibc.tune.x86_data_cache_size
|
|
The @code{glibc.tune.x86_data_cache_size} tunable allows the user to set
|
|
data cache size in bytes for use in memory and string routines.
|
|
|
|
This tunable is specific to i386 and x86-64.
|
|
@end deftp
|
|
|
|
@deftp Tunable glibc.tune.x86_shared_cache_size
|
|
The @code{glibc.tune.x86_shared_cache_size} tunable allows the user to
|
|
set shared cache size in bytes for use in memory and string routines.
|
|
@end deftp
|
|
|
|
@deftp Tunable glibc.tune.x86_non_temporal_threshold
|
|
The @code{glibc.tune.x86_non_temporal_threshold} tunable allows the user
|
|
to set threshold in bytes for non temporal store.
|
|
|
|
This tunable is specific to i386 and x86-64.
|
|
@end deftp
|