]>
Commit | Line | Data |
---|---|---|
cd238eff MCC |
1 | ================ |
2 | Kconfig Language | |
3 | ================ | |
4 | ||
1da177e4 LT |
5 | Introduction |
6 | ------------ | |
7 | ||
e95be9a5 | 8 | The configuration database is a collection of configuration options |
cd238eff | 9 | organized in a tree structure:: |
1da177e4 LT |
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 | ||
24 | Every entry has its own dependencies. These dependencies are used | |
25 | to determine the visibility of an entry. Any child entry is only | |
26 | visible if its parent entry is also visible. | |
27 | ||
28 | Menu entries | |
29 | ------------ | |
30 | ||
0486bc90 | 31 | Most entries define a config option; all other entries help to organize |
cd238eff | 32 | them. A single configuration option is defined like this:: |
1da177e4 | 33 | |
cd238eff | 34 | config MODVERSIONS |
1da177e4 | 35 | bool "Set version information on all module symbols" |
bef1f402 | 36 | depends on MODULES |
1da177e4 LT |
37 | help |
38 | Usually, modules have to be recompiled whenever you switch to a new | |
39 | kernel. ... | |
40 | ||
41 | Every line starts with a key word and can be followed by multiple | |
42 | arguments. "config" starts a new config entry. The following lines | |
43 | define attributes for this config option. Attributes can be the type of | |
44 | the config option, input prompt, dependencies, help text and default | |
45 | values. A config option can be defined multiple times with the same | |
46 | name, but every definition can have only a single input prompt and the | |
47 | type must not conflict. | |
48 | ||
49 | Menu attributes | |
50 | --------------- | |
51 | ||
52 | A menu entry can have a number of attributes. Not all of them are | |
53 | applicable everywhere (see syntax). | |
54 | ||
55 | - type definition: "bool"/"tristate"/"string"/"hex"/"int" | |
16886949 | 56 | |
1da177e4 | 57 | Every config option must have a type. There are only two basic types: |
0486bc90 | 58 | tristate and string; the other types are based on these two. The type |
1da177e4 | 59 | definition optionally accepts an input prompt, so these two examples |
cd238eff | 60 | are equivalent:: |
1da177e4 LT |
61 | |
62 | bool "Networking support" | |
cd238eff MCC |
63 | |
64 | and:: | |
65 | ||
1da177e4 LT |
66 | bool |
67 | prompt "Networking support" | |
68 | ||
69 | - input prompt: "prompt" <prompt> ["if" <expr>] | |
16886949 | 70 | |
1da177e4 LT |
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>] | |
16886949 | 76 | |
1da177e4 LT |
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. | |
83dcde4e JE |
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 | |
1da177e4 LT |
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. | |
83dcde4e | 86 | Optionally, dependencies only for this default value can be added with |
1da177e4 LT |
87 | "if". |
88 | ||
b7d4ec39 DHV |
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 | ||
cd238eff MCC |
110 | - type definition + default value:: |
111 | ||
6e66b900 | 112 | "def_bool"/"def_tristate" <expr> ["if" <expr>] |
cd238eff | 113 | |
6e66b900 RD |
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> | |
16886949 | 118 | |
1da177e4 | 119 | This defines a dependency for this menu entry. If multiple |
83dcde4e | 120 | dependencies are defined, they are connected with '&&'. Dependencies |
1da177e4 | 121 | are applied to all other options within this menu entry (which also |
cd238eff | 122 | accept an "if" expression), so these two examples are equivalent:: |
1da177e4 LT |
123 | |
124 | bool "foo" if BAR | |
125 | default y if BAR | |
cd238eff MCC |
126 | |
127 | and:: | |
128 | ||
1da177e4 LT |
129 | depends on BAR |
130 | bool "foo" | |
131 | default y | |
132 | ||
133 | - reverse dependencies: "select" <symbol> ["if" <expr>] | |
16886949 | 134 | |
1da177e4 LT |
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. | |
cd238eff | 142 | |
f8a74594 | 143 | Note: |
dfecbec8 MW |
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. | |
1da177e4 | 152 | |
237e3ad0 | 153 | - weak reverse dependencies: "imply" <symbol> ["if" <expr>] |
16886949 | 154 | |
237e3ad0 NP |
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 | ||
cd238eff | 159 | Given the following example:: |
237e3ad0 | 160 | |
cd238eff | 161 | config FOO |
3a9dd3ec | 162 | tristate "foo" |
237e3ad0 NP |
163 | imply BAZ |
164 | ||
cd238eff | 165 | config BAZ |
3a9dd3ec | 166 | tristate "baz" |
237e3ad0 NP |
167 | depends on BAR |
168 | ||
169 | The following values are possible: | |
170 | ||
cd238eff | 171 | === === ============= ============== |
237e3ad0 | 172 | FOO BAR BAZ's default choice for BAZ |
cd238eff | 173 | === === ============= ============== |
237e3ad0 NP |
174 | n y n N/m/y |
175 | m y m M/y/n | |
def2fbff | 176 | y y y Y/m/n |
3a9dd3ec MY |
177 | n m n N/m |
178 | m m m M/n | |
179 | y m n M/n | |
237e3ad0 | 180 | y n * N |
cd238eff | 181 | === === ============= ============== |
237e3ad0 NP |
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 | ||
def2fbff MY |
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 | ||
3a9dd3ec MY |
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 | ||
df835c2e | 205 | - limiting menu display: "visible if" <expr> |
16886949 | 206 | |
df835c2e MM |
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 | |
40e47125 | 210 | similar to a conditional "prompt" attribute for individual menu |
df835c2e MM |
211 | entries. Default value of "visible" is true. |
212 | ||
1da177e4 | 213 | - numerical ranges: "range" <symbol> <symbol> ["if" <expr>] |
16886949 | 214 | |
1da177e4 LT |
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 | ||
8f268881 | 220 | - help text: "help" |
16886949 | 221 | |
1da177e4 LT |
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. | |
1da177e4 | 225 | |
93449082 | 226 | - misc options: "option" <symbol>[=<value>] |
16886949 | 227 | |
93449082 RZ |
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. | |
e0627813 | 240 | At most one symbol may have the "modules" option set. |
93449082 | 241 | |
5d2acfc7 JT |
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 | ||
1da177e4 LT |
246 | Menu dependencies |
247 | ----------------- | |
248 | ||
249 | Dependencies define the visibility of a menu entry and can also reduce | |
250 | the input range of tristate symbols. The tristate logic used in the | |
251 | expressions uses one more state than normal boolean logic to express the | |
cd238eff | 252 | module state. Dependency expressions have the following syntax:: |
1da177e4 | 253 | |
cd238eff | 254 | <expr> ::= <symbol> (1) |
1da177e4 LT |
255 | <symbol> '=' <symbol> (2) |
256 | <symbol> '!=' <symbol> (3) | |
9059a349 NP |
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) | |
1da177e4 | 265 | |
cd238eff | 266 | Expressions are listed in decreasing order of precedence. |
1da177e4 LT |
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'. | |
9059a349 NP |
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/). | |
1da177e4 LT |
282 | |
283 | An expression can have a value of 'n', 'm' or 'y' (or 0, 1, 2 | |
4280eae0 | 284 | respectively for calculations). A menu entry becomes visible when its |
1da177e4 LT |
285 | expression evaluates to 'm' or 'y'. |
286 | ||
0486bc90 RD |
287 | There are two types of symbols: constant and non-constant symbols. |
288 | Non-constant symbols are the most common ones and are defined with the | |
289 | 'config' statement. Non-constant symbols consist entirely of alphanumeric | |
1da177e4 LT |
290 | characters or underscores. |
291 | Constant symbols are only part of expressions. Constant symbols are | |
83dcde4e | 292 | always surrounded by single or double quotes. Within the quote, any |
1da177e4 LT |
293 | other character is allowed and the quotes can be escaped using '\'. |
294 | ||
295 | Menu structure | |
296 | -------------- | |
297 | ||
298 | The position of a menu entry in the tree is determined in two ways. First | |
cd238eff | 299 | it can be specified explicitly:: |
1da177e4 | 300 | |
cd238eff | 301 | menu "Network device support" |
bef1f402 | 302 | depends on NET |
1da177e4 | 303 | |
cd238eff | 304 | config NETDEVICES |
1da177e4 LT |
305 | ... |
306 | ||
cd238eff | 307 | endmenu |
1da177e4 LT |
308 | |
309 | All entries within the "menu" ... "endmenu" block become a submenu of | |
310 | "Network device support". All subentries inherit the dependencies from | |
311 | the menu entry, e.g. this means the dependency "NET" is added to the | |
312 | dependency list of the config option NETDEVICES. | |
313 | ||
314 | The other way to generate the menu structure is done by analyzing the | |
315 | dependencies. If a menu entry somehow depends on the previous entry, it | |
316 | can be made a submenu of it. First, the previous (parent) symbol must | |
317 | be part of the dependency list and then one of these two conditions | |
318 | must be true: | |
cd238eff | 319 | |
1da177e4 | 320 | - the child entry must become invisible, if the parent is set to 'n' |
cd238eff | 321 | - the child entry must only be visible, if the parent is visible:: |
1da177e4 | 322 | |
cd238eff | 323 | config MODULES |
1da177e4 LT |
324 | bool "Enable loadable module support" |
325 | ||
cd238eff | 326 | config MODVERSIONS |
1da177e4 | 327 | bool "Set version information on all module symbols" |
bef1f402 | 328 | depends on MODULES |
1da177e4 | 329 | |
cd238eff | 330 | comment "module support disabled" |
bef1f402 | 331 | depends on !MODULES |
1da177e4 LT |
332 | |
333 | MODVERSIONS directly depends on MODULES, this means it's only visible if | |
3e2ba95f DG |
334 | MODULES is different from 'n'. The comment on the other hand is only |
335 | visible when MODULES is set to 'n'. | |
1da177e4 LT |
336 | |
337 | ||
338 | Kconfig syntax | |
339 | -------------- | |
340 | ||
341 | The configuration file describes a series of menu entries, where every | |
342 | line starts with a keyword (except help texts). The following keywords | |
343 | end a menu entry: | |
cd238eff | 344 | |
1da177e4 LT |
345 | - config |
346 | - menuconfig | |
347 | - choice/endchoice | |
348 | - comment | |
349 | - menu/endmenu | |
350 | - if/endif | |
351 | - source | |
1da177e4 | 352 | |
cd238eff | 353 | The first five also start the definition of a menu entry. |
1da177e4 | 354 | |
cd238eff | 355 | config:: |
16886949 | 356 | |
1da177e4 LT |
357 | "config" <symbol> |
358 | <config options> | |
359 | ||
360 | This defines a config symbol <symbol> and accepts any of above | |
361 | attributes as options. | |
362 | ||
cd238eff | 363 | menuconfig:: |
16886949 | 364 | |
1da177e4 LT |
365 | "menuconfig" <symbol> |
366 | <config options> | |
367 | ||
53cb4726 | 368 | This is similar to the simple config entry above, but it also gives a |
1da177e4 | 369 | hint to front ends, that all suboptions should be displayed as a |
cfd7c612 ER |
370 | separate list of options. To make sure all the suboptions will really |
371 | show up under the menuconfig entry and not outside of it, every item | |
372 | from the <config options> list must depend on the menuconfig symbol. | |
cd238eff MCC |
373 | In 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 | |
cfd7c612 ER |
388 | |
389 | In the following examples (3) and (4), C1 and C2 still have the M | |
390 | dependency, but will not appear under menuconfig M anymore, because | |
cd238eff MCC |
391 | of 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 | ||
409 | choices:: | |
1da177e4 | 410 | |
0719e1d2 | 411 | "choice" [symbol] |
1da177e4 LT |
412 | <choice options> |
413 | <choice block> | |
414 | "endchoice" | |
415 | ||
83dcde4e | 416 | This defines a choice group and accepts any of the above attributes as |
032a3187 | 417 | options. A choice can only be of type bool or tristate. If no type is |
08b220b3 | 418 | specified for a choice, its type will be determined by the type of |
032a3187 DG |
419 | the first choice element in the group or remain unknown if none of the |
420 | choice elements have a type specified, as well. | |
421 | ||
422 | While a boolean choice only allows a single config entry to be | |
423 | selected, a tristate choice also allows any number of config entries | |
424 | to be set to 'm'. This can be used if multiple drivers for a single | |
425 | hardware exists and only a single driver can be compiled/loaded into | |
426 | the kernel, but all drivers can be compiled as modules. | |
427 | ||
1da177e4 LT |
428 | A choice accepts another option "optional", which allows to set the |
429 | choice to 'n' and no entry needs to be selected. | |
0719e1d2 YM |
430 | If no [symbol] is associated with a choice, then you can not have multiple |
431 | definitions of that choice. If a [symbol] is associated to the choice, | |
08b220b3 | 432 | then you may define the same choice (i.e. with the same entries) in another |
0719e1d2 | 433 | place. |
1da177e4 | 434 | |
cd238eff | 435 | comment:: |
1da177e4 LT |
436 | |
437 | "comment" <prompt> | |
438 | <comment options> | |
439 | ||
440 | This defines a comment which is displayed to the user during the | |
441 | configuration process and is also echoed to the output files. The only | |
442 | possible options are dependencies. | |
443 | ||
cd238eff | 444 | menu:: |
1da177e4 LT |
445 | |
446 | "menu" <prompt> | |
447 | <menu options> | |
448 | <menu block> | |
449 | "endmenu" | |
450 | ||
451 | This defines a menu block, see "Menu structure" above for more | |
df835c2e MM |
452 | information. The only possible options are dependencies and "visible" |
453 | attributes. | |
1da177e4 | 454 | |
cd238eff | 455 | if:: |
1da177e4 LT |
456 | |
457 | "if" <expr> | |
458 | <if block> | |
459 | "endif" | |
460 | ||
461 | This defines an if block. The dependency expression <expr> is appended | |
462 | to all enclosed menu entries. | |
463 | ||
cd238eff | 464 | source:: |
1da177e4 LT |
465 | |
466 | "source" <prompt> | |
467 | ||
468 | This reads the specified configuration file. This file is always parsed. | |
6e66b900 | 469 | |
cd238eff | 470 | mainmenu:: |
6e66b900 RD |
471 | |
472 | "mainmenu" <prompt> | |
473 | ||
474 | This sets the config program's title bar if the config program chooses | |
8ea13e2c AL |
475 | to use it. It should be placed at the top of the configuration, before any |
476 | other statement. | |
0486bc90 | 477 | |
bdb60101 RD |
478 | '#' Kconfig source file comment: |
479 | ||
480 | An unquoted '#' character anywhere in a source file line indicates | |
481 | the beginning of a source file comment. The remainder of that line | |
482 | is a comment. | |
483 | ||
0486bc90 RD |
484 | |
485 | Kconfig hints | |
486 | ------------- | |
487 | This is a collection of Kconfig tips, most of which aren't obvious at | |
488 | first glance and most of which have become idioms in several Kconfig | |
489 | files. | |
490 | ||
9b3e4dad SR |
491 | Adding common features and make the usage configurable |
492 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
493 | It is a common idiom to implement a feature/functionality that are | |
494 | relevant for some architectures but not all. | |
495 | The recommended way to do so is to use a config variable named HAVE_* | |
496 | that is defined in a common Kconfig file and selected by the relevant | |
497 | architectures. | |
498 | An example is the generic IOMAP functionality. | |
499 | ||
cd238eff | 500 | We would in lib/Kconfig see:: |
9b3e4dad | 501 | |
cd238eff MCC |
502 | # Generic IOMAP is used to ... |
503 | config HAVE_GENERIC_IOMAP | |
9b3e4dad | 504 | |
cd238eff | 505 | config GENERIC_IOMAP |
9b3e4dad SR |
506 | depends on HAVE_GENERIC_IOMAP && FOO |
507 | ||
cd238eff | 508 | And in lib/Makefile we would see:: |
9b3e4dad | 509 | |
cd238eff | 510 | obj-$(CONFIG_GENERIC_IOMAP) += iomap.o |
9b3e4dad | 511 | |
cd238eff MCC |
512 | For each architecture using the generic IOMAP functionality we would see:: |
513 | ||
514 | config X86 | |
9b3e4dad SR |
515 | select ... |
516 | select HAVE_GENERIC_IOMAP | |
517 | select ... | |
518 | ||
519 | Note: we use the existing config option and avoid creating a new | |
520 | config variable to select HAVE_GENERIC_IOMAP. | |
521 | ||
522 | Note: the use of the internal config variable HAVE_GENERIC_IOMAP, it is | |
523 | introduced to overcome the limitation of select which will force a | |
524 | config option to 'y' no matter the dependencies. | |
525 | The dependencies are moved to the symbol GENERIC_IOMAP and we avoid the | |
526 | situation where select forces a symbol equals to 'y'. | |
527 | ||
8373b7d9 MY |
528 | Adding features that need compiler support |
529 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
530 | ||
531 | There are several features that need compiler support. The recommended way | |
532 | to describe the dependency on the compiler feature is to use "depends on" | |
cd238eff | 533 | followed by a test macro:: |
8373b7d9 | 534 | |
cd238eff | 535 | config STACKPROTECTOR |
8373b7d9 MY |
536 | bool "Stack Protector buffer overflow detection" |
537 | depends on $(cc-option,-fstack-protector) | |
538 | ... | |
539 | ||
540 | If you need to expose a compiler capability to makefiles and/or C source files, | |
cd238eff | 541 | `CC_HAS_` is the recommended prefix for the config option:: |
8373b7d9 | 542 | |
cd238eff | 543 | config CC_HAS_STACKPROTECTOR_NONE |
8373b7d9 MY |
544 | def_bool $(cc-option,-fno-stack-protector) |
545 | ||
0486bc90 RD |
546 | Build as module only |
547 | ~~~~~~~~~~~~~~~~~~~~ | |
548 | To restrict a component build to module-only, qualify its config symbol | |
cd238eff | 549 | with "depends on m". E.g.:: |
0486bc90 | 550 | |
cd238eff | 551 | config FOO |
0486bc90 RD |
552 | depends on BAR && m |
553 | ||
554 | limits FOO to module (=m) or disabled (=n). | |
1c199f28 LR |
555 | |
556 | Kconfig recursive dependency limitations | |
557 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
558 | ||
559 | If you've hit the Kconfig error: "recursive dependency detected" you've run | |
560 | into a recursive dependency issue with Kconfig, a recursive dependency can be | |
561 | summarized as a circular dependency. The kconfig tools need to ensure that | |
562 | Kconfig files comply with specified configuration requirements. In order to do | |
563 | that kconfig must determine the values that are possible for all Kconfig | |
564 | symbols, this is currently not possible if there is a circular relation | |
565 | between two or more Kconfig symbols. For more details refer to the "Simple | |
566 | Kconfig recursive issue" subsection below. Kconfig does not do recursive | |
567 | dependency resolution; this has a few implications for Kconfig file writers. | |
568 | We'll first explain why this issues exists and then provide an example | |
569 | technical limitation which this brings upon Kconfig developers. Eager | |
570 | developers wishing to try to address this limitation should read the next | |
571 | subsections. | |
572 | ||
573 | Simple Kconfig recursive issue | |
574 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
575 | ||
576 | Read: Documentation/kbuild/Kconfig.recursion-issue-01 | |
577 | ||
cd238eff | 578 | Test with:: |
1c199f28 | 579 | |
cd238eff | 580 | make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-01 allnoconfig |
1c199f28 LR |
581 | |
582 | Cumulative Kconfig recursive issue | |
583 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
584 | ||
585 | Read: Documentation/kbuild/Kconfig.recursion-issue-02 | |
586 | ||
cd238eff | 587 | Test with:: |
1c199f28 | 588 | |
cd238eff | 589 | make KBUILD_KCONFIG=Documentation/kbuild/Kconfig.recursion-issue-02 allnoconfig |
1c199f28 LR |
590 | |
591 | Practical solutions to kconfig recursive issue | |
592 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
593 | ||
5e8c5299 | 594 | Developers who run into the recursive Kconfig issue have two options |
1c199f28 LR |
595 | at their disposal. We document them below and also provide a list of |
596 | historical issues resolved through these different solutions. | |
597 | ||
598 | a) Remove any superfluous "select FOO" or "depends on FOO" | |
599 | b) Match dependency semantics: | |
cd238eff | 600 | |
1c199f28 | 601 | b1) Swap all "select FOO" to "depends on FOO" or, |
cd238eff | 602 | |
1c199f28 LR |
603 | b2) Swap all "depends on FOO" to "select FOO" |
604 | ||
605 | The resolution to a) can be tested with the sample Kconfig file | |
606 | Documentation/kbuild/Kconfig.recursion-issue-01 through the removal | |
607 | of the "select CORE" from CORE_BELL_A_ADVANCED as that is implicit already | |
608 | since CORE_BELL_A depends on CORE. At times it may not be possible to remove | |
609 | some dependency criteria, for such cases you can work with solution b). | |
610 | ||
611 | The two different resolutions for b) can be tested in the sample Kconfig file | |
612 | Documentation/kbuild/Kconfig.recursion-issue-02. | |
613 | ||
614 | Below is a list of examples of prior fixes for these types of recursive issues; | |
2b5072b9 BH |
615 | all errors appear to involve one or more "select" statements and one or more |
616 | "depends on". | |
1c199f28 | 617 | |
cd238eff | 618 | ============ =================================== |
1c199f28 | 619 | commit fix |
cd238eff | 620 | ============ =================================== |
1c199f28 LR |
621 | 06b718c01208 select A -> depends on A |
622 | c22eacfe82f9 depends on A -> depends on B | |
623 | 6a91e854442c select A -> depends on A | |
624 | 118c565a8f2e select A -> select B | |
625 | f004e5594705 select A -> depends on A | |
626 | c7861f37b4c6 depends on A -> (null) | |
627 | 80c69915e5fb select A -> (null) (1) | |
628 | c2218e26c0d0 select A -> depends on A (1) | |
629 | d6ae99d04e1c select A -> depends on A | |
630 | 95ca19cf8cbf select A -> depends on A | |
631 | 8f057d7bca54 depends on A -> (null) | |
632 | 8f057d7bca54 depends on A -> select A | |
633 | a0701f04846e select A -> depends on A | |
634 | 0c8b92f7f259 depends on A -> (null) | |
635 | e4e9e0540928 select A -> depends on A (2) | |
636 | 7453ea886e87 depends on A > (null) (1) | |
637 | 7b1fff7e4fdf select A -> depends on A | |
638 | 86c747d2a4f0 select A -> depends on A | |
639 | d9f9ab51e55e select A -> depends on A | |
640 | 0c51a4d8abd6 depends on A -> select A (3) | |
641 | e98062ed6dc4 select A -> depends on A (3) | |
642 | 91e5d284a7f1 select A -> (null) | |
cd238eff | 643 | ============ =================================== |
1c199f28 LR |
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 | ||
649 | Future kconfig work | |
650 | ~~~~~~~~~~~~~~~~~~~ | |
651 | ||
652 | Work on kconfig is welcomed on both areas of clarifying semantics and on | |
653 | evaluating the use of a full SAT solver for it. A full SAT solver can be | |
654 | desirable to enable more complex dependency mappings and / or queries, | |
655 | for instance on possible use case for a SAT solver could be that of handling | |
656 | the current known recursive dependency issues. It is not known if this would | |
657 | address such issues but such evaluation is desirable. If support for a full SAT | |
658 | solver proves too complex or that it cannot address recursive dependency issues | |
659 | Kconfig should have at least clear and well defined semantics which also | |
660 | addresses and documents limitations or requirements such as the ones dealing | |
661 | with recursive dependencies. | |
662 | ||
663 | Further work on both of these areas is welcomed on Kconfig. We elaborate | |
664 | on both of these in the next two subsections. | |
665 | ||
666 | Semantics of Kconfig | |
667 | ~~~~~~~~~~~~~~~~~~~~ | |
668 | ||
669 | The use of Kconfig is broad, Linux is now only one of Kconfig's users: | |
cd238eff | 670 | one study has completed a broad analysis of Kconfig use in 12 projects [0]_. |
1c199f28 LR |
671 | Despite its widespread use, and although this document does a reasonable job |
672 | in documenting basic Kconfig syntax a more precise definition of Kconfig | |
673 | semantics is welcomed. One project deduced Kconfig semantics through | |
cd238eff | 674 | the use of the xconfig configurator [1]_. Work should be done to confirm if |
1c199f28 LR |
675 | the deduced semantics matches our intended Kconfig design goals. |
676 | ||
677 | Having well defined semantics can be useful for tools for practical | |
2b5072b9 | 678 | evaluation of dependencies, for instance one such case was work to |
1c199f28 LR |
679 | express in boolean abstraction of the inferred semantics of Kconfig to |
680 | translate Kconfig logic into boolean formulas and run a SAT solver on this to | |
681 | find dead code / features (always inactive), 114 dead features were found in | |
cd238eff | 682 | Linux using this methodology [1]_ (Section 8: Threats to validity). |
1c199f28 LR |
683 | |
684 | Confirming this could prove useful as Kconfig stands as one of the the leading | |
cd238eff | 685 | industrial variability modeling languages [1]_ [2]_. Its study would help |
1c199f28 LR |
686 | evaluate practical uses of such languages, their use was only theoretical |
687 | and real world requirements were not well understood. As it stands though | |
688 | only reverse engineering techniques have been used to deduce semantics from | |
cd238eff | 689 | variability modeling languages such as Kconfig [3]_. |
1c199f28 | 690 | |
cd238eff MCC |
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 | |
1c199f28 LR |
695 | |
696 | Full SAT solver for Kconfig | |
697 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
698 | ||
cd238eff MCC |
699 | Although SAT solvers [4]_ haven't yet been used by Kconfig directly, as noted |
700 | in the previous subsection, work has been done however to express in boolean | |
1c199f28 | 701 | abstraction the inferred semantics of Kconfig to translate Kconfig logic into |
cd238eff MCC |
702 | boolean formulas and run a SAT solver on it [5]_. Another known related project |
703 | is CADOS [6]_ (former VAMOS [7]_) and the tools, mainly undertaker [8]_, which | |
704 | has been introduced first with [9]_. The basic concept of undertaker is to | |
2b5072b9 | 705 | extract variability models from Kconfig and put them together with a |
cd238eff MCC |
706 | propositional formula extracted from CPP #ifdefs and build-rules into a SAT |
707 | solver in order to find dead code, dead files, and dead symbols. If using a SAT | |
708 | solver is desirable on Kconfig one approach would be to evaluate repurposing | |
709 | such efforts somehow on Kconfig. There is enough interest from mentors of | |
710 | existing projects to not only help advise how to integrate this work upstream | |
711 | but also help maintain it long term. Interested developers should visit: | |
1c199f28 LR |
712 | |
713 | http://kernelnewbies.org/KernelProjects/kconfig-sat | |
714 | ||
cd238eff MCC |
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 |