]>
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 | |
bdc674d9 PE |
13 | example enables @code{malloc} checking and sets the @code{malloc} |
14 | trim threshold to 128 | |
b31b4d6a SP |
15 | bytes: |
16 | ||
17 | @example | |
18 | GLIBC_TUNABLES=glibc.malloc.trim_threshold=128:glibc.malloc.check=3 | |
19 | export GLIBC_TUNABLES | |
20 | @end example | |
21 | ||
22 | Tunables are not part of the @glibcadj{} stable ABI, and they are | |
23 | subject to change or removal across releases. Additionally, the method to | |
24 | modify tunable values may change between releases and across distributions. | |
25 | It is possible to implement multiple `frontends' for the tunables allowing | |
26 | distributions to choose their preferred method at build time. | |
27 | ||
28 | Finally, the set of tunables available may vary between distributions as | |
29 | the tunables feature allows distributions to add their own tunables under | |
30 | their own namespace. | |
31 | ||
86f65dff L |
32 | Passing @option{--list-tunables} to the dynamic loader to print all |
33 | tunables with minimum and maximum values: | |
34 | ||
35 | @example | |
36 | $ /lib64/ld-linux-x86-64.so.2 --list-tunables | |
37 | glibc.rtld.nns: 0x4 (min: 0x1, max: 0x10) | |
317f1c0a | 38 | glibc.elision.skip_lock_after_retries: 3 (min: 0, max: 2147483647) |
86f65dff L |
39 | glibc.malloc.trim_threshold: 0x0 (min: 0x0, max: 0xffffffffffffffff) |
40 | glibc.malloc.perturb: 0 (min: 0, max: 255) | |
41 | glibc.cpu.x86_shared_cache_size: 0x100000 (min: 0x0, max: 0xffffffffffffffff) | |
317f1c0a L |
42 | glibc.pthread.rseq: 1 (min: 0, max: 1) |
43 | glibc.cpu.prefer_map_32bit_exec: 0 (min: 0, max: 1) | |
86f65dff | 44 | glibc.mem.tagging: 0 (min: 0, max: 255) |
317f1c0a | 45 | glibc.elision.tries: 3 (min: 0, max: 2147483647) |
86f65dff | 46 | glibc.elision.enable: 0 (min: 0, max: 1) |
317f1c0a L |
47 | glibc.malloc.hugetlb: 0x0 (min: 0x0, max: 0xffffffffffffffff) |
48 | glibc.cpu.x86_rep_movsb_threshold: 0x2000 (min: 0x100, max: 0xffffffffffffffff) | |
86f65dff | 49 | glibc.malloc.mxfast: 0x0 (min: 0x0, max: 0xffffffffffffffff) |
317f1c0a L |
50 | glibc.rtld.dynamic_sort: 2 (min: 1, max: 2) |
51 | glibc.elision.skip_lock_busy: 3 (min: 0, max: 2147483647) | |
52 | glibc.malloc.top_pad: 0x20000 (min: 0x0, max: 0xffffffffffffffff) | |
86f65dff | 53 | glibc.cpu.x86_rep_stosb_threshold: 0x800 (min: 0x1, max: 0xffffffffffffffff) |
317f1c0a | 54 | glibc.cpu.x86_non_temporal_threshold: 0xc0000 (min: 0x4040, max: 0xfffffffffffffff) |
86f65dff | 55 | glibc.cpu.x86_shstk: |
317f1c0a | 56 | glibc.pthread.stack_cache_size: 0x2800000 (min: 0x0, max: 0xffffffffffffffff) |
86f65dff | 57 | glibc.cpu.hwcap_mask: 0x6 (min: 0x0, max: 0xffffffffffffffff) |
317f1c0a L |
58 | glibc.malloc.mmap_max: 0 (min: 0, max: 2147483647) |
59 | glibc.elision.skip_trylock_internal_abort: 3 (min: 0, max: 2147483647) | |
86f65dff L |
60 | glibc.malloc.tcache_unsorted_limit: 0x0 (min: 0x0, max: 0xffffffffffffffff) |
61 | glibc.cpu.x86_ibt: | |
62 | glibc.cpu.hwcaps: | |
317f1c0a | 63 | glibc.elision.skip_lock_internal_abort: 3 (min: 0, max: 2147483647) |
86f65dff L |
64 | glibc.malloc.arena_max: 0x0 (min: 0x1, max: 0xffffffffffffffff) |
65 | glibc.malloc.mmap_threshold: 0x0 (min: 0x0, max: 0xffffffffffffffff) | |
66 | glibc.cpu.x86_data_cache_size: 0x8000 (min: 0x0, max: 0xffffffffffffffff) | |
67 | glibc.malloc.tcache_count: 0x0 (min: 0x0, max: 0xffffffffffffffff) | |
68 | glibc.malloc.arena_test: 0x0 (min: 0x1, max: 0xffffffffffffffff) | |
69 | glibc.pthread.mutex_spin_count: 100 (min: 0, max: 32767) | |
70 | glibc.rtld.optional_static_tls: 0x200 (min: 0x0, max: 0xffffffffffffffff) | |
71 | glibc.malloc.tcache_max: 0x0 (min: 0x0, max: 0xffffffffffffffff) | |
72 | glibc.malloc.check: 0 (min: 0, max: 3) | |
73 | @end example | |
74 | ||
b31b4d6a SP |
75 | @menu |
76 | * Tunable names:: The structure of a tunable name | |
77 | * Memory Allocation Tunables:: Tunables in the memory allocation subsystem | |
0c7b002f | 78 | * Dynamic Linking Tunables:: Tunables in the dynamic linking subsystem |
07ed18d2 | 79 | * Elision Tunables:: Tunables in elision subsystem |
6310e6be | 80 | * POSIX Thread Tunables:: Tunables in the POSIX thread subsystem |
ea9b0ecb SP |
81 | * Hardware Capability Tunables:: Tunables that modify the hardware |
82 | capabilities seen by @theglibc{} | |
26450d04 RE |
83 | * Memory Related Tunables:: Tunables that control the use of memory by |
84 | @theglibc{}. | |
31be941e SK |
85 | * gmon Tunables:: Tunables that control the gmon profiler, used in |
86 | conjunction with gprof | |
87 | ||
b31b4d6a SP |
88 | @end menu |
89 | ||
90 | @node Tunable names | |
91 | @section Tunable names | |
92 | @cindex Tunable names | |
93 | @cindex Tunable namespaces | |
94 | ||
95 | A tunable name is split into three components, a top namespace, a tunable | |
96 | namespace and the tunable name. The top namespace for tunables implemented in | |
97 | @theglibc{} is @code{glibc}. Distributions that choose to add custom tunables | |
98 | in their maintained versions of @theglibc{} may choose to do so under their own | |
99 | top namespace. | |
100 | ||
101 | The tunable namespace is a logical grouping of tunables in a single | |
102 | module. This currently holds no special significance, although that may | |
103 | change in the future. | |
104 | ||
105 | The tunable name is the actual name of the tunable. It is possible that | |
106 | different tunable namespaces may have tunables within them that have the | |
107 | same name, likewise for top namespaces. Hence, we only support | |
108 | identification of tunables by their full name, i.e. with the top | |
109 | namespace, tunable namespace and tunable name, separated by periods. | |
110 | ||
111 | @node Memory Allocation Tunables | |
112 | @section Memory Allocation Tunables | |
113 | @cindex memory allocation tunables | |
114 | @cindex malloc tunables | |
115 | @cindex tunables, malloc | |
116 | ||
117 | @deftp {Tunable namespace} glibc.malloc | |
118 | Memory allocation behavior can be modified by setting any of the | |
119 | following tunables in the @code{malloc} namespace: | |
120 | @end deftp | |
121 | ||
122 | @deftp Tunable glibc.malloc.check | |
123 | This tunable supersedes the @env{MALLOC_CHECK_} environment variable and is | |
2d2d9f2b | 124 | identical in features. This tunable has no effect by default and needs the |
fb1621a8 | 125 | debug library @file{libc_malloc_debug} to be preloaded using the |
2d2d9f2b | 126 | @code{LD_PRELOAD} environment variable. |
b31b4d6a | 127 | |
83e55c98 | 128 | Setting this tunable to a non-zero value less than 4 enables a special (less |
bdc674d9 | 129 | efficient) memory allocator for the @code{malloc} family of functions that is |
ec2c1fce FW |
130 | designed to be tolerant against simple errors such as double calls of |
131 | free with the same argument, or overruns of a single byte (off-by-one | |
132 | bugs). Not all such errors can be protected against, however, and memory | |
133 | leaks can result. Any detected heap corruption results in immediate | |
134 | termination of the process. | |
b31b4d6a SP |
135 | |
136 | Like @env{MALLOC_CHECK_}, @code{glibc.malloc.check} has a problem in that it | |
137 | diverges from normal program behavior by writing to @code{stderr}, which could | |
138 | by exploited in SUID and SGID binaries. Therefore, @code{glibc.malloc.check} | |
139 | is disabled by default for SUID and SGID binaries. This can be enabled again | |
140 | by the system administrator by adding a file @file{/etc/suid-debug}; the | |
141 | content of the file could be anything or even empty. | |
142 | @end deftp | |
143 | ||
144 | @deftp Tunable glibc.malloc.top_pad | |
145 | This tunable supersedes the @env{MALLOC_TOP_PAD_} environment variable and is | |
146 | identical in features. | |
147 | ||
148 | This tunable determines the amount of extra memory in bytes to obtain from the | |
149 | system when any of the arenas need to be extended. It also specifies the | |
150 | number of bytes to retain when shrinking any of the arenas. This provides the | |
151 | necessary hysteresis in heap size such that excessive amounts of system calls | |
152 | can be avoided. | |
153 | ||
6c93af6b | 154 | The default value of this tunable is @samp{131072} (128 KB). |
b31b4d6a SP |
155 | @end deftp |
156 | ||
157 | @deftp Tunable glibc.malloc.perturb | |
158 | This tunable supersedes the @env{MALLOC_PERTURB_} environment variable and is | |
159 | identical in features. | |
160 | ||
161 | If set to a non-zero value, memory blocks are initialized with values depending | |
162 | on some low order bits of this tunable when they are allocated (except when | |
bdc674d9 | 163 | allocated by @code{calloc}) and freed. This can be used to debug the use of |
b31b4d6a SP |
164 | uninitialized or freed heap memory. Note that this option does not guarantee |
165 | that the freed block will have any specific values. It only guarantees that the | |
166 | content the block had before it was freed will be overwritten. | |
167 | ||
168 | The default value of this tunable is @samp{0}. | |
169 | @end deftp | |
170 | ||
171 | @deftp Tunable glibc.malloc.mmap_threshold | |
172 | This tunable supersedes the @env{MALLOC_MMAP_THRESHOLD_} environment variable | |
173 | and is identical in features. | |
174 | ||
175 | When this tunable is set, all chunks larger than this value in bytes are | |
176 | allocated outside the normal heap, using the @code{mmap} system call. This way | |
177 | it is guaranteed that the memory for these chunks can be returned to the system | |
178 | on @code{free}. Note that requests smaller than this threshold might still be | |
179 | allocated via @code{mmap}. | |
180 | ||
181 | If this tunable is not set, the default value is set to @samp{131072} bytes and | |
182 | the threshold is adjusted dynamically to suit the allocation patterns of the | |
183 | program. If the tunable is set, the dynamic adjustment is disabled and the | |
184 | value is set as static. | |
185 | @end deftp | |
186 | ||
187 | @deftp Tunable glibc.malloc.trim_threshold | |
188 | This tunable supersedes the @env{MALLOC_TRIM_THRESHOLD_} environment variable | |
189 | and is identical in features. | |
190 | ||
191 | The value of this tunable is the minimum size (in bytes) of the top-most, | |
192 | releasable chunk in an arena that will trigger a system call in order to return | |
193 | memory to the system from that arena. | |
194 | ||
195 | If this tunable is not set, the default value is set as 128 KB and the | |
196 | threshold is adjusted dynamically to suit the allocation patterns of the | |
197 | program. If the tunable is set, the dynamic adjustment is disabled and the | |
198 | value is set as static. | |
199 | @end deftp | |
200 | ||
201 | @deftp Tunable glibc.malloc.mmap_max | |
202 | This tunable supersedes the @env{MALLOC_MMAP_MAX_} environment variable and is | |
203 | identical in features. | |
204 | ||
205 | The value of this tunable is maximum number of chunks to allocate with | |
206 | @code{mmap}. Setting this to zero disables all use of @code{mmap}. | |
207 | ||
208 | The default value of this tunable is @samp{65536}. | |
209 | @end deftp | |
210 | ||
211 | @deftp Tunable glibc.malloc.arena_test | |
212 | This tunable supersedes the @env{MALLOC_ARENA_TEST} environment variable and is | |
213 | identical in features. | |
214 | ||
215 | The @code{glibc.malloc.arena_test} tunable specifies the number of arenas that | |
216 | can be created before the test on the limit to the number of arenas is | |
217 | conducted. The value is ignored if @code{glibc.malloc.arena_max} is set. | |
218 | ||
219 | The default value of this tunable is 2 for 32-bit systems and 8 for 64-bit | |
220 | systems. | |
221 | @end deftp | |
222 | ||
223 | @deftp Tunable glibc.malloc.arena_max | |
224 | This tunable supersedes the @env{MALLOC_ARENA_MAX} environment variable and is | |
225 | identical in features. | |
226 | ||
227 | This tunable sets the number of arenas to use in a process regardless of the | |
228 | number of cores in the system. | |
229 | ||
230 | The default value of this tunable is @code{0}, meaning that the limit on the | |
231 | number of arenas is determined by the number of CPU cores online. For 32-bit | |
232 | systems the limit is twice the number of cores online and on 64-bit systems, it | |
233 | is 8 times the number of cores online. | |
234 | @end deftp | |
ea9b0ecb | 235 | |
d5c3fafc DD |
236 | @deftp Tunable glibc.malloc.tcache_max |
237 | The maximum size of a request (in bytes) which may be met via the | |
238 | per-thread cache. The default (and maximum) value is 1032 bytes on | |
239 | 64-bit systems and 516 bytes on 32-bit systems. | |
240 | @end deftp | |
241 | ||
242 | @deftp Tunable glibc.malloc.tcache_count | |
243 | The maximum number of chunks of each size to cache. The default is 7. | |
1f50f2ad | 244 | The upper limit is 65535. If set to zero, the per-thread cache is effectively |
5ad533e8 | 245 | disabled. |
d5c3fafc DD |
246 | |
247 | The approximate maximum overhead of the per-thread cache is thus equal | |
248 | to the number of bins times the chunk count in each bin times the size | |
249 | of each chunk. With defaults, the approximate maximum overhead of the | |
250 | per-thread cache is approximately 236 KB on 64-bit systems and 118 KB | |
251 | on 32-bit systems. | |
252 | @end deftp | |
253 | ||
254 | @deftp Tunable glibc.malloc.tcache_unsorted_limit | |
255 | When the user requests memory and the request cannot be met via the | |
256 | per-thread cache, the arenas are used to meet the request. At this | |
257 | time, additional chunks will be moved from existing arena lists to | |
258 | pre-fill the corresponding cache. While copies from the fastbins, | |
259 | smallbins, and regular bins are bounded and predictable due to the bin | |
260 | sizes, copies from the unsorted bin are not bounded, and incur | |
261 | additional time penalties as they need to be sorted as they're | |
262 | scanned. To make scanning the unsorted list more predictable and | |
263 | bounded, the user may set this tunable to limit the number of chunks | |
264 | that are scanned from the unsorted list while searching for chunks to | |
265 | pre-fill the per-thread cache with. The default, or when set to zero, | |
266 | is no limit. | |
be8aa923 | 267 | @end deftp |
d5c3fafc | 268 | |
c48d92b4 | 269 | @deftp Tunable glibc.malloc.mxfast |
bdc674d9 | 270 | One of the optimizations @code{malloc} uses is to maintain a series of ``fast |
c48d92b4 DD |
271 | bins'' that hold chunks up to a specific size. The default and |
272 | maximum size which may be held this way is 80 bytes on 32-bit systems | |
273 | or 160 bytes on 64-bit systems. Applications which value size over | |
274 | speed may choose to reduce the size of requests which are serviced | |
275 | from fast bins with this tunable. Note that the value specified | |
bdc674d9 | 276 | includes @code{malloc}'s internal overhead, which is normally the size of one |
c48d92b4 DD |
277 | pointer, so add 4 on 32-bit systems or 8 on 64-bit systems to the size |
278 | passed to @code{malloc} for the largest bin size to enable. | |
279 | @end deftp | |
280 | ||
5f6d8d97 AZ |
281 | @deftp Tunable glibc.malloc.hugetlb |
282 | This tunable controls the usage of Huge Pages on @code{malloc} calls. The | |
283 | default value is @code{0}, which disables any additional support on | |
284 | @code{malloc}. | |
285 | ||
286 | Setting its value to @code{1} enables the use of @code{madvise} with | |
287 | @code{MADV_HUGEPAGE} after memory allocation with @code{mmap}. It is enabled | |
288 | only if the system supports Transparent Huge Page (currently only on Linux). | |
98d5fcb8 AZ |
289 | |
290 | Setting its value to @code{2} enables the use of Huge Page directly with | |
291 | @code{mmap} with the use of @code{MAP_HUGETLB} flag. The huge page size | |
292 | to use will be the default one provided by the system. A value larger than | |
293 | @code{2} specifies huge page size, which will be matched against the system | |
294 | supported ones. If provided value is invalid, @code{MAP_HUGETLB} will not | |
295 | be used. | |
5f6d8d97 AZ |
296 | @end deftp |
297 | ||
0c7b002f SN |
298 | @node Dynamic Linking Tunables |
299 | @section Dynamic Linking Tunables | |
300 | @cindex dynamic linking tunables | |
301 | @cindex rtld tunables | |
302 | ||
303 | @deftp {Tunable namespace} glibc.rtld | |
304 | Dynamic linker behavior can be modified by setting the | |
305 | following tunables in the @code{rtld} namespace: | |
306 | @end deftp | |
307 | ||
308 | @deftp Tunable glibc.rtld.nns | |
309 | Sets the number of supported dynamic link namespaces (see @code{dlmopen}). | |
310 | Currently this limit can be set between 1 and 16 inclusive, the default is 4. | |
311 | Each link namespace consumes some memory in all thread, and thus raising the | |
312 | limit will increase the amount of memory each thread uses. Raising the limit | |
17796419 SN |
313 | is useful when your application uses more than 4 dynamic link namespaces as |
314 | created by @code{dlmopen} with an lmid argument of @code{LM_ID_NEWLM}. | |
315 | Dynamic linker audit modules are loaded in their own dynamic link namespaces, | |
316 | but they are not accounted for in @code{glibc.rtld.nns}. They implicitly | |
317 | increase the per-thread memory usage as necessary, so this tunable does | |
318 | not need to be changed to allow many audit modules e.g. via @env{LD_AUDIT}. | |
0c7b002f SN |
319 | @end deftp |
320 | ||
ffb17e7b SN |
321 | @deftp Tunable glibc.rtld.optional_static_tls |
322 | Sets the amount of surplus static TLS in bytes to allocate at program | |
323 | startup. Every thread created allocates this amount of specified surplus | |
324 | static TLS. This is a minimum value and additional space may be allocated | |
325 | for internal purposes including alignment. Optional static TLS is used for | |
326 | optimizing dynamic TLS access for platforms that support such optimizations | |
327 | e.g. TLS descriptors or optimized TLS access for POWER (@code{DT_PPC64_OPT} | |
328 | and @code{DT_PPC_OPT}). In order to make the best use of such optimizations | |
329 | the value should be as many bytes as would be required to hold all TLS | |
330 | variables in all dynamic loaded shared libraries. The value cannot be known | |
331 | by the dynamic loader because it doesn't know the expected set of shared | |
332 | libraries which will be loaded. The existing static TLS space cannot be | |
333 | changed once allocated at process startup. The default allocation of | |
334 | optional static TLS is 512 bytes and is allocated in every thread. | |
335 | @end deftp | |
336 | ||
15a0c573 CLT |
337 | @deftp Tunable glibc.rtld.dynamic_sort |
338 | Sets the algorithm to use for DSO sorting, valid values are @samp{1} and | |
339 | @samp{2}. For value of @samp{1}, an older O(n^3) algorithm is used, which is | |
340 | long time tested, but may have performance issues when dependencies between | |
341 | shared objects contain cycles due to circular dependencies. When set to the | |
342 | value of @samp{2}, a different algorithm is used, which implements a | |
343 | topological sort through depth-first search, and does not exhibit the | |
344 | performance issues of @samp{1}. | |
345 | ||
0884724a | 346 | The default value of this tunable is @samp{2}. |
15a0c573 | 347 | @end deftp |
ffb17e7b | 348 | |
07ed18d2 RA |
349 | @node Elision Tunables |
350 | @section Elision Tunables | |
351 | @cindex elision tunables | |
352 | @cindex tunables, elision | |
353 | ||
354 | @deftp {Tunable namespace} glibc.elision | |
355 | Contended locks are usually slow and can lead to performance and scalability | |
356 | issues in multithread code. Lock elision will use memory transactions to under | |
357 | certain conditions, to elide locks and improve performance. | |
358 | Elision behavior can be modified by setting the following tunables in | |
359 | the @code{elision} namespace: | |
360 | @end deftp | |
361 | ||
362 | @deftp Tunable glibc.elision.enable | |
363 | The @code{glibc.elision.enable} tunable enables lock elision if the feature is | |
364 | supported by the hardware. If elision is not supported by the hardware this | |
365 | tunable has no effect. | |
366 | ||
367 | Elision tunables are supported for 64-bit Intel, IBM POWER, and z System | |
368 | architectures. | |
369 | @end deftp | |
370 | ||
371 | @deftp Tunable glibc.elision.skip_lock_busy | |
372 | The @code{glibc.elision.skip_lock_busy} tunable sets how many times to use a | |
373 | non-transactional lock after a transactional failure has occurred because the | |
374 | lock is already acquired. Expressed in number of lock acquisition attempts. | |
375 | ||
376 | The default value of this tunable is @samp{3}. | |
377 | @end deftp | |
378 | ||
379 | @deftp Tunable glibc.elision.skip_lock_internal_abort | |
380 | The @code{glibc.elision.skip_lock_internal_abort} tunable sets how many times | |
381 | the thread should avoid using elision if a transaction aborted for any reason | |
382 | other than a different thread's memory accesses. Expressed in number of lock | |
383 | acquisition attempts. | |
384 | ||
385 | The default value of this tunable is @samp{3}. | |
386 | @end deftp | |
387 | ||
388 | @deftp Tunable glibc.elision.skip_lock_after_retries | |
389 | The @code{glibc.elision.skip_lock_after_retries} tunable sets how many times | |
390 | to try to elide a lock with transactions, that only failed due to a different | |
391 | thread's memory accesses, before falling back to regular lock. | |
392 | Expressed in number of lock elision attempts. | |
393 | ||
394 | This tunable is supported only on IBM POWER, and z System architectures. | |
395 | ||
396 | The default value of this tunable is @samp{3}. | |
397 | @end deftp | |
398 | ||
399 | @deftp Tunable glibc.elision.tries | |
400 | The @code{glibc.elision.tries} sets how many times to retry elision if there is | |
401 | chance for the transaction to finish execution e.g., it wasn't | |
402 | aborted due to the lock being already acquired. If elision is not supported | |
403 | by the hardware this tunable is set to @samp{0} to avoid retries. | |
404 | ||
405 | The default value of this tunable is @samp{3}. | |
406 | @end deftp | |
407 | ||
408 | @deftp Tunable glibc.elision.skip_trylock_internal_abort | |
409 | The @code{glibc.elision.skip_trylock_internal_abort} tunable sets how many | |
410 | times the thread should avoid trying the lock if a transaction aborted due to | |
411 | reasons other than a different thread's memory accesses. Expressed in number | |
412 | of try lock attempts. | |
413 | ||
414 | The default value of this tunable is @samp{3}. | |
415 | @end deftp | |
416 | ||
6310e6be KW |
417 | @node POSIX Thread Tunables |
418 | @section POSIX Thread Tunables | |
419 | @cindex pthread mutex tunables | |
420 | @cindex thread mutex tunables | |
421 | @cindex mutex tunables | |
422 | @cindex tunables thread mutex | |
423 | ||
424 | @deftp {Tunable namespace} glibc.pthread | |
425 | The behavior of POSIX threads can be tuned to gain performance improvements | |
426 | according to specific hardware capabilities and workload characteristics by | |
427 | setting the following tunables in the @code{pthread} namespace: | |
428 | @end deftp | |
429 | ||
430 | @deftp Tunable glibc.pthread.mutex_spin_count | |
431 | The @code{glibc.pthread.mutex_spin_count} tunable sets the maximum number of times | |
432 | a thread should spin on the lock before calling into the kernel to block. | |
433 | Adaptive spin is used for mutexes initialized with the | |
434 | @code{PTHREAD_MUTEX_ADAPTIVE_NP} GNU extension. It affects both | |
435 | @code{pthread_mutex_lock} and @code{pthread_mutex_timedlock}. | |
436 | ||
437 | The thread spins until either the maximum spin count is reached or the lock | |
438 | is acquired. | |
439 | ||
440 | The default value of this tunable is @samp{100}. | |
441 | @end deftp | |
442 | ||
dd45734e FW |
443 | @deftp Tunable glibc.pthread.stack_cache_size |
444 | This tunable configures the maximum size of the stack cache. Once the | |
445 | stack cache exceeds this size, unused thread stacks are returned to | |
446 | the kernel, to bring the cache size below this limit. | |
447 | ||
448 | The value is measured in bytes. The default is @samp{41943040} | |
449 | (fourty mibibytes). | |
450 | @end deftp | |
451 | ||
e3e58982 FW |
452 | @deftp Tunable glibc.pthread.rseq |
453 | The @code{glibc.pthread.rseq} tunable can be set to @samp{0}, to disable | |
454 | restartable sequences support in @theglibc{}. This enables applications | |
455 | to perform direct restartable sequence registration with the kernel. | |
456 | The default is @samp{1}, which means that @theglibc{} performs | |
457 | registration on behalf of the application. | |
458 | ||
459 | Restartable sequences are a Linux-specific extension. | |
460 | @end deftp | |
461 | ||
ea9b0ecb SP |
462 | @node Hardware Capability Tunables |
463 | @section Hardware Capability Tunables | |
464 | @cindex hardware capability tunables | |
465 | @cindex hwcap tunables | |
466 | @cindex tunables, hwcap | |
03feacb5 L |
467 | @cindex hwcaps tunables |
468 | @cindex tunables, hwcaps | |
905947c3 L |
469 | @cindex data_cache_size tunables |
470 | @cindex tunables, data_cache_size | |
471 | @cindex shared_cache_size tunables | |
472 | @cindex tunables, shared_cache_size | |
473 | @cindex non_temporal_threshold tunables | |
474 | @cindex tunables, non_temporal_threshold | |
ea9b0ecb | 475 | |
dce452dc | 476 | @deftp {Tunable namespace} glibc.cpu |
ea9b0ecb | 477 | Behavior of @theglibc{} can be tuned to assume specific hardware capabilities |
dce452dc | 478 | by setting the following tunables in the @code{cpu} namespace: |
ea9b0ecb SP |
479 | @end deftp |
480 | ||
dce452dc | 481 | @deftp Tunable glibc.cpu.hwcap_mask |
ea9b0ecb SP |
482 | This tunable supersedes the @env{LD_HWCAP_MASK} environment variable and is |
483 | identical in features. | |
484 | ||
28c3f14f | 485 | The @code{AT_HWCAP} key in the Auxiliary Vector specifies instruction set |
ea9b0ecb | 486 | extensions available in the processor at runtime for some architectures. The |
dce452dc | 487 | @code{glibc.cpu.hwcap_mask} tunable allows the user to mask out those |
ea9b0ecb SP |
488 | capabilities at runtime, thus disabling use of those extensions. |
489 | @end deftp | |
905947c3 | 490 | |
dce452dc SP |
491 | @deftp Tunable glibc.cpu.hwcaps |
492 | The @code{glibc.cpu.hwcaps=-xxx,yyy,-zzz...} tunable allows the user to | |
905947c3 L |
493 | enable CPU/ARCH feature @code{yyy}, disable CPU/ARCH feature @code{xxx} |
494 | and @code{zzz} where the feature name is case-sensitive and has to match | |
d976d44a | 495 | the ones in @code{sysdeps/x86/include/cpu-features.h}. |
905947c3 | 496 | |
41f67ccb SL |
497 | On s390x, the supported HWCAP and STFLE features can be found in |
498 | @code{sysdeps/s390/cpu-features.c}. In addition the user can also set | |
499 | a CPU arch-level like @code{z13} instead of single HWCAP and STFLE features. | |
500 | ||
501 | This tunable is specific to i386, x86-64 and s390x. | |
905947c3 L |
502 | @end deftp |
503 | ||
dce452dc SP |
504 | @deftp Tunable glibc.cpu.cached_memopt |
505 | The @code{glibc.cpu.cached_memopt=[0|1]} tunable allows the user to | |
c9cd7b0c AZ |
506 | enable optimizations recommended for cacheable memory. If set to |
507 | @code{1}, @theglibc{} assumes that the process memory image consists | |
508 | of cacheable (non-device) memory only. The default, @code{0}, | |
509 | indicates that the process may use device memory. | |
510 | ||
511 | This tunable is specific to powerpc, powerpc64 and powerpc64le. | |
512 | @end deftp | |
513 | ||
dce452dc SP |
514 | @deftp Tunable glibc.cpu.name |
515 | The @code{glibc.cpu.name=xxx} tunable allows the user to tell @theglibc{} to | |
28cfa3a4 | 516 | assume that the CPU is @code{xxx} where xxx may have one of these values: |
9c9ec581 | 517 | @code{generic}, @code{falkor}, @code{thunderxt88}, @code{thunderx2t99}, |
fa527f34 NT |
518 | @code{thunderx2t99p1}, @code{ares}, @code{emag}, @code{kunpeng}, |
519 | @code{a64fx}. | |
28cfa3a4 SP |
520 | |
521 | This tunable is specific to aarch64. | |
522 | @end deftp | |
523 | ||
dce452dc SP |
524 | @deftp Tunable glibc.cpu.x86_data_cache_size |
525 | The @code{glibc.cpu.x86_data_cache_size} tunable allows the user to set | |
905947c3 L |
526 | data cache size in bytes for use in memory and string routines. |
527 | ||
528 | This tunable is specific to i386 and x86-64. | |
529 | @end deftp | |
530 | ||
dce452dc SP |
531 | @deftp Tunable glibc.cpu.x86_shared_cache_size |
532 | The @code{glibc.cpu.x86_shared_cache_size} tunable allows the user to | |
905947c3 L |
533 | set shared cache size in bytes for use in memory and string routines. |
534 | @end deftp | |
535 | ||
dce452dc SP |
536 | @deftp Tunable glibc.cpu.x86_non_temporal_threshold |
537 | The @code{glibc.cpu.x86_non_temporal_threshold} tunable allows the user | |
d3c57027 PM |
538 | to set threshold in bytes for non temporal store. Non temporal stores |
539 | give a hint to the hardware to move data directly to memory without | |
540 | displacing other data from the cache. This tunable is used by some | |
541 | platforms to determine when to use non temporal stores in operations | |
542 | like memmove and memcpy. | |
905947c3 L |
543 | |
544 | This tunable is specific to i386 and x86-64. | |
545 | @end deftp | |
6d90776d | 546 | |
3f4b61a0 L |
547 | @deftp Tunable glibc.cpu.x86_rep_movsb_threshold |
548 | The @code{glibc.cpu.x86_rep_movsb_threshold} tunable allows the user to | |
549 | set threshold in bytes to start using "rep movsb". The value must be | |
550 | greater than zero, and currently defaults to 2048 bytes. | |
551 | ||
552 | This tunable is specific to i386 and x86-64. | |
553 | @end deftp | |
554 | ||
555 | @deftp Tunable glibc.cpu.x86_rep_stosb_threshold | |
556 | The @code{glibc.cpu.x86_rep_stosb_threshold} tunable allows the user to | |
557 | set threshold in bytes to start using "rep stosb". The value must be | |
558 | greater than zero, and currently defaults to 2048 bytes. | |
559 | ||
560 | This tunable is specific to i386 and x86-64. | |
561 | @end deftp | |
562 | ||
dce452dc SP |
563 | @deftp Tunable glibc.cpu.x86_ibt |
564 | The @code{glibc.cpu.x86_ibt} tunable allows the user to control how | |
6d90776d L |
565 | indirect branch tracking (IBT) should be enabled. Accepted values are |
566 | @code{on}, @code{off}, and @code{permissive}. @code{on} always turns | |
567 | on IBT regardless of whether IBT is enabled in the executable and its | |
568 | dependent shared libraries. @code{off} always turns off IBT regardless | |
569 | of whether IBT is enabled in the executable and its dependent shared | |
570 | libraries. @code{permissive} is the same as the default which disables | |
571 | IBT on non-CET executables and shared libraries. | |
572 | ||
573 | This tunable is specific to i386 and x86-64. | |
574 | @end deftp | |
575 | ||
dce452dc SP |
576 | @deftp Tunable glibc.cpu.x86_shstk |
577 | The @code{glibc.cpu.x86_shstk} tunable allows the user to control how | |
6d90776d L |
578 | the shadow stack (SHSTK) should be enabled. Accepted values are |
579 | @code{on}, @code{off}, and @code{permissive}. @code{on} always turns on | |
580 | SHSTK regardless of whether SHSTK is enabled in the executable and its | |
581 | dependent shared libraries. @code{off} always turns off SHSTK regardless | |
582 | of whether SHSTK is enabled in the executable and its dependent shared | |
583 | libraries. @code{permissive} changes how dlopen works on non-CET shared | |
584 | libraries. By default, when SHSTK is enabled, dlopening a non-CET shared | |
585 | library returns an error. With @code{permissive}, it turns off SHSTK | |
586 | instead. | |
587 | ||
588 | This tunable is specific to i386 and x86-64. | |
589 | @end deftp | |
26450d04 | 590 | |
317f1c0a | 591 | @deftp Tunable glibc.cpu.prefer_map_32bit_exec |
188ecdb7 | 592 | When this tunable is set to @code{1}, shared libraries of non-setuid |
317f1c0a L |
593 | programs will be loaded below 2GB with MAP_32BIT. |
594 | ||
595 | Note that the @env{LD_PREFER_MAP_32BIT_EXEC} environment is an alias of | |
596 | this tunable. | |
597 | ||
598 | This tunable is specific to 64-bit x86-64. | |
599 | @end deftp | |
600 | ||
26450d04 RE |
601 | @node Memory Related Tunables |
602 | @section Memory Related Tunables | |
603 | @cindex memory related tunables | |
604 | ||
605 | @deftp {Tunable namespace} glibc.mem | |
606 | This tunable namespace supports operations that affect the way @theglibc{} | |
607 | and the process manage memory. | |
608 | @end deftp | |
609 | ||
610 | @deftp Tunable glibc.mem.tagging | |
611 | If the hardware supports memory tagging, this tunable can be used to | |
612 | control the way @theglibc{} uses this feature. At present this is only | |
613 | supported on AArch64 systems with the MTE extention; it is ignored for | |
614 | all other systems. | |
615 | ||
616 | This tunable takes a value between 0 and 255 and acts as a bitmask | |
617 | that enables various capabilities. | |
618 | ||
bdc674d9 PE |
619 | Bit 0 (the least significant bit) causes the @code{malloc} |
620 | subsystem to allocate | |
26450d04 RE |
621 | tagged memory, with each allocation being assigned a random tag. |
622 | ||
623 | Bit 1 enables precise faulting mode for tag violations on systems that | |
624 | support deferred tag violation reporting. This may cause programs | |
625 | to run more slowly. | |
626 | ||
e9dd3682 TB |
627 | Bit 2 enables either precise or deferred faulting mode for tag violations |
628 | whichever is preferred by the system. | |
629 | ||
26450d04 RE |
630 | Other bits are currently reserved. |
631 | ||
632 | @Theglibc{} startup code will automatically enable memory tagging | |
633 | support in the kernel if this tunable has any non-zero value. | |
634 | ||
635 | The default value is @samp{0}, which disables all memory tagging. | |
636 | @end deftp | |
31be941e SK |
637 | |
638 | @node gmon Tunables | |
639 | @section gmon Tunables | |
640 | @cindex gmon tunables | |
641 | ||
642 | @deftp {Tunable namespace} glibc.gmon | |
643 | This tunable namespace affects the behaviour of the gmon profiler. | |
644 | gmon is a component of @theglibc{} which is normally used in | |
645 | conjunction with gprof. | |
646 | ||
647 | When GCC compiles a program with the @code{-pg} option, it instruments | |
648 | the program with calls to the @code{mcount} function, to record the | |
649 | program's call graph. At program startup, a memory buffer is allocated | |
650 | to store this call graph; the size of the buffer is calculated using a | |
651 | heuristic based on code size. If during execution, the buffer is found | |
652 | to be too small, profiling will be aborted and no @file{gmon.out} file | |
653 | will be produced. In that case, you will see the following message | |
654 | printed to standard error: | |
655 | ||
656 | @example | |
657 | mcount: call graph buffer size limit exceeded, gmon.out will not be generated | |
658 | @end example | |
659 | ||
660 | Most of the symbols discussed in this section are defined in the header | |
661 | @code{sys/gmon.h}. However, some symbols (for example @code{mcount}) | |
662 | are not defined in any header file, since they are only intended to be | |
663 | called from code generated by the compiler. | |
664 | @end deftp | |
665 | ||
666 | @deftp Tunable glibc.mem.minarcs | |
667 | The heuristic for sizing the call graph buffer is known to be | |
668 | insufficient for small programs; hence, the calculated value is clamped | |
669 | to be at least a minimum size. The default minimum (in units of | |
670 | call graph entries, @code{struct tostruct}), is given by the macro | |
671 | @code{MINARCS}. If you have some program with an unusually complex | |
672 | call graph, for which the heuristic fails to allocate enough space, | |
673 | you can use this tunable to increase the minimum to a larger value. | |
674 | @end deftp | |
675 | ||
676 | @deftp Tunable glibc.mem.maxarcs | |
677 | To prevent excessive memory consumption when profiling very large | |
678 | programs, the call graph buffer is allowed to have a maximum of | |
679 | @code{MAXARCS} entries. For some very large programs, the default | |
680 | value of @code{MAXARCS} defined in @file{sys/gmon.h} is too small; in | |
681 | that case, you can use this tunable to increase it. | |
682 | ||
683 | Note the value of the @code{maxarcs} tunable must be greater or equal | |
684 | to that of the @code{minarcs} tunable; if this constraint is violated, | |
685 | a warning will printed to standard error at program startup, and | |
686 | the @code{minarcs} value will be used as the maximum as well. | |
687 | ||
688 | Setting either tunable too high may result in a call graph buffer | |
689 | whose size exceeds the available memory; in that case, an out of memory | |
690 | error will be printed at program startup, the profiler will be | |
691 | disabled, and no @file{gmon.out} file will be generated. | |
692 | @end deftp |