xref: /linux/Documentation/kbuild/kconfig-language.rst (revision 45c7f555bf5e716d9c6ffb737e97d4cc9b4c21ef)
1cd238effSMauro Carvalho Chehab================
2cd238effSMauro Carvalho ChehabKconfig Language
3cd238effSMauro Carvalho Chehab================
4cd238effSMauro Carvalho Chehab
5cd238effSMauro Carvalho ChehabIntroduction
6cd238effSMauro Carvalho Chehab------------
7cd238effSMauro Carvalho Chehab
8cd238effSMauro Carvalho ChehabThe configuration database is a collection of configuration options
9cd238effSMauro Carvalho Chehaborganized in a tree structure::
10cd238effSMauro Carvalho Chehab
11cd238effSMauro Carvalho Chehab	+- Code maturity level options
12cd238effSMauro Carvalho Chehab	|  +- Prompt for development and/or incomplete code/drivers
13cd238effSMauro Carvalho Chehab	+- General setup
14cd238effSMauro Carvalho Chehab	|  +- Networking support
15cd238effSMauro Carvalho Chehab	|  +- System V IPC
16cd238effSMauro Carvalho Chehab	|  +- BSD Process Accounting
17cd238effSMauro Carvalho Chehab	|  +- Sysctl support
18cd238effSMauro Carvalho Chehab	+- Loadable module support
19cd238effSMauro Carvalho Chehab	|  +- Enable loadable module support
20cd238effSMauro Carvalho Chehab	|     +- Set version information on all module symbols
21cd238effSMauro Carvalho Chehab	|     +- Kernel module loader
22cd238effSMauro Carvalho Chehab	+- ...
23cd238effSMauro Carvalho Chehab
24cd238effSMauro Carvalho ChehabEvery entry has its own dependencies. These dependencies are used
25cd238effSMauro Carvalho Chehabto determine the visibility of an entry. Any child entry is only
26cd238effSMauro Carvalho Chehabvisible if its parent entry is also visible.
27cd238effSMauro Carvalho Chehab
28cd238effSMauro Carvalho ChehabMenu entries
29cd238effSMauro Carvalho Chehab------------
30cd238effSMauro Carvalho Chehab
31cd238effSMauro Carvalho ChehabMost entries define a config option; all other entries help to organize
32cd238effSMauro Carvalho Chehabthem. A single configuration option is defined like this::
33cd238effSMauro Carvalho Chehab
34cd238effSMauro Carvalho Chehab  config MODVERSIONS
35cd238effSMauro Carvalho Chehab	bool "Set version information on all module symbols"
36cd238effSMauro Carvalho Chehab	depends on MODULES
37cd238effSMauro Carvalho Chehab	help
38cd238effSMauro Carvalho Chehab	  Usually, modules have to be recompiled whenever you switch to a new
39cd238effSMauro Carvalho Chehab	  kernel.  ...
40cd238effSMauro Carvalho Chehab
41cd238effSMauro Carvalho ChehabEvery line starts with a key word and can be followed by multiple
42cd238effSMauro Carvalho Chehabarguments.  "config" starts a new config entry. The following lines
43cd238effSMauro Carvalho Chehabdefine attributes for this config option. Attributes can be the type of
44cd238effSMauro Carvalho Chehabthe config option, input prompt, dependencies, help text and default
45cd238effSMauro Carvalho Chehabvalues. A config option can be defined multiple times with the same
46cd238effSMauro Carvalho Chehabname, but every definition can have only a single input prompt and the
47cd238effSMauro Carvalho Chehabtype must not conflict.
48cd238effSMauro Carvalho Chehab
49cd238effSMauro Carvalho ChehabMenu attributes
50cd238effSMauro Carvalho Chehab---------------
51cd238effSMauro Carvalho Chehab
52cd238effSMauro Carvalho ChehabA menu entry can have a number of attributes. Not all of them are
53cd238effSMauro Carvalho Chehabapplicable everywhere (see syntax).
54cd238effSMauro Carvalho Chehab
55cd238effSMauro Carvalho Chehab- type definition: "bool"/"tristate"/"string"/"hex"/"int"
5616886949SMauro Carvalho Chehab
57cd238effSMauro Carvalho Chehab  Every config option must have a type. There are only two basic types:
58cd238effSMauro Carvalho Chehab  tristate and string; the other types are based on these two. The type
59cd238effSMauro Carvalho Chehab  definition optionally accepts an input prompt, so these two examples
60cd238effSMauro Carvalho Chehab  are equivalent::
61cd238effSMauro Carvalho Chehab
62cd238effSMauro Carvalho Chehab	bool "Networking support"
63cd238effSMauro Carvalho Chehab
64cd238effSMauro Carvalho Chehab  and::
65cd238effSMauro Carvalho Chehab
66cd238effSMauro Carvalho Chehab	bool
67cd238effSMauro Carvalho Chehab	prompt "Networking support"
68cd238effSMauro Carvalho Chehab
69cd238effSMauro Carvalho Chehab- input prompt: "prompt" <prompt> ["if" <expr>]
7016886949SMauro Carvalho Chehab
71cd238effSMauro Carvalho Chehab  Every menu entry can have at most one prompt, which is used to display
72cd238effSMauro Carvalho Chehab  to the user. Optionally dependencies only for this prompt can be added
73cd238effSMauro Carvalho Chehab  with "if".
74cd238effSMauro Carvalho Chehab
75cd238effSMauro Carvalho Chehab- default value: "default" <expr> ["if" <expr>]
7616886949SMauro Carvalho Chehab
77cd238effSMauro Carvalho Chehab  A config option can have any number of default values. If multiple
78cd238effSMauro Carvalho Chehab  default values are visible, only the first defined one is active.
79cd238effSMauro Carvalho Chehab  Default values are not limited to the menu entry where they are
80cd238effSMauro Carvalho Chehab  defined. This means the default can be defined somewhere else or be
81cd238effSMauro Carvalho Chehab  overridden by an earlier definition.
82cd238effSMauro Carvalho Chehab  The default value is only assigned to the config symbol if no other
83cd238effSMauro Carvalho Chehab  value was set by the user (via the input prompt above). If an input
84cd238effSMauro Carvalho Chehab  prompt is visible the default value is presented to the user and can
85cd238effSMauro Carvalho Chehab  be overridden by him.
86cd238effSMauro Carvalho Chehab  Optionally, dependencies only for this default value can be added with
87cd238effSMauro Carvalho Chehab  "if".
88cd238effSMauro Carvalho Chehab
89cd238effSMauro Carvalho Chehab The default value deliberately defaults to 'n' in order to avoid bloating the
90cd238effSMauro Carvalho Chehab build. With few exceptions, new config options should not change this. The
91cd238effSMauro Carvalho Chehab intent is for "make oldconfig" to add as little as possible to the config from
92cd238effSMauro Carvalho Chehab release to release.
93cd238effSMauro Carvalho Chehab
94cd238effSMauro Carvalho Chehab Note:
95cd238effSMauro Carvalho Chehab	Things that merit "default y/m" include:
96cd238effSMauro Carvalho Chehab
97cd238effSMauro Carvalho Chehab	a) A new Kconfig option for something that used to always be built
98cd238effSMauro Carvalho Chehab	   should be "default y".
99cd238effSMauro Carvalho Chehab
100cd238effSMauro Carvalho Chehab	b) A new gatekeeping Kconfig option that hides/shows other Kconfig
101cd238effSMauro Carvalho Chehab	   options (but does not generate any code of its own), should be
102cd238effSMauro Carvalho Chehab	   "default y" so people will see those other options.
103cd238effSMauro Carvalho Chehab
104cd238effSMauro Carvalho Chehab	c) Sub-driver behavior or similar options for a driver that is
105cd238effSMauro Carvalho Chehab	   "default n". This allows you to provide sane defaults.
106cd238effSMauro Carvalho Chehab
107cd238effSMauro Carvalho Chehab	d) Hardware or infrastructure that everybody expects, such as CONFIG_NET
108cd238effSMauro Carvalho Chehab	   or CONFIG_BLOCK. These are rare exceptions.
109cd238effSMauro Carvalho Chehab
110cd238effSMauro Carvalho Chehab- type definition + default value::
111cd238effSMauro Carvalho Chehab
112cd238effSMauro Carvalho Chehab	"def_bool"/"def_tristate" <expr> ["if" <expr>]
113cd238effSMauro Carvalho Chehab
114cd238effSMauro Carvalho Chehab  This is a shorthand notation for a type definition plus a value.
115cd238effSMauro Carvalho Chehab  Optionally dependencies for this default value can be added with "if".
116cd238effSMauro Carvalho Chehab
117cd238effSMauro Carvalho Chehab- dependencies: "depends on" <expr>
11816886949SMauro Carvalho Chehab
119cd238effSMauro Carvalho Chehab  This defines a dependency for this menu entry. If multiple
120cd238effSMauro Carvalho Chehab  dependencies are defined, they are connected with '&&'. Dependencies
121cd238effSMauro Carvalho Chehab  are applied to all other options within this menu entry (which also
122cd238effSMauro Carvalho Chehab  accept an "if" expression), so these two examples are equivalent::
123cd238effSMauro Carvalho Chehab
124cd238effSMauro Carvalho Chehab	bool "foo" if BAR
125cd238effSMauro Carvalho Chehab	default y if BAR
126cd238effSMauro Carvalho Chehab
127cd238effSMauro Carvalho Chehab  and::
128cd238effSMauro Carvalho Chehab
129cd238effSMauro Carvalho Chehab	depends on BAR
130cd238effSMauro Carvalho Chehab	bool "foo"
131cd238effSMauro Carvalho Chehab	default y
132cd238effSMauro Carvalho Chehab
133cd238effSMauro Carvalho Chehab- reverse dependencies: "select" <symbol> ["if" <expr>]
13416886949SMauro Carvalho Chehab
135cd238effSMauro Carvalho Chehab  While normal dependencies reduce the upper limit of a symbol (see
136cd238effSMauro Carvalho Chehab  below), reverse dependencies can be used to force a lower limit of
137cd238effSMauro Carvalho Chehab  another symbol. The value of the current menu symbol is used as the
138cd238effSMauro Carvalho Chehab  minimal value <symbol> can be set to. If <symbol> is selected multiple
139cd238effSMauro Carvalho Chehab  times, the limit is set to the largest selection.
140cd238effSMauro Carvalho Chehab  Reverse dependencies can only be used with boolean or tristate
141cd238effSMauro Carvalho Chehab  symbols.
142cd238effSMauro Carvalho Chehab
143cd238effSMauro Carvalho Chehab  Note:
144cd238effSMauro Carvalho Chehab	select should be used with care. select will force
145cd238effSMauro Carvalho Chehab	a symbol to a value without visiting the dependencies.
146cd238effSMauro Carvalho Chehab	By abusing select you are able to select a symbol FOO even
147cd238effSMauro Carvalho Chehab	if FOO depends on BAR that is not set.
148cd238effSMauro Carvalho Chehab	In general use select only for non-visible symbols
149cd238effSMauro Carvalho Chehab	(no prompts anywhere) and for symbols with no dependencies.
150cd238effSMauro Carvalho Chehab	That will limit the usefulness but on the other hand avoid
151cd238effSMauro Carvalho Chehab	the illegal configurations all over.
152cd238effSMauro Carvalho Chehab
153*45c7f555SMasahiro Yamada	If "select" <symbol> is followed by "if" <expr>, <symbol> will be
154*45c7f555SMasahiro Yamada	selected by the logical AND of the value of the current menu symbol
155*45c7f555SMasahiro Yamada	and <expr>. This means, the lower limit can be downgraded due to the
156*45c7f555SMasahiro Yamada	presence of "if" <expr>. This behavior may seem weird, but we rely on
157*45c7f555SMasahiro Yamada	it. (The future of this behavior is undecided.)
158*45c7f555SMasahiro Yamada
159cd238effSMauro Carvalho Chehab- weak reverse dependencies: "imply" <symbol> ["if" <expr>]
16016886949SMauro Carvalho Chehab
161cd238effSMauro Carvalho Chehab  This is similar to "select" as it enforces a lower limit on another
162cd238effSMauro Carvalho Chehab  symbol except that the "implied" symbol's value may still be set to n
163cd238effSMauro Carvalho Chehab  from a direct dependency or with a visible prompt.
164cd238effSMauro Carvalho Chehab
165cd238effSMauro Carvalho Chehab  Given the following example::
166cd238effSMauro Carvalho Chehab
167cd238effSMauro Carvalho Chehab    config FOO
1683a9dd3ecSMasahiro Yamada	tristate "foo"
169cd238effSMauro Carvalho Chehab	imply BAZ
170cd238effSMauro Carvalho Chehab
171cd238effSMauro Carvalho Chehab    config BAZ
1723a9dd3ecSMasahiro Yamada	tristate "baz"
173cd238effSMauro Carvalho Chehab	depends on BAR
174cd238effSMauro Carvalho Chehab
175cd238effSMauro Carvalho Chehab  The following values are possible:
176cd238effSMauro Carvalho Chehab
177cd238effSMauro Carvalho Chehab	===		===		=============	==============
178cd238effSMauro Carvalho Chehab	FOO		BAR		BAZ's default	choice for BAZ
179cd238effSMauro Carvalho Chehab	===		===		=============	==============
180cd238effSMauro Carvalho Chehab	n		y		n		N/m/y
181cd238effSMauro Carvalho Chehab	m		y		m		M/y/n
182def2fbffSMasahiro Yamada	y		y		y		Y/m/n
1833a9dd3ecSMasahiro Yamada	n		m		n		N/m
1843a9dd3ecSMasahiro Yamada	m		m		m		M/n
185c199d5d0SMiguel Ojeda	y		m		m		M/n
186cd238effSMauro Carvalho Chehab	y		n		*		N
187cd238effSMauro Carvalho Chehab	===		===		=============	==============
188cd238effSMauro Carvalho Chehab
189cd238effSMauro Carvalho Chehab  This is useful e.g. with multiple drivers that want to indicate their
190cd238effSMauro Carvalho Chehab  ability to hook into a secondary subsystem while allowing the user to
191cd238effSMauro Carvalho Chehab  configure that subsystem out without also having to unset these drivers.
192cd238effSMauro Carvalho Chehab
193bf83266aSMasahiro Yamada  Note: If the combination of FOO=y and BAZ=m causes a link error,
194def2fbffSMasahiro Yamada  you can guard the function call with IS_REACHABLE()::
195def2fbffSMasahiro Yamada
196def2fbffSMasahiro Yamada	foo_init()
197def2fbffSMasahiro Yamada	{
198def2fbffSMasahiro Yamada		if (IS_REACHABLE(CONFIG_BAZ))
199def2fbffSMasahiro Yamada			baz_register(&foo);
200def2fbffSMasahiro Yamada		...
201def2fbffSMasahiro Yamada	}
202def2fbffSMasahiro Yamada
2033a9dd3ecSMasahiro Yamada  Note: If the feature provided by BAZ is highly desirable for FOO,
2043a9dd3ecSMasahiro Yamada  FOO should imply not only BAZ, but also its dependency BAR::
2053a9dd3ecSMasahiro Yamada
2063a9dd3ecSMasahiro Yamada    config FOO
2073a9dd3ecSMasahiro Yamada	tristate "foo"
2083a9dd3ecSMasahiro Yamada	imply BAR
2093a9dd3ecSMasahiro Yamada	imply BAZ
2103a9dd3ecSMasahiro Yamada
211*45c7f555SMasahiro Yamada  Note: If "imply" <symbol> is followed by "if" <expr>, the default of <symbol>
212*45c7f555SMasahiro Yamada  will be the logical AND of the value of the current menu symbol and <expr>.
213*45c7f555SMasahiro Yamada  (The future of this behavior is undecided.)
214*45c7f555SMasahiro Yamada
215cd238effSMauro Carvalho Chehab- limiting menu display: "visible if" <expr>
21616886949SMauro Carvalho Chehab
217cd238effSMauro Carvalho Chehab  This attribute is only applicable to menu blocks, if the condition is
218cd238effSMauro Carvalho Chehab  false, the menu block is not displayed to the user (the symbols
219cd238effSMauro Carvalho Chehab  contained there can still be selected by other symbols, though). It is
220cd238effSMauro Carvalho Chehab  similar to a conditional "prompt" attribute for individual menu
221cd238effSMauro Carvalho Chehab  entries. Default value of "visible" is true.
222cd238effSMauro Carvalho Chehab
223cd238effSMauro Carvalho Chehab- numerical ranges: "range" <symbol> <symbol> ["if" <expr>]
22416886949SMauro Carvalho Chehab
225cd238effSMauro Carvalho Chehab  This allows to limit the range of possible input values for int
226cd238effSMauro Carvalho Chehab  and hex symbols. The user can only input a value which is larger than
227cd238effSMauro Carvalho Chehab  or equal to the first symbol and smaller than or equal to the second
228cd238effSMauro Carvalho Chehab  symbol.
229cd238effSMauro Carvalho Chehab
2308f268881SMasahiro Yamada- help text: "help"
23116886949SMauro Carvalho Chehab
232cd238effSMauro Carvalho Chehab  This defines a help text. The end of the help text is determined by
233cd238effSMauro Carvalho Chehab  the indentation level, this means it ends at the first line which has
234cd238effSMauro Carvalho Chehab  a smaller indentation than the first line of the help text.
235cd238effSMauro Carvalho Chehab
2366dd85ff1SMasahiro Yamada- module attribute: "modules"
237cd238effSMauro Carvalho Chehab  This declares the symbol to be used as the MODULES symbol, which
238cd238effSMauro Carvalho Chehab  enables the third modular state for all config symbols.
239cd238effSMauro Carvalho Chehab  At most one symbol may have the "modules" option set.
240cd238effSMauro Carvalho Chehab
241cd238effSMauro Carvalho ChehabMenu dependencies
242cd238effSMauro Carvalho Chehab-----------------
243cd238effSMauro Carvalho Chehab
244cd238effSMauro Carvalho ChehabDependencies define the visibility of a menu entry and can also reduce
245cd238effSMauro Carvalho Chehabthe input range of tristate symbols. The tristate logic used in the
246cd238effSMauro Carvalho Chehabexpressions uses one more state than normal boolean logic to express the
247cd238effSMauro Carvalho Chehabmodule state. Dependency expressions have the following syntax::
248cd238effSMauro Carvalho Chehab
249cd238effSMauro Carvalho Chehab  <expr> ::= <symbol>                           (1)
250cd238effSMauro Carvalho Chehab           <symbol> '=' <symbol>                (2)
251cd238effSMauro Carvalho Chehab           <symbol> '!=' <symbol>               (3)
252cd238effSMauro Carvalho Chehab           <symbol1> '<' <symbol2>              (4)
253cd238effSMauro Carvalho Chehab           <symbol1> '>' <symbol2>              (4)
254cd238effSMauro Carvalho Chehab           <symbol1> '<=' <symbol2>             (4)
255cd238effSMauro Carvalho Chehab           <symbol1> '>=' <symbol2>             (4)
256cd238effSMauro Carvalho Chehab           '(' <expr> ')'                       (5)
257cd238effSMauro Carvalho Chehab           '!' <expr>                           (6)
258cd238effSMauro Carvalho Chehab           <expr> '&&' <expr>                   (7)
259cd238effSMauro Carvalho Chehab           <expr> '||' <expr>                   (8)
260cd238effSMauro Carvalho Chehab
261cd238effSMauro Carvalho ChehabExpressions are listed in decreasing order of precedence.
262cd238effSMauro Carvalho Chehab
263cd238effSMauro Carvalho Chehab(1) Convert the symbol into an expression. Boolean and tristate symbols
264cd238effSMauro Carvalho Chehab    are simply converted into the respective expression values. All
265cd238effSMauro Carvalho Chehab    other symbol types result in 'n'.
266cd238effSMauro Carvalho Chehab(2) If the values of both symbols are equal, it returns 'y',
267cd238effSMauro Carvalho Chehab    otherwise 'n'.
268cd238effSMauro Carvalho Chehab(3) If the values of both symbols are equal, it returns 'n',
269cd238effSMauro Carvalho Chehab    otherwise 'y'.
270cd238effSMauro Carvalho Chehab(4) If value of <symbol1> is respectively lower, greater, lower-or-equal,
271cd238effSMauro Carvalho Chehab    or greater-or-equal than value of <symbol2>, it returns 'y',
272cd238effSMauro Carvalho Chehab    otherwise 'n'.
273cd238effSMauro Carvalho Chehab(5) Returns the value of the expression. Used to override precedence.
274cd238effSMauro Carvalho Chehab(6) Returns the result of (2-/expr/).
275cd238effSMauro Carvalho Chehab(7) Returns the result of min(/expr/, /expr/).
276cd238effSMauro Carvalho Chehab(8) Returns the result of max(/expr/, /expr/).
277cd238effSMauro Carvalho Chehab
278cd238effSMauro Carvalho ChehabAn expression can have a value of 'n', 'm' or 'y' (or 0, 1, 2
279cd238effSMauro Carvalho Chehabrespectively for calculations). A menu entry becomes visible when its
280cd238effSMauro Carvalho Chehabexpression evaluates to 'm' or 'y'.
281cd238effSMauro Carvalho Chehab
282cd238effSMauro Carvalho ChehabThere are two types of symbols: constant and non-constant symbols.
283cd238effSMauro Carvalho ChehabNon-constant symbols are the most common ones and are defined with the
284cd238effSMauro Carvalho Chehab'config' statement. Non-constant symbols consist entirely of alphanumeric
285cd238effSMauro Carvalho Chehabcharacters or underscores.
286cd238effSMauro Carvalho ChehabConstant symbols are only part of expressions. Constant symbols are
287cd238effSMauro Carvalho Chehabalways surrounded by single or double quotes. Within the quote, any
288cd238effSMauro Carvalho Chehabother character is allowed and the quotes can be escaped using '\'.
289cd238effSMauro Carvalho Chehab
290cd238effSMauro Carvalho ChehabMenu structure
291cd238effSMauro Carvalho Chehab--------------
292cd238effSMauro Carvalho Chehab
293cd238effSMauro Carvalho ChehabThe position of a menu entry in the tree is determined in two ways. First
294cd238effSMauro Carvalho Chehabit can be specified explicitly::
295cd238effSMauro Carvalho Chehab
296cd238effSMauro Carvalho Chehab  menu "Network device support"
297cd238effSMauro Carvalho Chehab	depends on NET
298cd238effSMauro Carvalho Chehab
299cd238effSMauro Carvalho Chehab  config NETDEVICES
300cd238effSMauro Carvalho Chehab	...
301cd238effSMauro Carvalho Chehab
302cd238effSMauro Carvalho Chehab  endmenu
303cd238effSMauro Carvalho Chehab
304cd238effSMauro Carvalho ChehabAll entries within the "menu" ... "endmenu" block become a submenu of
305cd238effSMauro Carvalho Chehab"Network device support". All subentries inherit the dependencies from
306cd238effSMauro Carvalho Chehabthe menu entry, e.g. this means the dependency "NET" is added to the
307cd238effSMauro Carvalho Chehabdependency list of the config option NETDEVICES.
308cd238effSMauro Carvalho Chehab
309cd238effSMauro Carvalho ChehabThe other way to generate the menu structure is done by analyzing the
310cd238effSMauro Carvalho Chehabdependencies. If a menu entry somehow depends on the previous entry, it
311cd238effSMauro Carvalho Chehabcan be made a submenu of it. First, the previous (parent) symbol must
312cd238effSMauro Carvalho Chehabbe part of the dependency list and then one of these two conditions
313cd238effSMauro Carvalho Chehabmust be true:
314cd238effSMauro Carvalho Chehab
315cd238effSMauro Carvalho Chehab- the child entry must become invisible, if the parent is set to 'n'
316cd238effSMauro Carvalho Chehab- the child entry must only be visible, if the parent is visible::
317cd238effSMauro Carvalho Chehab
318cd238effSMauro Carvalho Chehab    config MODULES
319cd238effSMauro Carvalho Chehab	bool "Enable loadable module support"
320cd238effSMauro Carvalho Chehab
321cd238effSMauro Carvalho Chehab    config MODVERSIONS
322cd238effSMauro Carvalho Chehab	bool "Set version information on all module symbols"
323cd238effSMauro Carvalho Chehab	depends on MODULES
324cd238effSMauro Carvalho Chehab
325cd238effSMauro Carvalho Chehab    comment "module support disabled"
326cd238effSMauro Carvalho Chehab	depends on !MODULES
327cd238effSMauro Carvalho Chehab
328cd238effSMauro Carvalho ChehabMODVERSIONS directly depends on MODULES, this means it's only visible if
329cd238effSMauro Carvalho ChehabMODULES is different from 'n'. The comment on the other hand is only
330cd238effSMauro Carvalho Chehabvisible when MODULES is set to 'n'.
331cd238effSMauro Carvalho Chehab
332cd238effSMauro Carvalho Chehab
333cd238effSMauro Carvalho ChehabKconfig syntax
334cd238effSMauro Carvalho Chehab--------------
335cd238effSMauro Carvalho Chehab
336cd238effSMauro Carvalho ChehabThe configuration file describes a series of menu entries, where every
337cd238effSMauro Carvalho Chehabline starts with a keyword (except help texts). The following keywords
338cd238effSMauro Carvalho Chehabend a menu entry:
339cd238effSMauro Carvalho Chehab
340cd238effSMauro Carvalho Chehab- config
341cd238effSMauro Carvalho Chehab- menuconfig
342cd238effSMauro Carvalho Chehab- choice/endchoice
343cd238effSMauro Carvalho Chehab- comment
344cd238effSMauro Carvalho Chehab- menu/endmenu
345cd238effSMauro Carvalho Chehab- if/endif
346cd238effSMauro Carvalho Chehab- source
347cd238effSMauro Carvalho Chehab
348cd238effSMauro Carvalho ChehabThe first five also start the definition of a menu entry.
349cd238effSMauro Carvalho Chehab
350cd238effSMauro Carvalho Chehabconfig::
35116886949SMauro Carvalho Chehab
352cd238effSMauro Carvalho Chehab	"config" <symbol>
353cd238effSMauro Carvalho Chehab	<config options>
354cd238effSMauro Carvalho Chehab
355cd238effSMauro Carvalho ChehabThis defines a config symbol <symbol> and accepts any of above
356cd238effSMauro Carvalho Chehabattributes as options.
357cd238effSMauro Carvalho Chehab
358cd238effSMauro Carvalho Chehabmenuconfig::
35916886949SMauro Carvalho Chehab
360cd238effSMauro Carvalho Chehab	"menuconfig" <symbol>
361cd238effSMauro Carvalho Chehab	<config options>
362cd238effSMauro Carvalho Chehab
363cd238effSMauro Carvalho ChehabThis is similar to the simple config entry above, but it also gives a
364cd238effSMauro Carvalho Chehabhint to front ends, that all suboptions should be displayed as a
365cd238effSMauro Carvalho Chehabseparate list of options. To make sure all the suboptions will really
366cd238effSMauro Carvalho Chehabshow up under the menuconfig entry and not outside of it, every item
367cd238effSMauro Carvalho Chehabfrom the <config options> list must depend on the menuconfig symbol.
368cd238effSMauro Carvalho ChehabIn practice, this is achieved by using one of the next two constructs::
369cd238effSMauro Carvalho Chehab
370cd238effSMauro Carvalho Chehab  (1):
371cd238effSMauro Carvalho Chehab  menuconfig M
372cd238effSMauro Carvalho Chehab  if M
373cd238effSMauro Carvalho Chehab      config C1
374cd238effSMauro Carvalho Chehab      config C2
375cd238effSMauro Carvalho Chehab  endif
376cd238effSMauro Carvalho Chehab
377cd238effSMauro Carvalho Chehab  (2):
378cd238effSMauro Carvalho Chehab  menuconfig M
379cd238effSMauro Carvalho Chehab  config C1
380cd238effSMauro Carvalho Chehab      depends on M
381cd238effSMauro Carvalho Chehab  config C2
382cd238effSMauro Carvalho Chehab      depends on M
383cd238effSMauro Carvalho Chehab
384cd238effSMauro Carvalho ChehabIn the following examples (3) and (4), C1 and C2 still have the M
385cd238effSMauro Carvalho Chehabdependency, but will not appear under menuconfig M anymore, because
386cd238effSMauro Carvalho Chehabof C0, which doesn't depend on M::
387cd238effSMauro Carvalho Chehab
388cd238effSMauro Carvalho Chehab  (3):
389cd238effSMauro Carvalho Chehab  menuconfig M
390cd238effSMauro Carvalho Chehab      config C0
391cd238effSMauro Carvalho Chehab  if M
392cd238effSMauro Carvalho Chehab      config C1
393cd238effSMauro Carvalho Chehab      config C2
394cd238effSMauro Carvalho Chehab  endif
395cd238effSMauro Carvalho Chehab
396cd238effSMauro Carvalho Chehab  (4):
397cd238effSMauro Carvalho Chehab  menuconfig M
398cd238effSMauro Carvalho Chehab  config C0
399cd238effSMauro Carvalho Chehab  config C1
400cd238effSMauro Carvalho Chehab      depends on M
401cd238effSMauro Carvalho Chehab  config C2
402cd238effSMauro Carvalho Chehab      depends on M
403cd238effSMauro Carvalho Chehab
404cd238effSMauro Carvalho Chehabchoices::
405cd238effSMauro Carvalho Chehab
406c83f0209SMasahiro Yamada	"choice"
407cd238effSMauro Carvalho Chehab	<choice options>
408cd238effSMauro Carvalho Chehab	<choice block>
409cd238effSMauro Carvalho Chehab	"endchoice"
410cd238effSMauro Carvalho Chehab
411cd238effSMauro Carvalho ChehabThis defines a choice group and accepts any of the above attributes as
412cd238effSMauro Carvalho Chehaboptions. A choice can only be of type bool or tristate.  If no type is
413cd238effSMauro Carvalho Chehabspecified for a choice, its type will be determined by the type of
414cd238effSMauro Carvalho Chehabthe first choice element in the group or remain unknown if none of the
415cd238effSMauro Carvalho Chehabchoice elements have a type specified, as well.
416cd238effSMauro Carvalho Chehab
417cd238effSMauro Carvalho ChehabWhile a boolean choice only allows a single config entry to be
418cd238effSMauro Carvalho Chehabselected, a tristate choice also allows any number of config entries
419cd238effSMauro Carvalho Chehabto be set to 'm'. This can be used if multiple drivers for a single
420cd238effSMauro Carvalho Chehabhardware exists and only a single driver can be compiled/loaded into
421cd238effSMauro Carvalho Chehabthe kernel, but all drivers can be compiled as modules.
422cd238effSMauro Carvalho Chehab
423cd238effSMauro Carvalho Chehabcomment::
424cd238effSMauro Carvalho Chehab
425cd238effSMauro Carvalho Chehab	"comment" <prompt>
426cd238effSMauro Carvalho Chehab	<comment options>
427cd238effSMauro Carvalho Chehab
428cd238effSMauro Carvalho ChehabThis defines a comment which is displayed to the user during the
429cd238effSMauro Carvalho Chehabconfiguration process and is also echoed to the output files. The only
430cd238effSMauro Carvalho Chehabpossible options are dependencies.
431cd238effSMauro Carvalho Chehab
432cd238effSMauro Carvalho Chehabmenu::
433cd238effSMauro Carvalho Chehab
434cd238effSMauro Carvalho Chehab	"menu" <prompt>
435cd238effSMauro Carvalho Chehab	<menu options>
436cd238effSMauro Carvalho Chehab	<menu block>
437cd238effSMauro Carvalho Chehab	"endmenu"
438cd238effSMauro Carvalho Chehab
439cd238effSMauro Carvalho ChehabThis defines a menu block, see "Menu structure" above for more
440cd238effSMauro Carvalho Chehabinformation. The only possible options are dependencies and "visible"
441cd238effSMauro Carvalho Chehabattributes.
442cd238effSMauro Carvalho Chehab
443cd238effSMauro Carvalho Chehabif::
444cd238effSMauro Carvalho Chehab
445cd238effSMauro Carvalho Chehab	"if" <expr>
446cd238effSMauro Carvalho Chehab	<if block>
447cd238effSMauro Carvalho Chehab	"endif"
448cd238effSMauro Carvalho Chehab
449cd238effSMauro Carvalho ChehabThis defines an if block. The dependency expression <expr> is appended
450cd238effSMauro Carvalho Chehabto all enclosed menu entries.
451cd238effSMauro Carvalho Chehab
452cd238effSMauro Carvalho Chehabsource::
453cd238effSMauro Carvalho Chehab
454cd238effSMauro Carvalho Chehab	"source" <prompt>
455cd238effSMauro Carvalho Chehab
456cd238effSMauro Carvalho ChehabThis reads the specified configuration file. This file is always parsed.
457cd238effSMauro Carvalho Chehab
458cd238effSMauro Carvalho Chehabmainmenu::
459cd238effSMauro Carvalho Chehab
460cd238effSMauro Carvalho Chehab	"mainmenu" <prompt>
461cd238effSMauro Carvalho Chehab
462cd238effSMauro Carvalho ChehabThis sets the config program's title bar if the config program chooses
463cd238effSMauro Carvalho Chehabto use it. It should be placed at the top of the configuration, before any
464cd238effSMauro Carvalho Chehabother statement.
465cd238effSMauro Carvalho Chehab
466cd238effSMauro Carvalho Chehab'#' Kconfig source file comment:
467cd238effSMauro Carvalho Chehab
468cd238effSMauro Carvalho ChehabAn unquoted '#' character anywhere in a source file line indicates
469cd238effSMauro Carvalho Chehabthe beginning of a source file comment.  The remainder of that line
470cd238effSMauro Carvalho Chehabis a comment.
471cd238effSMauro Carvalho Chehab
472cd238effSMauro Carvalho Chehab
473cd238effSMauro Carvalho ChehabKconfig hints
474cd238effSMauro Carvalho Chehab-------------
475cd238effSMauro Carvalho ChehabThis is a collection of Kconfig tips, most of which aren't obvious at
476cd238effSMauro Carvalho Chehabfirst glance and most of which have become idioms in several Kconfig
477cd238effSMauro Carvalho Chehabfiles.
478cd238effSMauro Carvalho Chehab
479cd238effSMauro Carvalho ChehabAdding common features and make the usage configurable
480cd238effSMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
481cd238effSMauro Carvalho ChehabIt is a common idiom to implement a feature/functionality that are
482cd238effSMauro Carvalho Chehabrelevant for some architectures but not all.
483cd238effSMauro Carvalho ChehabThe recommended way to do so is to use a config variable named HAVE_*
484cd238effSMauro Carvalho Chehabthat is defined in a common Kconfig file and selected by the relevant
485cd238effSMauro Carvalho Chehabarchitectures.
486cd238effSMauro Carvalho ChehabAn example is the generic IOMAP functionality.
487cd238effSMauro Carvalho Chehab
488cd238effSMauro Carvalho ChehabWe would in lib/Kconfig see::
489cd238effSMauro Carvalho Chehab
490cd238effSMauro Carvalho Chehab  # Generic IOMAP is used to ...
491cd238effSMauro Carvalho Chehab  config HAVE_GENERIC_IOMAP
492cd238effSMauro Carvalho Chehab
493cd238effSMauro Carvalho Chehab  config GENERIC_IOMAP
494cd238effSMauro Carvalho Chehab	depends on HAVE_GENERIC_IOMAP && FOO
495cd238effSMauro Carvalho Chehab
496cd238effSMauro Carvalho ChehabAnd in lib/Makefile we would see::
497cd238effSMauro Carvalho Chehab
498cd238effSMauro Carvalho Chehab	obj-$(CONFIG_GENERIC_IOMAP) += iomap.o
499cd238effSMauro Carvalho Chehab
500cd238effSMauro Carvalho ChehabFor each architecture using the generic IOMAP functionality we would see::
501cd238effSMauro Carvalho Chehab
502cd238effSMauro Carvalho Chehab  config X86
503cd238effSMauro Carvalho Chehab	select ...
504cd238effSMauro Carvalho Chehab	select HAVE_GENERIC_IOMAP
505cd238effSMauro Carvalho Chehab	select ...
506cd238effSMauro Carvalho Chehab
507cd238effSMauro Carvalho ChehabNote: we use the existing config option and avoid creating a new
508cd238effSMauro Carvalho Chehabconfig variable to select HAVE_GENERIC_IOMAP.
509cd238effSMauro Carvalho Chehab
510cd238effSMauro Carvalho ChehabNote: the use of the internal config variable HAVE_GENERIC_IOMAP, it is
511cd238effSMauro Carvalho Chehabintroduced to overcome the limitation of select which will force a
512cd238effSMauro Carvalho Chehabconfig option to 'y' no matter the dependencies.
513cd238effSMauro Carvalho ChehabThe dependencies are moved to the symbol GENERIC_IOMAP and we avoid the
514cd238effSMauro Carvalho Chehabsituation where select forces a symbol equals to 'y'.
515cd238effSMauro Carvalho Chehab
516cd238effSMauro Carvalho ChehabAdding features that need compiler support
517cd238effSMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
518cd238effSMauro Carvalho Chehab
519cd238effSMauro Carvalho ChehabThere are several features that need compiler support. The recommended way
520cd238effSMauro Carvalho Chehabto describe the dependency on the compiler feature is to use "depends on"
521cd238effSMauro Carvalho Chehabfollowed by a test macro::
522cd238effSMauro Carvalho Chehab
523cd238effSMauro Carvalho Chehab  config STACKPROTECTOR
524cd238effSMauro Carvalho Chehab	bool "Stack Protector buffer overflow detection"
525cd238effSMauro Carvalho Chehab	depends on $(cc-option,-fstack-protector)
526cd238effSMauro Carvalho Chehab	...
527cd238effSMauro Carvalho Chehab
528cd238effSMauro Carvalho ChehabIf you need to expose a compiler capability to makefiles and/or C source files,
529cd238effSMauro Carvalho Chehab`CC_HAS_` is the recommended prefix for the config option::
530cd238effSMauro Carvalho Chehab
531a0a12c3eSNick Desaulniers  config CC_HAS_FOO
532a0a12c3eSNick Desaulniers	def_bool $(success,$(srctree)/scripts/cc-check-foo.sh $(CC))
533cd238effSMauro Carvalho Chehab
534cd238effSMauro Carvalho ChehabBuild as module only
535cd238effSMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~
536cd238effSMauro Carvalho ChehabTo restrict a component build to module-only, qualify its config symbol
537cd238effSMauro Carvalho Chehabwith "depends on m".  E.g.::
538cd238effSMauro Carvalho Chehab
539cd238effSMauro Carvalho Chehab  config FOO
540cd238effSMauro Carvalho Chehab	depends on BAR && m
541cd238effSMauro Carvalho Chehab
542cd238effSMauro Carvalho Chehablimits FOO to module (=m) or disabled (=n).
543cd238effSMauro Carvalho Chehab
544c613583bSGeert UytterhoevenCompile-testing
545c613583bSGeert Uytterhoeven~~~~~~~~~~~~~~~
546c613583bSGeert UytterhoevenIf a config symbol has a dependency, but the code controlled by the config
547c613583bSGeert Uytterhoevensymbol can still be compiled if the dependency is not met, it is encouraged to
548c613583bSGeert Uytterhoevenincrease build coverage by adding an "|| COMPILE_TEST" clause to the
549c613583bSGeert Uytterhoevendependency. This is especially useful for drivers for more exotic hardware, as
550c613583bSGeert Uytterhoevenit allows continuous-integration systems to compile-test the code on a more
551c613583bSGeert Uytterhoevencommon system, and detect bugs that way.
552c613583bSGeert UytterhoevenNote that compile-tested code should avoid crashing when run on a system where
553c613583bSGeert Uytterhoeventhe dependency is not met.
554c613583bSGeert Uytterhoeven
55518084e43SGeert UytterhoevenArchitecture and platform dependencies
55618084e43SGeert Uytterhoeven~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
55718084e43SGeert UytterhoevenDue to the presence of stubs, most drivers can now be compiled on most
55818084e43SGeert Uytterhoevenarchitectures. However, this does not mean it makes sense to have all drivers
55918084e43SGeert Uytterhoevenavailable everywhere, as the actual hardware may only exist on specific
56018084e43SGeert Uytterhoevenarchitectures and platforms. This is especially true for on-SoC IP cores,
56118084e43SGeert Uytterhoevenwhich may be limited to a specific vendor or SoC family.
56218084e43SGeert Uytterhoeven
56318084e43SGeert UytterhoevenTo prevent asking the user about drivers that cannot be used on the system(s)
56418084e43SGeert Uytterhoeventhe user is compiling a kernel for, and if it makes sense, config symbols
56518084e43SGeert Uytterhoevencontrolling the compilation of a driver should contain proper dependencies,
56618084e43SGeert Uytterhoevenlimiting the visibility of the symbol to (a superset of) the platform(s) the
56718084e43SGeert Uytterhoevendriver can be used on. The dependency can be an architecture (e.g. ARM) or
56818084e43SGeert Uytterhoevenplatform (e.g. ARCH_OMAP4) dependency. This makes life simpler not only for
56918084e43SGeert Uytterhoevendistro config owners, but also for every single developer or user who
57018084e43SGeert Uytterhoevenconfigures a kernel.
57118084e43SGeert Uytterhoeven
57218084e43SGeert UytterhoevenSuch a dependency can be relaxed by combining it with the compile-testing rule
57318084e43SGeert Uytterhoevenabove, leading to:
57418084e43SGeert Uytterhoeven
57518084e43SGeert Uytterhoeven  config FOO
57618084e43SGeert Uytterhoeven	bool "Support for foo hardware"
57718084e43SGeert Uytterhoeven	depends on ARCH_FOO_VENDOR || COMPILE_TEST
57818084e43SGeert Uytterhoeven
57928d49e17SArnd BergmannOptional dependencies
58028d49e17SArnd Bergmann~~~~~~~~~~~~~~~~~~~~~
58128d49e17SArnd Bergmann
58228d49e17SArnd BergmannSome drivers are able to optionally use a feature from another module
58328d49e17SArnd Bergmannor build cleanly with that module disabled, but cause a link failure
58428d49e17SArnd Bergmannwhen trying to use that loadable module from a built-in driver.
58528d49e17SArnd Bergmann
58628d49e17SArnd BergmannThe most common way to express this optional dependency in Kconfig logic
58728d49e17SArnd Bergmannuses the slightly counterintuitive::
58828d49e17SArnd Bergmann
58928d49e17SArnd Bergmann  config FOO
59028d49e17SArnd Bergmann	tristate "Support for foo hardware"
59128d49e17SArnd Bergmann	depends on BAR || !BAR
59228d49e17SArnd Bergmann
59328d49e17SArnd BergmannThis means that there is either a dependency on BAR that disallows
59428d49e17SArnd Bergmannthe combination of FOO=y with BAR=m, or BAR is completely disabled.
59528d49e17SArnd BergmannFor a more formalized approach if there are multiple drivers that have
59628d49e17SArnd Bergmannthe same dependency, a helper symbol can be used, like::
59728d49e17SArnd Bergmann
59828d49e17SArnd Bergmann  config FOO
59928d49e17SArnd Bergmann	tristate "Support for foo hardware"
60028d49e17SArnd Bergmann	depends on BAR_OPTIONAL
60128d49e17SArnd Bergmann
60228d49e17SArnd Bergmann  config BAR_OPTIONAL
60328d49e17SArnd Bergmann	def_tristate BAR || !BAR
60428d49e17SArnd Bergmann
605cd238effSMauro Carvalho ChehabKconfig recursive dependency limitations
606cd238effSMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
607cd238effSMauro Carvalho Chehab
608cd238effSMauro Carvalho ChehabIf you've hit the Kconfig error: "recursive dependency detected" you've run
609cd238effSMauro Carvalho Chehabinto a recursive dependency issue with Kconfig, a recursive dependency can be
610cd238effSMauro Carvalho Chehabsummarized as a circular dependency. The kconfig tools need to ensure that
611cd238effSMauro Carvalho ChehabKconfig files comply with specified configuration requirements. In order to do
612cd238effSMauro Carvalho Chehabthat kconfig must determine the values that are possible for all Kconfig
613cd238effSMauro Carvalho Chehabsymbols, this is currently not possible if there is a circular relation
614cd238effSMauro Carvalho Chehabbetween two or more Kconfig symbols. For more details refer to the "Simple
615cd238effSMauro Carvalho ChehabKconfig recursive issue" subsection below. Kconfig does not do recursive
616cd238effSMauro Carvalho Chehabdependency resolution; this has a few implications for Kconfig file writers.
617cd238effSMauro Carvalho ChehabWe'll first explain why this issues exists and then provide an example
618cd238effSMauro Carvalho Chehabtechnical limitation which this brings upon Kconfig developers. Eager
619cd238effSMauro Carvalho Chehabdevelopers wishing to try to address this limitation should read the next
620cd238effSMauro Carvalho Chehabsubsections.
621cd238effSMauro Carvalho Chehab
622cd238effSMauro Carvalho ChehabSimple Kconfig recursive issue
623cd238effSMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
624cd238effSMauro Carvalho Chehab
625cd238effSMauro Carvalho ChehabRead: Documentation/kbuild/Kconfig.recursion-issue-01
626cd238effSMauro Carvalho Chehab
627cd238effSMauro Carvalho ChehabTest with::
628cd238effSMauro Carvalho Chehab
629cd238effSMauro Carvalho Chehab  make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-01 allnoconfig
630cd238effSMauro Carvalho Chehab
631cd238effSMauro Carvalho ChehabCumulative Kconfig recursive issue
632cd238effSMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
633cd238effSMauro Carvalho Chehab
634cd238effSMauro Carvalho ChehabRead: Documentation/kbuild/Kconfig.recursion-issue-02
635cd238effSMauro Carvalho Chehab
636cd238effSMauro Carvalho ChehabTest with::
637cd238effSMauro Carvalho Chehab
638cd238effSMauro Carvalho Chehab  make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-02 allnoconfig
639cd238effSMauro Carvalho Chehab
640cd238effSMauro Carvalho ChehabPractical solutions to kconfig recursive issue
641cd238effSMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
642cd238effSMauro Carvalho Chehab
643cd238effSMauro Carvalho ChehabDevelopers who run into the recursive Kconfig issue have two options
644cd238effSMauro Carvalho Chehabat their disposal. We document them below and also provide a list of
645cd238effSMauro Carvalho Chehabhistorical issues resolved through these different solutions.
646cd238effSMauro Carvalho Chehab
647cd238effSMauro Carvalho Chehab  a) Remove any superfluous "select FOO" or "depends on FOO"
648cd238effSMauro Carvalho Chehab  b) Match dependency semantics:
649cd238effSMauro Carvalho Chehab
650cd238effSMauro Carvalho Chehab	b1) Swap all "select FOO" to "depends on FOO" or,
651cd238effSMauro Carvalho Chehab
652cd238effSMauro Carvalho Chehab	b2) Swap all "depends on FOO" to "select FOO"
653cd238effSMauro Carvalho Chehab
654cd238effSMauro Carvalho ChehabThe resolution to a) can be tested with the sample Kconfig file
655cd238effSMauro Carvalho ChehabDocumentation/kbuild/Kconfig.recursion-issue-01 through the removal
656cd238effSMauro Carvalho Chehabof the "select CORE" from CORE_BELL_A_ADVANCED as that is implicit already
657cd238effSMauro Carvalho Chehabsince CORE_BELL_A depends on CORE. At times it may not be possible to remove
658cd238effSMauro Carvalho Chehabsome dependency criteria, for such cases you can work with solution b).
659cd238effSMauro Carvalho Chehab
660cd238effSMauro Carvalho ChehabThe two different resolutions for b) can be tested in the sample Kconfig file
661cd238effSMauro Carvalho ChehabDocumentation/kbuild/Kconfig.recursion-issue-02.
662cd238effSMauro Carvalho Chehab
663cd238effSMauro Carvalho ChehabBelow is a list of examples of prior fixes for these types of recursive issues;
6642b5072b9SBjorn Helgaasall errors appear to involve one or more "select" statements and one or more
6652b5072b9SBjorn Helgaas"depends on".
666cd238effSMauro Carvalho Chehab
667cd238effSMauro Carvalho Chehab============    ===================================
668cd238effSMauro Carvalho Chehabcommit          fix
669cd238effSMauro Carvalho Chehab============    ===================================
670cd238effSMauro Carvalho Chehab06b718c01208    select A -> depends on A
671cd238effSMauro Carvalho Chehabc22eacfe82f9    depends on A -> depends on B
672cd238effSMauro Carvalho Chehab6a91e854442c    select A -> depends on A
673cd238effSMauro Carvalho Chehab118c565a8f2e    select A -> select B
674cd238effSMauro Carvalho Chehabf004e5594705    select A -> depends on A
675cd238effSMauro Carvalho Chehabc7861f37b4c6    depends on A -> (null)
676cd238effSMauro Carvalho Chehab80c69915e5fb    select A -> (null)              (1)
677cd238effSMauro Carvalho Chehabc2218e26c0d0    select A -> depends on A        (1)
678cd238effSMauro Carvalho Chehabd6ae99d04e1c    select A -> depends on A
679cd238effSMauro Carvalho Chehab95ca19cf8cbf    select A -> depends on A
680cd238effSMauro Carvalho Chehab8f057d7bca54    depends on A -> (null)
681cd238effSMauro Carvalho Chehab8f057d7bca54    depends on A -> select A
682cd238effSMauro Carvalho Chehaba0701f04846e    select A -> depends on A
683cd238effSMauro Carvalho Chehab0c8b92f7f259    depends on A -> (null)
684cd238effSMauro Carvalho Chehabe4e9e0540928    select A -> depends on A        (2)
685cd238effSMauro Carvalho Chehab7453ea886e87    depends on A > (null)           (1)
686cd238effSMauro Carvalho Chehab7b1fff7e4fdf    select A -> depends on A
687cd238effSMauro Carvalho Chehab86c747d2a4f0    select A -> depends on A
688cd238effSMauro Carvalho Chehabd9f9ab51e55e    select A -> depends on A
689cd238effSMauro Carvalho Chehab0c51a4d8abd6    depends on A -> select A        (3)
690cd238effSMauro Carvalho Chehabe98062ed6dc4    select A -> depends on A        (3)
691cd238effSMauro Carvalho Chehab91e5d284a7f1    select A -> (null)
692cd238effSMauro Carvalho Chehab============    ===================================
693cd238effSMauro Carvalho Chehab
694cd238effSMauro Carvalho Chehab(1) Partial (or no) quote of error.
695cd238effSMauro Carvalho Chehab(2) That seems to be the gist of that fix.
696cd238effSMauro Carvalho Chehab(3) Same error.
697cd238effSMauro Carvalho Chehab
698cd238effSMauro Carvalho ChehabFuture kconfig work
699cd238effSMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~
700cd238effSMauro Carvalho Chehab
701cd238effSMauro Carvalho ChehabWork on kconfig is welcomed on both areas of clarifying semantics and on
702cd238effSMauro Carvalho Chehabevaluating the use of a full SAT solver for it. A full SAT solver can be
703cd238effSMauro Carvalho Chehabdesirable to enable more complex dependency mappings and / or queries,
70459316eacSBaruch Siachfor instance one possible use case for a SAT solver could be that of handling
705cd238effSMauro Carvalho Chehabthe current known recursive dependency issues. It is not known if this would
706cd238effSMauro Carvalho Chehabaddress such issues but such evaluation is desirable. If support for a full SAT
707cd238effSMauro Carvalho Chehabsolver proves too complex or that it cannot address recursive dependency issues
708cd238effSMauro Carvalho ChehabKconfig should have at least clear and well defined semantics which also
709cd238effSMauro Carvalho Chehabaddresses and documents limitations or requirements such as the ones dealing
710cd238effSMauro Carvalho Chehabwith recursive dependencies.
711cd238effSMauro Carvalho Chehab
712cd238effSMauro Carvalho ChehabFurther work on both of these areas is welcomed on Kconfig. We elaborate
713cd238effSMauro Carvalho Chehabon both of these in the next two subsections.
714cd238effSMauro Carvalho Chehab
715cd238effSMauro Carvalho ChehabSemantics of Kconfig
716cd238effSMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~
717cd238effSMauro Carvalho Chehab
718cd238effSMauro Carvalho ChehabThe use of Kconfig is broad, Linux is now only one of Kconfig's users:
719cd238effSMauro Carvalho Chehabone study has completed a broad analysis of Kconfig use in 12 projects [0]_.
720cd238effSMauro Carvalho ChehabDespite its widespread use, and although this document does a reasonable job
721cd238effSMauro Carvalho Chehabin documenting basic Kconfig syntax a more precise definition of Kconfig
722cd238effSMauro Carvalho Chehabsemantics is welcomed. One project deduced Kconfig semantics through
723cd238effSMauro Carvalho Chehabthe use of the xconfig configurator [1]_. Work should be done to confirm if
724cd238effSMauro Carvalho Chehabthe deduced semantics matches our intended Kconfig design goals.
725cab802b7SNecip Fazil YildiranAnother project formalized a denotational semantics of a core subset of
726cab802b7SNecip Fazil Yildiranthe Kconfig language [10]_.
727cd238effSMauro Carvalho Chehab
728cd238effSMauro Carvalho ChehabHaving well defined semantics can be useful for tools for practical
7292b5072b9SBjorn Helgaasevaluation of dependencies, for instance one such case was work to
730cd238effSMauro Carvalho Chehabexpress in boolean abstraction of the inferred semantics of Kconfig to
731cd238effSMauro Carvalho Chehabtranslate Kconfig logic into boolean formulas and run a SAT solver on this to
732cd238effSMauro Carvalho Chehabfind dead code / features (always inactive), 114 dead features were found in
733cd238effSMauro Carvalho ChehabLinux using this methodology [1]_ (Section 8: Threats to validity).
734cab802b7SNecip Fazil YildiranThe kismet tool, based on the semantics in [10]_, finds abuses of reverse
735cab802b7SNecip Fazil Yildirandependencies and has led to dozens of committed fixes to Linux Kconfig files [11]_.
736cd238effSMauro Carvalho Chehab
73714bee167SRandy DunlapConfirming this could prove useful as Kconfig stands as one of the leading
738cd238effSMauro Carvalho Chehabindustrial variability modeling languages [1]_ [2]_. Its study would help
739cd238effSMauro Carvalho Chehabevaluate practical uses of such languages, their use was only theoretical
740cd238effSMauro Carvalho Chehaband real world requirements were not well understood. As it stands though
741cd238effSMauro Carvalho Chehabonly reverse engineering techniques have been used to deduce semantics from
742cd238effSMauro Carvalho Chehabvariability modeling languages such as Kconfig [3]_.
743cd238effSMauro Carvalho Chehab
74416a122c7SAlexander A. Klimov.. [0] https://www.eng.uwaterloo.ca/~shshe/kconfig_semantics.pdf
74516a122c7SAlexander A. Klimov.. [1] https://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf
74616a122c7SAlexander A. Klimov.. [2] https://gsd.uwaterloo.ca/sites/default/files/ase241-berger_0.pdf
74716a122c7SAlexander A. Klimov.. [3] https://gsd.uwaterloo.ca/sites/default/files/icse2011.pdf
748cd238effSMauro Carvalho Chehab
749cd238effSMauro Carvalho ChehabFull SAT solver for Kconfig
750cd238effSMauro Carvalho Chehab~~~~~~~~~~~~~~~~~~~~~~~~~~~
751cd238effSMauro Carvalho Chehab
752cd238effSMauro Carvalho ChehabAlthough SAT solvers [4]_ haven't yet been used by Kconfig directly, as noted
753cd238effSMauro Carvalho Chehabin the previous subsection, work has been done however to express in boolean
754cd238effSMauro Carvalho Chehababstraction the inferred semantics of Kconfig to translate Kconfig logic into
755cd238effSMauro Carvalho Chehabboolean formulas and run a SAT solver on it [5]_. Another known related project
756cd238effSMauro Carvalho Chehabis CADOS [6]_ (former VAMOS [7]_) and the tools, mainly undertaker [8]_, which
757cd238effSMauro Carvalho Chehabhas been introduced first with [9]_.  The basic concept of undertaker is to
7582b5072b9SBjorn Helgaasextract variability models from Kconfig and put them together with a
759cd238effSMauro Carvalho Chehabpropositional formula extracted from CPP #ifdefs and build-rules into a SAT
760cd238effSMauro Carvalho Chehabsolver in order to find dead code, dead files, and dead symbols. If using a SAT
761cd238effSMauro Carvalho Chehabsolver is desirable on Kconfig one approach would be to evaluate repurposing
762cd238effSMauro Carvalho Chehabsuch efforts somehow on Kconfig. There is enough interest from mentors of
763cd238effSMauro Carvalho Chehabexisting projects to not only help advise how to integrate this work upstream
764cd238effSMauro Carvalho Chehabbut also help maintain it long term. Interested developers should visit:
765cd238effSMauro Carvalho Chehab
76616a122c7SAlexander A. Klimovhttps://kernelnewbies.org/KernelProjects/kconfig-sat
767cd238effSMauro Carvalho Chehab
76816a122c7SAlexander A. Klimov.. [4] https://www.cs.cornell.edu/~sabhar/chapters/SATSolvers-KR-Handbook.pdf
76916a122c7SAlexander A. Klimov.. [5] https://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf
770cd238effSMauro Carvalho Chehab.. [6] https://cados.cs.fau.de
771cd238effSMauro Carvalho Chehab.. [7] https://vamos.cs.fau.de
772cd238effSMauro Carvalho Chehab.. [8] https://undertaker.cs.fau.de
773cd238effSMauro Carvalho Chehab.. [9] https://www4.cs.fau.de/Publications/2011/tartler_11_eurosys.pdf
774cab802b7SNecip Fazil Yildiran.. [10] https://paulgazzillo.com/papers/esecfse21.pdf
775cab802b7SNecip Fazil Yildiran.. [11] https://github.com/paulgazz/kmax
776