From: Heinrich Schuchardt Date: Mon, 11 Nov 2024 09:05:39 +0000 (+0100) Subject: doc: move README.kconfig to HTML documentation X-Git-Url: http://git.dujemihanovic.xyz/img/static/%7B%7B%20%24style.RelPermalink%20%7D%7D?a=commitdiff_plain;h=8c871871194d230af018d818824086c82faa5b4a;p=u-boot.git 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 --- diff --git a/doc/develop/index.rst b/doc/develop/index.rst index 30f7fdb884..d9f2a83820 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/README.kconfig b/doc/develop/kconfig.rst similarity index 54% rename from doc/README.kconfig rename to doc/develop/kconfig.rst index 808cf56e59..227074dc49 100644 --- a/doc/README.kconfig +++ b/doc/develop/kconfig.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + Kconfig in U-Boot ================= @@ -5,22 +7,20 @@ 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. - +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 - +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: @@ -33,31 +33,26 @@ Here are some worth-mentioning configuration targets. * 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 + (i.e. remove all the include/configs/\*.h), those additional processings above would be removed. -- defconfig - +defconfig In U-Boot, "make defconfig" is a shorthand of "make sandbox_defconfig" -- _defconfig - +_defconfig Now it works as in Linux. - The prefixes such as "+S:" in *_defconfig are deprecated. + The prefixes such as "+S:" in \*_defconfig are deprecated. You can simply remove the prefixes. Do not add them for new boards. -- _config - +_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 -------------------------- @@ -84,68 +79,79 @@ Configuration file for use in makefiles 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/_defconfig) - Maintainers -> "M:" entry of MAINTAINERS - +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 +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 +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 +* 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 +* 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.