From 8c871871194d230af018d818824086c82faa5b4a Mon Sep 17 00:00:00 2001 From: Heinrich Schuchardt Date: Mon, 11 Nov 2024 10:05:39 +0100 Subject: doc: move README.kconfig to HTML documentation * format according to Sphinx style * add link to Linux Kconfig documentation * sort table alphabetically in 'Conversion from boards.cfg to Kconfig' Signed-off-by: Heinrich Schuchardt --- doc/develop/index.rst | 1 + doc/develop/kconfig.rst | 157 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 158 insertions(+) create mode 100644 doc/develop/kconfig.rst (limited to 'doc/develop') diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 30f7fdb8847..d9f2a838207 100644 --- a/doc/develop/index.rst +++ b/doc/develop/index.rst @@ -13,6 +13,7 @@ General codingstyle designprinciples docstyle + kconfig memory patman process diff --git a/doc/develop/kconfig.rst b/doc/develop/kconfig.rst new file mode 100644 index 00000000000..227074dc497 --- /dev/null +++ b/doc/develop/kconfig.rst @@ -0,0 +1,157 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +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 +---------------------- + +The Kconfig configuration language originates in Linux kernel. +See the Linux document +`Kconfig Language `_ +for a description of Kconfig. + +Difference from Linux's Kconfig +------------------------------- + +Here are some worth-mentioning configuration targets. + +silentoldconfig + This target updates .config, include/generated/autoconf.h and + include/configs/* as in Linux. In U-Boot, it also does the following + for the compatibility with the old configuration system: + + * create a symbolic link "arch/${ARCH}/include/asm/arch" pointing to + the SoC/CPU specific header directory + * create include/config.h + * create include/autoconf.mk + * create spl/include/autoconf.mk (SPL and TPL only) + * create tpl/include/autoconf.mk (TPL only) + + If we could completely switch to Kconfig in a long run + (i.e. remove all the include/configs/\*.h), those additional processings + above would be removed. + +defconfig + In U-Boot, "make defconfig" is a shorthand of "make sandbox_defconfig" + +_defconfig + Now it works as in Linux. + The prefixes such as "+S:" in \*_defconfig are deprecated. + You can simply remove the prefixes. Do not add them for new boards. + +_config + This does not exist in Linux's Kconfig. + "make _config" works the same as "make _defconfig". + Prior to Kconfig, in U-Boot, "make _config" was used for the + configuration. It is still supported for backward compatibility, so + we do not need to update the distro recipes. + +The other configuration targets work as in Linux Kernel. + +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 have been 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) + - include/configs/.h (exists for all boards) + +Configuration file for use in makefiles + - include/config/auto.conf (generated by Kconfig) + - 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 to a header file. + +Conversion from boards.cfg to Kconfig +------------------------------------- + +Prior to Kconfig, boards.cfg was a primary database that contained Arch, CPU, +SoC, etc. of all the supported boards. It was deleted when switching to +Kconfig. Each field of boards.cfg was converted as follows: + +=========== ==================================================== +From To +=========== ==================================================== +Arch CONFIG_SYS_ARCH defined by Kconfig +Board CONFIG_SYS_BOARD defined by Kconfig +CPU CONFIG_SYS_CPU defined by Kconfig +Maintainers "M:" entry of MAINTAINERS +SoC CONFIG_SYS_SOC defined by Kconfig +Status "S:" entry of MAINTAINERS +Target File name of defconfig (configs/\_defconfig) +Vendor CONFIG_SYS_VENDOR defined by Kconfig +=========== ==================================================== + +Tips to add/remove boards +------------------------- + +When adding a new board, the following steps are generally needed: + +1. Add a header file include/configs/.h + +2. Make sure to define necessary CONFIG_SYS_* in Kconfig: + + * Define CONFIG_SYS_CPU="cpu" to compile arch//cpu/ + * Define CONFIG_SYS_SOC="soc" to compile arch//cpu// + * Define CONFIG_SYS_VENDOR="vendor" to compile board//common/\* + and board///\* + * Define CONFIG_SYS_BOARD="board" to compile board//\* + (or board///* if CONFIG_SYS_VENDOR is defined) + Define CONFIG_SYS_CONFIG_NAME="target" to include + include/configs/.h + +3. Add a new entry to the board select menu in Kconfig. + The board select menu is located in arch//Kconfig or + arch//\*/Kconfig. + +4. Add a MAINTAINERS file + It is generally placed at board//MAINTAINERS or + board///MAINTAINERS + +5. Add configs/_defconfig + +When removing an obsolete board, the following steps are generally needed: + +1. Remove configs/_defconfig + +2. Remove include/configs/.h if it is not used by any other boards + +3. Remove board///\* or board//\* if it is not used + by any other boards + +4. Update MAINTAINERS if necessary + +5. Remove the unused entry from the board select menu in Kconfig + +6. Add an entry to doc/README.scrapyard + +TODO +---- + +* In the pre-Kconfig, a single board had multiple entries in the boards.cfg + file with differences in the option fields. The corresponding defconfig + files were auto-generated when switching to Kconfig. Now we have too many + defconfig files compared 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. -- cgit v1.2.3