]>
Commit | Line | Data |
---|---|---|
b31b4d6a SP |
1 | @node Tunables |
2 | @c @node Tunables, , Internal Probes, Top | |
3 | @c %MENU% Tunable switches to alter libc internal behavior | |
4 | @chapter Tunables | |
5 | @cindex tunables | |
6 | ||
7 | @dfn{Tunables} are a feature in @theglibc{} that allows application authors and | |
8 | distribution maintainers to alter the runtime library behavior to match | |
9 | their workload. These are implemented as a set of switches that may be | |
10 | modified in different ways. The current default method to do this is via | |
11 | the @env{GLIBC_TUNABLES} environment variable by setting it to a string | |
12 | of colon-separated @var{name}=@var{value} pairs. For example, the following | |
13 | example enables malloc checking and sets the malloc trim threshold to 128 | |
14 | bytes: | |
15 | ||
16 | @example | |
17 | GLIBC_TUNABLES=glibc.malloc.trim_threshold=128:glibc.malloc.check=3 | |
18 | export GLIBC_TUNABLES | |
19 | @end example | |
20 | ||
21 | Tunables are not part of the @glibcadj{} stable ABI, and they are | |
22 | subject to change or removal across releases. Additionally, the method to | |
23 | modify tunable values may change between releases and across distributions. | |
24 | It is possible to implement multiple `frontends' for the tunables allowing | |
25 | distributions to choose their preferred method at build time. | |
26 | ||
27 | Finally, the set of tunables available may vary between distributions as | |
28 | the tunables feature allows distributions to add their own tunables under | |
29 | their own namespace. | |
30 | ||
31 | @menu | |
32 | * Tunable names:: The structure of a tunable name | |
33 | * Memory Allocation Tunables:: Tunables in the memory allocation subsystem | |
07ed18d2 | 34 | * Elision Tunables:: Tunables in elision subsystem |
6310e6be | 35 | * POSIX Thread Tunables:: Tunables in the POSIX thread subsystem |
ea9b0ecb SP |
36 | * Hardware Capability Tunables:: Tunables that modify the hardware |
37 | capabilities seen by @theglibc{} | |
b31b4d6a SP |
38 | @end menu |
39 | ||
40 | @node Tunable names | |
41 | @section Tunable names | |
42 | @cindex Tunable names | |
43 | @cindex Tunable namespaces | |
44 | ||
45 | A tunable name is split into three components, a top namespace, a tunable | |
46 | namespace and the tunable name. The top namespace for tunables implemented in | |
47 | @theglibc{} is @code{glibc}. Distributions that choose to add custom tunables | |
48 | in their maintained versions of @theglibc{} may choose to do so under their own | |
49 | top namespace. | |
50 | ||
51 | The tunable namespace is a logical grouping of tunables in a single | |
52 | module. This currently holds no special significance, although that may | |
53 | change in the future. | |
54 | ||
55 | The tunable name is the actual name of the tunable. It is possible that | |
56 | different tunable namespaces may have tunables within them that have the | |
57 | same name, likewise for top namespaces. Hence, we only support | |
58 | identification of tunables by their full name, i.e. with the top | |
59 | namespace, tunable namespace and tunable name, separated by periods. | |
60 | ||
61 | @node Memory Allocation Tunables | |
62 | @section Memory Allocation Tunables | |
63 | @cindex memory allocation tunables | |
64 | @cindex malloc tunables | |
65 | @cindex tunables, malloc | |
66 | ||
67 | @deftp {Tunable namespace} glibc.malloc | |
68 | Memory allocation behavior can be modified by setting any of the | |
69 | following tunables in the @code{malloc} namespace: | |
70 | @end deftp | |
71 | ||
72 | @deftp Tunable glibc.malloc.check | |
73 | This tunable supersedes the @env{MALLOC_CHECK_} environment variable and is | |
74 | identical in features. | |
75 | ||
ec2c1fce FW |
76 | Setting this tunable to a non-zero value enables a special (less |
77 | efficient) memory allocator for the malloc family of functions that is | |
78 | designed to be tolerant against simple errors such as double calls of | |
79 | free with the same argument, or overruns of a single byte (off-by-one | |
80 | bugs). Not all such errors can be protected against, however, and memory | |
81 | leaks can result. Any detected heap corruption results in immediate | |
82 | termination of the process. | |
b31b4d6a SP |
83 | |
84 | Like @env{MALLOC_CHECK_}, @code{glibc.malloc.check} has a problem in that it | |
85 | diverges from normal program behavior by writing to @code{stderr}, which could | |
86 | by exploited in SUID and SGID binaries. Therefore, @code{glibc.malloc.check} | |
87 | is disabled by default for SUID and SGID binaries. This can be enabled again | |
88 | by the system administrator by adding a file @file{/etc/suid-debug}; the | |
89 | content of the file could be anything or even empty. | |
90 | @end deftp | |
91 | ||
92 | @deftp Tunable glibc.malloc.top_pad | |
93 | This tunable supersedes the @env{MALLOC_TOP_PAD_} environment variable and is | |
94 | identical in features. | |
95 | ||
96 | This tunable determines the amount of extra memory in bytes to obtain from the | |
97 | system when any of the arenas need to be extended. It also specifies the | |
98 | number of bytes to retain when shrinking any of the arenas. This provides the | |
99 | necessary hysteresis in heap size such that excessive amounts of system calls | |
100 | can be avoided. | |
101 | ||
102 | The default value of this tunable is @samp{0}. | |
103 | @end deftp | |
104 | ||
105 | @deftp Tunable glibc.malloc.perturb | |
106 | This tunable supersedes the @env{MALLOC_PERTURB_} environment variable and is | |
107 | identical in features. | |
108 | ||
109 | If set to a non-zero value, memory blocks are initialized with values depending | |
110 | on some low order bits of this tunable when they are allocated (except when | |
111 | allocated by calloc) and freed. This can be used to debug the use of | |
112 | uninitialized or freed heap memory. Note that this option does not guarantee | |
113 | that the freed block will have any specific values. It only guarantees that the | |
114 | content the block had before it was freed will be overwritten. | |
115 | ||
116 | The default value of this tunable is @samp{0}. | |
117 | @end deftp | |
118 | ||
119 | @deftp Tunable glibc.malloc.mmap_threshold | |
120 | This tunable supersedes the @env{MALLOC_MMAP_THRESHOLD_} environment variable | |
121 | and is identical in features. | |
122 | ||
123 | When this tunable is set, all chunks larger than this value in bytes are | |
124 | allocated outside the normal heap, using the @code{mmap} system call. This way | |
125 | it is guaranteed that the memory for these chunks can be returned to the system | |
126 | on @code{free}. Note that requests smaller than this threshold might still be | |
127 | allocated via @code{mmap}. | |
128 | ||
129 | If this tunable is not set, the default value is set to @samp{131072} bytes and | |
130 | the threshold is adjusted dynamically to suit the allocation patterns of the | |
131 | program. If the tunable is set, the dynamic adjustment is disabled and the | |
132 | value is set as static. | |
133 | @end deftp | |
134 | ||
135 | @deftp Tunable glibc.malloc.trim_threshold | |
136 | This tunable supersedes the @env{MALLOC_TRIM_THRESHOLD_} environment variable | |
137 | and is identical in features. | |
138 | ||
139 | The value of this tunable is the minimum size (in bytes) of the top-most, | |
140 | releasable chunk in an arena that will trigger a system call in order to return | |
141 | memory to the system from that arena. | |
142 | ||
143 | If this tunable is not set, the default value is set as 128 KB and the | |
144 | threshold is adjusted dynamically to suit the allocation patterns of the | |
145 | program. If the tunable is set, the dynamic adjustment is disabled and the | |
146 | value is set as static. | |
147 | @end deftp | |
148 | ||
149 | @deftp Tunable glibc.malloc.mmap_max | |
150 | This tunable supersedes the @env{MALLOC_MMAP_MAX_} environment variable and is | |
151 | identical in features. | |
152 | ||
153 | The value of this tunable is maximum number of chunks to allocate with | |
154 | @code{mmap}. Setting this to zero disables all use of @code{mmap}. | |
155 | ||
156 | The default value of this tunable is @samp{65536}. | |
157 | @end deftp | |
158 | ||
159 | @deftp Tunable glibc.malloc.arena_test | |
160 | This tunable supersedes the @env{MALLOC_ARENA_TEST} environment variable and is | |
161 | identical in features. | |
162 | ||
163 | The @code{glibc.malloc.arena_test} tunable specifies the number of arenas that | |
164 | can be created before the test on the limit to the number of arenas is | |
165 | conducted. The value is ignored if @code{glibc.malloc.arena_max} is set. | |
166 | ||
167 | The default value of this tunable is 2 for 32-bit systems and 8 for 64-bit | |
168 | systems. | |
169 | @end deftp | |
170 | ||
171 | @deftp Tunable glibc.malloc.arena_max | |
172 | This tunable supersedes the @env{MALLOC_ARENA_MAX} environment variable and is | |
173 | identical in features. | |
174 | ||
175 | This tunable sets the number of arenas to use in a process regardless of the | |
176 | number of cores in the system. | |
177 | ||
178 | The default value of this tunable is @code{0}, meaning that the limit on the | |
179 | number of arenas is determined by the number of CPU cores online. For 32-bit | |
180 | systems the limit is twice the number of cores online and on 64-bit systems, it | |
181 | is 8 times the number of cores online. | |
182 | @end deftp | |
ea9b0ecb | 183 | |
d5c3fafc DD |
184 | @deftp Tunable glibc.malloc.tcache_max |
185 | The maximum size of a request (in bytes) which may be met via the | |
186 | per-thread cache. The default (and maximum) value is 1032 bytes on | |
187 | 64-bit systems and 516 bytes on 32-bit systems. | |
188 | @end deftp | |
189 | ||
190 | @deftp Tunable glibc.malloc.tcache_count | |
191 | The maximum number of chunks of each size to cache. The default is 7. | |
1f50f2ad | 192 | The upper limit is 65535. If set to zero, the per-thread cache is effectively |
5ad533e8 | 193 | disabled. |
d5c3fafc DD |
194 | |
195 | The approximate maximum overhead of the per-thread cache is thus equal | |
196 | to the number of bins times the chunk count in each bin times the size | |
197 | of each chunk. With defaults, the approximate maximum overhead of the | |
198 | per-thread cache is approximately 236 KB on 64-bit systems and 118 KB | |
199 | on 32-bit systems. | |
200 | @end deftp | |
201 | ||
202 | @deftp Tunable glibc.malloc.tcache_unsorted_limit | |
203 | When the user requests memory and the request cannot be met via the | |
204 | per-thread cache, the arenas are used to meet the request. At this | |
205 | time, additional chunks will be moved from existing arena lists to | |
206 | pre-fill the corresponding cache. While copies from the fastbins, | |
207 | smallbins, and regular bins are bounded and predictable due to the bin | |
208 | sizes, copies from the unsorted bin are not bounded, and incur | |
209 | additional time penalties as they need to be sorted as they're | |
210 | scanned. To make scanning the unsorted list more predictable and | |
211 | bounded, the user may set this tunable to limit the number of chunks | |
212 | that are scanned from the unsorted list while searching for chunks to | |
213 | pre-fill the per-thread cache with. The default, or when set to zero, | |
214 | is no limit. | |
be8aa923 | 215 | @end deftp |
d5c3fafc | 216 | |
07ed18d2 RA |
217 | @node Elision Tunables |
218 | @section Elision Tunables | |
219 | @cindex elision tunables | |
220 | @cindex tunables, elision | |
221 | ||
222 | @deftp {Tunable namespace} glibc.elision | |
223 | Contended locks are usually slow and can lead to performance and scalability | |
224 | issues in multithread code. Lock elision will use memory transactions to under | |
225 | certain conditions, to elide locks and improve performance. | |
226 | Elision behavior can be modified by setting the following tunables in | |
227 | the @code{elision} namespace: | |
228 | @end deftp | |
229 | ||
230 | @deftp Tunable glibc.elision.enable | |
231 | The @code{glibc.elision.enable} tunable enables lock elision if the feature is | |
232 | supported by the hardware. If elision is not supported by the hardware this | |
233 | tunable has no effect. | |
234 | ||
235 | Elision tunables are supported for 64-bit Intel, IBM POWER, and z System | |
236 | architectures. | |
237 | @end deftp | |
238 | ||
239 | @deftp Tunable glibc.elision.skip_lock_busy | |
240 | The @code{glibc.elision.skip_lock_busy} tunable sets how many times to use a | |
241 | non-transactional lock after a transactional failure has occurred because the | |
242 | lock is already acquired. Expressed in number of lock acquisition attempts. | |
243 | ||
244 | The default value of this tunable is @samp{3}. | |
245 | @end deftp | |
246 | ||
247 | @deftp Tunable glibc.elision.skip_lock_internal_abort | |
248 | The @code{glibc.elision.skip_lock_internal_abort} tunable sets how many times | |
249 | the thread should avoid using elision if a transaction aborted for any reason | |
250 | other than a different thread's memory accesses. Expressed in number of lock | |
251 | acquisition attempts. | |
252 | ||
253 | The default value of this tunable is @samp{3}. | |
254 | @end deftp | |
255 | ||
256 | @deftp Tunable glibc.elision.skip_lock_after_retries | |
257 | The @code{glibc.elision.skip_lock_after_retries} tunable sets how many times | |
258 | to try to elide a lock with transactions, that only failed due to a different | |
259 | thread's memory accesses, before falling back to regular lock. | |
260 | Expressed in number of lock elision attempts. | |
261 | ||
262 | This tunable is supported only on IBM POWER, and z System architectures. | |
263 | ||
264 | The default value of this tunable is @samp{3}. | |
265 | @end deftp | |
266 | ||
267 | @deftp Tunable glibc.elision.tries | |
268 | The @code{glibc.elision.tries} sets how many times to retry elision if there is | |
269 | chance for the transaction to finish execution e.g., it wasn't | |
270 | aborted due to the lock being already acquired. If elision is not supported | |
271 | by the hardware this tunable is set to @samp{0} to avoid retries. | |
272 | ||
273 | The default value of this tunable is @samp{3}. | |
274 | @end deftp | |
275 | ||
276 | @deftp Tunable glibc.elision.skip_trylock_internal_abort | |
277 | The @code{glibc.elision.skip_trylock_internal_abort} tunable sets how many | |
278 | times the thread should avoid trying the lock if a transaction aborted due to | |
279 | reasons other than a different thread's memory accesses. Expressed in number | |
280 | of try lock attempts. | |
281 | ||
282 | The default value of this tunable is @samp{3}. | |
283 | @end deftp | |
284 | ||
6310e6be KW |
285 | @node POSIX Thread Tunables |
286 | @section POSIX Thread Tunables | |
287 | @cindex pthread mutex tunables | |
288 | @cindex thread mutex tunables | |
289 | @cindex mutex tunables | |
290 | @cindex tunables thread mutex | |
291 | ||
292 | @deftp {Tunable namespace} glibc.pthread | |
293 | The behavior of POSIX threads can be tuned to gain performance improvements | |
294 | according to specific hardware capabilities and workload characteristics by | |
295 | setting the following tunables in the @code{pthread} namespace: | |
296 | @end deftp | |
297 | ||
298 | @deftp Tunable glibc.pthread.mutex_spin_count | |
299 | The @code{glibc.pthread.mutex_spin_count} tunable sets the maximum number of times | |
300 | a thread should spin on the lock before calling into the kernel to block. | |
301 | Adaptive spin is used for mutexes initialized with the | |
302 | @code{PTHREAD_MUTEX_ADAPTIVE_NP} GNU extension. It affects both | |
303 | @code{pthread_mutex_lock} and @code{pthread_mutex_timedlock}. | |
304 | ||
305 | The thread spins until either the maximum spin count is reached or the lock | |
306 | is acquired. | |
307 | ||
308 | The default value of this tunable is @samp{100}. | |
309 | @end deftp | |
310 | ||
ea9b0ecb SP |
311 | @node Hardware Capability Tunables |
312 | @section Hardware Capability Tunables | |
313 | @cindex hardware capability tunables | |
314 | @cindex hwcap tunables | |
315 | @cindex tunables, hwcap | |
03feacb5 L |
316 | @cindex hwcaps tunables |
317 | @cindex tunables, hwcaps | |
905947c3 L |
318 | @cindex data_cache_size tunables |
319 | @cindex tunables, data_cache_size | |
320 | @cindex shared_cache_size tunables | |
321 | @cindex tunables, shared_cache_size | |
322 | @cindex non_temporal_threshold tunables | |
323 | @cindex tunables, non_temporal_threshold | |
ea9b0ecb | 324 | |
dce452dc | 325 | @deftp {Tunable namespace} glibc.cpu |
ea9b0ecb | 326 | Behavior of @theglibc{} can be tuned to assume specific hardware capabilities |
dce452dc | 327 | by setting the following tunables in the @code{cpu} namespace: |
ea9b0ecb SP |
328 | @end deftp |
329 | ||
dce452dc | 330 | @deftp Tunable glibc.cpu.hwcap_mask |
ea9b0ecb SP |
331 | This tunable supersedes the @env{LD_HWCAP_MASK} environment variable and is |
332 | identical in features. | |
333 | ||
28c3f14f | 334 | The @code{AT_HWCAP} key in the Auxiliary Vector specifies instruction set |
ea9b0ecb | 335 | extensions available in the processor at runtime for some architectures. The |
dce452dc | 336 | @code{glibc.cpu.hwcap_mask} tunable allows the user to mask out those |
ea9b0ecb SP |
337 | capabilities at runtime, thus disabling use of those extensions. |
338 | @end deftp | |
905947c3 | 339 | |
dce452dc SP |
340 | @deftp Tunable glibc.cpu.hwcaps |
341 | The @code{glibc.cpu.hwcaps=-xxx,yyy,-zzz...} tunable allows the user to | |
905947c3 L |
342 | enable CPU/ARCH feature @code{yyy}, disable CPU/ARCH feature @code{xxx} |
343 | and @code{zzz} where the feature name is case-sensitive and has to match | |
344 | the ones in @code{sysdeps/x86/cpu-features.h}. | |
345 | ||
346 | This tunable is specific to i386 and x86-64. | |
347 | @end deftp | |
348 | ||
dce452dc SP |
349 | @deftp Tunable glibc.cpu.cached_memopt |
350 | The @code{glibc.cpu.cached_memopt=[0|1]} tunable allows the user to | |
c9cd7b0c AZ |
351 | enable optimizations recommended for cacheable memory. If set to |
352 | @code{1}, @theglibc{} assumes that the process memory image consists | |
353 | of cacheable (non-device) memory only. The default, @code{0}, | |
354 | indicates that the process may use device memory. | |
355 | ||
356 | This tunable is specific to powerpc, powerpc64 and powerpc64le. | |
357 | @end deftp | |
358 | ||
dce452dc SP |
359 | @deftp Tunable glibc.cpu.name |
360 | The @code{glibc.cpu.name=xxx} tunable allows the user to tell @theglibc{} to | |
28cfa3a4 | 361 | assume that the CPU is @code{xxx} where xxx may have one of these values: |
9c9ec581 | 362 | @code{generic}, @code{falkor}, @code{thunderxt88}, @code{thunderx2t99}, |
07c3d1ec | 363 | @code{thunderx2t99p1}, @code{ares}, @code{emag}. |
28cfa3a4 SP |
364 | |
365 | This tunable is specific to aarch64. | |
366 | @end deftp | |
367 | ||
dce452dc SP |
368 | @deftp Tunable glibc.cpu.x86_data_cache_size |
369 | The @code{glibc.cpu.x86_data_cache_size} tunable allows the user to set | |
905947c3 L |
370 | data cache size in bytes for use in memory and string routines. |
371 | ||
372 | This tunable is specific to i386 and x86-64. | |
373 | @end deftp | |
374 | ||
dce452dc SP |
375 | @deftp Tunable glibc.cpu.x86_shared_cache_size |
376 | The @code{glibc.cpu.x86_shared_cache_size} tunable allows the user to | |
905947c3 L |
377 | set shared cache size in bytes for use in memory and string routines. |
378 | @end deftp | |
379 | ||
dce452dc SP |
380 | @deftp Tunable glibc.cpu.x86_non_temporal_threshold |
381 | The @code{glibc.cpu.x86_non_temporal_threshold} tunable allows the user | |
905947c3 L |
382 | to set threshold in bytes for non temporal store. |
383 | ||
384 | This tunable is specific to i386 and x86-64. | |
385 | @end deftp | |
6d90776d | 386 | |
dce452dc SP |
387 | @deftp Tunable glibc.cpu.x86_ibt |
388 | The @code{glibc.cpu.x86_ibt} tunable allows the user to control how | |
6d90776d L |
389 | indirect branch tracking (IBT) should be enabled. Accepted values are |
390 | @code{on}, @code{off}, and @code{permissive}. @code{on} always turns | |
391 | on IBT regardless of whether IBT is enabled in the executable and its | |
392 | dependent shared libraries. @code{off} always turns off IBT regardless | |
393 | of whether IBT is enabled in the executable and its dependent shared | |
394 | libraries. @code{permissive} is the same as the default which disables | |
395 | IBT on non-CET executables and shared libraries. | |
396 | ||
397 | This tunable is specific to i386 and x86-64. | |
398 | @end deftp | |
399 | ||
dce452dc SP |
400 | @deftp Tunable glibc.cpu.x86_shstk |
401 | The @code{glibc.cpu.x86_shstk} tunable allows the user to control how | |
6d90776d L |
402 | the shadow stack (SHSTK) should be enabled. Accepted values are |
403 | @code{on}, @code{off}, and @code{permissive}. @code{on} always turns on | |
404 | SHSTK regardless of whether SHSTK is enabled in the executable and its | |
405 | dependent shared libraries. @code{off} always turns off SHSTK regardless | |
406 | of whether SHSTK is enabled in the executable and its dependent shared | |
407 | libraries. @code{permissive} changes how dlopen works on non-CET shared | |
408 | libraries. By default, when SHSTK is enabled, dlopening a non-CET shared | |
409 | library returns an error. With @code{permissive}, it turns off SHSTK | |
410 | instead. | |
411 | ||
412 | This tunable is specific to i386 and x86-64. | |
413 | @end deftp |