* 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 heinrich.schuchardt@canonical.com --- doc/README.kconfig | 151 -------------------------------------- doc/develop/index.rst | 1 + doc/develop/kconfig.rst | 157 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 158 insertions(+), 151 deletions(-) delete mode 100644 doc/README.kconfig create mode 100644 doc/develop/kconfig.rst

diff --git a/doc/README.kconfig b/doc/README.kconfig deleted file mode 100644 index 808cf56e59c..00000000000 --- a/doc/README.kconfig +++ /dev/null @@ -1,151 +0,0 @@ -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 -------------------------------- - -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" - -- <board>_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. - -- <board>_config - - This does not exist in Linux's Kconfig. - "make <board>_config" works the same as "make <board>_defconfig". - Prior to Kconfig, in U-Boot, "make <board>_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/<board>.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: - - Status -> "S:" entry of MAINTAINERS - Arch -> CONFIG_SYS_ARCH defined by Kconfig - CPU -> CONFIG_SYS_CPU defined by Kconfig - SoC -> CONFIG_SYS_SOC defined by Kconfig - Vendor -> CONFIG_SYS_VENDOR defined by Kconfig - Board -> CONFIG_SYS_BOARD defined by Kconfig - Target -> File name of defconfig (configs/<target>_defconfig) - Maintainers -> "M:" entry of MAINTAINERS - - -Tips to add/remove boards -------------------------- - -When adding a new board, the following steps are generally needed: - - [1] Add a header file include/configs/<target>.h - [2] Make sure to define necessary CONFIG_SYS_* in Kconfig: - Define CONFIG_SYS_CPU="cpu" to compile arch/<arch>/cpu/<cpu> - Define CONFIG_SYS_SOC="soc" to compile arch/<arch>/cpu/<cpu>/<soc> - Define CONFIG_SYS_VENDOR="vendor" to compile board/<vendor>/common/* - and board/<vendor>/<board>/* - Define CONFIG_SYS_BOARD="board" to compile board/<board>/* - (or board/<vendor>/<board>/* if CONFIG_SYS_VENDOR is defined) - Define CONFIG_SYS_CONFIG_NAME="target" to include - include/configs/<target>.h - [3] Add a new entry to the board select menu in Kconfig. - The board select menu is located in arch/<arch>/Kconfig or - arch/<arch>/*/Kconfig. - [4] Add a MAINTAINERS file - It is generally placed at board/<board>/MAINTAINERS or - board/<vendor>/<board>/MAINTAINERS - [5] Add configs/<target>_defconfig - -When removing an obsolete board, the following steps are generally needed: - - [1] Remove configs/<target>_defconfig - [2] Remove include/configs/<target>.h if it is not used by any other boards - [3] Remove board/<vendor>/<board>/* or board/<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. 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..3a2be54e117 --- /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 https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html`_ +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" + +<board>_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. + +<board>_config + This does not exist in Linux's Kconfig. + "make <board>_config" works the same as "make <board>_defconfig". + Prior to Kconfig, in U-Boot, "make <board>_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/<board>.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/<target>_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/<target>.h + +2. Make sure to define necessary CONFIG_SYS_* in Kconfig: + + * Define CONFIG_SYS_CPU="cpu" to compile arch/<arch>/cpu/<cpu> + * Define CONFIG_SYS_SOC="soc" to compile arch/<arch>/cpu/<cpu>/<soc> + * Define CONFIG_SYS_VENDOR="vendor" to compile board/<vendor>/common/* + and board/<vendor>/<board>/* + * Define CONFIG_SYS_BOARD="board" to compile board/<board>/* + (or board/<vendor>/<board>/* if CONFIG_SYS_VENDOR is defined) + Define CONFIG_SYS_CONFIG_NAME="target" to include + include/configs/<target>.h + +3. Add a new entry to the board select menu in Kconfig. + The board select menu is located in arch/<arch>/Kconfig or + arch/<arch>/*/Kconfig. + +4. Add a MAINTAINERS file + It is generally placed at board/<board>/MAINTAINERS or + board/<vendor>/<board>/MAINTAINERS + +5. Add configs/<target>_defconfig + +When removing an obsolete board, the following steps are generally needed: + +1. Remove configs/<target>_defconfig + +2. Remove include/configs/<target>.h if it is not used by any other boards + +3. Remove board/<vendor>/<board>/* or board/<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.