blob: 808cf56e59c41b28321326b41da84d147c114131 [file] [log] [blame]
Masahiro Yamada6933b5c2014-08-16 00:50:30 +09001Kconfig 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
Masahiro Yamadae02ee252015-02-24 22:26:20 +090020Here are some worth-mentioning configuration targets.
Masahiro Yamada6933b5c2014-08-16 00:50:30 +090021
22- silentoldconfig
23
24 This target updates .config, include/generated/autoconf.h and
Masahiro Yamadac21fc7e2016-08-21 16:12:36 +090025 include/configs/* as in Linux. In U-Boot, it also does the following
Masahiro Yamadae02ee252015-02-24 22:26:20 +090026 for the compatibility with the old configuration system:
Masahiro Yamada6933b5c2014-08-16 00:50:30 +090027
Masahiro Yamadae02ee252015-02-24 22:26:20 +090028 * 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)
Masahiro Yamada6933b5c2014-08-16 00:50:30 +090034
Masahiro Yamadae02ee252015-02-24 22:26:20 +090035 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.
Masahiro Yamada6933b5c2014-08-16 00:50:30 +090038
Masahiro Yamadae02ee252015-02-24 22:26:20 +090039- defconfig
Masahiro Yamada6933b5c2014-08-16 00:50:30 +090040
Masahiro Yamadae02ee252015-02-24 22:26:20 +090041 In U-Boot, "make defconfig" is a shorthand of "make sandbox_defconfig"
Masahiro Yamada6933b5c2014-08-16 00:50:30 +090042
Masahiro Yamadae02ee252015-02-24 22:26:20 +090043- <board>_defconfig
Masahiro Yamada6933b5c2014-08-16 00:50:30 +090044
Masahiro Yamadae02ee252015-02-24 22:26:20 +090045 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.
Masahiro Yamada6933b5c2014-08-16 00:50:30 +090048
Masahiro Yamadad1b60d32014-08-28 10:56:55 +090049- <board>_config
50
51 This does not exist in Linux's Kconfig.
Masahiro Yamadae02ee252015-02-24 22:26:20 +090052 "make <board>_config" works the same as "make <board>_defconfig".
Masahiro Yamadad1b60d32014-08-28 10:56:55 +090053 Prior to Kconfig, in U-Boot, "make <board>_config" was used for the
Masahiro Yamadae02ee252015-02-24 22:26:20 +090054 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.
Masahiro Yamadad1b60d32014-08-28 10:56:55 +090059
Masahiro Yamada6933b5c2014-08-16 00:50:30 +090060
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)
Masahiro Yamada6933b5c2014-08-16 00:50:30 +090076 - include/configs/<board>.h (exists for all boards)
77
78Configuration file for use in makefiles
Masahiro Yamadae02ee252015-02-24 22:26:20 +090079 - include/config/auto.conf (generated by Kconfig)
Masahiro Yamada6933b5c2014-08-16 00:50:30 +090080 - 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)
Masahiro Yamada6933b5c2014-08-16 00:50:30 +0900102 Maintainers -> "M:" entry of MAINTAINERS
103
104
105Tips to add/remove boards
106-------------------------
107
108When adding a new board, the following steps are generally needed:
109
110 [1] Add a header file include/configs/<target>.h
111 [2] Make sure to define necessary CONFIG_SYS_* in Kconfig:
112 Define CONFIG_SYS_CPU="cpu" to compile arch/<arch>/cpu/<cpu>
113 Define CONFIG_SYS_SOC="soc" to compile arch/<arch>/cpu/<cpu>/<soc>
114 Define CONFIG_SYS_VENDOR="vendor" to compile board/<vendor>/common/*
115 and board/<vendor>/<board>/*
116 Define CONFIG_SYS_BOARD="board" to compile board/<board>/*
117 (or board/<vendor>/<board>/* if CONFIG_SYS_VENDOR is defined)
118 Define CONFIG_SYS_CONFIG_NAME="target" to include
119 include/configs/<target>.h
120 [3] Add a new entry to the board select menu in Kconfig.
121 The board select menu is located in arch/<arch>/Kconfig or
122 arch/<arch>/*/Kconfig.
123 [4] Add a MAINTAINERS file
124 It is generally placed at board/<board>/MAINTAINERS or
125 board/<vendor>/<board>/MAINTAINERS
126 [5] Add configs/<target>_defconfig
127
128When removing an obsolete board, the following steps are generally needed:
129
130 [1] Remove configs/<target>_defconfig
131 [2] Remove include/configs/<target>.h if it is not used by any other boards
132 [3] Remove board/<vendor>/<board>/* or board/<board>/* if it is not used
133 by any other boards
134 [4] Update MAINTAINERS if necessary
135 [5] Remove the unused entry from the board select menu in Kconfig
136 [6] Add an entry to doc/README.scrapyard
137
138
139TODO
140----
141
Masahiro Yamada6933b5c2014-08-16 00:50:30 +0900142- In the pre-Kconfig, a single board had multiple entries in the boards.cfg
Masahiro Yamadae02ee252015-02-24 22:26:20 +0900143 file with differences in the option fields. The corresponding defconfig
144 files were auto-generated when switching to Kconfig. Now we have too many
Masahiro Yamada6933b5c2014-08-16 00:50:30 +0900145 defconfig files compared with the number of the supported boards. It is
146 recommended to have only one defconfig per board and allow users to select
147 the config options.
148
149- Move the config macros in header files to Kconfig. When we move at least
150 macros used in makefiles, we can drop include/autoconfig.mk, which makes
151 the build scripts much simpler.