1================
2Kconfig Language
3================
4
5Introduction
6------------
7
8The configuration database is a collection of configuration options
9organized in a tree structure::
10
11	+- Code maturity level options
12	|  +- Prompt for development and/or incomplete code/drivers
13	+- General setup
14	|  +- Networking support
15	|  +- System V IPC
16	|  +- BSD Process Accounting
17	|  +- Sysctl support
18	+- Loadable module support
19	|  +- Enable loadable module support
20	|     +- Set version information on all module symbols
21	|     +- Kernel module loader
22	+- ...
23
24Every entry has its own dependencies. These dependencies are used
25to determine the visibility of an entry. Any child entry is only
26visible if its parent entry is also visible.
27
28Menu entries
29------------
30
31Most entries define a config option; all other entries help to organize
32them. A single configuration option is defined like this::
33
34  config MODVERSIONS
35	bool "Set version information on all module symbols"
36	depends on MODULES
37	help
38	  Usually, modules have to be recompiled whenever you switch to a new
39	  kernel.  ...
40
41Every line starts with a key word and can be followed by multiple
42arguments.  "config" starts a new config entry. The following lines
43define attributes for this config option. Attributes can be the type of
44the config option, input prompt, dependencies, help text and default
45values. A config option can be defined multiple times with the same
46name, but every definition can have only a single input prompt and the
47type must not conflict.
48
49Menu attributes
50---------------
51
52A menu entry can have a number of attributes. Not all of them are
53applicable everywhere (see syntax).
54
55- type definition: "bool"/"tristate"/"string"/"hex"/"int"
56
57  Every config option must have a type. There are only two basic types:
58  tristate and string; the other types are based on these two. The type
59  definition optionally accepts an input prompt, so these two examples
60  are equivalent::
61
62	bool "Networking support"
63
64  and::
65
66	bool
67	prompt "Networking support"
68
69- input prompt: "prompt" <prompt> ["if" <expr>]
70
71  Every menu entry can have at most one prompt, which is used to display
72  to the user. Optionally dependencies only for this prompt can be added
73  with "if".
74
75- default value: "default" <expr> ["if" <expr>]
76
77  A config option can have any number of default values. If multiple
78  default values are visible, only the first defined one is active.
79  Default values are not limited to the menu entry where they are
80  defined. This means the default can be defined somewhere else or be
81  overridden by an earlier definition.
82  The default value is only assigned to the config symbol if no other
83  value was set by the user (via the input prompt above). If an input
84  prompt is visible the default value is presented to the user and can
85  be overridden by him.
86  Optionally, dependencies only for this default value can be added with
87  "if".
88
89 The default value deliberately defaults to 'n' in order to avoid bloating the
90 build. With few exceptions, new config options should not change this. The
91 intent is for "make oldconfig" to add as little as possible to the config from
92 release to release.
93
94 Note:
95	Things that merit "default y/m" include:
96
97	a) A new Kconfig option for something that used to always be built
98	   should be "default y".
99
100	b) A new gatekeeping Kconfig option that hides/shows other Kconfig
101	   options (but does not generate any code of its own), should be
102	   "default y" so people will see those other options.
103
104	c) Sub-driver behavior or similar options for a driver that is
105	   "default n". This allows you to provide sane defaults.
106
107	d) Hardware or infrastructure that everybody expects, such as CONFIG_NET
108	   or CONFIG_BLOCK. These are rare exceptions.
109
110- type definition + default value::
111
112	"def_bool"/"def_tristate" <expr> ["if" <expr>]
113
114  This is a shorthand notation for a type definition plus a value.
115  Optionally dependencies for this default value can be added with "if".
116
117- dependencies: "depends on" <expr>
118
119  This defines a dependency for this menu entry. If multiple
120  dependencies are defined, they are connected with '&&'. Dependencies
121  are applied to all other options within this menu entry (which also
122  accept an "if" expression), so these two examples are equivalent::
123
124	bool "foo" if BAR
125	default y if BAR
126
127  and::
128
129	depends on BAR
130	bool "foo"
131	default y
132
133- reverse dependencies: "select" <symbol> ["if" <expr>]
134
135  While normal dependencies reduce the upper limit of a symbol (see
136  below), reverse dependencies can be used to force a lower limit of
137  another symbol. The value of the current menu symbol is used as the
138  minimal value <symbol> can be set to. If <symbol> is selected multiple
139  times, the limit is set to the largest selection.
140  Reverse dependencies can only be used with boolean or tristate
141  symbols.
142
143  Note:
144	select should be used with care. select will force
145	a symbol to a value without visiting the dependencies.
146	By abusing select you are able to select a symbol FOO even
147	if FOO depends on BAR that is not set.
148	In general use select only for non-visible symbols
149	(no prompts anywhere) and for symbols with no dependencies.
150	That will limit the usefulness but on the other hand avoid
151	the illegal configurations all over.
152
153- weak reverse dependencies: "imply" <symbol> ["if" <expr>]
154
155  This is similar to "select" as it enforces a lower limit on another
156  symbol except that the "implied" symbol's value may still be set to n
157  from a direct dependency or with a visible prompt.
158
159  Given the following example::
160
161    config FOO
162	tristate "foo"
163	imply BAZ
164
165    config BAZ
166	tristate "baz"
167	depends on BAR
168
169  The following values are possible:
170
171	===		===		=============	==============
172	FOO		BAR		BAZ's default	choice for BAZ
173	===		===		=============	==============
174	n		y		n		N/m/y
175	m		y		m		M/y/n
176	y		y		y		Y/m/n
177	n		m		n		N/m
178	m		m		m		M/n
179	y		m		n		M/n
180	y		n		*		N
181	===		===		=============	==============
182
183  This is useful e.g. with multiple drivers that want to indicate their
184  ability to hook into a secondary subsystem while allowing the user to
185  configure that subsystem out without also having to unset these drivers.
186
187  Note: If the combination of FOO=y and BAR=m causes a link error,
188  you can guard the function call with IS_REACHABLE()::
189
190	foo_init()
191	{
192		if (IS_REACHABLE(CONFIG_BAZ))
193			baz_register(&foo);
194		...
195	}
196
197  Note: If the feature provided by BAZ is highly desirable for FOO,
198  FOO should imply not only BAZ, but also its dependency BAR::
199
200    config FOO
201	tristate "foo"
202	imply BAR
203	imply BAZ
204
205- limiting menu display: "visible if" <expr>
206
207  This attribute is only applicable to menu blocks, if the condition is
208  false, the menu block is not displayed to the user (the symbols
209  contained there can still be selected by other symbols, though). It is
210  similar to a conditional "prompt" attribute for individual menu
211  entries. Default value of "visible" is true.
212
213- numerical ranges: "range" <symbol> <symbol> ["if" <expr>]
214
215  This allows to limit the range of possible input values for int
216  and hex symbols. The user can only input a value which is larger than
217  or equal to the first symbol and smaller than or equal to the second
218  symbol.
219
220- help text: "help"
221
222  This defines a help text. The end of the help text is determined by
223  the indentation level, this means it ends at the first line which has
224  a smaller indentation than the first line of the help text.
225
226- misc options: "option" <symbol>[=<value>]
227
228  Various less common options can be defined via this option syntax,
229  which can modify the behaviour of the menu entry and its config
230  symbol. These options are currently possible:
231
232  - "defconfig_list"
233    This declares a list of default entries which can be used when
234    looking for the default configuration (which is used when the main
235    .config doesn't exists yet.)
236
237  - "modules"
238    This declares the symbol to be used as the MODULES symbol, which
239    enables the third modular state for all config symbols.
240    At most one symbol may have the "modules" option set.
241
242  - "allnoconfig_y"
243    This declares the symbol as one that should have the value y when
244    using "allnoconfig". Used for symbols that hide other symbols.
245
246Menu dependencies
247-----------------
248
249Dependencies define the visibility of a menu entry and can also reduce
250the input range of tristate symbols. The tristate logic used in the
251expressions uses one more state than normal boolean logic to express the
252module state. Dependency expressions have the following syntax::
253
254  <expr> ::= <symbol>                           (1)
255           <symbol> '=' <symbol>                (2)
256           <symbol> '!=' <symbol>               (3)
257           <symbol1> '<' <symbol2>              (4)
258           <symbol1> '>' <symbol2>              (4)
259           <symbol1> '<=' <symbol2>             (4)
260           <symbol1> '>=' <symbol2>             (4)
261           '(' <expr> ')'                       (5)
262           '!' <expr>                           (6)
263           <expr> '&&' <expr>                   (7)
264           <expr> '||' <expr>                   (8)
265
266Expressions are listed in decreasing order of precedence.
267
268(1) Convert the symbol into an expression. Boolean and tristate symbols
269    are simply converted into the respective expression values. All
270    other symbol types result in 'n'.
271(2) If the values of both symbols are equal, it returns 'y',
272    otherwise 'n'.
273(3) If the values of both symbols are equal, it returns 'n',
274    otherwise 'y'.
275(4) If value of <symbol1> is respectively lower, greater, lower-or-equal,
276    or greater-or-equal than value of <symbol2>, it returns 'y',
277    otherwise 'n'.
278(5) Returns the value of the expression. Used to override precedence.
279(6) Returns the result of (2-/expr/).
280(7) Returns the result of min(/expr/, /expr/).
281(8) Returns the result of max(/expr/, /expr/).
282
283An expression can have a value of 'n', 'm' or 'y' (or 0, 1, 2
284respectively for calculations). A menu entry becomes visible when its
285expression evaluates to 'm' or 'y'.
286
287There are two types of symbols: constant and non-constant symbols.
288Non-constant symbols are the most common ones and are defined with the
289'config' statement. Non-constant symbols consist entirely of alphanumeric
290characters or underscores.
291Constant symbols are only part of expressions. Constant symbols are
292always surrounded by single or double quotes. Within the quote, any
293other character is allowed and the quotes can be escaped using '\'.
294
295Menu structure
296--------------
297
298The position of a menu entry in the tree is determined in two ways. First
299it can be specified explicitly::
300
301  menu "Network device support"
302	depends on NET
303
304  config NETDEVICES
305	...
306
307  endmenu
308
309All entries within the "menu" ... "endmenu" block become a submenu of
310"Network device support". All subentries inherit the dependencies from
311the menu entry, e.g. this means the dependency "NET" is added to the
312dependency list of the config option NETDEVICES.
313
314The other way to generate the menu structure is done by analyzing the
315dependencies. If a menu entry somehow depends on the previous entry, it
316can be made a submenu of it. First, the previous (parent) symbol must
317be part of the dependency list and then one of these two conditions
318must be true:
319
320- the child entry must become invisible, if the parent is set to 'n'
321- the child entry must only be visible, if the parent is visible::
322
323    config MODULES
324	bool "Enable loadable module support"
325
326    config MODVERSIONS
327	bool "Set version information on all module symbols"
328	depends on MODULES
329
330    comment "module support disabled"
331	depends on !MODULES
332
333MODVERSIONS directly depends on MODULES, this means it's only visible if
334MODULES is different from 'n'. The comment on the other hand is only
335visible when MODULES is set to 'n'.
336
337
338Kconfig syntax
339--------------
340
341The configuration file describes a series of menu entries, where every
342line starts with a keyword (except help texts). The following keywords
343end a menu entry:
344
345- config
346- menuconfig
347- choice/endchoice
348- comment
349- menu/endmenu
350- if/endif
351- source
352
353The first five also start the definition of a menu entry.
354
355config::
356
357	"config" <symbol>
358	<config options>
359
360This defines a config symbol <symbol> and accepts any of above
361attributes as options.
362
363menuconfig::
364
365	"menuconfig" <symbol>
366	<config options>
367
368This is similar to the simple config entry above, but it also gives a
369hint to front ends, that all suboptions should be displayed as a
370separate list of options. To make sure all the suboptions will really
371show up under the menuconfig entry and not outside of it, every item
372from the <config options> list must depend on the menuconfig symbol.
373In practice, this is achieved by using one of the next two constructs::
374
375  (1):
376  menuconfig M
377  if M
378      config C1
379      config C2
380  endif
381
382  (2):
383  menuconfig M
384  config C1
385      depends on M
386  config C2
387      depends on M
388
389In the following examples (3) and (4), C1 and C2 still have the M
390dependency, but will not appear under menuconfig M anymore, because
391of C0, which doesn't depend on M::
392
393  (3):
394  menuconfig M
395      config C0
396  if M
397      config C1
398      config C2
399  endif
400
401  (4):
402  menuconfig M
403  config C0
404  config C1
405      depends on M
406  config C2
407      depends on M
408
409choices::
410
411	"choice" [symbol]
412	<choice options>
413	<choice block>
414	"endchoice"
415
416This defines a choice group and accepts any of the above attributes as
417options. A choice can only be of type bool or tristate.  If no type is
418specified for a choice, its type will be determined by the type of
419the first choice element in the group or remain unknown if none of the
420choice elements have a type specified, as well.
421
422While a boolean choice only allows a single config entry to be
423selected, a tristate choice also allows any number of config entries
424to be set to 'm'. This can be used if multiple drivers for a single
425hardware exists and only a single driver can be compiled/loaded into
426the kernel, but all drivers can be compiled as modules.
427
428A choice accepts another option "optional", which allows to set the
429choice to 'n' and no entry needs to be selected.
430If no [symbol] is associated with a choice, then you can not have multiple
431definitions of that choice. If a [symbol] is associated to the choice,
432then you may define the same choice (i.e. with the same entries) in another
433place.
434
435comment::
436
437	"comment" <prompt>
438	<comment options>
439
440This defines a comment which is displayed to the user during the
441configuration process and is also echoed to the output files. The only
442possible options are dependencies.
443
444menu::
445
446	"menu" <prompt>
447	<menu options>
448	<menu block>
449	"endmenu"
450
451This defines a menu block, see "Menu structure" above for more
452information. The only possible options are dependencies and "visible"
453attributes.
454
455if::
456
457	"if" <expr>
458	<if block>
459	"endif"
460
461This defines an if block. The dependency expression <expr> is appended
462to all enclosed menu entries.
463
464source::
465
466	"source" <prompt>
467
468This reads the specified configuration file. This file is always parsed.
469
470mainmenu::
471
472	"mainmenu" <prompt>
473
474This sets the config program's title bar if the config program chooses
475to use it. It should be placed at the top of the configuration, before any
476other statement.
477
478'#' Kconfig source file comment:
479
480An unquoted '#' character anywhere in a source file line indicates
481the beginning of a source file comment.  The remainder of that line
482is a comment.
483
484
485Kconfig hints
486-------------
487This is a collection of Kconfig tips, most of which aren't obvious at
488first glance and most of which have become idioms in several Kconfig
489files.
490
491Adding common features and make the usage configurable
492~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
493It is a common idiom to implement a feature/functionality that are
494relevant for some architectures but not all.
495The recommended way to do so is to use a config variable named HAVE_*
496that is defined in a common Kconfig file and selected by the relevant
497architectures.
498An example is the generic IOMAP functionality.
499
500We would in lib/Kconfig see::
501
502  # Generic IOMAP is used to ...
503  config HAVE_GENERIC_IOMAP
504
505  config GENERIC_IOMAP
506	depends on HAVE_GENERIC_IOMAP && FOO
507
508And in lib/Makefile we would see::
509
510	obj-$(CONFIG_GENERIC_IOMAP) += iomap.o
511
512For each architecture using the generic IOMAP functionality we would see::
513
514  config X86
515	select ...
516	select HAVE_GENERIC_IOMAP
517	select ...
518
519Note: we use the existing config option and avoid creating a new
520config variable to select HAVE_GENERIC_IOMAP.
521
522Note: the use of the internal config variable HAVE_GENERIC_IOMAP, it is
523introduced to overcome the limitation of select which will force a
524config option to 'y' no matter the dependencies.
525The dependencies are moved to the symbol GENERIC_IOMAP and we avoid the
526situation where select forces a symbol equals to 'y'.
527
528Adding features that need compiler support
529~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
530
531There are several features that need compiler support. The recommended way
532to describe the dependency on the compiler feature is to use "depends on"
533followed by a test macro::
534
535  config STACKPROTECTOR
536	bool "Stack Protector buffer overflow detection"
537	depends on $(cc-option,-fstack-protector)
538	...
539
540If you need to expose a compiler capability to makefiles and/or C source files,
541`CC_HAS_` is the recommended prefix for the config option::
542
543  config CC_HAS_STACKPROTECTOR_NONE
544	def_bool $(cc-option,-fno-stack-protector)
545
546Build as module only
547~~~~~~~~~~~~~~~~~~~~
548To restrict a component build to module-only, qualify its config symbol
549with "depends on m".  E.g.::
550
551  config FOO
552	depends on BAR && m
553
554limits FOO to module (=m) or disabled (=n).
555
556Kconfig recursive dependency limitations
557~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
558
559If you've hit the Kconfig error: "recursive dependency detected" you've run
560into a recursive dependency issue with Kconfig, a recursive dependency can be
561summarized as a circular dependency. The kconfig tools need to ensure that
562Kconfig files comply with specified configuration requirements. In order to do
563that kconfig must determine the values that are possible for all Kconfig
564symbols, this is currently not possible if there is a circular relation
565between two or more Kconfig symbols. For more details refer to the "Simple
566Kconfig recursive issue" subsection below. Kconfig does not do recursive
567dependency resolution; this has a few implications for Kconfig file writers.
568We'll first explain why this issues exists and then provide an example
569technical limitation which this brings upon Kconfig developers. Eager
570developers wishing to try to address this limitation should read the next
571subsections.
572
573Simple Kconfig recursive issue
574~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
575
576Read: Documentation/kbuild/Kconfig.recursion-issue-01
577
578Test with::
579
580  make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-01 allnoconfig
581
582Cumulative Kconfig recursive issue
583~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
584
585Read: Documentation/kbuild/Kconfig.recursion-issue-02
586
587Test with::
588
589  make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-02 allnoconfig
590
591Practical solutions to kconfig recursive issue
592~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
593
594Developers who run into the recursive Kconfig issue have two options
595at their disposal. We document them below and also provide a list of
596historical issues resolved through these different solutions.
597
598  a) Remove any superfluous "select FOO" or "depends on FOO"
599  b) Match dependency semantics:
600
601	b1) Swap all "select FOO" to "depends on FOO" or,
602
603	b2) Swap all "depends on FOO" to "select FOO"
604
605The resolution to a) can be tested with the sample Kconfig file
606Documentation/kbuild/Kconfig.recursion-issue-01 through the removal
607of the "select CORE" from CORE_BELL_A_ADVANCED as that is implicit already
608since CORE_BELL_A depends on CORE. At times it may not be possible to remove
609some dependency criteria, for such cases you can work with solution b).
610
611The two different resolutions for b) can be tested in the sample Kconfig file
612Documentation/kbuild/Kconfig.recursion-issue-02.
613
614Below is a list of examples of prior fixes for these types of recursive issues;
615all errors appear to involve one or more "select" statements and one or more
616"depends on".
617
618============    ===================================
619commit          fix
620============    ===================================
62106b718c01208    select A -> depends on A
622c22eacfe82f9    depends on A -> depends on B
6236a91e854442c    select A -> depends on A
624118c565a8f2e    select A -> select B
625f004e5594705    select A -> depends on A
626c7861f37b4c6    depends on A -> (null)
62780c69915e5fb    select A -> (null)              (1)
628c2218e26c0d0    select A -> depends on A        (1)
629d6ae99d04e1c    select A -> depends on A
63095ca19cf8cbf    select A -> depends on A
6318f057d7bca54    depends on A -> (null)
6328f057d7bca54    depends on A -> select A
633a0701f04846e    select A -> depends on A
6340c8b92f7f259    depends on A -> (null)
635e4e9e0540928    select A -> depends on A        (2)
6367453ea886e87    depends on A > (null)           (1)
6377b1fff7e4fdf    select A -> depends on A
63886c747d2a4f0    select A -> depends on A
639d9f9ab51e55e    select A -> depends on A
6400c51a4d8abd6    depends on A -> select A        (3)
641e98062ed6dc4    select A -> depends on A        (3)
64291e5d284a7f1    select A -> (null)
643============    ===================================
644
645(1) Partial (or no) quote of error.
646(2) That seems to be the gist of that fix.
647(3) Same error.
648
649Future kconfig work
650~~~~~~~~~~~~~~~~~~~
651
652Work on kconfig is welcomed on both areas of clarifying semantics and on
653evaluating the use of a full SAT solver for it. A full SAT solver can be
654desirable to enable more complex dependency mappings and / or queries,
655for instance on possible use case for a SAT solver could be that of handling
656the current known recursive dependency issues. It is not known if this would
657address such issues but such evaluation is desirable. If support for a full SAT
658solver proves too complex or that it cannot address recursive dependency issues
659Kconfig should have at least clear and well defined semantics which also
660addresses and documents limitations or requirements such as the ones dealing
661with recursive dependencies.
662
663Further work on both of these areas is welcomed on Kconfig. We elaborate
664on both of these in the next two subsections.
665
666Semantics of Kconfig
667~~~~~~~~~~~~~~~~~~~~
668
669The use of Kconfig is broad, Linux is now only one of Kconfig's users:
670one study has completed a broad analysis of Kconfig use in 12 projects [0]_.
671Despite its widespread use, and although this document does a reasonable job
672in documenting basic Kconfig syntax a more precise definition of Kconfig
673semantics is welcomed. One project deduced Kconfig semantics through
674the use of the xconfig configurator [1]_. Work should be done to confirm if
675the deduced semantics matches our intended Kconfig design goals.
676
677Having well defined semantics can be useful for tools for practical
678evaluation of dependencies, for instance one such case was work to
679express in boolean abstraction of the inferred semantics of Kconfig to
680translate Kconfig logic into boolean formulas and run a SAT solver on this to
681find dead code / features (always inactive), 114 dead features were found in
682Linux using this methodology [1]_ (Section 8: Threats to validity).
683
684Confirming this could prove useful as Kconfig stands as one of the the leading
685industrial variability modeling languages [1]_ [2]_. Its study would help
686evaluate practical uses of such languages, their use was only theoretical
687and real world requirements were not well understood. As it stands though
688only reverse engineering techniques have been used to deduce semantics from
689variability modeling languages such as Kconfig [3]_.
690
691.. [0] http://www.eng.uwaterloo.ca/~shshe/kconfig_semantics.pdf
692.. [1] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf
693.. [2] http://gsd.uwaterloo.ca/sites/default/files/ase241-berger_0.pdf
694.. [3] http://gsd.uwaterloo.ca/sites/default/files/icse2011.pdf
695
696Full SAT solver for Kconfig
697~~~~~~~~~~~~~~~~~~~~~~~~~~~
698
699Although SAT solvers [4]_ haven't yet been used by Kconfig directly, as noted
700in the previous subsection, work has been done however to express in boolean
701abstraction the inferred semantics of Kconfig to translate Kconfig logic into
702boolean formulas and run a SAT solver on it [5]_. Another known related project
703is CADOS [6]_ (former VAMOS [7]_) and the tools, mainly undertaker [8]_, which
704has been introduced first with [9]_.  The basic concept of undertaker is to
705extract variability models from Kconfig and put them together with a
706propositional formula extracted from CPP #ifdefs and build-rules into a SAT
707solver in order to find dead code, dead files, and dead symbols. If using a SAT
708solver is desirable on Kconfig one approach would be to evaluate repurposing
709such efforts somehow on Kconfig. There is enough interest from mentors of
710existing projects to not only help advise how to integrate this work upstream
711but also help maintain it long term. Interested developers should visit:
712
713http://kernelnewbies.org/KernelProjects/kconfig-sat
714
715.. [4] http://www.cs.cornell.edu/~sabhar/chapters/SATSolvers-KR-Handbook.pdf
716.. [5] http://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf
717.. [6] https://cados.cs.fau.de
718.. [7] https://vamos.cs.fau.de
719.. [8] https://undertaker.cs.fau.de
720.. [9] https://www4.cs.fau.de/Publications/2011/tartler_11_eurosys.pdf
721