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