xref: /openbmc/u-boot/doc/README.kconfig (revision 0f67e239)
1Kconfig in U-Boot
2=================
3
4This document describes the configuration infrastructure of U-Boot.
5
6The conventional configuration was replaced by Kconfig at v2014.10-rc1 release.
7
8
9Language Specification
10----------------------
11
12Kconfig originates in Linux Kernel.
13See the file "Documentation/kbuild/kconfig*.txt" in your Linux Kernel
14source directory for a basic specification of Kconfig.
15
16
17Difference from Linux's Kconfig
18-------------------------------
19
20Here are some worth-mentioning configuration targets.
21
22- silentoldconfig
23
24  This target updates .config, include/generated/autoconf.h and
25  include/configs/* as in Linux.  In U-Boot, it also does the followings
26  for the compatibility with the old configuration system:
27
28   * create a symbolic link "arch/${ARCH}/include/asm/arch" pointing to
29     the SoC/CPU specific header directory
30   * create include/config.h
31   * create include/autoconf.mk
32   * create spl/include/autoconf.mk (SPL and TPL only)
33   * create tpl/include/autoconf.mk (TPL only)
34
35   If we could completely switch to Kconfig in a long run
36   (i.e. remove all the include/configs/*.h), those additional processings
37   above would be removed.
38
39- defconfig
40
41  In U-Boot, "make defconfig" is a shorthand of "make sandbox_defconfig"
42
43- <board>_defconfig
44
45  Now it works as in Linux.
46  The prefixes such as "+S:" in *_defconfig are deprecated.
47  You can simply remove the prefixes.  Do not add them for new boards.
48
49- <board>_config
50
51  This does not exist in Linux's Kconfig.
52  "make <board>_config" works the same as "make <board>_defconfig".
53  Prior to Kconfig, in U-Boot, "make <board>_config" was used for the
54  configuration.  It is still supported for backward compatibility, so
55  we do not need to update the distro recipes.
56
57
58The other configuration targets work as in Linux Kernel.
59
60
61Migration steps to Kconfig
62--------------------------
63
64Prior to Kconfig, the C preprocessor based board configuration had been used
65in U-Boot.
66
67Although Kconfig was introduced and some configs have been moved to Kconfig,
68many of configs are still defined in C header files.  It will take a very
69long term to move all of them to Kconfig.  In the interim, the two different
70configuration infrastructures should coexist.
71The configuration files are generated by both Kconfig and the old preprocessor
72based configuration as follows:
73
74Configuration files for use in C sources
75  - include/generated/autoconf.h     (generated by Kconfig for Normal)
76  - include/configs/<board>.h        (exists for all boards)
77
78Configuration file for use in makefiles
79  - include/config/auto.conf         (generated by Kconfig)
80  - include/autoconf.mk              (generated by the old config for Normal)
81  - spl/include/autoconfig.mk        (generated by the old config for SPL)
82  - tpl/include/autoconfig.mk        (generated by the old config for TPL)
83
84When adding a new CONFIG macro, it is highly recommended to add it to Kconfig
85rather than to a header file.
86
87
88Conversion from boards.cfg to Kconfig
89-------------------------------------
90
91Prior to Kconfig, boards.cfg was a primary database that contained Arch, CPU,
92SoC, etc. of all the supported boards.  It was deleted when switching to
93Kconfig.  Each field of boards.cfg was converted as follows:
94
95 Status      ->  "S:" entry of MAINTAINERS
96 Arch        ->  CONFIG_SYS_ARCH defined by Kconfig
97 CPU         ->  CONFIG_SYS_CPU defined by Kconfig
98 SoC         ->  CONFIG_SYS_SOC defined by Kconfig
99 Vendor      ->  CONFIG_SYS_VENDOR defined by Kconfig
100 Board       ->  CONFIG_SYS_BOARD defined by Kconfig
101 Target      ->  File name of defconfig (configs/<target>_defconfig)
102 Options     ->  CONFIG_SYS_EXTRA_OPTIONS defined by Kconfig
103 Maintainers ->  "M:" entry of MAINTAINERS
104
105
106Tips to add/remove boards
107-------------------------
108
109When adding a new board, the following steps are generally needed:
110
111 [1] Add a header file include/configs/<target>.h
112 [2] Make sure to define necessary CONFIG_SYS_* in Kconfig:
113       Define CONFIG_SYS_CPU="cpu" to compile arch/<arch>/cpu/<cpu>
114       Define CONFIG_SYS_SOC="soc" to compile arch/<arch>/cpu/<cpu>/<soc>
115       Define CONFIG_SYS_VENDOR="vendor" to compile board/<vendor>/common/*
116         and board/<vendor>/<board>/*
117       Define CONFIG_SYS_BOARD="board" to compile board/<board>/*
118         (or board/<vendor>/<board>/* if CONFIG_SYS_VENDOR is defined)
119       Define CONFIG_SYS_CONFIG_NAME="target" to include
120         include/configs/<target>.h
121 [3] Add a new entry to the board select menu in Kconfig.
122     The board select menu is located in arch/<arch>/Kconfig or
123     arch/<arch>/*/Kconfig.
124 [4] Add a MAINTAINERS file
125     It is generally placed at board/<board>/MAINTAINERS or
126     board/<vendor>/<board>/MAINTAINERS
127 [5] Add configs/<target>_defconfig
128
129When removing an obsolete board, the following steps are generally needed:
130
131 [1] Remove configs/<target>_defconfig
132 [2] Remove include/configs/<target>.h if it is not used by any other boards
133 [3] Remove board/<vendor>/<board>/* or board/<board>/* if it is not used
134     by any other boards
135 [4] Update MAINTAINERS if necessary
136 [5] Remove the unused entry from the board select menu in Kconfig
137 [6] Add an entry to doc/README.scrapyard
138
139
140TODO
141----
142
143- The option field of boards.cfg, which was used for the pre-Kconfig
144  configuration, moved to CONFIG_SYS_EXTRA_OPTIONS verbatim now.
145  Board maintainers are expected to implement proper Kconfig options
146  and switch over to them.  Eventually CONFIG_SYS_EXTRA_OPTIONS will go away.
147  CONFIG_SYS_EXTRA_OPTIONS should not be used for new boards.
148
149- In the pre-Kconfig, a single board had multiple entries in the boards.cfg
150  file with differences in the option fields.  The corresponding defconfig
151  files were auto-generated when switching to Kconfig.  Now we have too many
152  defconfig files compared with the number of the supported boards.  It is
153  recommended to have only one defconfig per board and allow users to select
154  the config options.
155
156- Move the config macros in header files to Kconfig.  When we move at least
157  macros used in makefiles, we can drop include/autoconfig.mk, which makes
158  the build scripts much simpler.
159