diff options
Diffstat (limited to 'Documentation/kbuild/kconfig-language.rst')
| -rw-r--r-- | Documentation/kbuild/kconfig-language.rst | 88 |
1 files changed, 57 insertions, 31 deletions
diff --git a/Documentation/kbuild/kconfig-language.rst b/Documentation/kbuild/kconfig-language.rst index a1601ec3317b..858ed5d80def 100644 --- a/Documentation/kbuild/kconfig-language.rst +++ b/Documentation/kbuild/kconfig-language.rst @@ -176,7 +176,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 === === ============= ============== @@ -223,25 +223,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 ----------------- @@ -540,8 +525,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 +538,41 @@ 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 + Kconfig recursive dependency limitations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -652,7 +672,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 +693,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 +702,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 +734,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 |