About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / kbuild / kconfig-language.txt

Custom Search

Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.