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