|
Packit |
6c4009 |
TUNABLE FRAMEWORK
|
|
Packit |
6c4009 |
=================
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Tunables is a feature in the GNU C Library that allows application authors and
|
|
Packit |
6c4009 |
distribution maintainers to alter the runtime library behaviour to match their
|
|
Packit |
6c4009 |
workload.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The tunable framework allows modules within glibc to register variables that
|
|
Packit |
6c4009 |
may be tweaked through an environment variable. It aims to enforce a strict
|
|
Packit |
6c4009 |
namespace rule to bring consistency to naming of these tunable environment
|
|
Packit |
6c4009 |
variables across the project. This document is a guide for glibc developers to
|
|
Packit |
6c4009 |
add tunables to the framework.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
ADDING A NEW TUNABLE
|
|
Packit |
6c4009 |
--------------------
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The TOP_NAMESPACE macro is defined by default as 'glibc'. If distributions
|
|
Packit |
6c4009 |
intend to add their own tunables, they should do so in a different top
|
|
Packit |
6c4009 |
namespace by overriding the TOP_NAMESPACE macro for that tunable. Downstream
|
|
Packit |
6c4009 |
implementations are discouraged from using the 'glibc' top namespace for
|
|
Packit |
6c4009 |
tunables they don't already have consensus to push upstream.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
There are three steps to adding a tunable:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
1. Add a tunable to the list and fully specify its properties:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
For each tunable you want to add, make an entry in elf/dl-tunables.list. The
|
|
Packit |
6c4009 |
format of the file is as follows:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
TOP_NAMESPACE {
|
|
Packit |
6c4009 |
NAMESPACE1 {
|
|
Packit |
6c4009 |
TUNABLE1 {
|
|
Packit |
6c4009 |
# tunable attributes, one per line
|
|
Packit |
6c4009 |
}
|
|
Packit |
6c4009 |
# A tunable with default attributes, i.e. string variable.
|
|
Packit |
6c4009 |
TUNABLE2
|
|
Packit |
6c4009 |
TUNABLE3 {
|
|
Packit |
6c4009 |
# its attributes
|
|
Packit |
6c4009 |
}
|
|
Packit |
6c4009 |
}
|
|
Packit |
6c4009 |
NAMESPACE2 {
|
|
Packit |
6c4009 |
...
|
|
Packit |
6c4009 |
}
|
|
Packit |
6c4009 |
}
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The list of allowed attributes are:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
- type: Data type. Defaults to STRING. Allowed types are:
|
|
Packit |
6c4009 |
INT_32, UINT_64, SIZE_T and STRING. Numeric types may
|
|
Packit |
6c4009 |
be in octal or hexadecimal format too.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
- minval: Optional minimum acceptable value. For a string type
|
|
Packit |
6c4009 |
this is the minimum length of the value.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
- maxval: Optional maximum acceptable value. For a string type
|
|
Packit |
6c4009 |
this is the maximum length of the value.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
- default: Specify an optional default value for the tunable.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
- env_alias: An alias environment variable
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
- security_level: Specify security level of the tunable. Valid values:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
SXID_ERASE: (default) Don't read for AT_SECURE binaries and
|
|
Packit |
6c4009 |
removed so that child processes can't read it.
|
|
Packit |
6c4009 |
SXID_IGNORE: Don't read for AT_SECURE binaries, but retained for
|
|
Packit |
6c4009 |
non-AT_SECURE subprocesses.
|
|
Packit |
6c4009 |
NONE: Read all the time.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
2. Use TUNABLE_GET/TUNABLE_SET to get and set tunables.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
3. OPTIONAL: If tunables in a namespace are being used multiple times within a
|
|
Packit |
6c4009 |
specific module, set the TUNABLE_NAMESPACE macro to reduce the amount of
|
|
Packit |
6c4009 |
typing.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
GETTING AND SETTING TUNABLES
|
|
Packit |
6c4009 |
----------------------------
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
When the TUNABLE_NAMESPACE macro is defined, one may get tunables in that
|
|
Packit |
6c4009 |
module using the TUNABLE_GET macro as follows:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
val = TUNABLE_GET (check, int32_t, TUNABLE_CALLBACK (check_callback))
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
where 'check' is the tunable name, 'int32_t' is the C type of the tunable and
|
|
Packit |
6c4009 |
'check_callback' is the function to call if the tunable got initialized to a
|
|
Packit |
6c4009 |
non-default value. The macro returns the value as type 'int32_t'.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The callback function should be defined as follows:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
void
|
|
Packit |
6c4009 |
TUNABLE_CALLBACK (check_callback) (int32_t *valp)
|
|
Packit |
6c4009 |
{
|
|
Packit |
6c4009 |
...
|
|
Packit |
6c4009 |
}
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
where it can expect the tunable value to be passed in VALP.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Tunables in the module can be updated using:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
TUNABLE_SET (check, int32_t, val)
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
where 'check' is the tunable name, 'int32_t' is the C type of the tunable and
|
|
Packit |
6c4009 |
'val' is a value of same type.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
To get and set tunables in a different namespace from that module, use the full
|
|
Packit |
6c4009 |
form of the macros as follows:
|
|
Packit |
6c4009 |
|
|
Packit Service |
1f32a9 |
val = TUNABLE_GET_FULL (glibc, tune, hwcap_mask, uint64_t, NULL)
|
|
Packit |
6c4009 |
|
|
Packit Service |
1f32a9 |
TUNABLE_SET_FULL (glibc, tune, hwcap_mask, uint64_t, val)
|
|
Packit |
6c4009 |
|
|
Packit Service |
1f32a9 |
where 'glibc' is the top namespace, 'tune' is the tunable namespace and the
|
|
Packit |
6c4009 |
remaining arguments are the same as the short form macros.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
When TUNABLE_NAMESPACE is not defined in a module, TUNABLE_GET is equivalent to
|
|
Packit |
6c4009 |
TUNABLE_GET_FULL, so you will need to provide full namespace information for
|
|
Packit |
6c4009 |
both macros. Likewise for TUNABLE_SET and TUNABLE_SET_FULL.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
** IMPORTANT NOTE **
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The tunable list is set as read-only after the dynamic linker relocates itself,
|
|
Packit |
6c4009 |
so setting tunable values must be limited only to tunables within the dynamic
|
|
Packit |
6c4009 |
linker, that too before relocation.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
FUTURE WORK
|
|
Packit |
6c4009 |
-----------
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The framework currently only allows a one-time initialization of variables
|
|
Packit |
6c4009 |
through environment variables and in some cases, modification of variables via
|
|
Packit |
6c4009 |
an API call. A future goals for this project include:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
- Setting system-wide and user-wide defaults for tunables through some
|
|
Packit |
6c4009 |
mechanism like a configuration file.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
- Allow tweaking of some tunables at runtime
|