aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/kbuild/kconfig-language.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/kbuild/kconfig-language.txt')
-rw-r--r--Documentation/kbuild/kconfig-language.txt669
1 files changed, 0 insertions, 669 deletions
diff --git a/Documentation/kbuild/kconfig-language.txt b/Documentation/kbuild/kconfig-language.txt
deleted file mode 100644
index 864e740811da..000000000000
--- a/Documentation/kbuild/kconfig-language.txt
+++ /dev/null
@@ -1,669 +0,0 @@
-Introduction
-------------
-
-The configuration database is a collection of configuration options
-organized in a tree structure:
-
- +- Code maturity level options
- | +- Prompt for development and/or incomplete code/drivers
- +- General setup
- | +- Networking support
- | +- System V IPC
- | +- BSD Process Accounting
- | +- Sysctl support
- +- Loadable module support
- | +- Enable loadable module support
- | +- Set version information on all module symbols
- | +- Kernel module loader
- +- ...
-
-Every entry has its own dependencies. These dependencies are used
-to determine the visibility of an entry. Any child entry is only
-visible if its parent entry is also visible.
-
-Menu entries
-------------
-
-Most entries define a config option; all other entries help to organize
-them. A single configuration option is defined like this:
-
-config MODVERSIONS
- bool "Set version information on all module symbols"
- depends on MODULES
- help
- Usually, modules have to be recompiled whenever you switch to a new
- kernel. ...
-
-Every line starts with a key word and can be followed by multiple
-arguments. "config" starts a new config entry. The following lines
-define attributes for this config option. Attributes can be the type of
-the config option, input prompt, dependencies, help text and default
-values. A config option can be defined multiple times with the same
-name, but every definition can have only a single input prompt and the
-type must not conflict.
-
-Menu attributes
----------------
-
-A menu entry can have a number of attributes. Not all of them are
-applicable everywhere (see syntax).
-
-- type definition: "bool"/"tristate"/"string"/"hex"/"int"
- Every config option must have a type. There are only two basic types:
- tristate and string; the other types are based on these two. The type
- definition optionally accepts an input prompt, so these two examples
- are equivalent:
-
- bool "Networking support"
- and
- bool
- prompt "Networking support"
-
-- input prompt: "prompt" <prompt> ["if" <expr>]
- Every menu entry can have at most one prompt, which is used to display
- to the user. Optionally dependencies only for this prompt can be added
- with "if".
-
-- default value: "default" <expr> ["if" <expr>]
- A config option can have any number of default values. If multiple
- default values are visible, only the first defined one is active.
- Default values are not limited to the menu entry where they are
- defined. This means the default can be defined somewhere else or be
- overridden by an earlier definition.
- The default value is only assigned to the config symbol if no other
- value was set by the user (via the input prompt above). If an input
- prompt is visible the default value is presented to the user and can
- be overridden by him.
- Optionally, dependencies only for this default value can be added with
- "if".
-
- The default value deliberately defaults to 'n' in order to avoid bloating the
- build. With few exceptions, new config options should not change this. The
- intent is for "make oldconfig" to add as little as possible to the config from
- release to release.
-
- Note:
- Things that merit "default y/m" include:
-
- a) A new Kconfig option for something that used to always be built
- should be "default y".
-
- b) A new gatekeeping Kconfig option that hides/shows other Kconfig
- options (but does not generate any code of its own), should be
- "default y" so people will see those other options.
-
- c) Sub-driver behavior or similar options for a driver that is
- "default n". This allows you to provide sane defaults.
-
- d) Hardware or infrastructure that everybody expects, such as CONFIG_NET
- or CONFIG_BLOCK. These are rare exceptions.
-
-- type definition + default value:
- "def_bool"/"def_tristate" <expr> ["if" <expr>]
- This is a shorthand notation for a type definition plus a value.
- Optionally dependencies for this default value can be added with "if".
-
-- dependencies: "depends on" <expr>
- This defines a dependency for this menu entry. If multiple
- dependencies are defined, they are connected with '&&'. Dependencies
- are applied to all other options within this menu entry (which also
- accept an "if" expression), so these two examples are equivalent:
-
- bool "foo" if BAR
- default y if BAR
- and
- depends on BAR
- bool "foo"
- default y
-
-- reverse dependencies: "select" <symbol> ["if" <expr>]
- While normal dependencies reduce the upper limit of a symbol (see
- below), reverse dependencies can be used to force a lower limit of
- another symbol. The value of the current menu symbol is used as the
- minimal value <symbol> can be set to. If <symbol> is selected multiple
- times, the limit is set to the largest selection.
- Reverse dependencies can only be used with boolean or tristate
- symbols.
- Note:
- select should be used with care. select will force
- a symbol to a value without visiting the dependencies.
- By abusing select you are able to select a symbol FOO even
- if FOO depends on BAR that is not set.
- In general use select only for non-visible symbols
- (no prompts anywhere) and for symbols with no dependencies.
- That will limit the usefulness but on the other hand avoid
- the illegal configurations all over.
-
-- weak reverse dependencies: "imply" <symbol> ["if" <expr>]
- This is similar to "select" as it enforces a lower limit on another
- symbol except that the "implied" symbol's value may still be set to n
- from a direct dependency or with a visible prompt.
-
- Given the following example:
-
- config FOO
- tristate
- imply BAZ
-
- config BAZ
- tristate
- depends on BAR
-
- The following values are possible:
-
- FOO BAR BAZ's default choice for BAZ
- --- --- ------------- --------------
- n y n N/m/y
- m y m M/y/n
- y y y Y/n
- y n * N
-
- This is useful e.g. with multiple drivers that want to indicate their
- ability to hook into a secondary subsystem while allowing the user to
- configure that subsystem out without also having to unset these drivers.
-
-- limiting menu display: "visible if" <expr>
- This attribute is only applicable to menu blocks, if the condition is
- false, the menu block is not displayed to the user (the symbols
- contained there can still be selected by other symbols, though). It is
- similar to a conditional "prompt" attribute for individual menu
- entries. Default value of "visible" is true.
-
-- numerical ranges: "range" <symbol> <symbol> ["if" <expr>]
- This allows to limit the range of possible input values for int
- and hex symbols. The user can only input a value which is larger than
- or equal to the first symbol and smaller than or equal to the second
- symbol.
-
-- help text: "help" or "---help---"
- This defines a help text. The end of the help text is determined by
- the indentation level, this means it ends at the first line which has
- a smaller indentation than the first line of the help text.
- "---help---" and "help" do not differ in behaviour, "---help---" is
- used to help visually separate configuration logic from help within
- the file as an aid to developers.
-
-- misc options: "option" <symbol>[=<value>]
- Various less common options can be defined via this option syntax,
- which can modify the behaviour of the menu entry and its config
- symbol. These options are currently possible:
-
- - "defconfig_list"
- This declares a list of default entries which can be used when
- looking for the default configuration (which is used when the main
- .config doesn't exists yet.)
-
- - "modules"
- This declares the symbol to be used as the MODULES symbol, which
- enables the third modular state for all config symbols.
- At most one symbol may have the "modules" option set.
-
- - "allnoconfig_y"
- This declares the symbol as one that should have the value y when
- using "allnoconfig". Used for symbols that hide other symbols.
-
-Menu dependencies
------------------
-
-Dependencies define the visibility of a menu entry and can also reduce
-the input range of tristate symbols. The tristate logic used in the
-expressions uses one more state than normal boolean logic to express the
-module state. Dependency expressions have the following syntax:
-
-<expr> ::= <symbol> (1)
- <symbol> '=' <symbol> (2)
- <symbol> '!=' <symbol> (3)
- <symbol1> '<' <symbol2> (4)
- <symbol1> '>' <symbol2> (4)
- <symbol1> '<=' <symbol2> (4)
- <symbol1> '>=' <symbol2> (4)
- '(' <expr> ')' (5)
- '!' <expr> (6)
- <expr> '&&' <expr> (7)
- <expr> '||' <expr> (8)
-
-Expressions are listed in decreasing order of precedence.
-
-(1) Convert the symbol into an expression. Boolean and tristate symbols
- are simply converted into the respective expression values. All
- other symbol types result in 'n'.
-(2) If the values of both symbols are equal, it returns 'y',
- otherwise 'n'.
-(3) If the values of both symbols are equal, it returns 'n',
- otherwise 'y'.
-(4) If value of <symbol1> is respectively lower, greater, lower-or-equal,
- or greater-or-equal than value of <symbol2>, it returns 'y',
- otherwise 'n'.
-(5) Returns the value of the expression. Used to override precedence.
-(6) Returns the result of (2-/expr/).
-(7) Returns the result of min(/expr/, /expr/).
-(8) Returns the result of max(/expr/, /expr/).
-
-An expression can have a value of 'n', 'm' or 'y' (or 0, 1, 2
-respectively for calculations). A menu entry becomes visible when its
-expression evaluates to 'm' or 'y'.
-
-There are two types of symbols: constant and non-constant symbols.
-Non-constant symbols are the most common ones and are defined with the
-'config' statement. Non-constant symbols consist entirely of alphanumeric
-characters or underscores.
-Constant symbols are only part of expressions. Constant symbols are
-always surrounded by single or double quotes. Within the quote, any
-other character is allowed and the quotes can be escaped using '\'.
-
-Menu structure
---------------
-
-The position of a menu entry in the tree is determined in two ways. First
-it can be specified explicitly:
-
-menu "Network device support"
- depends on NET
-
-config NETDEVICES
- ...
-
-endmenu
-
-All entries within the "menu" ... "endmenu" block become a submenu of
-"Network device support". All subentries inherit the dependencies from
-the menu entry, e.g. this means the dependency "NET" is added to the
-dependency list of the config option NETDEVICES.
-
-The other way to generate the menu structure is done by analyzing the
-dependencies. If a menu entry somehow depends on the previous entry, it
-can be made a submenu of it. First, the previous (parent) symbol must
-be part of the dependency list and then one of these two conditions
-must be true:
-- the child entry must become invisible, if the parent is set to 'n'
-- the child entry must only be visible, if the parent is visible
-
-config MODULES
- bool "Enable loadable module support"
-
-config MODVERSIONS
- bool "Set version information on all module symbols"
- depends on MODULES
-
-comment "module support disabled"
- depends on !MODULES
-
-MODVERSIONS directly depends on MODULES, this means it's only visible if
-MODULES is different from 'n'. The comment on the other hand is only
-visible when MODULES is set to 'n'.
-
-
-Kconfig syntax
---------------
-
-The configuration file describes a series of menu entries, where every
-line starts with a keyword (except help texts). The following keywords
-end a menu entry:
-- config
-- menuconfig
-- choice/endchoice
-- comment
-- menu/endmenu
-- if/endif
-- source
-The first five also start the definition of a menu entry.
-
-config:
-
- "config" <symbol>
- <config options>
-
-This defines a config symbol <symbol> and accepts any of above
-attributes as options.
-
-menuconfig:
- "menuconfig" <symbol>
- <config options>
-
-This is similar to the simple config entry above, but it also gives a
-hint to front ends, that all suboptions should be displayed as a
-separate list of options. To make sure all the suboptions will really
-show up under the menuconfig entry and not outside of it, every item
-from the <config options> list must depend on the menuconfig symbol.
-In practice, this is achieved by using one of the next two constructs:
-
-(1):
-menuconfig M
-if M
- config C1
- config C2
-endif
-
-(2):
-menuconfig M
-config C1
- depends on M
-config C2
- depends on M
-
-In the following examples (3) and (4), C1 and C2 still have the M
-dependency, but will not appear under menuconfig M anymore, because
-of C0, which doesn't depend on M:
-
-(3):
-menuconfig M
- config C0
-if M
- config C1
- config C2
-endif
-
-(4):
-menuconfig M
-config C0
-config C1
- depends on M
-config C2
- depends on M
-
-choices:
-
- "choice" [symbol]
- <choice options>
- <choice block>
- "endchoice"
-
-This defines a choice group and accepts any of the above attributes as
-options. A choice can only be of type bool or tristate. If no type is
-specified for a choice, its type will be determined by the type of
-the first choice element in the group or remain unknown if none of the
-choice elements have a type specified, as well.
-
-While a boolean choice only allows a single config entry to be
-selected, a tristate choice also allows any number of config entries
-to be set to 'm'. This can be used if multiple drivers for a single
-hardware exists and only a single driver can be compiled/loaded into
-the kernel, but all drivers can be compiled as modules.
-
-A choice accepts another option "optional", which allows to set the
-choice to 'n' and no entry needs to be selected.
-If no [symbol] is associated with a choice, then you can not have multiple
-definitions of that choice. If a [symbol] is associated to the choice,
-then you may define the same choice (i.e. with the same entries) in another
-place.
-
-comment:
-
- "comment" <prompt>
- <comment options>
-
-This defines a comment which is displayed to the user during the
-configuration process and is also echoed to the output files. The only
-possible options are dependencies.
-
-menu:
-
- "menu" <prompt>
- <menu options>
- <menu block>
- "endmenu"
-
-This defines a menu block, see "Menu structure" above for more
-information. The only possible options are dependencies and "visible"
-attributes.
-
-if:
-
- "if" <expr>
- <if block>
- "endif"
-
-This defines an if block. The dependency expression <expr> is appended
-to all enclosed menu entries.
-
-source:
-
- "source" <prompt>
-
-This reads the specified configuration file. This file is always parsed.
-
-mainmenu:
-
- "mainmenu" <prompt>
-
-This sets the config program's title bar if the config program chooses
-to use it. It should be placed at the top of the configuration, before any
-other statement.
-
-'#' Kconfig source file comment:
-
-An unquoted '#' character anywhere in a source file line indicates
-the beginning of a source file comment. The remainder of that line
-is a comment.
-
-
-Kconfig hints
--------------
-This is a collection of Kconfig tips, most of which aren't obvious at
-first glance and most of which have become idioms in several Kconfig
-files.
-
-Adding common features and make the usage configurable
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-It is a common idiom to implement a feature/functionality that are
-relevant for some architectures but not all.
-The recommended way to do so is to use a config variable named HAVE_*
-that is defined in a common Kconfig file and selected by the relevant
-architectures.
-An example is the generic IOMAP functionality.
-
-We would in lib/Kconfig see:
-
-# Generic IOMAP is used to ...
-config HAVE_GENERIC_IOMAP
-
-config GENERIC_IOMAP
- depends on HAVE_GENERIC_IOMAP && FOO
-
-And in lib/Makefile we would see:
-obj-$(CONFIG_GENERIC_IOMAP) += iomap.o
-
-For each architecture using the generic IOMAP functionality we would see:
-
-config X86
- select ...
- select HAVE_GENERIC_IOMAP
- select ...
-
-Note: we use the existing config option and avoid creating a new
-config variable to select HAVE_GENERIC_IOMAP.
-
-Note: the use of the internal config variable HAVE_GENERIC_IOMAP, it is
-introduced to overcome the limitation of select which will force a
-config option to 'y' no matter the dependencies.
-The dependencies are moved to the symbol GENERIC_IOMAP and we avoid the
-situation where select forces a symbol equals to 'y'.
-
-Adding features that need compiler support
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-There are several features that need compiler support. The recommended way
-to describe the dependency on the compiler feature is to use "depends on"
-followed by a test macro.
-
-config STACKPROTECTOR
- bool "Stack Protector buffer overflow detection"
- depends on $(cc-option,-fstack-protector)
- ...
-
-If you need to expose a compiler capability to makefiles and/or C source files,
-CC_HAS_ is the recommended prefix for the config option.
-
-config CC_HAS_STACKPROTECTOR_NONE
- def_bool $(cc-option,-fno-stack-protector)
-
-Build as module only
-~~~~~~~~~~~~~~~~~~~~
-To restrict a component build to module-only, qualify its config symbol
-with "depends on m". E.g.:
-
-config FOO
- depends on BAR && m
-
-limits FOO to module (=m) or disabled (=n).
-
-Kconfig recursive dependency limitations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you've hit the Kconfig error: "recursive dependency detected" you've run
-into a recursive dependency issue with Kconfig, a recursive dependency can be
-summarized as a circular dependency. The kconfig tools need to ensure that
-Kconfig files comply with specified configuration requirements. In order to do
-that kconfig must determine the values that are possible for all Kconfig
-symbols, this is currently not possible if there is a circular relation
-between two or more Kconfig symbols. For more details refer to the "Simple
-Kconfig recursive issue" subsection below. Kconfig does not do recursive
-dependency resolution; this has a few implications for Kconfig file writers.
-We'll first explain why this issues exists and then provide an example
-technical limitation which this brings upon Kconfig developers. Eager
-developers wishing to try to address this limitation should read the next
-subsections.
-
-Simple Kconfig recursive issue
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Read: Documentation/kbuild/Kconfig.recursion-issue-01
-
-Test with:
-
-make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-01 allnoconfig
-
-Cumulative Kconfig recursive issue
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Read: Documentation/kbuild/Kconfig.recursion-issue-02
-
-Test with:
-
-make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-02 allnoconfig
-
-Practical solutions to kconfig recursive issue
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Developers who run into the recursive Kconfig issue have two options
-at their disposal. We document them below and also provide a list of
-historical issues resolved through these different solutions.
-
- a) Remove any superfluous "select FOO" or "depends on FOO"
- b) Match dependency semantics:
- b1) Swap all "select FOO" to "depends on FOO" or,
- b2) Swap all "depends on FOO" to "select FOO"
-
-The resolution to a) can be tested with the sample Kconfig file
-Documentation/kbuild/Kconfig.recursion-issue-01 through the removal
-of the "select CORE" from CORE_BELL_A_ADVANCED as that is implicit already
-since CORE_BELL_A depends on CORE. At times it may not be possible to remove
-some dependency criteria, for such cases you can work with solution b).
-
-The two different resolutions for b) can be tested in the sample Kconfig file
-Documentation/kbuild/Kconfig.recursion-issue-02.
-
-Below is a list of examples of prior fixes for these types of recursive issues;
-all errors appear to involve one or more select's and one or more "depends on".
-
-commit fix
-====== ===
-06b718c01208 select A -> depends on A
-c22eacfe82f9 depends on A -> depends on B
-6a91e854442c select A -> depends on A
-118c565a8f2e select A -> select B
-f004e5594705 select A -> depends on A
-c7861f37b4c6 depends on A -> (null)
-80c69915e5fb select A -> (null) (1)
-c2218e26c0d0 select A -> depends on A (1)
-d6ae99d04e1c select A -> depends on A
-95ca19cf8cbf select A -> depends on A
-8f057d7bca54 depends on A -> (null)
-8f057d7bca54 depends on A -> select A
-a0701f04846e select A -> depends on A
-0c8b92f7f259 depends on A -> (null)
-e4e9e0540928 select A -> depends on A (2)
-7453ea886e87 depends on A > (null) (1)
-7b1fff7e4fdf select A -> depends on A
-86c747d2a4f0 select A -> depends on A
-d9f9ab51e55e select A -> depends on A
-0c51a4d8abd6 depends on A -> select A (3)
-e98062ed6dc4 select A -> depends on A (3)
-91e5d284a7f1 select A -> (null)
-
-(1) Partial (or no) quote of error.
-(2) That seems to be the gist of that fix.
-(3) Same error.
-
-Future kconfig work
-~~~~~~~~~~~~~~~~~~~
-
-Work on kconfig is welcomed on both areas of clarifying semantics and on
-evaluating the use of a full SAT solver for it. A full SAT solver can be
-desirable to enable more complex dependency mappings and / or queries,
-for instance on possible use case for a SAT solver could be that of handling
-the current known recursive dependency issues. It is not known if this would
-address such issues but such evaluation is desirable. If support for a full SAT
-solver proves too complex or that it cannot address recursive dependency issues
-Kconfig should have at least clear and well defined semantics which also
-addresses and documents limitations or requirements such as the ones dealing
-with recursive dependencies.
-
-Further work on both of these areas is welcomed on Kconfig. We elaborate
-on both of these in the next two subsections.
-
-Semantics of Kconfig
-~~~~~~~~~~~~~~~~~~~~
-
-The use of Kconfig is broad, Linux is now only one of Kconfig's users:
-one study has completed a broad analysis of Kconfig use in 12 projects [0].
-Despite its widespread use, and although this document does a reasonable job
-in documenting basic Kconfig syntax a more precise definition of Kconfig
-semantics is welcomed. One project deduced Kconfig semantics through
-the use of the xconfig configurator [1]. Work should be done to confirm if
-the deduced semantics matches our intended Kconfig design goals.
-
-Having well defined semantics can be useful for tools for practical
-evaluation of depenencies, for instance one such use known case was work to
-express in boolean abstraction of the inferred semantics of Kconfig to
-translate Kconfig logic into boolean formulas and run a SAT solver on this to
-find dead code / features (always inactive), 114 dead features were found in
-Linux using this methodology [1] (Section 8: Threats to validity).
-
-Confirming this could prove useful as Kconfig stands as one of the the leading
-industrial variability modeling languages [1] [2]. Its study would help
-evaluate practical uses of such languages, their use was only theoretical
-and real world requirements were not well understood. As it stands though
-only reverse engineering techniques have been used to deduce semantics from
-variability modeling languages such as Kconfig [3].
-
-[0] http://www.eng.uwaterloo.ca/~shshe/kconfig_semantics.pdf
-[1] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf
-[2] http://gsd.uwaterloo.ca/sites/default/files/ase241-berger_0.pdf
-[3] http://gsd.uwaterloo.ca/sites/default/files/icse2011.pdf
-
-Full SAT solver for Kconfig
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Although SAT solvers [0] haven't yet been used by Kconfig directly, as noted in
-the previous subsection, work has been done however to express in boolean
-abstraction the inferred semantics of Kconfig to translate Kconfig logic into
-boolean formulas and run a SAT solver on it [1]. Another known related project
-is CADOS [2] (former VAMOS [3]) and the tools, mainly undertaker [4], which has
-been introduced first with [5]. The basic concept of undertaker is to exract
-variability models from Kconfig, and put them together with a propositional
-formula extracted from CPP #ifdefs and build-rules into a SAT solver in order
-to find dead code, dead files, and dead symbols. If using a SAT solver is
-desirable on Kconfig one approach would be to evaluate repurposing such efforts
-somehow on Kconfig. There is enough interest from mentors of existing projects
-to not only help advise how to integrate this work upstream but also help
-maintain it long term. Interested developers should visit:
-
-http://kernelnewbies.org/KernelProjects/kconfig-sat
-
-[0] http://www.cs.cornell.edu/~sabhar/chapters/SATSolvers-KR-Handbook.pdf
-[1] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf
-[2] https://cados.cs.fau.de
-[3] https://vamos.cs.fau.de
-[4] https://undertaker.cs.fau.de
-[5] https://www4.cs.fau.de/Publications/2011/tartler_11_eurosys.pdf