Signed-off-by: Masahiro Yamada yamada.m@jp.panasonic.com ---

Please point out if my English is strange, there is something unclear, or something important is missing.

doc/README.kconfig | 163 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 doc/README.kconfig

diff --git a/doc/README.kconfig b/doc/README.kconfig new file mode 100644 index 0000000..6a3b80f --- /dev/null +++ b/doc/README.kconfig @@ -0,0 +1,163 @@ +Kconfig in U-Boot +================= + +This document describes the configuration infrastructure of U-Boot. + +The conventional configuration was replaced by Kconfig at v2014.10-rc1 release. + +Language Specification +---------------------- + +Kconfig originates in Linux Kernel. +See the file "Documentation/kbuild/kconfig*.txt" in your Linux Kernel +source directory for a basic specification of Kconfig. + +Difference from Linux's Kconfig +------------------------------- + +The biggest difference between Linux Kernel and U-Boot in terms of the +configuration is that U-Boot has to configure multiple boot images per board: +Normal, SPL, TPL. +Kconfig functions need to be expanded for U-Boot to handle multiple images. +The files scripts/kconfig/* were imported from Linux Kernel and adjusted +for that purpose. + +See below for how each configuration target works in U-Boot: + +- config, nconfig, menuconfig, xconfig, gconfig + + These targets are used to configure Normal and create (or modify) the .config + file. For SPL configuration, the configutation targets must be prefixed + with "spl/", for example "male spl/config", "make spl/menuconfig", etc. + Those targets create or modify the spl/.config file. Likewise, run + "make tpl/config", "make tpl/menuconfig", etc. for TPL. + +- silentoldconfig + + This target updates .config, include/generated/autoconf.h and + include/configs/*. In U-Boot, the same thing is done for SPL, TPL + for boards supporting them. Depending on whether CONFIG_SPL and CONFIG_TPL + are defined, "make silentoldconfig" iterates three times at most. + + To sum up, "make silentoldconfig" possibly updates: + - .config, include/generated/autoconf.h, include/config/* + - spl/.config, spl/include/generated/autoconf.h, spl/include/config/* + (in case CONFIG_SPL=y) + - tpl/.config, tpl/include/generated/autoconf.h, tpl/include/config/* + (in case CONFIG_TPL=y) + +- defconfig, <board>_defconfig + + The target "<board>_defconfig" is used to create the .config based on the + file configs/<board>_defconfig. The "defconfig" target is the same + except it checks for a file specified with KBUILD_DEFCONFIG environment. + + Note: + The defconfig files are placed under the "configs" directory, + not "arch/$(ARCH)/configs". This is because "ARCH" is not necessarily + given from the command line for the U-Boot configuration and build. + + The defconfig file format in U-Boot has the special syntax; each line has + "<condition>:" prefix to show which image(s) the line is valid for. + For example, + + CONFIG_FOO=100 + S:CONFIG_FOO=200 + T:CONFIG_FOO=300 + ST:CONFIG_BAR=y + +S:CONFIG_BAZ=y + +T:CONFIG_QUX=y + +ST:CONFIG_QUUX=y + + Here, the "<condition>:" prefix is one of: + None - the line is valid only for Normal image + S: - the line is valid only for SPL image + T: - the line is valid only for TPL image + ST: - the line is valid for SPL and TPL images + +S: - the line is valid for Normal and SPL images + +T: - the line is valid for Normal and TPL images + +ST: - the line is valid for Normal, SPL and SPL images + + So, if neither CONFIG_SPL nor CONFIG_TPL is defined, the defconfig file + has no "<condition>:" part and therefore has the same form of that of + Linux Kernel. + From the example defconfig above, three separete configuration sets are + generated and used for creating .config, spl/.config and tpl/.config. + + - Input for the default configuration of Normal + CONFIG_FOO=100 + CONFIG_BAZ=y + CONFIG_QUX=y + CONFIG_QUUX=y + + - Input for the default configuration of SPL + CONFIG_FOO=200 + CONFIG_BAR=y + CONFIG_BAZ=y + CONFIG_QUUX=y + + - Input for the default configuration of TPL + CONFIG_FOO=300 + CONFIG_BAR=y + CONFIG_QUX=y + CONFIG_QUUX=y + +- savedefconfig + + This is the reverse operation of "make defconfig". If neither CONFIG_SPL + nor CONFIG_TPL is defined in the .config file, it works as "savedefconfig" + in Linux Kernel: creates the minimal set of config based on the .config + and save it into the "defconfig" file. If CONFIG_SPL (and CONFIG_TPL) is + defined, the common lines among .config, spl/.config and tpl/.config are + coalesced together with "condition:" prefix for each line as shown above. + This file can be used as an input of "defconfig" target. + +Migration steps to Kconfig +-------------------------- + +Prior to Kconfig, the C preprocessor based board configuration had been used +in U-Boot. + +Although Kconfig was introduced and some configs were moved to Kconfig, +many of configs are still defined in C header files. It will take a very +long term to move all of them to Kconfig. In the interim, the two different +configuration infrastructures should coexist. +The configuration files are generated by both Kconfig and the old preprocessor +based configuration as follows: + +Configuration files for use in C sources + - include/generated/autoconf.h (generated by Kconfig for Normal) + - spl/include/generated/autoconf.h (generated by Kconfig for SPL) + - tpl/include/generated/autoconf.h (generated by Kconfig for TPL) + - include/configs/<board>.h (generated by the old config) + +Configuration file for use in makefiles + - include/config/auto.conf (generated by Kconfig for Normal) + - spl/include/config/auto.conf (generated by Kconfig for SPL) + - tpl/include/config/auto.conf (generated by Kconfig for TPL) + - include/autoconf.mk (generated by the old config for Normal) + - spl/include/autoconfig.mk (generated by the old config for SPL) + - tpl/include/autoconfig.mk (generated by the old config for TPL) + +When adding a new CONFIG macro, it is highly recommended to add it to Kconfig +rather than a header file. + +TODO +---- + +- The option field of boards.cfg, which was used for the pre-Kconfig + configuration, moved to CONFIG_SYS_EXTRA_OPTIONS verbatim now. + Board maintainers are expected to implement proper Kconfig options + and switch over to them. Eventually CONFIG_SYS_EXTRA_OPTIONS goes away. + CONFIG_SYS_EXTRA_OPTIONS should not be used for new boards. + +- In the pre-Kconfig, a single board had multiple entries in the boards.cfg + file with differences in the option fields. The correspoing defconfig files + were auto-generated when switching to Kconfig. Now we have too many + defconfig files comared with the number of the supported boards. It is + recommended to have only one defconfig per board and allow users to select + the config options. + +- Move the config macros in header files to Kconfig. When we move at least + macros used in makefiles, we can drop include/autoconfig.mk, which makes + the build scripts much simpler.