about summary refs log tree commit diff
path: root/manual/tunables.texi
blob: ec18b1083412f33154e2c4b258567139f4b4c134 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
@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
* Elision Tunables::  Tunables in elision subsystem
* POSIX Thread Tunables:: Tunables in the POSIX thread 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.
The upper limit is 65535.  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

@deftp Tunable glibc.malloc.mxfast
One of the optimizations malloc uses is to maintain a series of ``fast
bins'' that hold chunks up to a specific size.  The default and
maximum size which may be held this way is 80 bytes on 32-bit systems
or 160 bytes on 64-bit systems.  Applications which value size over
speed may choose to reduce the size of requests which are serviced
from fast bins with this tunable.  Note that the value specified
includes malloc's internal overhead, which is normally the size of one
pointer, so add 4 on 32-bit systems or 8 on 64-bit systems to the size
passed to @code{malloc} for the largest bin size to enable.
@end deftp

@node Elision Tunables
@section Elision Tunables
@cindex elision tunables
@cindex tunables, elision

@deftp {Tunable namespace} glibc.elision
Contended locks are usually slow and can lead to performance and scalability
issues in multithread code. Lock elision will use memory transactions to under
certain conditions, to elide locks and improve performance.
Elision behavior can be modified by setting the following tunables in
the @code{elision} namespace:
@end deftp

@deftp Tunable glibc.elision.enable
The @code{glibc.elision.enable} tunable enables lock elision if the feature is
supported by the hardware.  If elision is not supported by the hardware this
tunable has no effect.

Elision tunables are supported for 64-bit Intel, IBM POWER, and z System
architectures.
@end deftp

@deftp Tunable glibc.elision.skip_lock_busy
The @code{glibc.elision.skip_lock_busy} tunable sets how many times to use a
non-transactional lock after a transactional failure has occurred because the
lock is already acquired.  Expressed in number of lock acquisition attempts.

The default value of this tunable is @samp{3}.
@end deftp

@deftp Tunable glibc.elision.skip_lock_internal_abort
The @code{glibc.elision.skip_lock_internal_abort} tunable sets how many times
the thread should avoid using elision if a transaction aborted for any reason
other than a different thread's memory accesses.  Expressed in number of lock
acquisition attempts.

The default value of this tunable is @samp{3}.
@end deftp

@deftp Tunable glibc.elision.skip_lock_after_retries
The @code{glibc.elision.skip_lock_after_retries} tunable sets how many times
to try to elide a lock with transactions, that only failed due to a different
thread's memory accesses, before falling back to regular lock.
Expressed in number of lock elision attempts.

This tunable is supported only on IBM POWER, and z System architectures.

The default value of this tunable is @samp{3}.
@end deftp

@deftp Tunable glibc.elision.tries
The @code{glibc.elision.tries} sets how many times to retry elision if there is
chance for the transaction to finish execution e.g., it wasn't
aborted due to the lock being already acquired.  If elision is not supported
by the hardware this tunable is set to @samp{0} to avoid retries.

The default value of this tunable is @samp{3}.
@end deftp

@deftp Tunable glibc.elision.skip_trylock_internal_abort
The @code{glibc.elision.skip_trylock_internal_abort} tunable sets how many
times the thread should avoid trying the lock if a transaction aborted due to
reasons other than a different thread's memory accesses.  Expressed in number
of try lock attempts.

The default value of this tunable is @samp{3}.
@end deftp

@node POSIX Thread Tunables
@section POSIX Thread Tunables
@cindex pthread mutex tunables
@cindex thread mutex tunables
@cindex mutex tunables
@cindex tunables thread mutex

@deftp {Tunable namespace} glibc.pthread
The behavior of POSIX threads can be tuned to gain performance improvements
according to specific hardware capabilities and workload characteristics by
setting the following tunables in the @code{pthread} namespace:
@end deftp

@deftp Tunable glibc.pthread.mutex_spin_count
The @code{glibc.pthread.mutex_spin_count} tunable sets the maximum number of times
a thread should spin on the lock before calling into the kernel to block.
Adaptive spin is used for mutexes initialized with the
@code{PTHREAD_MUTEX_ADAPTIVE_NP} GNU extension.  It affects both
@code{pthread_mutex_lock} and @code{pthread_mutex_timedlock}.

The thread spins until either the maximum spin count is reached or the lock
is acquired.

The default value of this tunable is @samp{100}.
@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.cpu
Behavior of @theglibc{} can be tuned to assume specific hardware capabilities
by setting the following tunables in the @code{cpu} namespace:
@end deftp

@deftp Tunable glibc.cpu.hwcap_mask
This tunable supersedes the @env{LD_HWCAP_MASK} environment variable and is
identical in features.

The @code{AT_HWCAP} key in the Auxiliary Vector specifies instruction set
extensions available in the processor at runtime for some architectures.  The
@code{glibc.cpu.hwcap_mask} tunable allows the user to mask out those
capabilities at runtime, thus disabling use of those extensions.
@end deftp

@deftp Tunable glibc.cpu.hwcaps
The @code{glibc.cpu.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.cpu.cached_memopt
The @code{glibc.cpu.cached_memopt=[0|1]} tunable allows the user to
enable optimizations recommended for cacheable memory.  If set to
@code{1}, @theglibc{} assumes that the process memory image consists
of cacheable (non-device) memory only.  The default, @code{0},
indicates that the process may use device memory.

This tunable is specific to powerpc, powerpc64 and powerpc64le.
@end deftp

@deftp Tunable glibc.cpu.name
The @code{glibc.cpu.name=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}, @code{ares}, @code{emag}, @code{kunpeng}.

This tunable is specific to aarch64.
@end deftp

@deftp Tunable glibc.cpu.x86_data_cache_size
The @code{glibc.cpu.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.cpu.x86_shared_cache_size
The @code{glibc.cpu.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.cpu.x86_non_temporal_threshold
The @code{glibc.cpu.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

@deftp Tunable glibc.cpu.x86_ibt
The @code{glibc.cpu.x86_ibt} tunable allows the user to control how
indirect branch tracking (IBT) should be enabled.  Accepted values are
@code{on}, @code{off}, and @code{permissive}.  @code{on} always turns
on IBT regardless of whether IBT is enabled in the executable and its
dependent shared libraries.  @code{off} always turns off IBT regardless
of whether IBT is enabled in the executable and its dependent shared
libraries.  @code{permissive} is the same as the default which disables
IBT on non-CET executables and shared libraries.

This tunable is specific to i386 and x86-64.
@end deftp

@deftp Tunable glibc.cpu.x86_shstk
The @code{glibc.cpu.x86_shstk} tunable allows the user to control how
the shadow stack (SHSTK) should be enabled.  Accepted values are
@code{on}, @code{off}, and @code{permissive}.  @code{on} always turns on
SHSTK regardless of whether SHSTK is enabled in the executable and its
dependent shared libraries.  @code{off} always turns off SHSTK regardless
of whether SHSTK is enabled in the executable and its dependent shared
libraries.  @code{permissive} changes how dlopen works on non-CET shared
libraries.  By default, when SHSTK is enabled, dlopening a non-CET shared
library returns an error.  With @code{permissive}, it turns off SHSTK
instead.

This tunable is specific to i386 and x86-64.
@end deftp