diff options
Diffstat (limited to 'Documentation/kbuild/kconfig-language.rst')
| -rw-r--r-- | Documentation/kbuild/kconfig-language.rst | 181 |
1 files changed, 120 insertions, 61 deletions
diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst index a1601ec3317b..a91abb8f6840 100644 --- a/Documentation/kbuild/kconfig-language.rst +++ b/Documentation/kbuild/kconfig-language.rst @@ -70,7 +70,11 @@ applicable everywhere (see syntax). 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". + with "if". If a prompt is not present, the config option is a non-visible + symbol, meaning its value cannot be directly changed by the user (such as + altering the value in ``.config``) and the option will not appear in any + config menus. Its value can only be set via "default" and "select" (see + below). - default value: "default" <expr> ["if" <expr>] @@ -150,6 +154,12 @@ applicable everywhere (see syntax). That will limit the usefulness but on the other hand avoid the illegal configurations all over. + If "select" <symbol> is followed by "if" <expr>, <symbol> will be + selected by the logical AND of the value of the current menu symbol + and <expr>. This means, the lower limit can be downgraded due to the + presence of "if" <expr>. This behavior may seem weird, but we rely on + it. (The future of this behavior is undecided.) + - weak reverse dependencies: "imply" <symbol> ["if" <expr>] This is similar to "select" as it enforces a lower limit on another @@ -176,7 +186,7 @@ applicable everywhere (see syntax). y y y Y/m/n n m n N/m m m m M/n - y m n M/n + y m m M/n y n * N === === ============= ============== @@ -184,16 +194,6 @@ applicable everywhere (see syntax). ability to hook into a secondary subsystem while allowing the user to configure that subsystem out without also having to unset these drivers. - Note: If the combination of FOO=y and BAR=m causes a link error, - you can guard the function call with IS_REACHABLE():: - - foo_init() - { - if (IS_REACHABLE(CONFIG_BAZ)) - baz_register(&foo); - ... - } - Note: If the feature provided by BAZ is highly desirable for FOO, FOO should imply not only BAZ, but also its dependency BAR:: @@ -202,6 +202,10 @@ applicable everywhere (see syntax). imply BAR imply BAZ + Note: If "imply" <symbol> is followed by "if" <expr>, the default of <symbol> + will be the logical AND of the value of the current menu symbol and <expr>. + (The future of this behavior is undecided.) + - limiting menu display: "visible if" <expr> This attribute is only applicable to menu blocks, if the condition is @@ -223,25 +227,10 @@ applicable everywhere (see syntax). the indentation level, this means it ends at the first line which has a smaller indentation than the first line of the help text. -- 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. +- module attribute: "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. Menu dependencies ----------------- @@ -408,29 +397,15 @@ of C0, which doesn't depend on M:: choices:: - "choice" [symbol] + "choice" <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. +This defines a choice group and accepts "prompt", "default", "depends on", and +"help" attributes as options. + +A choice only allows a single config entry to be selected. comment:: @@ -540,8 +515,8 @@ followed by a test macro:: 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) + config CC_HAS_FOO + def_bool $(success,$(srctree)/scripts/cc-check-foo.sh $(CC)) Build as module only ~~~~~~~~~~~~~~~~~~~~ @@ -553,6 +528,84 @@ with "depends on m". E.g.:: limits FOO to module (=m) or disabled (=n). +Compile-testing +~~~~~~~~~~~~~~~ +If a config symbol has a dependency, but the code controlled by the config +symbol can still be compiled if the dependency is not met, it is encouraged to +increase build coverage by adding an "|| COMPILE_TEST" clause to the +dependency. This is especially useful for drivers for more exotic hardware, as +it allows continuous-integration systems to compile-test the code on a more +common system, and detect bugs that way. +Note that compile-tested code should avoid crashing when run on a system where +the dependency is not met. + +Architecture and platform dependencies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Due to the presence of stubs, most drivers can now be compiled on most +architectures. However, this does not mean it makes sense to have all drivers +available everywhere, as the actual hardware may only exist on specific +architectures and platforms. This is especially true for on-SoC IP cores, +which may be limited to a specific vendor or SoC family. + +To prevent asking the user about drivers that cannot be used on the system(s) +the user is compiling a kernel for, and if it makes sense, config symbols +controlling the compilation of a driver should contain proper dependencies, +limiting the visibility of the symbol to (a superset of) the platform(s) the +driver can be used on. The dependency can be an architecture (e.g. ARM) or +platform (e.g. ARCH_OMAP4) dependency. This makes life simpler not only for +distro config owners, but also for every single developer or user who +configures a kernel. + +Such a dependency can be relaxed by combining it with the compile-testing rule +above, leading to: + + config FOO + bool "Support for foo hardware" + depends on ARCH_FOO_VENDOR || COMPILE_TEST + +Optional dependencies +~~~~~~~~~~~~~~~~~~~~~ + +Some drivers are able to optionally use a feature from another module +or build cleanly with that module disabled, but cause a link failure +when trying to use that loadable module from a built-in driver. + +The most common way to express this optional dependency in Kconfig logic +uses the slightly counterintuitive:: + + config FOO + tristate "Support for foo hardware" + depends on BAR || !BAR + +This means that there is either a dependency on BAR that disallows +the combination of FOO=y with BAR=m, or BAR is completely disabled. The BAR +module must provide all the stubs for !BAR case. + +For a more formalized approach if there are multiple drivers that have +the same dependency, a helper symbol can be used, like:: + + config FOO + tristate "Support for foo hardware" + depends on BAR_OPTIONAL + + config BAR_OPTIONAL + def_tristate BAR || !BAR + +Much less favorable way to express optional dependency is IS_REACHABLE() within +the module code, useful for example when the module BAR does not provide +!BAR stubs:: + + foo_init() + { + if (IS_REACHABLE(CONFIG_BAR)) + bar_register(&foo); + ... + } + +IS_REACHABLE() is generally discouraged, because the code will be silently +discarded, when CONFIG_BAR=m and this code is built-in. This is not what users +usually expect when enabling BAR as module. + Kconfig recursive dependency limitations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -652,7 +705,7 @@ 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 +for instance one 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 @@ -673,6 +726,8 @@ 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. +Another project formalized a denotational semantics of a core subset of +the Kconfig language [10]_. Having well defined semantics can be useful for tools for practical evaluation of dependencies, for instance one such case was work to @@ -680,18 +735,20 @@ 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). +The kismet tool, based on the semantics in [10]_, finds abuses of reverse +dependencies and has led to dozens of committed fixes to Linux Kconfig files [11]_. -Confirming this could prove useful as Kconfig stands as one of the the leading +Confirming this could prove useful as Kconfig stands as one of 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 +.. [0] https://www.eng.uwaterloo.ca/~shshe/kconfig_semantics.pdf +.. [1] https://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf +.. [2] https://gsd.uwaterloo.ca/sites/default/files/ase241-berger_0.pdf +.. [3] https://gsd.uwaterloo.ca/sites/default/files/icse2011.pdf Full SAT solver for Kconfig ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -710,11 +767,13 @@ 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 +https://kernelnewbies.org/KernelProjects/kconfig-sat -.. [4] http://www.cs.cornell.edu/~sabhar/chapters/SATSolvers-KR-Handbook.pdf -.. [5] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf +.. [4] https://www.cs.cornell.edu/~sabhar/chapters/SATSolvers-KR-Handbook.pdf +.. [5] https://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf .. [6] https://cados.cs.fau.de .. [7] https://vamos.cs.fau.de .. [8] https://undertaker.cs.fau.de .. [9] https://www4.cs.fau.de/Publications/2011/tartler_11_eurosys.pdf +.. [10] https://paulgazzillo.com/papers/esecfse21.pdf +.. [11] https://github.com/paulgazz/kmax |